Documentation version: nextdevelopment documentation
Skip to content

Architecture decision records ​

Decisions that shape what Gesso is, rather than how one part of it works. A change that contradicts an accepted ADR needs a new ADR that supersedes it, not just a pull request.

ADRStatusDateDecision
0001 — Align the v2 technical identity with GessoAccepted2026-07-13Namespace, package, and CLI rename to the Gesso identity, with the scope boundaries the rename did not authorize.
0002 — Phase Arazzo workflow execution behind shared runtime expressionsAccepted, amended 2026-10-13 and 2026-10-262026-07-30Arazzo support lands in phases, starting from a runtime-expression evaluator shared with the existing validators. Amendments: embedded non-scalar runtime-expression values stay rejected until #430; the workflow runner moves to a separate package while the evaluator stays in the core.
0003 — Branch-complete response payloads and an SDK round-trip harnessAccepted2026-07-31Close the SDK ⇄ spec gap by feeding spec-derived payloads through a generated decoder.
0004 — v3 consistency policy and protected coreAccepted, amended 2026-08-12; partly superseded by 00072026-08-06v3 changes shape, not capability: the invariants that may not regress, the inclusion criterion and its non-goals, and the rule a reduction PR is held to. Amendments: the #508 exception; the sequencing rule that the final v2 minors carry the adopter-visible value while v3.0 deletes; and the condition — not a date — that opens the v3.0 window.
0005 — v3 configuration and CLI namingAccepted2026-08-06Resolves the naming conflicts between the four v3 rename issues, and fixes the gesso.php key set and the coverage:merge flag set they all target.
0006 — Server base paths and request-path matchingAccepted; sections 1 and 4 superseded by 00082026-08-07servers[].url stays out of path matching; strip_prefixes remains authoritative, and a failed match names the server base path that would have matched.
0007 — v3 scope and release windowAccepted, amended 2026-11-152026-10-26Lets v3 add capability, change verdicts toward spec agreement, and remove surfaces with a shipped deprecation plus evidence, and replaces ADR 0004's v1-EOL floor and trigger with release gates. Supersedes ADR 0004's Decision section and its 2026-08-07 and 2026-08-12 amendments.
0008 — Server base paths in request-path matchingAccepted2026-11-05v3 matches the base paths the spec's servers declare: the path as written first, then each base path verified against the template's effective servers; disagreeing base paths fail loudly, and a non-empty strip_prefixes turns them off. Supersedes ADR 0006 sections 1 and 4.

Writing one ​

Follow the most recent file. The header carries Status, Date, Issue, and Related; 0004 adds Supersedes, which every later ADR should carry even when the value is none. Number files sequentially and add the row above in the same change, so this page never lags the directory.