Skip to content

Latest commit

 

History

History
3794 lines (3268 loc) · 290 KB

DECISIONS.md

File metadata and controls

3794 lines (3268 loc) · 290 KB

Decisions

Settled decisions for this repository. Deliberately short: this is the record of what must not be re-litigated or accidentally undone, not a history of how the libraries were built. That history lives in frontier-workflow's IMPLEMENTATION-PLAN.md and DESIGN-DECISIONS.md, which were not ported — they are the record of the other repo's build.


ADR-PA1 — Platform.Abstractions is the zero-dependency kernel

Frontier.Platform.Abstractions has no Frontier references and no third-party packages — only the base class library.

Every other package sits above it, so anything added here is inherited by all of them and by every consumer. The cost of a casual addition compounds; the constraint is what keeps it cheap to depend on.

Note, 2026-10-24: this originally said "all nine" — the governance tier at extraction. The engine tier's three packages (ADR-PA3 onwards) make twelve; the decision is unchanged and covers them all. README.md lists the current set.

Enforced by PlatformAbstractions_HasNoFrontierOrThirdPartyDependencies.

ADR-PA2 — no platform library references Frontier.Reason.*

No assembly in this repo may reference, or contain a type depending on, any Frontier.Reason.* assembly. Ever.

This is the guarantee that made the extraction possible and the one that keeps it reversible. It is enforced at two levels because they catch different things: PlatformLibrary_DoesNotReferenceReasonWorkflowAssemblies inspects the assembly reference graph; PlatformAssemblyTypes_DoNotDependOnReasonWorkflowTypes (NetArchTest) inspects type dependencies and catches leakage a reference check cannot see, such as a compile-linked source file.

Where a library needs data the consuming solution owns, it declares a consumer-owned port that the solution implements in its composition root. IReferencedRolesSource in ModelRoleConfig is the worked example: the governance rule stays platform-owned, and how referenced roles are discovered stays solution-owned.

Never weaken one of these tests to make a build pass. If a boundary genuinely needs to change, the reason gets recorded here first.

ADR-PA3 — the engine lands here, and it stays workload-neutral

Frontier.Platform.Workflow.Model is the first of the workflow engine's packages to arrive (the consuming repo tracks this as ADR-E3a step 3). The platform is no longer only governance: it is governance plus the engine those workloads run on.

The condition attached to that is not decorative. No package in this family may name a workload's contract type — not in a signature, not in a doc comment the design agent reads back as schema description, not in a test fixture. The first workload's vocabulary reaching a platform package would recreate exactly the fusion this move exists to undo, and it would do so invisibly, because everything would still compile and every test would still pass.

Three things follow, and each has already caught something real:

  • Doc comments are API here. The schema generator reads these XML summaries and hands them to the design agent as field descriptions, so a workload-flavoured example in a <summary> ships as guidance to every consumer. Four such examples were neutralised on arrival.
  • Test fixtures are subject to the same rule. ContractTypeSetTests arrived using the first workload's contracts as its fixtures and was re-based onto the engine's own.
  • Dead types do not travel. Three types that nothing referenced (ClientEntity, DeadLetterRecord, EventResolutionResult) stayed behind rather than becoming permanent compatibility obligations for a feature nobody has built yet.

The XML documentation is a runtime artifact, not just IDE comfort. The schema generator reads these summaries and turns them into the design agent's field descriptions, so the doc file has to reach the consumer's output directory — and NuGet does not put it there by default. Consumers that read it must set CopyDocumentationFilesFromPackages. This was found by the consumer smoke test, not by reasoning: packing includes the .xml, restoring does not deploy it, and the failure mode is silent — descriptions become empty and nothing throws. The smoke test now asserts the file resolves.

The model itself depends only on Platform.Abstractions — not on Serialization. It declares canonical wire shape through attributes and leaves the profile that writes those bytes to the consumer, so nothing about adopting the model commits a consumer to a serializer.

Moving these types between assemblies changed no stored byte: ContractMigrator keys on the stored schema_version string, never on a CLR type name (ADR-PA1). The golden files moved byte-identical for the same reason — a golden rewritten to suit its new home would discard the evidence it exists to carry.


ADR-PA4 — the audit family speaks artifact, and pre-rename records are refused rather than migrated

AuditTelemetryRecord.section_key, AgentInvocation.section_key and ValidatorOutcome.target_section_key become artifact_key / target_artifact_key. AuditRecord and SignedAuditRecord bump to schema 2.0. This completes the vocabulary decision the consuming repo's ADR-E3a deferred to the point where audit and the interpreter are settled together (its D5(a)); it is a breaking public API change, shipped as audit!:.

There is deliberately no migration adapter, and that is the whole substance of this ADR.

Verification here does not hash the stored bytes. AuditChainVerifier.IsSignatureValid rehydrates the record, recomputes its canonical bytes through CanonicalProfile, and compares the result to the stored hash and signature. A migration adapter would therefore not rescue a pre-rename record: it would rehydrate as 2.0, re-serialize to different bytes, and fail its signature. The record would read fine and verify as broken — and a broken hash chain is the signal this system reserves for tampering.

So the choice was never "migrate or not". It was: make a schema change indistinguishable from altered evidence, carry a permanently versioned hasher through the most safety-critical code in the platform, or refuse to read incompatible records at all. The third is the honest one at this point in the project's life, and AuditRecordSchemaGuard implements it: an incompatible major throws ContractViolationException naming the version found, rather than returning degraded evidence. Minor versions stay readable — omit-null defaults cover a field a build has not heard of; only a major says the bytes mean something different.

Cost, measured rather than assumed. Four signed records existed at decision time, all in the local emulator, all carrying populated section_key (19 occurrences across their agent invocations), all reseedable. No deployed environment exists. That is the entire protected population, and it is the cheapest this rename will ever be — the moment real evidence is retained, the only remaining option is the versioned hasher, and it becomes permanent.

Pre-rename golden files are not preserved as fixtures. With no adapter they would assert nothing and imply support that does not exist; git history holds the 1.0 bytes if they are ever needed.


ADR-PA5 — the platform is two tiers now, and the dependency runs one way

Frontier.Platform.Workflow.Orchestration — the interpreter — depends on Audit, HITL, ContextAssembly, ModelRoleConfig, Guardrails and Resilience. Until now every platform library referenced only Abstractions and Serialization, and an architecture test said so of all of them.

That flat rule was written when the platform was only governance. The engine is a composition layer: walking a DAG means calling an approval store, assembling context, resolving a model, staging audit telemetry. Re-abstracting the platform's own interfaces behind a second set of ports to preserve flatness would be ceremony, not design — IApprovalStore is already an interface, and wrapping it would buy nothing.

So the graph gains a tier:

  • Governance tier — Abstractions, Serialization, Audit, ContextAssembly, Guardrails, Hitl, ModelRoleConfig, Observability, Resilience. Still flat: each references only Abstractions and Serialization among platform libraries, so each stays independently consumable and adding one never drags in a sibling.
  • Engine tier — Workflow.Model, Workflow.Orchestration. May depend on governance.

The half that carries the weight is the direction. GovernanceLibrary_DoesNotDependOnTheEngine asserts that no governance library references an engine assembly. A two-tier graph is only worth having if the dependency runs one way: a solution that wants audit or approvals and no interpreter at all must still be able to take them. A single reference in the wrong direction would collapse the tiers back into one graph — and it would compile perfectly, which is why it is a test rather than a convention.

This is not a new decision so much as the consequence of one already taken: the consuming repo's ADR-E3a D1 put the engine in this repo. The tiering is what that means structurally, written down rather than left implicit.

Found while doing it — the second invisible workload coupling. The orchestrator body decided whether an MCP tool was a write by consulting a hardcoded set of two demo connectors' tool names. No type-based architecture test could see it: the coupling was in string literals. It is now IMcpWriteClassifier, a consumer-owned port, and — because it is consulted from inside the orchestrator body — its contract requires a pure, replay-stable answer, the same requirement IResiliencePolicyProvider already carries. The first such coupling was EntryContractBuilder; a third is known and scheduled in the consuming repo (a design prompt naming the workload's entry contract). The pattern is worth stating: the couplings that survive a type-level guard are the ones written as strings.


ADR-PA6 — the compiler joins the engine tier, and publish governance comes with it

Frontier.Platform.Workflow.Compiler completes the engine tier: structural validation, the design-language schema, and the publish lifecycle — draft, validate, propose, approve, publish, pin, retire — over Cosmos.

Publish governance moved deliberately, and it was not obvious. The consuming repo's ADR-E3a named "the DefinitionCompiler engine + structural rules" and said nothing about the lifecycle, so it could equally have stayed. It moved because none of it names a workload: versioned publish with approval and pinning is what any deployment needs, and leaving it behind would mean a second workload reimplementing draft/propose/approve from scratch — the exact fusion the severability work exists to undo. The precedent settled it: Platform.Hitl is already a Cosmos-backed, solution-agnostic store driven by its callers, so the platform owning a store is established rather than novel.

There were no workload rule packs to leave behind. ADR-E3a anticipated them; all 29 rules turned out to be structural — graph shape, data-edge agreement, determinism, versioning, retention. What stays registerable is the extension point: a rule is an IDefinitionValidationRule registration, so a deployment adds its own policy without forking anything. The shipped set encodes what makes a workflow executable, never what makes one acceptable to a particular business.

The stricter analyzers here caught something the consuming repo did not run. AnalysisLevel is latest-all, and ComputeDefinitionHash tripped CA1850 and CA1308. CA1850 was adopted — behaviour-identical. CA1308 is suppressed on purpose: the hash is wire-visible, stored on every published definition, pinned by running executions and used as a cache key, so switching to upper-case hex would silently invalidate every stored hash and every pin. The rule guards locale-sensitive normalisation of user text; this is hex from a digest. Worth stating plainly, because "satisfy the analyzer" is the obvious and wrong move.

Consumability was checked before the move this time. When the interpreter moved it took three PRs to become implementable from another assembly (ADR-PA5). Here the four types a consumer reaches were identified up front, and the smoke test wires the compiler and implements every catalogue port — so it passed first time. The lesson generalises: a package's public surface is not a property you can observe from inside the repo that produces it.


ADR-PA7 — the design agent lives here, and names no consumer's contract

The chat-designer protocol joins Workflow.Compiler, completing the engine's arrival. Its dependency set was already entirely in that package, so it needs no thirteenth library.

ChatDesignerService is internal: consumers resolve IChatDesignerService. A concrete class is a permanent obligation, and nothing outside needs to construct this one.

The condition on it living here is the one ADR-PA3 stated and this move tested. The agent's system prompt used to name one deployment's entry contract and dynamic field as string literals — invisible to every type-level guard, and about to be published. IEntryContractCatalog now supplies them, alongside IChatClient and IDesignerModelProvider.

The rule that came out of it, worth keeping: four workload couplings were found across this programme — a type reference, a hardcoded classification, a demo connector quoted in an error message, and this prompt. Only the first was visible to an architecture test. The couplings that survive a type-level guard are the ones written as strings, so a move should include a literal scan of the moving source for the consumer's contract names and identifiers. Applied to this move, it found exactly one remaining instance — a // comment in ExampleSkeletonBuilder that shipped at v0.7.0 — and confirmed the designer itself was clean.

Agreement matters more than neutrality here. The agent is told to request a field the runtime then reads. If those ever disagree, every workflow the agent designs validates and then fails live, in a way that looks like a model problem. The README says plainly: derive both from one constant.


ADR-PA8 — a definition replayed from history migrates, and that is what keeps replay working

The workflow definition rides inline in the orchestration input (the consuming repo's ADR-2), so it lives in durable history and is rehydrated on every replay. Snapshots migrated; stored definitions migrate as of ADR-PA7's release; history did not.

The consuming repo raised this as a deploy-time fork — freeze the definition model at deployment, or build the history seam first. Investigation collapsed it: the worker already configures JsonDataConverter(CanonicalProfile.Options), System.Text.Json honours property-level converters, and the converter's only dependency is the model itself. Moving it from the compiler into Workflow.Model and attributing one property closes the gap. The expensive option turned out to be unnecessary.

Migrating on a replay path deserves suspicion, so state why it is safe. Determinism requires that identical recorded bytes yield identical decisions. The recorded bytes never change, and the adapter is a pure total function of them, so every replay yields the identical definition — pinned by a test that rehydrates three times and compares canonical bytes. More importantly the migration restores the run's own semantics rather than altering them: the value was always "scope", only the property carrying it was renamed. Without migration a running execution replays with null artifact keys and makes different scheduling decisions than the run it is replaying, which is the one thing replay may never do. The seam is not a risk to replay; its absence was.

What this does not cover, and must not be read as covering. This is safe because the change was a rename — adaptable, value-preserving. A change to what a field means, or one that drops information, cannot be adapted and remains a drain-and-declare event: a named phase boundary, as ADR-PA4 took for audit and the consuming repo's ADR-E15 exception took for activity names. The seam widens the class of changes that are cheap; it does not make every change cheap.

Activity inputs and results also travel in history. The pattern established here applies to them, but each contract needs its own adapters — nothing here migrates them, and claiming otherwise would be worse than the gap.


ADR-PA9 — a rule registered into a tier nothing executes is worse than no rule

determinism.sample-eval is retired. It was the compiler's only RuleTier.Runtime rule, and nothing executes that tier — DefinitionValidator runs Pure and Resourced, and no other code references Runtime at all. The rule body also returned no findings unconditionally. So it was inert twice over, while appearing in the catalogue as a governance rule the product performs.

That is the failure worth naming: the catalogue is a claim. A row in it says "this is checked". A rule that cannot fire makes the claim false in a way that no test catches, because every test of an empty rule passes.

Its own doc comment compounded it by citing a blocker that had been removed — "Phase 1 has no designer sample-data channel yet; wiring lands with S9.38". S9.38 shipped, ITestRunService exposes SampleInputs, and the comment still read as pending work. A stale rationale is how an inert rule survives review.

Retired rather than built, deliberately. Building it means a design-time overload of PredicateEvaluator (the live decision-routing code used inside the orchestrator body) and an executor for the Runtime tier inside the test-run channel. That is a feature, for an Info-severity convenience, and the decision legibility it would provide was already delivered another way — test runs surface the selected branch and skipped nodes. Doc 13 §4.2 R4 stays specified and unbuilt, with the first workload wanting predicate previews as its trigger.

What replaces it is a guard, not a comment. NoRuleIsRegisteredIntoATierNothingExecutes fails if anything is registered into Runtime again. RuleTier.Runtime keeps its place as the declared seam — removing it would hide the gap rather than close it — but now says in its own documentation that it has no executor, so the next person registering into it learns that at the point of the mistake.

This is the first breaking change to a published package here. Everything since v0.1.0 has been additive. DeterminismSampleEvalRule was public and is gone.


ADR-PA10 — orchestrator purity is checked by walking what replay executes, not what the source says

Hard invariant 2 — orchestrator bodies are pure, no DateTime.Now, no GUIDs, no I/O — had no mechanism. GraphOrchestrator's own doc comment states the rule, the behavioural orchestrator tests are thorough, and nothing failed the build when a body broke it. This is the same shape as ADR-PA9: a claim written where a check should be. It is the more dangerous instance, because a non-deterministic body does not throw. It replays, diverges from the recorded history, and corrupts the execution quietly and later.

The guard reads IL, not source, and follows the call closure. GraphOrchestrator.RunAsync is four delegating lines; the walk it governs lives in GraphOrchestratorSteps. A check scoped to the orchestrator type would have passed while inspecting nothing. Orchestrators are discovered by their Durable Task interface rather than listed, so a second orchestrator is covered on arrival — the property the P1 backlog item asked for.

The finding that justifies the whole approach. The first working version passed against a DateTime.UtcNow deliberately planted in GraphOrchestratorSteps. An async method's body compiles into a generated state-machine type that no call instruction points at — the stub hands it to a builder — so a call-following walk sails past every asynchronous body, which here is nearly all of them. The guard reported success while checking almost nothing. It now follows StateMachineAttribute into the generated type, and a regression test pins that it reaches a MoveNext body rather than only the stub that launches it.

The lesson generalises past this test: a guard's own green result is evidence of nothing until it has been shown to fail. Planting a real violation, in the real code, is the cheapest way to learn that a mechanism is decorative — and it is the second time in this batch that the check needed checking.

What it deliberately does not cover, stated rather than implied. The traversal stops at the platform boundary, so an impure implementation of an injected port — IMcpWriteClassifier, IRollbackPlanner, IResiliencePolicyProvider, all consulted inside the body — is invisible to it. Those carry a documented purity contract instead, which is a weaker guarantee honestly stated. Activities are invisible for the right reason: they are reached by name through the durable context, never by a call instruction, and doing I/O is their job.

K10 gets the same treatment. One shared JsonSerializerOptions profile is invariant 1, and it too was unenforced. Two source rules now hold it: only Frontier.Platform.Serialization may construct the options, and every JsonSerializer call must pass the canonical profile. This found one real fork — Phase1EngagementContextStore serialized with framework defaults — fixed here rather than allowlisted, since for a bare string the bytes are identical and the exception would have outlived its reason. A passed-through options parameter is tolerated, because ContractMigrator and the migrating converters take the live options and must honour them; that tolerance is the rule's stated limit, not an oversight.


ADR-PA11 — the execution-id format is kernel vocabulary, because internal did not survive the splits

ExecutionId joins Frontier.Platform.Abstractions: Mint, Parse, ParseOrNull and the Separator constant for the {engagementId}::{workflowId} instance-id format (invariant 3).

The reason it belongs in the kernel is the count. The format was written out in eight places across two repositories — twice in this one. Two helper copies (Workflow.Orchestration and Audit), two identical test suites covering them, one sanctioned mint site in the consuming repo's composition root, one duplicate mint, and two hand-rolled splits in its controllers, one of which had already drifted (it returns everything after the first separator, so a dispatcher child id would yield {workflowId}::{workItemId}).

None of that was carelessness, which is the part worth recording. Each copy was created at an assembly boundary, by someone with no other option: Audit's copy appeared when it was severed from Orchestration at S11.6 — the note of the day says so plainly ("Audit keeps its own") — and the consuming repo's four appeared when the engine moved out at E3b. An internal helper is a correct decision inside one assembly and a silent instruction to duplicate after a split. This codebase has now split twice, and the format duplicated both times.

So the generalisable rule is not "make things public". It is that a repo split converts every internal shared helper into a fork waiting to happen, and the ones to promote are those whose callers ended up on both sides of the new wall. That test names this one exactly.

Kept deliberately small. The segments come back as a named tuple, not a declared type. ADR-PA1's whole argument is that the kernel is inherited by every package and every consumer, so a record carrying two strings — fourteen public symbols once the analyzer enumerated them — would have been a poor trade for what a tuple says with none.

Two readings, because the callers genuinely differ. Parse throws: the platform's own sites receive ids the platform minted, so a malformed one is a programming error. ParseOrNull returns null: both controllers hold identifiers that may legitimately not be execution ids and fall back to using the value as-is. Collapsing them onto the throwing form would have changed API behaviour silently, which is the failure this ADR is about.

Mint additionally refuses a segment containing the separator. Such an id looks well-formed and parses back to values other than those minted — visible only downstream, if at all.

Publishing Mint does not loosen invariant 3. The invariant governs who mints an id for scheduling, not who may know the format, and the consuming repo's guard gets stronger for it: it currently matches an interpolated-string shape and cannot distinguish {engagementId}::{workflowId} from any other two-part key, so it carries an allowlist. A named call site needs no such heuristic.

Additive: the deleted copies were internal, so no published surface changed.


ADR-PA12 — an execution id is read from the right, and reading it from the left was a live defect

Superseded by ADR-PA15 (2026-09-01): the readers this rule governed are gone. It remains the correct reading of any id written under it, and its lesson about production-shaped test data is carried forward rather than retired.

ExecutionId.Parse splits at the last separator. Everything before it is the engagement id; the final segment is the workflow id.

This is what doc 16 §3 has always specified — "the workflow suffix is always the final :: segment of an instance ID, so instance-ID parsing stays unambiguous regardless of how many segments the engagement ID itself has" — and it is not what any implementation did. Both retired ExecutionIdParser copies took parts[0] and parts[1], as did the consuming repo's two hand-rolled splits.

That was wrong in production shape, not merely in theory. Engagement ids are composite and config-templated (doc 16 ADR-E2: {type}::{client}::{site}, e.g. E2E::Acme::Admin-Website), so a real execution id has four or more segments. Reading from the left returns ("E2E", "Acme"): wrong engagement, wrong workflow. The three callers are the audit spine —

  • AuditSigner derives the audit record's partition key from it,
  • CosmosAuditRecordStore derives the partition key it reads by,
  • AuditConsolidator writes both identity fields into the consolidated record.

So every audit record for a composite-engagement execution would have been written to a partition named after the engagement's type, carrying a workflow id that was actually the client name. On the evidence chain this system treats as its moat.

Why it survived. Every test in both suites used eng-1::wf-1. A single-segment engagement id makes reading from the left and reading from the right the same operation, so the bug was invisible to a suite that never wrote down a realistic id. It surfaced only because Mint validated its arguments and the consuming repo's E2E fixtures — which do use E2E::Acme::HQ — began failing. The fixtures had been carrying the counter-example all along; nothing asked them.

The lesson is narrower and more useful than "test more": an identifier's test data has to have the shape production gives it. A simplified id is not a simplified test, it is a different function.

What stays ambiguous, deliberately. A dispatcher child appends ::{workItemId}, and eng-1::wf-1::item-1 cannot be told from a two-segment engagement id running item-1. Parse is therefore defined for top-level ids — which is all three callers hold, audit consolidation running only against top-level executions — and a child id read here yields the work-item id as its final segment. That is pinned by a test rather than left to be discovered, and doc 16's own two statements (§3's "always terminal" and §4's child format) do not agree; the consuming repo owns reconciling them.

Behavioural change to a published package, in the direction of the specification. Signatures are unchanged.


ADR-PA13 — migration adapters go direct to current, so each one must be brought forward at every bump

ContractMigrator does not chain. It reads the stored schema_version, looks it up once, and calls that single adapter. There is no 1.0 → 2.0 → 3.0 walk, and none is planned: a chain needs every intermediate CLR shape kept alive as a type, which is a permanent tax for a rare event.

The consequence is the thing to record, because it is not visible from the code. Every registered adapter must reach the current schema by itself, so a bump to 3.0 obliges someone to revisit the adapter written for 1.0 back when current was 2.0. If they do not, it does not break — it keeps producing a 2.0-shaped object which is then deserialized as the 3.0 type with the new fields left at their defaults. Nothing throws. An execution paused at a gate long enough to cross two versions is exactly what meets it, which is why the consuming repo tracks this as E15b.

The guard is generic and self-updating. MigrationReachesCurrentSchemaTests runs every registered adapter over the real legacy goldens and asserts the result carries the contract type's current version — obtained by deserializing a current golden with its schema_version removed and letting the property initializer answer. Nothing in the test needs editing at the next bump; it simply starts failing until each adapter is brought forward. Two companion rules: no adapter may be registered for the current version, and the snapshot and definition tables must cover the same stored versions, since they describe one wire break and a version adapted for only one of them leaves half a paused execution readable.

The existing tests could not have caught this, and the reason generalises. ArtifactVocabularyMigrationTests asserted the migrated version equalled ArtifactVocabularyMigration.RenamedSchemaVersion — the adapter's own constant. At 3.0 that constant still reads "2.0", so the assertion passes while the adapter is wrong. Verified rather than argued: with ExecutionSnapshot temporarily moved to 3.0, the new test fails with Expected: "3.0", Actual: "2.0" and the old one passes five for five. Both sites now compare against the type. An assertion that compares a thing to its own constant survives the change it appears to guard — the same shape as ADR-PA9's inert rule and ADR-PA10's decorative guard, which is three times in one batch that a green test was the camouflage.


ADR-PA14 — the durable engagement-context store is registrable, not just present

Shipping an implementation nothing can register is the same as not shipping it. ContextAssembly carried CosmosEngagementContextStore — epoch-versioned, tested against the emulator — as an internal type that no registration path reached, while AddFrontierContextAssembly hardwired the compiled-in Phase1EngagementContextStore (two hard-coded engagement ids). A consumer running real engagements therefore resolved no dynamic context at all for anything outside that catalogue, and its entry nodes contract-violated permanently. frontier-workflow found this the first time an automated test started an execution on a freshly created engagement (its S13.50).

Decision. AddFrontierCosmosEngagementContext(IConfiguration) is public and opt-in: it binds this library's own CosmosOptions (each Cosmos-using library binds its own, so none depends on another's registration order), TryAdds the CosmosClient so a consumer's shared client wins, and replaces rather than appends the IEngagementContextStore registration — leaving both would make the resolved implementation depend on call order, which is true in one head and false in the other. AddFrontierContextAssembly still needs no Cosmos configuration, so composing context assembly in a test or a tool stays free of a database.

Consequences. The store's Container constructor is unchanged, so its integration tests are untouched. Consumers opt in explicitly; those that do not keep today's behaviour exactly. Public surface grows by one extension method and one options type, both tracked in PublicAPI.

Lockstep versioning

Every package takes its version from a single git tag via MinVer. A change to one library republishes all of them at the new version.

The alternative — nine tag prefixes, nine changelogs, nine version histories — buys precision nobody has asked for and costs real ceremony on every release. Accepted trade: one tag, one changelog, some packages republished with no changes in them.

Note, 2026-10-24: this was decided over the nine governance packages at extraction, and the first paragraph originally said "all nine". The engine tier's arrival (ADR-PA3 onwards) brought the count to twelve, all versioned by the same tag; the trade above holds with more force, not less. README.md lists the current set.

While the major version is 0, breaking changes may ship in a minor. After 1.0, majors only, at deliberate boundaries.

Deprecation policy (restated for package consumers)

frontier-workflow's rule is that deprecated code survives "until a phase boundary". Consumers of a package have no phase boundaries, so:

  • [Obsolete] must name both the replacement and the version it was deprecated in.
  • Removal only in a major version.
  • A deprecation is always a changelog entry. Never silent.

Public API surface is tracked

Every public member appears in that library's PublicAPI.Shipped.txt or PublicAPI.Unshipped.txt; Microsoft.CodeAnalysis.PublicApiAnalyzers fails the build otherwise.

In a single solution an accidental public is harmless. Here it is a permanent compatibility obligation to whoever resolved the version. This makes each surface change a reviewable diff and turns the major-vs-minor decision into diff-reading rather than judgement.

Dependency floors are a published decision

Central package management means the exact PackageVersion pinned here becomes a minimum version in every published nuspec, which every consumer inherits into its resolution graph. Bumping a floor is no longer an internal choice. Do it deliberately, not casually.

No licence declared

These are private packages on an authenticated feed, so no PackageLicenseExpression is set.

Known consequence: the rights are undefined if this repository is ever made public or changes hands. Revisit before either happens.

Newtonsoft.Json is a Cosmos SDK build requirement

Several libraries reference Newtonsoft.Json without using it in code. The Cosmos SDK's build targets mandate an explicit reference and fail the build without one, regardless of the fact that serialization here goes through System.Text.Json via CanonicalProfile.

Do not "clean up" these references. Microsoft intends to migrate the Cosmos SDK to System.Text.Json in a future major version, with no published timeline; the references can go then. An abstraction layer isolating Cosmos-facing serialization was considered and deferred as not yet worth its cost.


ADR-PA15 — an execution id is written, never read; identity travels as fields

ExecutionId.Parse and ExecutionId.ParseOrNull are removed. Mint stays. Nothing splits, slices or pattern-matches an execution id to recover the parts that went into it; the engagement and workflow travel as typed fields on the contracts that need them — ConsolidateAuditInput.EngagementId/WorkflowId, and the engagementId parameter now taken by IAuditSigner.VerifyAsync, IAuditRecordStore.GetAsync and IAuditQueryService.GetAsync.

The id was doing two unrelated jobs. As an addressing key it must be unique per run and may be opaque; as a metadata carrier it must be structured and unambiguous. Every recurring defect here came from the second job, never the first. ADR-PA12 was a parse bug: splitting from the left on a composite engagement id (E2E::Acme::Admin-Website::wf-sow) returned the engagement's type as the engagement and the client as the workflow, mis-partitioning every audit record for a real engagement. The dispatcher child id (::{workItemId}) is indistinguishable from a longer engagement id by inspection, so Parse had to be documented around rather than fixed. Both are readings of a format that was never itself wrong.

The evidence that this is a subtraction, not a redesign. All five readers across the two repositories wanted a single value between them — the engagement id, for a Cosmos partition key — and two discarded the rest outright (var (engagementId, _) = …). Every caller already held it as a typed value before it called. AuditConsolidator was the clearest case: it parsed the engagement and workflow out of the string, then loaded the ExecutionSnapshot that has carried both as required typed fields all along, and wrote the parsed values rather than the snapshot's.

No behaviour changes. The same values reach the same fields by a route that cannot silently be wrong — and a mis-set field is a compile error or a validation failure, where a mis-parsed id was neither.

What this costs. A public-surface break on the kernel (ADR-PA11) and on three audit interfaces, so consumers update in lockstep. ConsolidateAuditInput gains two required properties, which is a wire change to a DTF activity input — in-flight orchestrations replay the shape they recorded, so this must not be deployed alongside a mid-flight execution that started before it. That is the ADR-E15 accept-and-record posture, flagged rather than assumed.

What it does not settle. Whether the id gains a per-run discriminator, which is the consuming repo's S13.51 and its ADR-EX1. This decision is a prerequisite for it: a run token in the id is only safe once nothing is reading the id for its parts. ExecutionId.Mint therefore still requires a single-segment workflow id, because the minted {engagementId}::{workflowId} remains the derivable key that the affinity claim will be built on.

Supersedes ADR-PA12 — not by contradicting it. "Read from the right" remains the correct reading of any id written under it, and its lesson outlives its rule: an identifier's test data has to have the shape production gives it. A single-segment engagement id made reading from the left and from the right the same operation, which is why a whole suite missed the defect. The replacement tests mint against composite engagement ids for exactly that reason.


ADR-PA16 — a run is a field and a suffix, and the affinity key is what it extends

Superseded in part by ADR-PA20 (2026-09-10): the suffix is gone — the run token is the whole instance id. Everything else here stands: the affinity key is still Mint(engagementId, workflowId), still what the claim is taken on, and still not the instance id; RunId and StartedAtUtc are still fields. The ~ reasoning is kept as the record of why a separator has to survive Cosmos ids and URL paths, which is exactly the class of constraint ADR-PA20 hit next.

ExecutionId.MintRun(engagementId, workflowId, runToken) produces {engagementId}::{workflowId}#{runToken}. RunId joins GraphOrchestratorInput, ExecutionSnapshot, ConsolidateAuditInput — and ExecutionSnapshot also gains a real StartedAtUtc.

Why a suffix and not a new format. The two-argument Mint stays exactly as it was, because it is no longer the addressing key alone: it is the affinity key, the derivable value the consumer takes a claim on to enforce one live run per engagement-workflow. MintRun extends it rather than replacing it, and a test pins that relationship — if the run token were folded into the middle of the id, or the two-argument form were retired, the claim would have nothing deterministic to key on and the K9 guarantee would have no mechanism at all.

Why ~. The run is not another level of the engagement hierarchy. Sharing :: for both would recreate precisely the ambiguity that makes a dispatcher child id unreadable.

The mark was # for one commit, and # was wrong on two counts that no amount of taste would have caught. An execution id is carried verbatim into Cosmos document ids — the consumer's execution-snapshots ids are {executionId}:{sequence} — and Cosmos forbids / \ ? # in an item id, so every snapshot write for a run-scoped execution would have failed. It is also carried in URL path segments (/api/gates/{executionId}/{nodeId}), where # begins a fragment and truncates the path. ~ is unreserved in RFC 3986, legal in a Cosmos id, and already this estate's sanitisation target (the consumer's registry ids map / to ~). Caught while writing the consumer's affinity store, before anything minted a run-scoped id — the cheapest moment it could have been caught, and a test now pins both properties.

Because nothing parses an execution id (ADR-PA15), the choice of mark is a readability question — but its legality in the stores and routes that carry the id is not, and that distinction is what the first choice missed.

Why the token is supplied, not generated here. Platform.Abstractions is the zero-dependency kernel (ADR-PA1), so it cannot take a ULID package; and generation must happen in the composition root before scheduling, never inside an orchestrator body where non-deterministic values are banned outright. The kernel validates the token's shape and refuses one carrying either separator.

Every field is additive and optional, and that is a rule now. RunId and StartedAtUtc are nullable: inputs and documents written before them replay and read as null, meaning "the single run of a pre-change execution". This is the ADR-E15 compatibility floor honoured rather than excepted — the consuming repo's S13.51/ADR-PA15 exception was a breach worth recording and the last of its kind, and S10.7 makes the rule mechanical. GraphExecutionState.StartedAtUtc is required by contrast, because it is internal orchestrator state and never a wire shape.

Why StartedAtUtc is here rather than deferred. The B3 surface was returning CheckpointedAtUtc as the start time under a standing note. With one run per engagement-workflow that is merely imprecise; with several it orders a runs list by last activity, so a long first run appears to start after a quick second one. It is captured once from context.CurrentUtcDateTime at the start of the walk, so it is deterministic under replay and identical on every checkpoint.

What this does not do. It does not mint run ids, take the affinity claim, or make anything re-runnable — those are the consumer's (ADR-EX1). This is the vocabulary that makes them expressible, shipped first so the consumer has something to build against.


ADR-PA17 — what a workflow needs before it runs is asked, not re-derived

IWorkflowEntryInspector.GetEntry(definition) returns the entry node's id, its input contract type, and the dynamic context fields its ContextRequest declares. It declines (null) on exactly the conditions ITestRunInputSchemaProvider declines: no single resolvable AgentTaskNode entry.

Why it is here rather than in the consumer. Entry detection is control-graph knowledge — ControlGraphWalker.FindEntryNodeIds, nodes with no incoming control edge — and that walker is internal to this package because it exists for the validation rules. A consumer needing "which node runs first, and what does it require" would otherwise re-derive the walk from Edges and EdgeKind.Control. That is how one rule ends up written in six places, which is the defect ADR-PA11 was written about; publishing the question is cheaper than policing the copies.

Why RequiredDynamicFields and not the input contract. The consuming repo's start path was about to be built on the entry contract schema, and that would have been wrong: a caller does not supply the entry node's payload. Context assembly builds it, from baseline components plus the dynamic fields the node requests, and the caller's "input" writes that engagement context. So the question a trigger must answer before scheduling is "which dynamic fields does the first node ask for, and does this engagement already hold them?" — the first half of which is this type. A workflow declaring fields here can still start with no input at all where the engagement already holds them, which is how the consumer's seeded PoC engagement runs and would have been broken by keying on the contract instead.

Additive only. A new interface and a new record; nothing existing changes shape, so the ADR-E15 compatibility floor is honoured rather than excepted (the S10.7 rule).

What it deliberately does not do. It reports requirements; it does not resolve them. Whether an engagement satisfies them is the consumer's question, because the context store is the consumer's composition-root concern and this package must not reach for it (ADR-PA2, and the port rule).


Drift ownership

Some concerns exist in both this repo and frontier-workflow. The principle: split by audience, not by copy. A file that says something different in each repo cannot drift; a file that says the same thing in both always will.

Concern Owner Mechanism
canonical-serialization skill split This repo owns the producer half: profile definition, converter authoring, golden-file rules. frontier-workflow's copy is the consumer contract — put [JsonPropertyOrder] on every property, never construct your own options, golden-file every contract. The profile itself lives in the package.
cosmos-conventions skill split This repo owns the conventions and the platform containers. frontier-workflow keeps its own container inventory and snapshot-writer rules. Containers named here but owned there (execution-snapshots) are ports, verified for presence only.
library-boundaries skill split by scope Here: the platform-internal graph and how ports are declared. There: the Reason.* map, plus — once it consumes packages — a rule that a ProjectReference to a platform library is a violation, the mirror image of ADR-PA2.
tests/Shared duplicated, knowingly EmulatorCosmos and ContractRoundTripAssertions are generic and both repos need them. The clean fix is a tenth package, Frontier.Platform.TestSupport, holding only those two — not HitlFixtures/TelemetrySamples, which would drag half the graph into it. Deferred. This is the highest-drift item in the repo; it is a known state, not an accident.
.editorconfig, Directory.Build.targets, coverlet.runsettings, coverage_by_assembly.py, check-vulnerabilities.sh frontier-workflow owns; this repo vendors Genuinely identical, no audience split available. Each carries a provenance header naming the source commit and a runnable drift-check command. Both clones sit side by side under ~/Documents/repos.
PR template, CI workflows, CLAUDE.md divergent by design These intentionally say different things. Do not "helpfully" re-sync them.

Skills deliberately not ported

dtf-determinism (no DTF here), implementation-plan (no plan file), local-dev (no Aspire, DTS or Playwright). definition-of-done was folded into code-review and the PR template rather than kept separate.

ADR-PA18 — a run reads the dynamic-context epoch it was pinned to, and its evidence names it

DynamicTier has always carried EngagementId, DynamicEpoch and AssembledFromSnapshotRef, and ContextAssemblerSimple has always filled them with "unknown", 0, "unknown". The store (CosmosEngagementContextStore) is append-only and versioned by epoch; the read path resolved :current and threw the epoch away before the caller saw it. So two runs of one engagement-workflow with different context produced evidence that could not say which version either read — a linkage gap, not a retention one. The consumer's doc 04 §4 step 3 specifies the read as DynamicTier(engagementId, snapshot.Epoch, snapshot.Ref, …) from a snapshot "frozen-at-init or last refresh"; this restores that. (frontier-workflow S13.60 / C-42.)

Decision. IEngagementContextStore gains an epoch-addressed read that returns the version with its provenance (EngagementContextSnapshot: epoch, document id, content hash, content). The orchestrator carries the pin inline as GraphOrchestratorInput.DynamicContextEpoch / DynamicContextHash — resolved by the Host before scheduling, exactly as the definition is — seeds GraphExecutionState from it, and every AgentTaskActivityInput reads state, never the input, so an explicit refresh (ADR-CR1) can move the pin without the snapshot lying. The composer reads the pinned epoch and throws if it does not resolve: a run pinned to bytes the store cannot produce is an evidential failure, not a fallback case. ExecutionSnapshot and AuditRecord gain dynamic_context_epoch / dynamic_context_hash beside the definition version and hash they have always carried; the audit record copies from the snapshot, which holds the final pin. All additions are optional and omit-null, so existing goldens and signed bytes are byte-identical.

What is not decided here. Nothing moves the pin yet — the refresh signal loop is the consumer's S13.62. Phase1EngagementContextStore keeps no history and answers a non-current epoch with null rather than the latest; Host never resolves it (ADR-PA14), so that honesty is free.

Breaking for implementors of IEngagementContextStore and IContextAssembler (both gain a member); no consumer implements either outside test fakes. ADR-PA17 is claimed by #26, in flight; this is numbered past it deliberately.

ADR-PA19 — the canonical profile reads a polymorphic document in any key order, and still writes it in one

System.Text.Json's polymorphic reader requires the type discriminator to be the first property of the object. That is a streaming-performance choice in the library, not a property of JSON, and it made every query read of a [JsonPolymorphic] document in this platform depend on the store returning keys in written order — a property no store documents. The Azure service happens to preserve order; the Cosmos emulator's June 2026 build happened to; its September build's query path does not: its query path returns every object's keys in Postgres jsonb order — shortest key first, then bytewise — with id appended last. A discriminator therefore stays first only when it is the shortest key in its object, so the same read survives for one document shape and throws for another. CosmosDefinitionStore's SELECT * listings of DefinitionVersionDocument (polymorphic WorkflowNodes inside) are exposed; the existing PhaseC listing test happened to pass against the September build because that fixture's node keys came back with node_type still first. The consumer's engagement-event store did not get that luck and failed. (frontier-workflow S13.64.)

Decision. CanonicalProfile.Options sets AllowOutOfOrderMetadataProperties = true. It is read-side only: the profile still writes the discriminator first, so canonical bytes — and every definition hash, cache key and audit signature computed over them — are byte-identical before and after. The one profile stays one profile. The documented cost is buffering on very large objects; ADR-E1 keeps payload tonnage off the graph, so documents here are small by construction.

Consequences. A test proves a discriminator-last graph deserialises to the same canonical bytes and that the profile's own writes still lead with the discriminator. Pinning the emulator image is the consumer's concern and is about CI determinism, not correctness — after this change the platform reads correctly against any build.

ADR-PA17 — amended 2026-09-10: the sandbox's sample input reaches the executor as context

TestRunRequest.SampleInputs was accepted by TestRunService.StartAsync and discarded before the executor was called — the consumer's S13.50 shape one layer over, found as S13.61's second finding. ITestRunExecutor.StartAsync now takes the input as what ADR-PA17 already says it is: the sandbox engagement's dynamic context, canonical JSON, or null when nothing was supplied (an empty object is "nothing"). The executor writes it before scheduling; what a run with no context gets is the implementation's call — the consumer seeds a default brief when the entry node needs one. Breaking for implementors of ITestRunExecutor; the consumer's adapter is the only one.

ADR-PA17 — amended 2026-10-22: a gate decision names the visit it answers, and is recorded before it is raised

Found by the consumer's S13.112 run and fixed as its S13.119. Doc 06 §9 always specified the approval record's one non-append-only write — the ETag-guarded pending → decided transition, made before the gate event is raised so doc 12 §8's sweep can re-raise a lost raise — but IApprovalStore had no member for it, so every decided gate stayed pending in the projection. IApprovalStore.DecideAsync is that write: exactly one decision wins (Decided), the loser is told who won (AlreadyDecided with the record), an unknown id is NotFound; the pure half, ApprovalDecisionTransition, takes a decision from pending or escalated only (escalation never decides, doc 06 §7) and refuses one addressed to another request.

Two consequences follow. A decision's RequestId is now load-bearing: the gate event name carries only the gate id, so the sweep can deliver an earlier visit's decision to a later visit's wait; GraphOrchestratorSteps.DecideAsync ignores a decision whose RequestId is not the open request's id and keeps waiting — a pure comparison, replay-safe, no new activity. And the sandbox channel must therefore name the real visit: ITestRunExecutor.RaiseGateDecisionAsync takes the run's engagement id so the implementation can find the open request, give the decision its id and record it the way a published run's gate does; null for a test-run document from before the engagement was stored. Breaking for implementors of ITestRunExecutor; the consumer's adapter is the only one, and it hard-coded occurrence 1 where every first visit is 0.


ADR-PA20 — the instance id is the run token; the affinity key stays a key

ExecutionId.ForRun(runToken) returns the token: a DTF instance id is the run's opaque token and nothing else. ExecutionId.MintRun and RunSeparator are removed. ExecutionId.Mint(engagementId, workflowId) is unchanged and is now named for what it always was — the affinity key, a Cosmos document id the one-live-run claim is taken on, never an instance id. ExecutionId.MaxInstanceIdLength (100) states the scheduler's cap once.

The defect. Durable Task Scheduler caps orchestration instance ids at 1–100 printable-ASCII characters, and Microsoft.DurableTask.Client (1.24) enforces it before the request leaves the process: "Instance IDs must be between 1 and 100 characters; actual length is 111." ADR-PA16's {engagementId}::{workflowId}~{runToken} spent 32 of those on a v7-GUID token and left the rest to two ids that are both caller-shaped: a UI-authored workflow id is a 36-character GUID, an engagement id is composite and config-templated ({type}::{client}::{site}), and a sandbox engagement is SANDBOX- + 32 hex. A sandbox run of any UI-authored workflow could not start (111 characters); a real run on any templated engagement id longer than 29 characters could not either. Found 2026-09-10 by the first test run of a UI-authored workflow; every live proof before it ran the seeded advisory-sow (12 characters) on ENGAGEMENT-12345 (16) and fitted at 63.

Why removing the prefix is the fix and not a workaround. ADR-PA15 established that an execution id is written and never read: identity travels as fields (EngagementId, WorkflowId, RunId) on every contract that needs it, and nothing parses the id. The composite prefix was therefore metadata riding in an address — legible on a dashboard, load-bearing nowhere. An address that carries nothing cannot overflow, and the token's length is the composition root's to fix (32 characters today; the cap is now a named rule the kernel checks). Shortening the tokens instead would have moved the cliff, not removed it: engagement id templates are administrator-configured, so any fixed budget is one config change from being exceeded.

What is still keyed on the composite. The affinity key — because the claim needs a derivable key for "this engagement-workflow", and that is exactly what Mint produces. It is a Cosmos id (255-character limit) and never reaches DTS. The relationship ADR-PA16 pinned ("MintRun extends the affinity key") is retired with MintRun; the relationship that matters is pinned instead: ForRun returns a value that contains no affinity key.

What read the id and now reads a field. ApprovalRequestFactory set a sandbox gate's TTL by the execution id's SANDBOX- prefix; it reads GateOpenRequest.EngagementId. IMcpToolCatalog.ResolveAsync took an executionId whose only use was the same prefix test; it takes the engagementId. Both pipelines already held it. Consumer-side readers (the approvals inbox filter, the tool catalogue's sandbox fencing, the orchestration factory) change in the same way in the consumer's S13.68.

Dispatcher children. DispatcherOrchestrator never set a child instance id — DTF assigns one — so the {engagementId}::{workflowId}::{workItemId} shape the docs describe was never minted. The child is identified by GraphOrchestratorInput.WorkItemId, a field; the consumer's S13.40 (which asked how a child id could be parsed unambiguously) is answered by there being nothing to parse.

Breaking. MintRun and RunSeparator removed (abstractions!:); IMcpToolCatalog.ResolveAsync's second parameter is now the engagement id (same shape, different meaning — a consumer passing an execution id would silently disable sandbox fencing, so the rename is deliberate and the consumer's own tests pin it). ADR-E15's compatibility floor: an in-flight execution keeps the instance id it was scheduled under; ids of both shapes coexist in stores and neither is ever parsed.

Evidence. Microsoft Learn, "Durable orchestrations overview" (instance ids: 1–100 characters, printable ASCII, not / \ # ?, not starting with @), read 2026-09-10; the scheduling exception above, reproduced against the local DTS emulator the same day; ADR-PA15/PA16 for the position this completes.

ADR-PA20 — amended 2026-09-10 (same day): two readers in the sandbox channel

TestRunService derived the engagement id from the test-run id twice — ExtractEngagementId for the snapshot read that drives reconciliation, and EnrichWithArtifactContentAsync for the section store's keys — and neither was found by a search for ExecutionId because both parsed the string by hand. With an opaque token the "engagement" became the token, the snapshot lookup hit the wrong partition, and every sandbox run stayed running forever with its gate never auto-approved. TestRunDocument gains an optional engagementId, written at start (and for a blocked run), and both readers use it; a document without one is returned as persisted. Additive; the parser is deleted. The lesson is the one ADR-PA15 recorded and this ADR repeated: the readers were never where the format was.


ADR-PA21 — a cost is an amount and a currency, and two currencies are never added

Every cost amount on the platform drops the currency from its name and gains an ISO 4217 currency code beside it. ModelEntry.InputCostPer1kGbp/OutputCostPer1kGbp/CacheReadCostPer1kGbp become InputCostPer1k/OutputCostPer1k/CacheReadCostPer1k plus Currency (wire input_cost_per_1k, output_cost_per_1k, cache_read_cost_per_1k, currency); BudgetSpec.MaxCostGbp becomes MaxCost + Currency; InvocationCostEstimate.EstimatedCostGbp becomes EstimatedCost + Currency; UsageRecord.CostGbp and BudgetSnapshot.CostGbp become Cost + Currency; BudgetLedgerDocument and ExecutionLedgerSnapshot store total_cost + currency; Observability's TierEconomics, TierEconomicsRow and NodeMetrics take neutral names + Currency. The Phase 1 catalogues are priced in USD: claude-opus-4-8 at 0.0050 / 0.0250 / 0.0005 and claude-fable-5 at 0.0100 / 0.0500 / 0.0010 per 1,000 input / output / cache-read tokens, and the guardrail ceilings keep their numbers in USD (default 2.00, sandbox C-28 0.50). Scales are unchanged: prices 4, budgets 2.

The defect. A sandbox test run of a seven-call workflow reported £1.32. The arithmetic was right; the prices were not. claude-opus-4-8 was seeded at £0.03 / £0.15 per 1,000 tokens, a placeholder about six times Anthropic's list price, and the currency itself was a guess hard-wired into every member name. The consumer's API had already noticed the mismatch the other way: it served these GBP amounts as avg_cost_usd and spent_usd. Two wrong labels on one number is what a currency baked into a name produces. Nothing checks a name.

Why a currency per amount, not one platform currency. The ledger adds amounts that came from different role mappings, and each mapping names its own model and so its own provider's price list. A single configured currency would be one more unchecked assumption at the point where amounts combine. With a code on each amount the combination point can check it. It also sets up the future correctly. Currency conversion is the consumer repo's evolution item E25, and when it lands it removes a refusal at the combination points. It does not add fields to every stored document.

Mixing is refused, never converted. No conversion exists, so wherever two amounts meet in different currencies the platform throws ContractViolationException. That is the two-loop model's permanent failure: FailureClassifier maps it to contract_violation and the outer DTF retry handler never retries it, because no retry can make GBP comparable with USD. The refusals sit in CostCurrency (Guardrails) and are applied at:

  • ledger accumulation — BudgetLedger.RecordUsageAsync refuses usage whose currency differs from the engagement's recorded usage, before storing it; CosmosBudgetLedger.RecordUsageAsync refuses usage whose currency differs from the ledger document's currency. One currency per engagement makes every scope aggregate (invocation, execution, engagement) single-currency by construction.
  • hierarchy aggregation — BudgetHierarchy.BudgetHasCapacity checks, before adding, that the scope ceiling, the snapshot's accumulated cost and the estimate share a currency. A snapshot with nothing recorded has a null currency and combines with anything. A ceiling with no currency is refused.
  • admission — AdmissionController.Admit refuses a per-invocation cost ceiling in a currency other than the estimate's. A judgement call: Admit does not yet enforce the cost ceiling (tokens only), so nothing is added there. The check is placed anyway, so a model entry priced in the wrong currency fails at its first admission and not on the day cost enforcement lands.

The metric. context.cost.saved_gbp (unit GBP) becomes context.cost.saved with the static unit {cost} and a currency attribute beside engagement_type. An OpenTelemetry instrument has one unit for life, so a currency in the unit or the name would need an instrument per currency. As an attribute, one instrument covers all of them, and a dashboard sums only within a currency series. That is the same rule the ledger enforces. currency is a bounded ISO 4217 code, so it respects ADR-O1's no-unbounded-dimension rule.

Breaking, and a bounded exception to lazy migration. This is a public-surface break in Guardrails, ModelRoleConfig and Observability, and a wire break in two stored documents: the model-role-config chain entries and the guardrail-ledger documents. currency is required on both, so a document written before this change fails deserialization instead of being read as currency-less. No migration adapter is written, and the exception is named and bounded the way ADR-PA4 and ADR-PA15 bounded theirs. No deployed environment exists. These documents live only in local emulators, and those are re-seeded (the consumer's cosmos-init.py seed must match Phase1RoleCatalogue byte-for-value and changes with it). Neither document carries a schema_version, and neither is registered with ContractMigrator, so ADR-PA13's adapter ratchet does not reach them. No golden file contains these wire names, so none changes. Any stored cost document written after the first deployment is outside this exception and gets an adapter. ADR-E15's floor: no DTF activity input or output carries a renamed member. AgentTaskActivityPipeline builds InvocationCostEstimate inside the activity from the resolved ModelEntry, AgentTaskActivityInput carries identifiers only, and ResolvedModelSummary carries no cost, so no recorded orchestration history changes shape. Release: minor bump, v0.23.0 (major version 0).

Evidence. Anthropic first-party list prices, from the Claude API pricing table cached 2026-06-24: claude-opus-4-8 $5 / $25 and claude-fable-5 $10 / $50 per million input / output tokens. Anthropic's prompt-caching reference, read 2026-09-11, gives cache reads at ~0.1× the base input price. The £1.32 figure is the consumer's sandbox test run of a seven-call workflow against the old catalogue. That catalogue's own doc comment already called its opus figures "PoC placeholders pending verified provider pricing". Decided by the owner 2026-09-11.

ADR-PA21 — amended 2026-09-11 (same day): the test-run cost summary

The sandbox's cost summary was the one amount the ADR missed. TestRunCostMetrics.EstimatedCost had no currency beside it, so the consumer's test-run screen could show a number but not say what it was in. TestRunCostMetrics gains Currency, the ISO 4217 code of EstimatedCost, and TestRunService stores it in the run document's cost-metrics dictionary under a currency key, written only when non-null. The existing keys are unchanged. Unlike the ledger and catalogue members above, it is optional. It is null when no invocation was priced. Stored test-run documents predate it and are not migrated: they expire on their 7-day TTL, and until then they read back as currency-less instead of failing. ADR-E15's floor holds: the member is additive, never required, and rides no DTF activity input or output. Release: patch, v0.23.1.

ADR-PA21 — amended 2026-09-11: the ledger keeps every execution's snapshot current, at scale 4

Two defects in CosmosBudgetLedger sat under this ADR's ledger members. First, only the create path wrote execution_snapshots. The replace path advanced the engagement totals and left the map alone, so an execution-scope snapshot returned the first invocation's usage for good, and every execution after the document's first had no snapshot at all. Second, the execution-scope read used a LINQ ContainsKey that the Cosmos SDK cannot translate, so it threw before reaching the map. Accumulation now lives in the pure BudgetLedgerAccumulation, which advances the totals and the recorded execution's snapshot together and refuses usage whose currency differs from the document's or from the snapshot's. The read is a parameterised SQL IS_DEFINED query.

The ledger's costs are scale 4, not scale 2. "Budgets 2" above means BudgetSpec.MaxCost, a ceiling, which is unchanged. BudgetLedgerDocument.TotalCost and ExecutionLedgerSnapshot.TotalCost accumulate real usage, and one invocation costs a fraction of a cent (0.0012 USD, say). Scale 2 would round that usage away. Both members were already written at the profile's default scale 4. They now declare [DecimalPrecision(4)] explicitly, so the stored bytes are unchanged and no migration is needed. Release: patch, v0.23.2.

ADR-PA22 — verification resolves the key version that signed the record, not the current one

AuditSigner.VerifyAsync fetched one key from IKeyProvider.GetCurrentKeyAsync and handed it to AuditChainVerifier for the whole chain, so every record was checked against whatever key is current now. Each record has always stored the version it was signed under in SigningKeyId; verification never read it. Audit chains are per engagement and span that engagement's entire life, so the first rotation would have reported every engagement's pre-rotation records as broken links — permanently, and with no way to tell that from tampering. Doc 05 §5 already specified the correct behaviour ("verification resolves the key version from SigningKeyId, so old records verify under old key versions forever; rotation requires no re-signing"), so this is a defect against the spec, not a change of position. It is a K6 repair: the HMAC chain is only evidence if it survives the key lifecycle.

The surface. IKeyProvider gains GetKeyAsync(keyId, ct) returning null for an unresolvable id, with no default interface implementation — the only default available would be to fall back to the current key, which is the defect itself, so every implementation must answer by version or admit it cannot. A new internal SigningKeyResolver resolves a chain's distinct key ids, one provider call per distinct id (a 500-record chain over two rotations costs three calls, not 500). AuditChainVerifier.Verify/FindBrokenLink/IsSignatureValid take an IReadOnlyDictionary<string, SigningKey> and look each record up by its own SigningKeyId. SignedAuditRecord is unchanged — no bytes, hashes or signatures move, so every record already stored stays verifiable and no golden file changes.

Fail closed, but distinguishable. An unresolvable key id makes SignatureValid false for the target record and lists the id in the new optional VerificationResult.UnresolvedKeyIds (unresolved_key_ids, property order 4). "The key version is gone" and "the signature is forged" are different findings and an auditor must not have to guess which one they are looking at. The list is chain-wide: any unresolvable id anywhere in the chain is reported even when the target record itself verifies, because a caller auditing a chain needs to know a version has been destroyed regardless of which record they asked about. It is optional and omit-null, so a clean verification's bytes are unchanged.

An unresolvable key does not stop the walk. Hash-chain continuity needs no key, so FindBrokenLink still walks past a record whose key is missing and still reports a genuine hash discontinuity later in the chain. A missing key version is reported through SignatureValid and UnresolvedKeyIds, never as a broken link.

VerifiedAgainstKeyId is redefined — read this before upgrading. It was "the key verification was performed against", which in practice meant the current key. It now means the target record's own key id: the version its signature was actually checked against. The shape is unchanged (still required string, same wire name, same order), so nothing fails to compile or deserialize, and that is exactly why it is called out here and in the release notes. Any consumer reading it as "the key the system is currently signing with" is now wrong, and silently so. After a rotation a pre-rotation record reports the older version here forever. This is the honest meaning: reporting a key the record was not verified against was never useful.

Evidence. NIST SP 800-57 Part 1 Rev. 5 (May 2020) separates a key's originator-usage period from its longer recipient-usage period — a key retired for producing protection must remain available for processing already-protected data — which is the rule doc 05 §5 states as "old versions are disabled for signing, retained for verify". HMAC is per RFC 2104. Sources read 2026-09-12.

Release: minor, v0.24.0 (major version 0, so a breaking change may ship in a minor — README "Versioning"). Breaking for any out-of-repo IKeyProvider implementation, which must now implement GetKeyAsync; the in-repo DevKeyProvider resolves its own key id and returns null for anything else. Tracked as S13.66.

ADR-PA23 — a draft says when it predates the schema it is read with

MigratingWorkflowDefinitionConverter.Read adapted only stored versions with a registered adapter. Every other version deserialized straight through — unrecognised keys were dropped with no log, no exception and no finding. The nulled fields then surfaced as ordinary content errors ("rollback target … produces no section (no artifact_key)"), so a designer debugged a phantom content problem on an innocent node instead of being told the draft predates the schema this build reads. The read behaviour is deliberately unchanged: a definition that cannot be read faithfully is never silently guessed at. What changes is that the condition is now named.

The stored version must be probed and carried. ArtifactVocabularyMigration.Migrate stamps the current schema_version onto the node before deserializing, so a definition that has been read always reports the current version — the stored one is gone by the time anything downstream could classify it. MigratingWorkflowDefinitionConverter.ProbeStoredSchemaVersion(json) reads it from the pre-migration bytes, and DefinitionDraftDocument.StoredSchemaVersion carries it on the storage envelope. On the envelope, not in the definition: the definition's canonical bytes — and therefore every published hash — stay byte-identical with and without the field (hard invariant 1, pinned by DefinitionDraftDocument_StoredSchemaVersion_DoesNotChangeTheDefinitionsCanonicalBytes). Absent reads as null, which means "not probed", never "current".

Info when adapted, Error when unsupported (decided by the owner, 2026-09-12). An adapted draft is readable and correct — the designer only needs to know why it looks old — so an Error there would block a publish that is fine. An unsupported stored version means fields were dropped, so the definition on screen is not the definition that was saved; Error blocks publish, which is what an unreadable draft deserves. Nothing at all is emitted when the version is current or was never probed: the common path stays silent.

A newer minor of the current major is Current, not a finding. Same major means this build reads it and the converter already deserializes it normally; minor versions are additive by convention, so saying nothing matches what actually happens. A newer major is Unsupported — there is no backward adapter and never will be, and treating "not older" as "fine" is how a downgrade silently corrupts a draft. DefinitionSchemaCompatibility.CurrentSchemaVersion derives from ArtifactVocabularyMigration.RenamedSchemaVersion, the same constant WorkflowDefinition.SchemaVersion defaults to, so the classification cannot drift from the type at the next schema bump.

Rule schema.version-supported is pure-tier and definition-scoped (NodeId/EdgeRef null): anchoring it to a node would send the designer to the wrong place, which is the failure this defect is about. The doc 13 §4.2 catalogue row lives in the consumer repo and is tracked there; RuleCatalogueSpecCoverageTests pins the catalogue as a checked-in fixture in this repo, so it passes here on registration and does not depend on that amendment.

Known gap at the time of this decision. The probed version reaches the storage envelope and DefinitionValidationContext, but no caller yet passes it into a validation run: wiring it through IDefinitionCompiler.ValidateStructural broke seven pre-existing TestRunServiceTests as a mocking artifact and sat outside the agreed surface, so it was reverted rather than absorbed here. The rule and its plumbing are correct and tested; until that wiring lands, schema.version-supported cannot fire in a real validation. Tracked as S13.34.

Gap closed (S13.77, 2026-10-29). The seam is ValidateAsync, whose consumer callers already hold the stored DefinitionDraftDocument. It takes the stored version as a required, nullable parameter: ValidateAsync(draft, draftRevision, storedSchemaVersion, ct). Why required, not a trailing optional: an optional parameter cannot be omitted inside a Moq expression tree (CS0854), so it would have broken the same mock setups the reverted ValidateStructural overload did. An extra overload with a default body would have made loose mocks of the new overload return null at run time instead. A required parameter makes every caller say which case it is, and the compiler finds each one. null is right for an in-memory definition: ChatDesignerService passes it for the designer's proposal, which is a fresh definition, not the stored draft. A breaking change to Workflow.Compiler's public surface, permitted in a minor while the major is 0. ValidateAsync_StoredSchemaVersion_ReachesTheSchemaRule proves the finding through the validation path.

ADR-PA24 — ADR-CR1's refresh lands at quiescence, merges, and reports a real epoch

S13.62 closed ADR-CR1's loop: the orchestrator now consumes a DynamicContextRefreshRequired signal, decides what to do with it, and moves the run's dynamic-context pin. Four decisions were open and are settled here.

The event has one wire contract, in the kernel. DynamicContextRefreshRequired lives in Frontier.Platform.Abstractions, and both halves of the seam use it: the consumer's ingest surface emits it, GraphOrchestrator consumes it. A consumer-side duplicate of the same event would be two contracts for one wire — divergent bytes, divergent hashes, and nothing to fail when they drift apart — which is what ADR-PA2 and K10 exist to prevent. It carries engagement id, reason, changed fields, detected-at UTC, and an optional components list whose names are the snake_case document keys (engagement_profile), not doc 18 §1's kebab-case tier-table spelling: the names have to match the keys the merge writes under, and hard invariant 1 governs the wire.

The name is DynamicContextRefreshRequired. Doc 04 §8's code block raises DynamicContextRefreshNeeded while constructing a DynamicContextRefreshRequired payload on the very next line, so the block contradicts itself; doc 04's own prose above it, doc 16 §4's refresh-class list and doc 18 §3 all say Required. Event names are contracts, so the three consistent sources win and the doc's code block is wrong.

Refresh at quiescence only — doc 04 §8 gives the orchestrator three outcomes ("refresh now, defer to next checkpoint, acknowledge") but never defines the predicate, so this is policy the docs left open rather than behaviour invented against them. The orchestrator refreshes when no nodes are in flight; a signal arriving mid-flight is held and applied at the next iteration that quiesces (doc 04 §8's "queue for next checkpoint"). The reason is evidential, not aesthetic: the pin is stamped onto every checkpoint and consolidated into the signed audit record (S13.60/S13.65), so moving it while activities scheduled against the old epoch are still running would leave the snapshot attesting to an epoch that half the completed steps never read. Two consequences are deliberate and pinned by tests so nobody "fixes" them — nodes already in flight keep the epoch they were scheduled with (that is what AgentTaskActivityInput.DynamicContextEpoch is for), and a signal raised while a human gate is open is not observed until the gate returns, because a gate runs inline in the walk rather than inside the walk's Task.WhenAny. DTF buffers it; nothing is lost; doc 18 §3 states the same outcome from the other side.

The subscription is created once, outside the walk loop and kept out of walk.Running, re-armed only after a signal is consumed. Both halves are load-bearing: re-creating it per iteration writes a new subscription into history on every pass and consumes buffered events out of order, and parking it in walk.Running would make the loop count it as outstanding work — so every ordinary run, which is to say almost every run, would hang at the point the graph is otherwise finished. It is left dangling when the walk ends and DTF discards it with the instance. It is not hand-rolled from Task.WhenAny + CreateTimer + CancellationTokenSource.Cancel, for the reason already recorded on GraphOrchestratorSteps.TryWaitForArtifactUpdateAsync: that races a TimerFired history replay against an already-cancelled timer and throws.

A scoped refresh merges; it does not replace. IEngagementContextStore gains MergeDynamicContextAsync, which writes only its named components and leaves every other key byte-identical. This is a correctness fix, not tidiness. An ADR-CR1 refresh is scoped — doc 18 §3 raises it for named components and doc 04 §8's payload carries changed_fields, not a whole context — but the only primitive available was UpsertDynamicContextAsync, which replaces the whole document. Routing a scoped refresh through it deletes every key the refresh did not produce; the one that matters is engagement_brief, because ContextContentFilter.Filter throws ContractViolationException for a requested key the document no longer holds, and hard invariant 7 makes a contract violation permanent — never retried. A single scoped refresh would therefore have permanently killed every entry node requesting the brief, on a live engagement, with no retry to recover it. That is why this is a store primitive rather than a read-modify-write each caller is trusted to get right. A named component is replaced wholesale, not merged into recursively: the unit is the component, and doc 18 §2's stub→enriched transition legitimately removes fields that a recursive merge would strand. Byte-identity still governs the epoch (ADR-EC1, doc 04 §8): a merge that changes nothing writes nothing and reports the epoch already current, so a primed provider cache stays primed.

The epoch-0 no-op defect is fixed. DynamicContextRefresher returned Epoch: 0 on the identical-bytes path. That constant is not "no epoch" — it is a valid epoch, the first one, since the store's counter is 0-based. S13.60 made it reachable and harmful in one change by giving the run a pin in GraphExecutionState.DynamicContextEpoch, and S13.62 is the first caller to assign a refresh result to it: a run that refreshes at epoch 4, finds the bytes unchanged and stores the returned 0 has silently dragged its pin back four epochs, after which every assembly reads stale bytes while the snapshot and the signed audit record both attest to an epoch the run never read. Wrong provenance is worse than none, because it reads as true. A no-op now reports the store's current epoch, read through the existing GetDynamicContextSnapshotAsync(id, null, ct); the no-op semantics themselves are unchanged and must stay unchanged. The pre-existing refresher tests were accidentally right — each seeds exactly one upsert, so the current epoch there genuinely is 0 — which is precisely why the defect survived them.

The content producer is the consumer's half. The refresh activity takes rendered content through IDynamicContextContentProducer, a port. The dynamic components themselves are consumer-side types over the consumer's engagement entity and its CRM enrichment (doc 18 §1's "thin readers", ADR-EC1); recreating them here would be an ADR-PA2 breach. The engine knows only that a refresh needs rendered content and asks for it. The decision runs in the orchestrator body, the work runs in an activity — hard invariant 2, enforced by OrchestratorPurityTests.

Release: minor, v0.25.0 proposed (major version 0, so a breaking change may ship in a minor — README "Versioning"). Breaking for any out-of-repo IEngagementContextStore implementation, which must now implement MergeDynamicContextAsync; EngagementContextMerge.ApplyThroughAsync is public so that obligation is satisfiable in one line, over the interface's own members.

ADR-PA25 — the dispatcher is a router, not a queue; and its generation boundary is where a version moves

S13.22 and S13.18 are recorded together because they are one change: the resolve-before- ContinueAsNew edit and the body rewrite touch the same twelve lines of DispatcherOrchestrator.

The defect. DispatcherOrchestrator awaited CallSubOrchestratorAsync inside its loop, before looping back to the WorkItem wait. One child parked at a human gate therefore blocked every later work item — the exact inverse of doc 00 §4.4's "work items process in parallel: a child paused at a human gate never blocks the queue" and doc 16 §4's children running "normal run-to-completion semantics". A dispatcher-mode definition typically contains a gate, so the serial form would have parked the queue on the first ticket and looked like nothing worse than a slow system. It had never run: nothing raises WorkItem yet (that is the consumer half), which is why five years of green tests said nothing about it.

Spawning is parallel and unbounded, and ContinueAsNew counts spawns, not completions. The body races the WorkItem wait against its outstanding children and never throttles; the generation boundary fires on the Nth spawn, with every child still in flight, and does not wait for them. Both read as bugs and are the design, so both are commented at the call site and pinned by tests. The evidence for the second is explicit: a sub-orchestration "runs as a child of the calling (parent) orchestrator" as its own orchestration instance with its own history, which "can run standalone for one-off device setup, or a parent orchestrator can schedule it as a sub-orchestration" (Microsoft Learn, Sub-orchestrations in Durable Task, ms.date 2026-04-23, updated 2026-08-03). What continue-as-new discards is stated just as precisely: "The results of any incomplete tasks are discarded when an orchestration calls continue-as-new" (Microsoft Learn, Eternal Orchestrations in Durable Task, ms.date 2026-04-23, updated 2026-08-05) — the results, in the parent's own execution, not the child instances, which are separately scheduled and complete on their own, writing their own snapshots and their own signed audit records. A rollover mid-flight therefore orphans nothing. Restoring an await in the loop, adding a throttle, or putting a WhenAll at the boundary would each turn the router back into the queue this replaced.

The same page fixes the other half of the boundary: in .NET "continue-as-new preserves unprocessed events by default … unprocessed events are delivered when the orchestration next calls waitForExternalEvent". That default is load-bearing here — a work item raised between the Nth spawn and the new generation must cross, or an ingest surface accepted an event and dropped it — and it is also what makes the refresh drain necessary, below.

The WorkItem wait is subscribed once per generation and re-armed only after a delivery. DTF writes one history record per subscription, so a wait re-created inside the loop grows history on every pass and consumes buffered events out of order. This is not a new hazard: it is the one already documented on the ADR-CR1 refresh wait in GraphOrchestratorSteps, and the dispatcher inherits it wholesale the moment the loop races that wait against outstanding children.

EnsureSupported gains a work-item carve-out; rewriting the child's definition was rejected. A dispatcher hands its child its own pinned definition, whose mode is dispatcher, so every spawned child would have died on the Mode != OneShot guard — a contract violation, permanent and never retried (invariant 7). The carve-out is exactly as wide as a non-blank WorkItemId: a child of a dispatcher carries one, a top-level execution never does. The alternative — rewriting the child's definition to OneShot before spawning — mutates a pinned definition and changes its definition_hash, a K3/ADR-2 breach. The hash is what the signed audit record pins to prove which graph version produced the output, so a child whose definition was edited in flight would attest to a version that was never published. The mode guard gives, not the definition. The dispatcher's own mode guard moves from InvalidOperationException to ContractViolationException at the same time: one vocabulary for one class of mistake, and the permanent-failure classification is read off the exception type.

The rollover port fails loud. IDispatcherVersionResolver is declared here and deliberately not DI-registered — the IDynamicContextContentProducer precedent: what a published version is, and what an engagement's pin means, is the consumer's knowledge (doc 16 §8, ADR-E7), and a default would let a misconfigured deployment roll a dispatcher onto the wrong definition instead of failing to start. Resolution runs in an activity because it is a store read (invariant 2) and at the generation boundary because a running generation stays pinned to the definition its history recorded (invariant 6). null means "no successor — continue on the current version" (doc 16 §8's third bullet; ADR-E15 D2's "the queue never stalls on a retired version"). Failure must throw and must never be reported as null, and the XML doc says so: conflating "nothing newer" with "lookup failed" would pin a dispatcher to a stale definition silently and forever, with no later moment at which the mistake surfaces — the same silent-fallback shape as the epoch-0 no-op (ADR-PA24) and the S13.66 key provider. The next generation's input is rebuilt around the resolved definition while preserving RunId, EngagementId and InitiatedBy: a generation change is the same run continuing, so a new run id would fork the audit chain (ADR-EX1) and a dropped initiator would break the S13.19 attribution chain at an arbitrary 100-item boundary.

WorkItem.Payload becomes an ADR-E2 TypedPayload. It was required object, which is not a contract: object deserializes as a JsonElement, so every consumer re-inspects an untyped blob and ADR-E1 tonnage has nowhere to live. This is K4 erosion in the one place it matters most — the only path carrying external input across the DTF history boundary, where the bytes are evidential and replayed for the life of an eternal instance. The contract now implements IVersionedContract, validates (cascading the envelope's own violations), and has a golden file; for rules, by CellyRuleEngineTests, CelSchemaTypesTests, CelPayloadTests, RuleCostHintsTests and RuleProfileTests, all against the real engine. Adding schema_version at property order 0 renumbers the rest, which canonical-serialization normally forbids outright; it is safe because of the defect above — nothing has ever raised a WorkItem, so no stored or replayed bytes exist. It is a break in theory only, and only until the first dispatcher runs.

Two consequences were followed rather than worked around. ContinueAsNewThreshold became internal so tests reference the boundary instead of hard-coding 100. And CanonicalOutputSchema now refuses any contract that carries a TypedPayload, not just TypedPayload itself: making WorkItem a versioned contract brought it into the schema sweep, where its free-form payload exported as the boolean schema Anthropic rejects. Inventing a schema for it would contradict ADR-E2 deferral (c) — the honest schema is the capability-declared schema_ref — and a work item is not an agent output contract in any case. The sweep now skips whatever the generator refuses, and a new test pins the refused set to exactly TypedPayload and WorkItem so refusal stays a visible decision rather than a quiet exemption.

The dispatcher drains refresh signals it will never act on. S13.62's fan-out raises DynamicContextRefreshRequired at every live instance of an engagement, dispatchers included. A dispatcher has no walk and no epoch to move, so it never acts on one — but with unprocessed events preserved by default (cited above), every such signal would be carried into the next generation, and the next, forever: unbounded history growth for the life of an eternal instance, entirely silently. A drain-and-discard wait bounds it. Excluding dispatchers from the fan-out on the consumer side is a separate, complementary fix; this half holds even if that one is forgotten.

Release: minor, v0.26.0 proposed (major version 0, so a breaking change may ship in a minor — README "Versioning"). Breaking on two counts, both on WorkItem: Payload is retyped from object to TypedPayload, and the new schema_version at property order 0 renumbers every other property — a wire-compatibility break that canonical-serialization normally forbids outright. Both are safe for exactly one reason, and it is the defect above rather than any property of the change: nothing has ever raised a WorkItem, so no stored or replayed bytes exist to break. That reason expires the moment the first dispatcher runs.

ADR-PA26 — the projection records a run's mode and its work item, and a child writes its own sequence 0

ADR-PA25 made the dispatcher spawn a child per work item. ExecutionSnapshot carried neither the mode nor the item, so every child run of an engagement looked identical in the projection and in the engagement timeline: nobody could say which ticket a given run was serving.

The mode is stored, not derived, and not reduced to a boolean. execution_mode (property order 21) is the definition's existing ExecutionMode smart enum on its canonical wire string; work_item_id (order 22) is the child's item, null on every run that is not one. An is_dispatcher flag was rejected: the question a projection has to answer is what kind of run is this, and a derived boolean is wrong the moment a third mode exists. The two fields are read together — a child is handed its parent's pinned definition unaltered (ADR-PA25 — rewriting it would move the definition_hash), so a child's mode is dispatcher too. The router is therefore execution_mode == dispatcher && work_item_id == null, and a child is dispatcher with an item. Neither field alone separates them, which is the concrete reason the pair is stored rather than a flag.

The field is execution_mode, not mode. It was mode when #44 merged — matching WorkflowDefinition.mode, the contract it is copied from — and was renamed before v0.27.0 was tagged, so nothing had ever shipped under that spelling and no stored bytes carry it. The projection's readers are the boundary that matters here, and execution_mode is their established vocabulary; the consumer binds the CLR name by reflection, which is why the property is ExecutionMode rather than Mode. Internal consistency with the definition contract lost to consistency where the value is actually read.

The leak this closes. S13.62's refresh fan-out filters on status alone, so it raises DynamicContextRefreshRequired at dispatcher instances, which never wait on it; ContinueAsNew's preserveUnprocessedEvents: true then carries those events into every generation — silent, unbounded history growth. The dispatcher's own drain (ADR-PA25) bounds it from inside; excluding routers from the fan-out is the consumer's complementary half, and it was impossible because the projection could not say which runs were routers. Now it can.

A dispatcher child writes its own sequence-0 snapshot. Sequence 0 is the pre-start projection slot, filled by the Host's OrchestrationFactory for a normal run (S4.7a) — which is why GraphExecutionState.Sequence starts at 1. A child bypasses that factory entirely, so nothing wrote its slot and the child stayed invisible until its first node completed: the S13.70 shape, a run that exists but cannot be seen, already fixed once for test runs. GraphOrchestrator now calls WriteChildStartSnapshotAsync before the walk, which writes through the same SnapshotStateActivity path at sequence 0 and does nothing at all for a top-level run. It is an activity call, never body I/O (invariant 2), and the discriminator is the same non-blank WorkItemId that EnsureSupported's dispatcher-child carve-out already uses, so the two cannot drift.

Both properties are optional, omit-null and appended — nothing is renumbered, no member is required, and bytes recorded before them read back as null per the ADR-E15 floor. Every existing snapshot golden is byte-identical, pinned by a test that re-serializes the unchanged sample against the pre-change golden rather than by inspection.

Release: minor, v0.27.0 proposed — purely additive, but the consumer's fan-out exclusion needs a version to bump to.

ADR-PA26 — amended 2026-10-22: the projection also records why a run paused on a failure

Found by the consumer's S13.112 run and fixed as its S13.120. A paused_on_failure snapshot carried only failure_classification — doc 10 §3's reason code — while the exception behind it lived in durable history and the worker's console, so diagnosing a paused run meant reading its artifacts in Cosmos or reproducing the call by hand. ExecutionSnapshot.failure_detail (property order 23) is an ExecutionFailureDetail — node_id, exception_type, message — built by the orchestrator from the walk's first failure, a pure function of the exception it already held (invariant 2), and written through the same SnapshotStateActivity call as the classification.

What it carries is a decision, not a convenience. Only the exception's message — never its ToString(), stack trace or data. An activity failure's TaskFailureDetails chain is read head-first, so the type is the one the classification was read from, and inner messages follow an arrow. The result is bounded to 512 characters, ending in an ellipsis, and credential-shaped fragments — a Bearer/Basic token, sig=, key=, api_key=, token=, secret=, password= and their spellings — have their values replaced with [redacted] before the detail is written, because a projection is read by every visitor to the execution screen and must never carry a bearer credential (ADR-SEC5). Additive and optional under the ADR-E15 floor: nothing is renumbered, no member of the snapshot is required, Validate() does not demand it, and the existing paused-on-failure golden is byte-identical — pinned by a test that re-serializes the unchanged sample against it. A snapshot a consumer's recovery sweep heals carries no detail: the sweep sees the orchestration's fault rather than the node's, and saying nothing is better than naming the wrong node.

Release: minor, v0.37.0 proposed — purely additive; the consumer's B3 failure band needs a version to bump to.

ADR-PA26 — amended 2026-11-06: a terminated run says who ended it, and its pending approval is withdrawn under a guard

Consumer S13.149 adds a governed route that ends a stuck live run (Mark's decisions of 2026-11-03, review-01 GOV-06, and 2026-11-06).

  • ExecutionStatus.Terminated (terminated) is a new terminal status. It is kept apart from cancelled, which no person asked for by name.
  • ExecutionSnapshot gains terminated_by, termination_reason and terminated_at_utc (orders 24–26). Validate() requires all three on a terminated snapshot, as it requires failure_classification on a paused_on_failure one. No other status is checked.
  • Mark kept the rule for machine terminates (2026-11-06). A terminate no person asked for, such as a recovery sweep, must still give an actor, a reason and a time. By the ADR-E8 convention its actor is an explicit system:* id such as system:recovery. Validate() cannot enforce that convention: a human principal id has no fixed format, so a non-blank actor is all it can require. The consumer's snapshot writer keeps it.
  • ApprovalRequestStatus.Withdrawn (withdrawn) is for a gate-paused run that is terminated. The request gains withdrawn_by and withdrawal_reason (orders 12–13, after ttl).
  • The sandbox test-run mapping treats terminated as terminal, like cancelled.

Withdrawal and escalation are guarded transitions (Mark, 2026-11-06). An unguarded upsert would let a withdrawal overwrite a decision that landed after the consumer's read. It would also let an escalation activity still running when the run is terminated write escalated back over withdrawn.

  • IApprovalStore gains WithdrawAsync(engagementId, approvalId, withdrawnBy, withdrawalReason) and EscalateAsync(engagementId, approvalId). Both return an ApprovalTransitionResult, which is applied, refused with the stored record, or not_found.
  • They run over the same read, check and replace loop as DecideAsync, now ApprovalTransitioner. A lost ETag race re-reads once and is refused if the winner no longer allows it, so a decision and a withdrawal racing each other cannot both land.
  • A withdrawal accepts exactly the statuses a decision does: pending and escalated.
  • An escalation accepts pending, escalated (a retried activity) and a decided request whose decision is the approver's own escalate. That last case is what the unguarded write did: the approver's escalate is recorded through DecideAsync, and the escalation re-opens the request for the real decision. An approve, a reject, an expired request and a withdrawn one are never overwritten.
  • EscalateApprovalActivity now writes through EscalateAsync and returns the stored record when refused; the orchestrator discards that return value, as it always did. It writes the request whole only when the store does not hold it, as before, so a lost projection document is rebuilt rather than failing the gate. Its CLR input and output types are unchanged. Its wire shape gains only additive members, the withdrawn status value and the two optional withdrawal members, as activity-shapes.json records.
  • Each transition names the statuses it accepts, so a status added later is refused by construction. ApprovalStatusTransitionsTests classifies every value of ApprovalRequestStatus.List in one explicit table and fails when a value is missing from it.
  • The scripted ApprovalLifecycleTests drive each direction of the race. The emulator test runs a decision and a withdrawal concurrently and shows they never both land. It cannot force them to conflict, so it does not by itself prove the retry path.

This is a public-surface break, so the commit is scoped hitl!. Every implementation of IApprovalStore must add the two members. ADR-PA41 and ADR-PA43 treat a new member on an implemented interface this way. The consumer's three test doubles are the implementations affected.

The platform offers no terminate operation. The orchestration factory, the one-live-run claim, the snapshot store and the governance catalogue are all the consumer's (doc 12 §5).

Every new member is omit-null under the ADR-E15 floor. Nothing is renumbered and no member is required. Every older snapshot golden reads the new members as null and re-serializes byte-identically (ExecutionTerminationTests), and so does approval_request_pending.json, which was written by the code before this change. The activity-shape snapshot records the change as additive.

Release: rides v0.54.0. While the major version is 0, a break may ship in a minor.

ADR-PA27 — a role's chain may resolve to a remote agent; the invoker learns what it resolved to

frontier-workflow is wiring A2A agents hosted in Azure AI Foundry into workflows (its S13.80–S13.89). PLATFORM-EVOLUTION-CANDIDATES E4 and E6 already settle how an external agent is reached: through role, not a new node field — E4 says A2A slots behind IAgentInvoker "with no orchestrator or definition changes", and E6 says runtime resolves only which instance of the named thing serves. So a role's chain has to be able to hold an agent. It could not: every chain entry was a ModelEntry whose token prices, context window and max output tokens are required, and AgentInvocationRequest carried only ModelId, so the invoker could not tell an agent from a model, or azure-openai from anthropic.

Two entry types, one chain, never mixed. ChainEntry is an abstract base holding Provider and Currency; ModelEntry keeps every member it had, and AgentEntry names a registry resource (ResourceName, ResourceVersion) with a fixed CostPerInvocation. A nullable-fields ModelEntry was rejected (the consumer's choice, 2026-09-13): it would type an agent as a model with holes, and every reader would have to guess which holes are allowed. A chain is all-model or all-agent — a fallback from a model to a remote agent, or back, would change the kind of thing that produced a section mid-outage, which ADR-M2's "the audit pins the exact model used" does not tolerate.

An agent's cost is per invocation, and positive. A remote agent reports no tokens the platform can price, so the estimate is CostPerInvocation, and the entry grants no output-token budget and contributes no context window. Zero is refused: EstimateCost would admit it under every ceiling, making budget enforcement silently blind for exactly the calls that cost real money elsewhere.

The guard splits by who can see what. The platform checks shape — a mixed chain, or an agent entry without its provider, resource or a positive cost, is a permanent ContractViolationException — both when a mapping document is read and when a mapping is resolved. That covers a mapping edited outside any publish path. Whether the named resource is active is the consumer's check, because only the consumer can see its registry: it refuses a publish against an inactive resource and fails the call permanently if the resource has been retired since. The plan had put both rules in mapping approval; MappingGovernanceService's propose and approve are still NotSupported stubs, so there was nowhere to put them, and a platform port onto the consumer's registry was rejected as a dependency the resolver would take on every call.

The stored document is additive; an absent target is the migration. One wire record, ChainEntryDocument (was ModelEntryDocument), carries both kinds. target (property order 9) is written only for an agent; the model fields became nullable on the wire but a model entry writes them all and never writes target, so its bytes are unchanged — pinned by a test that serializes a Phase-1 entry against its pre-change bytes. Reading treats an absent target as a model, which is the adapter for every mapping stored before this ADR. An unknown target, or a missing field for the target named, is a permanent violation naming the field.

The invoker receives the resolved entry. AgentInvocationRequest.Target (required) is the ChainEntry itself, so a consumer invoker routes on provider, reads an azure-openai model's new optional Endpoint/Deployment, or finds the agent's registry resource. ModelId stays and carries the target's identifier (ChainEntry.TargetId: the model id, or the agent's resource name), which is also what the circuit breaker keys on.

Attribution rides the existing summary. ResolvedModelSummary gains resource_name, resource_version and card_hash at orders 6–8, optional and omit-null, so every existing audit and telemetry golden is byte-identical. This is E6's Article 12 requirement — which resource produced this output — on the AgentInvocation/StepCompletion path that already carries ADR-E8's directing-human chain. The card hash is the pinned snapshot's, never a live fetch, and only the invoker knows it, so it returns on AgentInvocationOutcome.CardHash and is ignored for a model target.

azure-openai gets the OpenAI caching strategy. Without a registration it fell to NoCachingStrategy: calls worked, and OpenAI-family models cache matching prefixes server-side regardless, but the prompt layout and cache-hit metrics were lost. It now resolves OpenAiCachingStrategy, beside the existing openai registration (the consumer's call, 2026-09-13).

Evidence (accessed 2026-09-13): frontier-workflow's S13.81 spike against a live Foundry agent — the agent is addressed by a registry resource with a pinned card, answers with an AgentTask rather than a token-metered response, and so has no per-token price to estimate from; Microsoft Learn, Azure AI Foundry incoming A2A — agents are called over A2A with Entra auth, separately from model deployments; PLATFORM-EVOLUTION-CANDIDATES E4 and E6 (role-based reach, and the Article 12 attribution requirement); the code audit for this change — the single AgentInvocationRequest construction site (AgentTaskActivityPipeline) set only ModelId, and CachingStrategyRegistry registered no azure-openai provider.

Addendum (v0.30.0, frontier-workflow S13.88) — the remote task id rides too. The consumer's A2A invoker found on execution (its S13.85) that the outcome had no slot for the agent's own task id, so an audit record could name the resource and the pinned card but not which run on the agent's side produced the section — the join key an operator needs when reading both sides. AgentInvocationOutcome.RemoteTaskId and AgentInvocationResult.RemoteTaskId (optional, bridged by the dispatcher like the card hash) and ResolvedModelSummary.remote_task_id (order 9, omit-null, ignored for a model target) close it. Additive; every existing golden is byte-identical. Release: minor, v0.30.0.

Release: minor, v0.29.0 proposed — source-breaking. RoleMapping.Chain and ResolvedModel.Entry change type to ChainEntry, ModelEntry's Provider and Currency move to the base, and AgentInvocationRequest.Target is required. No stored bytes change and nothing is renamed on the wire. The only consumer is frontier-workflow, which moves in lockstep: its model-role display and test-run cost reader branch on the entry kind, and its invoker sets nothing new on the outcome until an agent path exists.

ADR-PA28 — a remote agent's tool use is recorded as self-reported, never as observed

frontier-workflow's S13.89 closes the governance gap decision 2A left open: a remote A2A agent's tools run on its side, so the platform never sees them, and the audit could only mark them not visible. The fleet convention that closes it asks each agent to say which tools it used — and the audit has to carry that answer without letting a claim pass for evidence.

The convention can only live in the reply payload. Microsoft Learn, "Enable incoming A2A on a Foundry agent" (accessed 2026-09-14): incoming A2A is text-only, the reply is the artifact text the agent writes, and Foundry's A2A guidance describes an opacity contract — the caller never sees the server agent's prompt, model or tools. Nothing in the A2A response surfaces tool calls and a prompt agent controls only its text, so a tools_used list can ride nowhere but inside the reply the agent composes. That is exactly why the audit must say where the fact came from: a list the agent wrote is the agent's word, and K6 says a claim is never rendered as observed evidence.

ToolCall says how the platform knows. ToolCallProvenance is a smart enum, observed for a call the platform made itself (the MCP path, S9.25) and self_reported for one lifted from a reply. ToolCall.provenance (order 3) and note (order 4) are optional and omit-null. The platform's own writers never set either, so every existing audit and telemetry golden is byte-identical, and a reader treats an absent provenance as observed — the adapter for every record written before this field. note carries the agent's stated purpose for a self-reported call, capped at 200 characters (ADR-E1 tonnage — an auditor needs the why, not the arguments); AuditRecord.Validate and SignedAuditRecord.Validate refuse a longer one as a contract violation. Lifting tools_used out of the reply before contract binding, dropping malformed claims, and labelling self-reported calls in the UI are the consumer's (S13.89b–c).

Evidence (accessed 2026-09-14): Microsoft Learn, "Enable incoming A2A on a Foundry agent" — text-only incoming A2A, the reply is the agent's artifact text, and the opacity contract over prompt, model and tools; frontier-workflow's S13.81/S13.88 spikes against a live Foundry agent; the platform-keeps register, K6.

Release: minor, v0.31.0 — additive. Two optional properties and one smart enum; no stored bytes change, nothing is renamed on the wire, and every golden is unchanged.

ADR-PA29 — an execution pins the model-role mapping version it was served, at its own start

frontier-workflow's S13.102 found that doc 08 §5's pin was specified but never built: AgentTaskActivityPipeline.BuildResolutionRequest set MappingVersion = null, so every agent invocation resolved the current pointer. A rollback or an approval therefore changed a running execution between nodes. That contradicts doc 08 §2 principle 6, ADR-M1's execution-pinned versions, and ADR-M3's promise that a rollback reaches new executions while in-flight executions stay pinned.

Placement and the compatibility gate. Doc 08 §5 puts the pin in PinMappingsActivity, called by the orchestrator at execution start. Doc 12 §5 sketched it factory-side; this ADR follows doc 08, and the consumer amends doc 12 §5. The activity is GraphOrchestrator's first action, and it is scheduled only when the new optional input member GraphOrchestratorInput.pin_model_roles (order 7) is true. The gate is required, not cautious. DurableTask.Core checks activity names against recorded history on replay, so an unconditional pin at sequence 0 would fail every in-flight run. An input recorded without the flag replays exactly as before: no pin, and resolution against the current mapping. The pin uses the snapshot-persistence retry profile.

The pin records the version actually served. ModelRolePin { role_id, mapping_version, ring } is decided once, by IMappingPinner. That covers canary assignment (a hash of the engagement id against CanaryPercent) and the shadow or unassigned-canary fallback to PredecessorFleetVersion. ModelResolver shares the ring rules through one internal ServedMappingSelector, so the two cannot drift. A ResolutionRequest carrying the optional Pin reads exactly that version and walks its fallback chain. It never re-evaluates rings, because re-evaluating would re-ask a question the pin already answered. Doc 08 §5's continuity exception still holds: a fallback within the pinned version may serve, recorded as ChainPosition > 0, under the same mapping_version. The per-invocation mapping_version in the signed audit therefore equals the pinned version, and the record's shape is unchanged. IModelResolver and IRoleRegistry gain no members, because consumers' test doubles implement them. IMappingPinner is new, and AddFrontierModelRoleConfig registers it.

Roles and results. The roles are collected purely from the inline definition (hard invariant 2): every AgentTaskNode's role, deduplicated and ordinally sorted. Nodes are a flat list, and parallel and loop nodes reference other nodes by id and contain none, so nothing is nested. The activity returns a list ordered by role id, not a dictionary, so its recorded bytes are canonical. The orchestrator keeps the pins in execution state, and each AgentTaskActivityInput carries its node's entry in the optional pinned_mapping (order 14). A null entry means the old behaviour.

An unmapped role fails the start. The pinner turns a missing mapping into a ContractViolationException naming the role. That is a permanent failure, never retried (invariant 7), and it happens before any agent runs. Failing a run at its first node is better than failing it half-written.

Dispatcher. The router pins nothing. BuildChildInput and BuildNextGenerationInput carry pin_model_roles forward, and each child pins at its own start. A long-lived dispatcher therefore gives every ticket the mapping current when that ticket began, which matches its per-child definition and epoch pins. Sandbox runs pin the same way.

Shadow-ready. S13.101 sequences shadow execution after the cloud proof. A shadow candidate will be pinned alongside the served version as optional candidate_version and candidate_ring members on ModelRolePin, which is additive and needs no rework.

Residual skew — accepted and recorded under ADR-E15. A Host on the new package could schedule a flagged run onto a worker still running an old package. That worker ignores the unknown member, so the run executes unpinned and resolves current, as every run did before this ADR. Nothing fails and nothing misreplays, because the old worker's history never holds a pin action. The run simply lacks the guarantee. Deploying workers before or with the Host closes the window.

Evidence: frontier-workflow doc 08 §2 (principle 6), §5 (resolution flow and PinMappingsActivity), §7–§8 (rollback reaches new executions only), §11 ADR-M1; ADR-M3; DurableTask.Core 3.8.0's replay check on scheduled activity names (the S13.102 design check, 2026-09-15). A live emulator replay has not yet verified this; the consumer's emulator test does that.

Release: minor, v0.32.0 — additive. New optional members GraphOrchestratorInput.pin_model_roles, AgentTaskActivityInput.pinned_mapping and ResolutionRequest.Pin; new types ModelRolePin, IMappingPinner, PinMappingsRequest and PinMappingsActivity; and the constant WorkflowActivityNames.PinMappingsActivity. Null members are omitted, so every recorded input keeps its bytes.

ADR-PA30 — governance changes get their own signed chain, and the ADR-E2 envelope moves down to carry it

frontier-workflow's S13.103 found that doc 05's signed record covers executions only. An approver role created, edited or retired (S13.100), or a model-role mapping approved or rolled back (S13.101), left no evidential trail; the consumer's IGovernanceAuditWriter seam was a no-op. That is a K6 gap against ADR-E8's attribution rule and EU AI Act Art. 12's record-keeping obligation. Doc 15 §3 already promises that "each change passes through the consumer's governance audit seam; the signed governance audit record lands with S13.103". This ADR builds the platform half. Mark's decisions, 2026-09-15.

The record. SignedGovernanceAuditRecord (schema 1.0, every property ordered, snake_case, omit-null): schema_version, record_id, scope, sequence, event_type, subject_type, subject_id, subject_version?, actor, actor_upn?, reason, occurred_at_utc, correlation_id?, engagement_id?, change (an ADR-E2 TypedPayload), before_hash?, after_hash?, compensates_record_id?, then previous_record_hash, record_hash, signature, signing_key_id. Callers submit a GovernanceAuditEntry, which carries the same caller fields. subject_version is a string, so a role version, a mapping version and a content hash all fit without the platform choosing.

Vocabulary neutrality. event_type and subject_type are validated snake_case strings, not platform enums. The consumer owns the catalogue (ADR-E2, ADR-E3a). Validation is structural only: snake_case types and scope, non-empty subject_id and reason, and ADR-E8's actor rule. The actor is required, is never unknown in any case or padding, and a system: actor must name its origin. Every violation is a ContractViolationException, which is permanent and never retried.

Hashing. record_id = SHA-256("governance-entry:" ‖ JCS(canonical entry)), so an identical retry derives the same id. record_hash = SHA-256(JCS(canonical record with record_hash and signature empty)), and signature = HMAC-SHA256(record_hash, key) (RFC 2104). The canonical profile fixes the typed shell. RFC 8785 JCS over the whole document fixes the untyped change content that rides inside it, as ADR-E2 decision 2 requires. Unlike the execution chain, signing_key_id is inside the hash, so swapping it to another valid version is a signature mismatch rather than a silent re-attribution. JCS numbers are IEEE-754 doubles, so a payload number beyond double precision is hashed at double precision. Callers who need exact values carry them as strings, as the canonical profile already does for decimals.

Chain scope and head allocation. There is one chain per scope, and phase 1 has one scope, deployment. The chain is ordered by sequence, never by timestamp. Genesis is SHA-256("governance:" + scope); the execution genesis hashes the bare engagement id. The two can only coincide if an engagement id is literally governance:<scope>, which composite engagement ids ({a}::{b}::{c}, doc 16 ADR-E2) do not produce. The head document chain-head:{scope} holds {sequence, record_hash}. An append reads the head and its ETag, allocates sequence + 1, signs, and then runs one transactional batch on the scope's partition. The batch creates {scope}:{sequence:D12}, creates a record-id:{recordId} marker, and creates the head (genesis) or replaces it with If-Match. The zero-padded id makes id order equal sequence order, and verification reads in that order. The marker makes idempotency hold under concurrency. Two identical appends that both miss the existence check cannot both land, because the second marker create conflicts; its retry then finds the stored record and returns it.

The retry is optimistic-concurrency re-hashing, not transient-fault handling. A 412 (the head moved) or a 409 (sequence, head or marker already exists) means another writer won; the append re-reads, re-hashes and re-signs. The policy is data. GovernanceAuditOptions (section GovernanceAudit) holds AppendMaxAttempts 8, AppendBaseDelayMs 25 and AppendMaxDelayMs 1000, validated at start, with exponential backoff capped and jittered into its upper half. It is owned by Audit, not taken from the Resilience catalogue, because ADR-PA5 keeps governance libraries referencing only Abstractions and Serialization among platform packages. Throttling and unavailability are left to the Cosmos SDK's own retries (doc 10 §4's storage profile posture). A batch failing with any other status throws GovernanceAuditAppendException, as does exhausting the attempts.

Storage and partition key. The container is governance-audit-records, partition key /scope, defaultTtl: -1; it is added to CosmosTopologyCheck. Invariant 4 does not apply, because this is not an engagement-hot container. Most governance changes (a deployment's role catalogue, its model mappings) belong to no engagement, and a transactional batch and an If-Match-guarded head require every write of one chain to share one logical partition. A partition per scope is the only key that gives a single serialisable chain. At phase-1 governance write rates, one partition is far inside Cosmos's per-partition limits. Signed records are archived to Blob governance-audit-records-archive by the existing change-feed pattern, under their own processor and lease prefix archival-governance-audit-records. Heads and markers are mutable bookkeeping and are not archived.

Key purpose. A new SigningKeyPurpose (execution_audit, governance_audit) and ISigningKeyRing.GetProvider(purpose) are added. The registered SharedSigningKeyRing returns the one IKeyProvider for every purpose, so governance records reuse the versioned audit key and record signing_key_id. A separate governance key later is a new ring registration; no existing signature changes. The execution signer still takes IKeyProvider directly.

Fail closed, and compensation. AppendAsync returns the stored, signed record or throws. The consumer turns GovernanceAuditAppendException into a 503 and does not perform the mutation. When the mutation fails after its audit landed, the consumer appends a compensating entry whose compensates_record_id names the earlier record. I chose a typed field over an event_type naming convention. The contract validates it (it must be non-empty, and the service refuses it with a ContractViolationException unless the named record exists in the scope), it is covered by the hash, and it keeps the event vocabulary wholly consumer-owned. Nothing stored is ever altered.

Verification. The pure GovernanceAuditChainVerifier.Verify(scope, records, head, keys) backs IGovernanceAuditService.VerifyAsync and works equally over an archive copy. It never throws for a broken chain. It lists every break with its 1-based stored position, record id, recorded sequence and kind: signature_mismatch (content or hash altered), sequence_gap (a record missing before it), out_of_order (reordered or duplicated), hash_link_break, unresolved_key, scope_mismatch, or head_mismatch (a forged or stale head, or records without a head). As in ADR-PA22, each record's own key version is resolved, one provider call per distinct id, and an unresolvable version fails closed. Here that means valid: false, with the id also listed in unresolved_key_ids.

The envelope moves to Serialization. TypedPayload and PayloadRef lived in Frontier.Platform.Workflow.Model, which is engine tier, so Audit could not carry them without breaking ADR-PA5. Both are now compiled into Frontier.Platform.Serialization, which both tiers may reference. They keep the namespace Frontier.Platform.Workflow.Model and are [TypeForwardedTo] from the Model assembly. A type forward requires the full type name to be unchanged, and keeping it means: binary compatibility, because an assembly compiled against Model still resolves the types through the forwards; source compatibility, because using Frontier.Platform.Workflow.Model; still finds them and Model now references Serialization, so every Model consumer receives the assembly transitively; and wire compatibility, because no bytes, goldens or schema versions change. The PublicAPI entries moved from Model's Unshipped file to Serialization's. Model lists the forwarded members with the analyzer's (forwarded, contained in Frontier.Platform.Serialization) suffix. Model's single-dependency comment was updated. No architecture test changed: Audit references only Abstractions and Serialization. ADR-E2 deferral (b) is resolved: JsonCanonicalizer (RFC 8785) lives in Serialization, and governance audit signing is its first in-repo consumer. It writes JSON text directly and constructs no JsonSerializerOptions, so K10's one-profile rule holds. It is tested against the RFC's §3.2.2 and §3.2.3 samples and Appendix B number vectors.

Out of scope. (1) The execution chain is untouched. AuditSigner's read-then-create can fork under concurrent closes on one engagement; that is S13.106, which will adopt this ADR's head-document pattern and decide the treatment of already-stored chains. (2) A Key Vault IKeyProvider is S13.107: AddFrontierAudit still registers only DevKeyProvider, so until then governance records, like execution records, are signed with the development key. (3) Multiple scopes and a separate governance key are enabled but not configured.

Evidence (accessed 2026-09-15): RFC 8785, JSON Canonicalization Scheme (rfc-editor.org, Informational, 2020): property names sorted as UTF-16 code units, numbers per ECMA-262 §7.1.12.1, Appendix B vectors. RFC 2104, HMAC (1997), as already cited by ADR-PA22. NIST SP 800-57 Part 1 Rev. 5, Recommendation for Key Management: Part 1 – General (May 2020): originator-usage versus recipient-usage periods, the basis for verifying old records under retired versions (as ADR-PA22). EU AI Act Article 12(1)–(2) (artificialintelligenceact.eu): automatic recording of events over the system's lifetime, including events relevant to substantial modification. Microsoft Learn, Transactional batch operations in Azure Cosmos DB (updated 2026-04-27): operations sharing a partition key succeed or fail together; a failed operation carries its own status (409 for an existing item) and the rest 424; limits of 100 operations, 2 MB and 5 s. Microsoft Learn, Database transactions and optimistic concurrency control (updated 2026-04-27): _etag with if-match, rejected with HTTP 412 when stale.

Release: minor, additive. New public types in Audit (GovernanceAuditEntry, SignedGovernanceAuditRecord, IGovernanceAuditService, GovernanceAuditQuery, GovernanceAuditPage, GovernanceAuditChainVerifier, GovernanceAuditVerificationResult, GovernanceAuditChainBreak, GovernanceAuditBreakKind, GovernanceAuditChainHead, GovernanceAuditScopes, GovernanceAuditOptions, GovernanceAuditAppendException, SigningKeyPurpose, ISigningKeyRing) and in Serialization (JsonCanonicalizer, plus the moved envelope). AddFrontierAudit gains registrations, a hosted service and a topology row. The topology row means a consumer must create governance-audit-records before upgrading, or the boot check fails. Tracked as S13.103.

ADR-PA30 — amended 2026-10-24: node input and output hashes are taken over the JCS form

Found by the consumer's S13.112 groundwork and fixed as its S13.113. ADR-E2 decision 2 requires the RFC 8785 (JCS) form wherever JSON whose shape is not CLR-declared takes part in a hash, and this ADR built the canonicaliser, but governance signing was its only caller. Three execution hashes took SHA-256 straight over serializer output: OutputPayloadBuilder.Build (the agent step's output_hash, which also becomes the artifact version's content_hash and the audit record's output_hash), McpToolInvocationPipeline.RunAsync (CanonicalProfile.Hash(payload), which hashed the payload as a JSON string literal, quotes and escapes included), and AgentTaskActivityPipeline.ComputeInputHash (the audit input_hash, over raw UTF-8 of an input that is often an upstream MCP reply). [JsonPropertyOrder] fixes a typed contract's own members, so today's typed outputs were stable — but a JsonElement inside one (a TypedPayload's payload or facts), an MCP tool's reply, and S13.114's untyped schema-ref outputs all keep their producer's key order, so two identical replies hashed differently.

The fix. JsonCanonicalizer.Hash(ReadOnlySpan<byte>) returns the upper-case hex SHA-256 of the JCS bytes — the same format as CanonicalProfile.Hash — and all three sites call it. One public helper rather than three private copies, because ADR-E2 makes the rule normative for capabilities too and the smell this ADR's guard watches for is hashing code that serializes on its own.

The payload is not canonicalised; only the hash is. output_payload and the artifact content stay the canonical profile's bytes (for MCP, the tool's own order). Changing them would change stored bytes, and whether stored payloads are canonicalised is an open question the consumer's S13.116 decides. Hashing the JCS form of an unchanged payload is sound either way: anyone holding the payload can recompute the hash, because JCS is a pure function of it.

Compatibility: every newly computed input and output hash changes, and nothing stored changes. JCS sorts members by code unit rather than by [JsonPropertyOrder], writes non-ASCII raw where the profile's encoder escapes it, and rewrites numbers, so the new hash differs from the old one even for a typed contract. A hash-stable variant (JCS only when a payload carries untyped content) was rejected: it needs a type-graph walk to decide, gives one field two meanings, and is exactly the kind of conditional that drifts. What the change does and does not touch:

  • Stored hashes are never recomputed. No code in this repo or the consumer derives an output or input hash from a stored payload and compares it with a stored hash (checked 2026-10-24); the only hash-equality checks are the audit and governance chain verifiers, which recompute record_hash from stored fields with output_hash as an opaque string, and the definition store, whose hash is untouched. Every existing signed audit record therefore still verifies.
  • Replay is unaffected. All three hashes are computed in activities, whose results DTF history records, so a replayed run reads the old hash rather than recomputing it (invariant 2).
  • The cut-over is versioned by the build that computed it. An in-flight run that crosses an upgrade has steps hashed both ways. ADR-E15 decision 3 already stamps the host build on every step (StepCompletion.host_build), an audit invocation joins its step by correlation_id, and the platform version is resolvable from the build, so which algorithm produced a given hash is a lookup: releases before the one carrying this amendment hashed serializer bytes, it and later ones hash JCS bytes. No hash_algorithm field was added; that would be a schema change across StepCompletion and both audit families to label something the pin set already answers.
  • A hash comparison across the boundary is meaningless, so identical content written before and after the upgrade gets different content_hash values on its two artifact versions. Nothing compares them today; anything that later wants content identity across versions must compare hashes from one side of the boundary.

The format and length of every hash are unchanged, so no validator, column or consumer parser moves. JCS reads numbers as IEEE-754 doubles (above), so an untyped number beyond double precision is hashed at double precision, and one beyond double range makes the hash throw — that is, the activity fails — rather than hash something false. Out of scope: the definition hash (typed, stored, pinned and used for idempotent publish, so changing it would invalidate every pin) and the context assembly hashes (they hash text, not JSON structure).

Release: minor, v0.39.0 proposed — one additive public member in Serialization (JsonCanonicalizer.Hash); a behaviour change in Orchestration's computed hashes, flagged here as ADR-E15 decision 1 requires.

ADR-PA31 — the execution audit chain is appended under a head-document guard, and a pre-fix fork says so

frontier-workflow's S13.106. AuditSigner.SignAsync read the engagement's chain, took the last record's record_hash, signed, and created {executionId}:audit with no concurrency guard, while CosmosAuditRecordStore ordered the chain by closed_at_utc. K9 permits one live execution per engagement-workflow, so one engagement can run several workflows at once. Two of them closing in the same moment both read the same chain tail and both chained from it: two records, one previous_record_hash, a forked chain. Verification then walked the chain linearly, found the second record's predecessor hash not matching its neighbour's, and reported a broken link — the signal this package reserves for altered evidence. A concurrency defect was therefore indistinguishable from tampering, which is a K6 failure: the HMAC chain is only evidence if its findings mean what they say. Found by the S13.103 design check, 2026-09-15; Mark's decisions, 2026-09-16.

The record shape does not change. No new member on SignedAuditRecord, no schema version bump, no golden-file change. This is the binding constraint and everything else is built around it: every record already stored must keep verifying byte-for-byte, and verification recomputes canonical bytes rather than hashing the stored ones (ADR-PA4), so any addition to the signed shape would invalidate every record written before it. The guard therefore lives entirely in documents beside the record and in properties on the document wrapper, which is outside the signed record object.

Head-document allocation, as ADR-PA30 does it. Each engagement gets one head document, chain-head:{engagementId}, in the same audit-records container and the same /engagement_id partition as its records — a transactional batch requires both. It holds sequence, record_hash, last_execution_id and unguarded_record_count. An append reads the head and its ETag, chains and signs against record_hash, and then runs one transactional batch on the engagement's partition: create {executionId}:audit, and create the head (first ever) or If-Match-replace it. A 412 (the head moved) or 409 (the head or record document already exists) means another close won; the append re-reads, re-hashes and re-signs. Nothing is ever written twice and no record is ever signed twice for the same chain position.

Reads still order by closed_at_utc. The chain's read order is unchanged, so no query, index or consumer expectation moves. sequence on the head is allocation bookkeeping, not the read key — the opposite of the governance chain, which is ordered by sequence precisely because it had no timestamp it could trust. Two document kinds now share the container, so every reader filters on doc_type: the chain query, the AuditQueryBuilder projection (a head has no record property and would otherwise project a row of nulls per engagement), and the archival change feed, which never archives a head — a head legitimately changes, and an immutable archive is for things that do not. Records written before this ADR carry no doc_type at all, so the predicate must treat its absence as "record"; omitting that would hide every pre-upgrade record from its own chain.

The retry is data. ExecutionAuditOptions (section ExecutionAudit) holds AppendMaxAttempts 8, AppendBaseDelayMs 25 and AppendMaxDelayMs 1000, validated at start, exponential and jittered into the delay's upper half so contending closes spread out — the GovernanceAuditOptions precedent in this package, sharing one backoff curve. Exhausting the attempts throws AuditChainAppendException and the record is not stored: fail closed, never a silent gap.

Migration: the first append after the upgrade creates the head from the existing tail. Every engagement in an upgraded deployment has records and no head. The append reads the head, finds none, falls back to GetChainAsync, chains from the stored tail's record_hash (or genesis for an empty chain), and the batch creates the head rather than replacing it. If a concurrent close created the head first, the create returns 409, and the retry now finds a head and takes the normal path. So migration is self-healing, needs no backfill job and rewrites nothing — which matters because batch-rewriting stored audit documents is itself forbidden. The head it creates records unguarded_record_count = the number of records that already existed, frozen at creation and carried forward unchanged by every later append. Note honestly that for a migrated engagement sequence counts stored records, not distinct chain links: if that chain already contains a fork it holds more records than links, so the sequence is a position, not a proof of length.

A pre-fix fork is reported as legacy_fork, never as tampering. VerificationResult gains an optional forks list (AuditChainFork: the shared predecessor hash, the execution ids claiming it, and an AuditChainForkKind of legacy_fork or guarded_fork). A fork is not a signature mismatch and must never be presented as one — each forked record verifies perfectly against its own key, because nothing about it was altered. signature_valid is therefore unaffected by a fork, and a tampered record inside a forked chain still fails its own signature, as its own test pins. A fork does make chain_valid false: it is a real discontinuity, and suppressing it would be the dishonest half of this fix. Nothing stored is rewritten and nothing is ever re-signed.

How "predates the fix" is determined, and what that inference cannot do. The signed record carries no "written under the guard" marker and this ADR deliberately declines to add one, so the classification is an inference from the head document. No head at all means nothing in the chain has been appended to since the upgrade, so every record predates the guard and any fork is legacy_fork. Where a head exists, the records that already existed when it was created are the unguarded ones and the head froze that count; a fork lying wholly inside that prefix could not have been created under the guard, and one reaching beyond it could not have been created by this platform at all and is reported guarded_fork. The limits, stated plainly: the head is mutable bookkeeping, not signed evidence, so someone with write access to it could inflate unguarded_record_count and have a genuine fork misclassified as legacy — which is exactly why a fork of either kind still invalidates the chain, and why the kind explains a finding rather than clearing one. The inference is also engagement-wide rather than per-record: it cannot say which of two forked records came first, only that the pair sits in the unguarded prefix. An auditor who needs more than that has the stored records themselves, which are unchanged and independently verifiable.

Evidence. K6 ("HMAC-chained audit for every governance fact") is the position this repairs: the S13.103 design check found the defect while adopting ADR-PA30, and an audit chain whose break reporting cannot separate a concurrency artefact from tampering fails K6's purpose even while satisfying its letter. Doc 05 §5–§6 specify the per-engagement chain, the closed_at_utc read order and the append-only store, none of which this ADR changes. External sources are those ADR-PA30 already relied on and are carried forward rather than re-fetched (last accessed 2026-09-15, as recorded there): Microsoft Learn, Transactional batch operations in Azure Cosmos DB (updated 2026-04-27) — operations sharing a partition key succeed or fail together, a failed operation carries its own status (409 for an existing item) and the rest 424; Microsoft Learn, Database transactions and optimistic concurrency control (updated 2026-04-27) — _etag with if-match, rejected with HTTP 412 when stale, which is the whole basis of the guard. RFC 2104, HMAC (1997) and NIST SP 800-57 Part 1 Rev. 5 (May 2020) continue to govern the signature and key lifecycle unchanged (ADR-PA22); this ADR touches neither.

Verification follows the hash links, not the stored order (Mark's decision, 2026-09-16). Found while building this ADR's concurrency test. Before the guard, the signer chained from the last record in closed_at_utc order, so the hash links always followed the read order by construction. Under the guard it chains from the head, so the links follow the order in which closes won the head race, which is independent of their closed_at_utc. A 12-way concurrent-close test produced a provably intact chain (12 records, 12 distinct predecessors, no fork, every record reachable from genesis) that the old linear walk reported as chain_valid: false — the same false-tamper failure this ADR exists to remove, arriving through a different door.

The rationale for the fix: a hash chain's order is its append order. Every record names its predecessor, and that is the only ordering the chain itself asserts. closed_at_utc is a business field that was merely incidentally aligned with append order while appends were serialised by the absent guard; treating it as the chain's order was always a coincidence rather than a design. AuditChainVerifier therefore walks each record's previous_record_hash from genesis. Reads are unchanged — GetChainAsync and the governance queries still return closed_at_utc order, which is what a human reading an engagement's history wants; only verification changed.

A stored record the links cannot reach is reported in the new VerificationResult.UnreachableRecords — its own finding, distinct from a signature mismatch and from either fork kind, because such a record is typically well signed and the fault lies in what precedes it. Where a fork puts two records on one predecessor the walk takes the first in stored order deterministically, and the arms it does not take surface as unreachable beside the fork that explains them. A crafted cycle ends the walk rather than looping.

broken_link_at keeps its meaning for a genuine link break and is worth stating precisely. It is the first record on the walk whose signature fails against an available key, or failing that the first record the links cannot reach. A record whose previous_record_hash points at nothing still names itself there, exactly as before — every pre-existing broken-link test passes unchanged, which is the evidence that the semantics were narrowed rather than replaced. What changed is only the concurrent case: a chain stored out of timestamp order by the head race now yields null here instead of a false break.

Rejected: (B) keeping the linear walk and accepting false breaks on concurrent closes — that is the defect itself; and (C) giving each record a sequence so the stored order could be sorted into append order — it changes the signed shape, which decision 1 forbids, and would invalidate every record already stored. Doc 05 §5 is amended to match (frontier-workflow).

Release: minor, additive. New public types (ExecutionAuditOptions, AuditChainFork, AuditChainForkKind, AuditChainAppendException) and VerificationResult.Forks. No public member changes shape and IAuditRecordStore is untouched — the head port is internal precisely because that interface is shipped and implemented by consumers, and adding to it would be a source break for every implementor. No container, partition key or topology row is added, so a consumer needs no migration step: the first append per engagement performs it. One behaviour is preserved deliberately: signing an execution whose record already exists still throws InvalidOperationException rather than retrying to exhaustion, so the consolidator's idempotent-retry path (doc 05 §11) is unchanged. Tracked as S13.106.

ADR-PA32 — a mapping change is a proposal with a state machine, and its version is allocated create-only

frontier-workflow's S13.101. MappingGovernanceService.ProposeChangeAsync and ApproveAsync threw NotSupportedException, so the consumer's API answered 500; RollbackAsync rewrote the current pointer with no audit, no existence check and no attribution, and an omitted target wrote a pointer to a nonexistent v0. Doc 08 §7 specifies the governance loop and §8 the rollback contract, but no proposal document had ever been designed. Mark's decisions, 2026-09-15.

Proposals live with the versions they may become. A proposal is stored in model-role-config in the role's own /role_id partition, as {roleId}:proposal:{proposalId} with doc_type mapping_proposal. Co-location is not tidiness: a transactional batch requires one logical partition, and the batch is what makes an approval atomic. The :proposal: infix cannot collide with :v{n} or :current, so all three kinds share the partition unambiguously, and readers that predate this ADR are unaffected because they point-read ids they already know. A proposal is the one mutable document of the three — it carries a state machine, and each decision replaces it under an ETag guard — while the version an approval produces is append-only and never rewritten. The chain is lifted into the document's own proposed_chain (the ChainEntryDocument shape) and the nested copy emptied, so a chain is stored once, in the one shape that can read an abstract ChainEntry back (ADR-PA27), and can never disagree with itself.

Version allocation is the create-only write, not a counter. An approval reads the role's stored versions, takes max + 1, and runs one transactional batch on the role's partition: create {roleId}:v{n}, replace the proposal with If-Match on its ETag, and upsert current. Because the version id is created and never upserted, two approvals that both computed the same n cannot both land — the loser gets 409, re-reads, re-allocates and retries, as ADR-PA30's head allocation does. There is deliberately no separate sequence document: the version documents are the allocation, so there is nothing for a counter to drift from. MappingGovernanceException is thrown when the attempts are exhausted, and a consumer maps it to 503.

The state machine, and the slot that is deliberately empty. MappingProposalState is a smart enum: pending_approval → shadow | approved | rejected | withdrawn; shadow → approved | rejected | withdrawn; approved → promoted | rolled_back; promoted → rolled_back; and rejected, withdrawn, rolled_back are terminal. Shadow execution is deferred (S13.101 sequences it after the cloud proof): nothing in this release duplicates an invocation, charges a shadow budget, or enters the shadow state. The slot ships now so that enabling it later is an additive transition rather than the rename of a shipped wire value. An approval therefore goes straight to the canary ring, and canary→fleet promotion is manual only — no auto-promotion after N clean days is built.

A shadow version never becomes current. The batch repoints current only when the version's ring is not shadow, and RollbackToVersionAsync refuses a shadow target outright. Both matter for the same reason: a shadow mapping was never served, so making it current would put an unevaluated chain in front of every new execution and would fail RoleCatalogueCheck at the next boot, which admits only fleet and canary. The guard is structural rather than advisory.

Promotion appends a version; it does not edit one. This follows from two rules already in force rather than from a new preference: a mapping version is immutable once written (doc 08 §6), and the ring is a property of the version (Mark's call — the ring stays per mapping version, doc 20 amended). Promoting to fleet therefore writes a new version carrying the same chain with ring: fleet, canary_percent: 0 and no predecessor_fleet_version, and repoints current at it. Rewriting the canary document's ring in place would have been the cheaper edit and would have destroyed the record of what was live, in which ring, and when.

PredecessorFleetVersion is stamped at propose time (the S6.6 verdict): the role's fleet version when the proposal was made, which is what an engagement outside the canary keeps being served and what ServedMappingSelector falls back to. ApprovedBy and EffectiveFromUtc are stamped by the service and never taken from the caller, and a proposal's mapping carries version 0 and an empty approver until an approver makes it real. A distinct approver is required under the existing requireDistinctApprover semantics: the principal who proposed a change may never approve it, compared case-insensitively.

Audit goes through a port, because the reference rule is the rule. Every decision — propose, approve, reject, withdraw, promote, rollback — must reach S13.103's signed governance record (K6). ModelRoleConfig is governance-tier, so ADR-PA5 and GovernanceLibrary_OnlyReferencesAbstractionsAndSerializationAmongPlatformLibraries forbid it referencing Frontier.Platform.Audit. Weakening that test to let it call IGovernanceAuditService directly was rejected: the rule is what keeps each governance library independently consumable. The library therefore declares IMappingDecisionRecorder with a vocabulary it owns (MappingGovernanceDecision, MappingGovernanceEventTypes), free of platform audit types, and the consumer adapts it over the IGovernanceAuditWriter it already has on the signed chain (ADR-PA30). There is no default registration, following IReferencedRolesSource: a no-op default would make an unwired consumer a silent audit gap, which is precisely the K6 failure the port exists to close, so an unregistered recorder fails at composition instead. The ordering is ADR-PA30's — the record is appended before the change, and a change that fails afterwards appends a compensating record naming the first.

Propose-time validation. A proposal is refused as a permanent ContractViolationException unless it names a role and a reason, its mapping's role matches the change's, its canary percent is 0–100, and its chain is non-empty and passes ChainShape (all-model or all-agent, ADR-PA27). K7's half that this library can enforce is that every chain entry names a target: an entry whose TargetId is absent or blank is refused at propose time rather than discovered at the first invocation. Stated plainly, because it is a limit rather than a guarantee: the platform holds no model catalogue — Phase1RoleCatalogue enumerates roles, not models — so "resolvable" here means structurally resolvable. Whether a given model id exists at its provider, like whether an agent resource is active, is the consumer's check, for the same ADR-PA2 reason.

The shipped surface. ProposeChangeAsync(change, ct), ApproveAsync(proposalId, approverId, ct) and RollbackAsync(roleId, toVersion, reason, ct) are kept and marked [Obsolete] with migration notes rather than removed, so no consumer's build breaks silently and the PublicAPI entries stay. The first two have thrown NotSupportedException since S4.3 and still do, so nothing regresses. The third did work, and now throws — recorded here as the one deliberate behaviour change on a working shipped member. It cannot be forwarded honestly: it carries no actor, and ADR-E8 forbids inventing one (unknown is the hole doc 15 §5 exists to close), so attributing a human rollback to a system: actor would have been a worse answer than a compile-time obsolete warning plus a runtime message naming RollbackToVersionAsync. Its only caller is the consumer's API, which S13.101's next slice rewrites.

Evidence. K6 ("HMAC-chained audit for every governance fact") and K7 ("governance is data") are the positions this serves; doc 08 §2 principle 3 (a remap is a governed release), §6 (the container and its append-only versions), §7 (the propose → ring → approve loop) and §8/ADR-M3 (the rollback contract) are the specification, with doc 08 §7 amended so proposing requires model-governance and doc 20 amended so the ring is per mapping version. External sources are those ADR-PA30 already relied on and are carried forward rather than re-fetched (last accessed 2026-09-15, as recorded there): Microsoft Learn, Transactional batch operations in Azure Cosmos DB (updated 2026-04-27) — operations sharing a partition key succeed or fail together, and a failed operation carries its own status, 409 for an item that already exists, which is exactly what makes the create-only version id an allocation; Microsoft Learn, Database transactions and optimistic concurrency control (updated 2026-04-27) — _etag with if-match, rejected with HTTP 412 when stale, which is the proposal guard. No live emulator run has yet exercised this; the Integration-category test written alongside it does that, and CI runs it.

Mark's decisions, 2026-09-16, taken after the platform slice reported which questions its build had already settled and which were genuinely open.

One undecided proposal per role. ProposeAsync refuses when the role already holds a proposal awaiting a decision, naming that proposal and its proposer so the caller goes and reviews it. It is a ContractViolationException, which a consumer maps to 409 — the request is not malformed, the role is occupied. This is a governance rule, not a storage constraint: an approver should never have to work out which of several competing proposals wins, and approving two in sequence must not quietly supersede the first rollout before anyone has judged it.

The two state sets are named explicitly in code, never derived from terminality. The slot is held only by a proposal someone still has to decide — pending_approval, and shadow when that stage exists. It is released by approved, promoted, rejected, withdrawn and rolled_back, listed as exactly that set (MappingProposalState.ReleasesRoleProposalSlot, beside IsAwaitingDecision). Expressing the lock as "not terminal" would have been the natural shorthand and is wrong: approved and promoted are non-terminal, because a rollback can still move them, so a role whose mapping had reached fleet could never take another proposal until somebody rolled it back. A test pins that the two sets partition every declared value, so adding a state forces the choice rather than inheriting a default. (Caught by the docs agent while this was being implemented; the platform slice had already read Mark's intent this way, and the explicit naming is what stops the shorthand creeping back in later.)

A deliberate non-rule, recorded so nothing assumes otherwise: a live canary does not block a new proposal. Once a proposal is approved, its canary is serving and the role is free to take the next change request. Whether a role with a canary in flight should refuse further proposals until that canary is promoted or rolled back is a plausible additional rule, and it is Mark's to add later — it is not implied by this one, and no code should be written as though it were. Residual, recorded rather than hidden: the check is check-then-act, not storage-guarded, so two genuinely simultaneous proposes could both pass it. A deterministic pending-marker document would close it, at the cost of a lifecycle that can leak a marker and block a role permanently. At human proposal rates the trade did not look worth it; if proposals ever become machine-driven, revisit.

Canary percent is 1–100. Zero is refused at propose time, naming the field. A mapping approved at 0% reports itself live in the canary ring while ServedMappingSelector sends every engagement to its fleet predecessor — live and serving nobody, with nothing to say so. The path that produced it is mundane: a consumer whose JSON omits canary_percent binds int as 0. A deliberately staged, non-serving version is what the shadow stage is for, which is exactly why that stage exists.

Withdrawal is the proposer's; rejection is someone else's. Only the proposer may withdraw — that is the route for killing your own idea. Rejection now carries the same distinct-approver rule approval always had, because a rejection is a recorded decision on another principal's change. Previously EnsureDistinctApprover guarded approval alone, so a proposer could reject their own proposal and leave a governance record that read as someone else's judgement.

Evaluation evidence stays optional and unvalidated, deliberately. Doc 08 §7 expects shadow evaluation to generate it, and shadow is deferred until after the cloud proof — requiring evidence now would require inventing a source for it. The natural rule to add when shadow lands is that approval requires evidence, and it is recorded here so it is adopted rather than rediscovered.

Retry policy is data. MappingGovernanceOptions (section ModelRoleGovernance) holds DecisionMaxAttempts 8, DecisionBaseDelayMs 25 and DecisionMaxDelayMs 1000, validated at start, with the exponential curve jittered into its upper half. The const this replaced was the divergence; GovernanceAuditOptions (ADR-PA30) and ExecutionAuditOptions (ADR-PA31) are the precedent, and K7 is the reason. The curve is reimplemented locally rather than shared, because ADR-PA5 forbids this library referencing Audit and eight duplicated lines is the cheaper price.

Two robustness findings from the platform slice, both fixed rather than merely recorded. The rollback that marks the owning proposal rolled_back used to scan one page of proposals, capped at 200, so a role with more would have silently left its proposal open after a rollback; it is now a point query on the live version (FindProposalByLiveVersionAsync). And the mapping-version listing identified version documents by the absence of a doc_type, which would have silently returned an empty list — and therefore reallocated from v1 — the day version documents gained one; it now selects positively on the {roleId}:v id prefix, which neither the current pointer nor a proposal matches.

Release: minor — additive. New public types (MappingProposalState, MappingRollbackResult, MappingProposalQuery, MappingProposalPage, IMappingDecisionRecorder, MappingGovernanceDecision, MappingGovernanceEventTypes, MappingGovernanceException, MappingGovernanceOptions), new optional members on MappingChangeProposal, and new members on IMappingGovernanceService. Three existing members become [Obsolete]; none is removed. IRoleRegistry and IModelResolver gain nothing — version listing and allocation went onto a new internal IMappingProposalStore, one step beyond the IMappingPinner precedent, because nothing outside this library needs to implement it and both shipped interfaces are implemented by consumers' test doubles. Consumers must register an IMappingDecisionRecorder: that is the one adoption step this release requires.

Two compatibility notes, recorded rather than left to be discovered. First, MappingChangeProposal gains three required members (RoleId, State, ProposedBy), which is a source break for any code that constructs one — its wire shape and its three shipped members are unchanged, and nothing deserialized breaks, but an object initializer must now supply them. That is accepted rather than softened with defaults: a proposal with no role, no state and no proposer is not a proposal, and the type is now service-constructed on every real path. Second, RollbackAsync throwing is the behaviour change described above. Both are compile-time or immediate failures, never silent.

ADR-PA33 — audit records are signed with ES256 inside Key Vault, and the key id says which algorithm verified them

Status: accepted (Mark's decision, 2026-09-16). Supersedes the signing half of doc 05 §5; leaves ADR-PA22 (key-version resolution) intact in every particular. Tracked as S13.107.

The defect. AddFrontierAudit registered exactly one IKeyProvider — DevKeyProvider, holding the fixed key dev-key/v1 whose material is a UTF-8 string committed to this repository. A deployed platform would therefore have signed every execution and governance audit record with a key known to anyone who can read the source. Such records verify perfectly and prove nothing: the signature attests that someone with the repository wrote them, which is everyone. Found by the S13.103 design check, before any deployed environment existed.

The investigation that changed the answer. Doc 05 §5 specified HMAC-SHA256(RecordHash, key) with the key in Azure Key Vault, the signer holding sign-only access, and "key material never leaves Key Vault — use the Key Vault cryptography client". Read literally, that is not implementable on a standard Key Vault key, and the reason is worth recording because it is not obvious: standard Key Vault vaults hold only RSA and EC keys. Symmetric (oct-HSM) keys with HMAC HS256 sign/verify exist in Managed HSM (GA) and, since recently, in Key Vault Premium — but there they are public preview, "no service-level agreement, and not recommended for production workloads", and the documentation is internally inconsistent about whether sign is even enabled on a vault oct-HSM key. Managed HSM is the only GA way to keep HMAC inside a vault, and it costs $3.20/hour — about $28,000 a year — to protect one signing key. Meanwhile Get never returns symmetric key material at all, so the "HMAC key fetched from Key Vault" reading of the doc necessarily means a Key Vault secret, which is what doc 15 §8 separately specifies (SecretClient) — the two design docs already contradicted each other, and this ADR is where that was resolved rather than inherited.

Decision 1 — signing moves to ECDSA P-256 / SHA-256 (JWA ES256) on a standard Key Vault key. The private key is generated in and never leaves the vault; the signing identity holds sign only, so doc 05 §5's sign-only requirement becomes literally true rather than aspirational — the port this package owns (IKeyVaultSigningClient) has no operation that could return key material.

Decision 2 — verification is local, free, and needs no vault access. A key version's public part is fetched once, cached for the process lifetime (safe because a key version is immutable), and every signature is checked in-process. This is the argument that decided the choice over the alternatives: with HMAC, verifying is only possible for someone holding the secret, so an auditor needs the signing key and a long chain costs a vault round trip per record or a shared secret in memory. With ES256 an auditor needs nothing secret at all, and verifying a 500-record chain costs zero vault calls. The security property improved and the running cost fell at the same time; that rarely happens, and it is why this was worth doing before a deployed environment existed rather than after.

Decision 3 — signing_key_id is the algorithm discriminator, and the signed shape does not change. A record's signing_key_id already names exactly one key version, and a key version has exactly one algorithm, so an algorithm field would have carried no information while changing the canonical bytes of every record ever written. Ids beginning dev-key/ verify by HMAC; Key Vault key identifiers verify by ES256. Consequences: no schema version bump, no migration adapter, no re-signing, and no golden-file change — records written before this ADR verify unaltered, beside ES256 records, in the same chain. The signed payload is also unchanged (UTF8(record_hash) under both algorithms), so the hash chain is algorithm-independent and ADR-PA31's walk is untouched.

Decision 4 — the dev key is refused outside the local-emulator profile. SigningProfileCheck is a boot invariant (doc 12 §6): no AuditSigning:KeyIdentifier plus a non-loopback Cosmos endpoint means the process refuses to start. The discriminator is the configured data-plane endpoint, not ASPNETCORE_ENVIRONMENT — a deployment can set the latter to Development and would then walk straight through the check that exists to stop it. An absent endpoint is deliberately not local, so a misconfiguration fails towards "deployed". SigningKeyCheck was strengthened alongside it: it now signs a probe through the real signing path and verifies the result, so an unreachable vault, a missing key or an unassigned Key Vault Crypto User role fails boot instead of surfacing at the first execution close, when the audit record cannot be written and the evidence is simply lost.

Decision 5 — signing and verification became two capabilities. IKeyProvider keeps answering "what verifies key version X" (ADR-PA22, unchanged, including that an unresolvable version returns null and never falls back to the current key). The new IAuditSigningService performs the signing operation, because under ES256 signing happens where the private key lives and is no longer a calculation this process can do. ISigningKeyRing now hands out both. No credential, key or secret appears in configuration: the vault is reached with DefaultAzureCredential (ADR-SEC3, ADR-SEC5) and configuration holds only a location.

K6 is engaged, not ignored. The keep reads "HMAC-chained audit for every governance fact"; the chain is SHA-256 and is untouched, but the signature algorithm named in K6 changes here. Its evidence is not weakened by the change: RFC 2104 (HMAC) and NIST SP 800-57 Part 1 Rev. 5's separation of originator-usage from recipient-usage periods — the basis of ADR-PA22's "old versions verify forever" — are algorithm-independent lifecycle properties that ES256 satisfies identically. What K6 was protecting is every governance fact carries a verifiable signature bound to a key version, and that is strengthened rather than traded: the signature is now made where the key cannot be exfiltrated and can be checked by someone holding no secret. K6's wording should be updated to "signature-chained audit" at the next register pass.

Rejected. (a) Managed HSM, keeping HMAC and doc 05 §5 literally true — ~$28k/year to protect a single key, and it makes verification more expensive (a vault call per record, or the secret in memory anyway). (b) A Key Vault secret holding the HMAC key, fetched and cached — the fast path, and already half-blessed by doc 15 §8, but it parks a live signing secret in process memory permanently, keeps verification impossible without that secret, and requires striking doc 05 §5's "never leaves Key Vault" sentence rather than satisfying it. (b′) Key Vault Premium oct-HSM with HS256 — literally compliant and nearly free, but public preview with no SLA is not a foundation for the audit keep. (c′) Ed25519, which doc 05 §5's own Phase 2 note anticipates — not available on a standard vault: vaults support P-256/P-256K/P-384/P-521 only, the EdDSA/Ed25519 additions in the SDKs are Managed HSM-only, and az keyvault key create --curve Ed25519 returns "Unsupported curve". ES256 is the substitution, and it delivers the same external-verifiability property Ed25519 was wanted for.

Doc 05 §5 must be amended (frontier-workflow; the exact replacement wording is in the S13.107 hand-off). In short: the Signature bullet becomes ES256 signed inside Key Vault with the signer holding sign-only access and verification performed locally from the public key; the Phase 2 Ed25519 note becomes a note that external verifiability is already delivered and that Ed25519 remains unavailable on standard vaults.

Evidence. Microsoft Learn, About keys and Key types, algorithms, and operations (Key Vault, pages dated 2026-07-07, updated 2026-07-30) — vaults support RSA and EC; oct-HSM symmetric support in Premium is public preview with no SLA; Get returns neither an asymmetric private key nor symmetric key material; EC sign/verify is ES256/ES256K/ES384/ES512 over P-256/P-256K/P-384/P-521. Microsoft Learn, Key types, algorithms, and operations (Managed HSM, dated 2026-05-21, updated 2026-06-12) — oct-HSM with HS256/384/512 is GA there. Azure Retail Prices API, UK South, queried 2026-09-16 — "Key Vault HSM Pool, Standard B1" at $3.20/hour. Azure/azure-cli issue #26898 — Ed25519 unsupported on vaults. RFC 7518 (JWA) for ES256; RFC 2104 (HMAC) and NIST SP 800-57 Part 1 Rev. 5 carried forward unchanged from ADR-PA22. All sources accessed 2026-09-16.

Release: minor, additive. New public types (SigningAlgorithm, AuditSigningOptions, IAuditSigningService, AuditSignature), a new SigningKey.Algorithm property defaulting to hmac_sha256 so the shipped positional constructor keeps its exact meaning, SigningKey.ForEs256, and ISigningKeyRing.GetSigningService (that interface is unshipped, so adding to it breaks nobody). No shipped public member changes shape; no stored record changes; no container or schema version moves. A deployed environment needs a vault, an EC-P256 key, and a Key Vault Crypto User role assignment scoped to that key before it can sign — until AuditSigning:KeyIdentifier is set, a non-local deployment refuses to boot, which is the intended failure.

Verified live, 2026-09-16. This ADR was built and tested entirely against a faked IKeyVaultSigningClient and had never made a real call. It has now been exercised against a real vault (EC P-256, sign/verify, DefaultAzureCredential) by KeyVaultLiveSigningTests — an on-demand gate carrying Integration + RequiresAzureKeyVault, excluded from both CI jobs and skipped with a message when AuditSigning:KeyIdentifier is unset. Passed first attempt, 5/5 in 8.3 s, proving against the live service: an execution audit record signs through KeyVaultAuditSigningService and verifies locally from the cached public key with no vault call (decision 2); the signature carries the full versioned key identifier while configuration stays versionless, verification resolves that exact version, and a version the vault never issued resolves to null rather than falling back to current (decision 5 / ADR-PA22, confirmed against the service's real 404); a legacy dev-key/* HMAC record and a real ES256 record verify side by side in one chain, unaltered and un-re-signed (decision 3); and SigningKeyCheck's boot probe signs and verifies against the vault and passes (decision 4). SigningProfileCheck's refusal of the dev key outside the local profile is asserted in the same suite and needs no vault. Nothing was created or modified in the vault — the only operations are public-key reads and signs. No surprises: the code needed no change to work against real Azure. The one thing the fake could not have told us is now pinned by an assertion — Key Vault returns ES256 signatures as raw r ‖ s (IEEE P1363), not DER, and AuditSignatureVerifier was already right about it.

ADR-PA34 — the mapping governance surface says who changed what, refuses staleness by name, and answers across roles

frontier-workflow's S13.101 API slice stopped: doc 20's model-role endpoints and doc 19's D3 screen specify four things Frontier.Platform.ModelRoleConfig could not express, and Mark's call (2026-09-16) was to fix the platform rather than amend the docs down to what shipped. ADR-PA32 built the proposal store and the governance flow; this extends its surface without changing how a decision is stored, allocated or audited.

1. The proposal carries its concurrency token, and a decision may name the one it expects. MappingChangeProposal gains an optional ConcurrencyToken (concurrency_token), stamped from the stored document's ETag on every read — GetProposalAsync, ListProposalsAsync, and the proposal each decision returns. ApproveAsync, RejectAsync, WithdrawAsync and PromoteAsync take an optional expectedConcurrencyToken; when it is supplied and stale, the decision is refused with MappingConcurrencyConflictException. D3 needs exactly this: doc 19 requires every mutating call to send If-Match from the loaded row and to render a 409 saying "this proposal changed while you were deciding: it is now {state}, decided by {actor}" — which is unimplementable if the caller can never learn the token, and unenforceable if the service ignores it. The token is never stored: it is a property of the document, not of the proposal, so MappingProposalDocument.FromDomain does not write it and stored bytes are unchanged. ADR-E15's floor holds — the member is additive and optional, and proposals recorded before it read back with it null.

Why an optional token and not a required one: a caller with no prior view — a script, a migration, a test — has nothing to be stale about, and forcing it to read-then-decide would add a race rather than remove one. The consumer's HTTP layer makes If-Match required; the platform makes the guard available.

2. Refuse the stale token; keep retrying the allocation race. They are different failures. This is the distinction the code and the types now make explicit, because conflating them is the easy mistake. The allocation retry (ADR-PA32, DecisionMaxAttempts) loses a race for a mapping version: two approvals computed the same n, the create-only {roleId}:v{n} write let exactly one land, and the loser re-reads, re-allocates and tries again — which produces the decision the caller asked for, just at a different version number. Retrying is correct and invisible. A stale token means the proposal itself moved: somebody else approved, rejected or withdrew it. Re-reading and proceeding would take a decision on a proposal the caller has never seen — so the only correct answer is to stop and say who got there first. EnsureExpectedToken therefore runs before the transition and authority checks: a caller reasoning about a state that no longer exists has had every later judgement invalidated too, so the first thing to report is the staleness. Both behaviours are tested: stale-token refusal and fresh-token success on all four decisions, and the allocation race still retrying to success and still exhausting into MappingGovernanceException.

3. The proposals query loses its required role and gains a state set. MappingProposalQuery.RoleId becomes optional and State becomes States, a repeatable set. D3's Proposals tab is a cross-role view — "everything awaiting a decision, across every role" — which no per-role query can answer, and doc 20 documents state as optional and repeatable. There is deliberately no default state filter: D3 defaults its own filter to pending_approval, but a store that silently applied that default would make "show me everything" unexpressible and would hide decided proposals from any caller that forgot the filter. The caller chooses.

The cross-partition cost, recorded honestly. With no role the query fans out across every physical partition of model-role-config and its RU cost grows with the number of partitions, not with the number of rows returned — the cosmos-conventions rule that a cross-partition query in a hot path is a design smell. This one is bounded and deliberate: it is an admin screen behind model-governance, driven by a human, not an execution path. It is bounded three ways — PageSize (default 50, max 200) caps the rows, ContinuationToken does the paging rather than a TOP-less scan, and MaxConcurrency is capped at 4 so one screen cannot fan out across every partition at once. A query that does name a role stays single-partition exactly as before. If proposal volume ever makes this hurt, the fix is a per-state projection document, not a bigger page.

4. Version listing becomes public through a new interface, not a new member on a shipped one. D3 renders each role's append-only history — version, ring, canary percent, chain, change reason, approved by, and which one is current — and doc 20 returns it as version_history. Listing existed only on the internal IMappingProposalStore. It is exposed as a new IMappingVersionHistory returning MappingVersionSummary, rather than as a member on IRoleRegistry. Why: IRoleRegistry and IModelResolver are implemented by consumers' test doubles, so a new member on either breaks every implementor at compile time — the same reasoning that produced IMappingPinner (ADR-PA29), and the precedent this follows. A new interface costs one DI registration and breaks nobody. The implementation reads the role's version documents in one query plus one pointer read, rather than a point-read per version, which would have cost one request per row of a history panel.

5. Typed refusals, so a caller maps a status code by catch rather than by string matching. One ContractViolationException covered unknown role, unknown proposal, illegal transition, distinct-approver, proposer-only, already-pending and invalid input, so the consumer could only tell them apart by parsing message text — and doc 20 needs 400, 403, 404 and 409 to be distinguishable. Each refusal now has its own type under an abstract MappingGovernanceRefusalException: InvalidMappingChangeException (400), UnknownMappingProposalException and UnknownMappingVersionException (404), DistinctApproverRequiredException and ProposerOnlyWithdrawalException (403), IllegalMappingTransitionException, MappingProposalAlreadyPendingException, MappingVersionNotRollbackEligibleException and MappingConcurrencyConflictException (409).

ContractViolationException is unsealed to carry them, and that is the load-bearing decision here. The alternative — a parallel hierarchy beside it — was rejected because it would have been a silent behaviour break rather than a compile-time one: every catch (ContractViolationException) in the consumer's API (four sites) would have stopped catching these refusals, and, worse, the permanent-failure classification would have been lost. FailureClassifier maps ContractViolationException => Permanent by type pattern and DTF's outer retry handler asks TaskFailureDetails.IsCausedBy<ContractViolationException>(); both honour base types, so a derived refusal stays permanent and is never retried (invariant 7), while a sibling type would have become retryable — the platform would have quietly retried a rejected approval. Deriving keeps every existing catch, every classification, and the K4 rule that a contract violation is never retried. Unsealing is source- and binary-compatible and adds no member, so no PublicAPI entry for ContractViolationException changes. The type's doc comment now records why it is open, so "sealed by default" is not re-applied to it by habit.

Residual, recorded rather than hidden: IsCausedBy<T> resolves the failure's ErrorType by name and returns false if the type cannot be loaded, so classification across a process boundary depends on the refusal's assembly being loadable in the worker — which it is, since the Host loads this package. Nothing in this library throws a refusal from inside a DTF activity today; if one ever does, this is the line to re-check.

Partly superseded by ADR-PA48's 2026-11-17 amendment: the outer retry handler no longer calls IsCausedBy<T> (it threw AmbiguousMatchException for HttpRequestException). It now matches the recorded ErrorType by exact full name, which loads nothing and so stays deterministic. A derived refusal crossing an activity boundary is therefore no longer recognised as permanent: an activity must throw ContractViolationException itself. FailureClassifier, which classifies live exceptions, still honours derived types. No derived refusal is thrown from an activity today; this library's refusals reach only the consumer's governance controllers.

A defect fixed in passing, because the change exposed it. MappingProposalQueryBuilder filtered on c.proposal.state and ordered by c.proposal.proposed_at_utc. Proposal documents are flat — state and proposed_at_utc sit at the root, as FindUndecidedProposalAsync already assumed — so the state filter matched no document and the ordering was arbitrary. It went unnoticed because the only test asserted the query text rather than its behaviour against a document, and no emulator test covered the filter. Both paths are corrected and the tests now assert the shape the documents actually have.

Source breaks — every one, named. (a) ApproveAsync, RejectAsync, WithdrawAsync and PromoteAsync take expectedConcurrencyToken before cancellationToken, so an existing call passing the token positionally does not compile until it passes the token (or names the argument). This is deliberate rather than absorbed into an overload: doc 20 makes If-Match required on all four endpoints, so a second, unguarded overload would institutionalise exactly the call this change exists to prevent, and a break the compiler catches is cheaper than a guard silently not applied. (b) MappingProposalQuery.State is replaced by States, and RoleId is now nullable — a break for object-initialiser callers. (c) The internal IMappingProposalStore now returns the new token from TryReplaceProposalAsync/TryAllocateVersionAsync instead of a bool and gains ListMappingsAsync; internal, so it breaks nobody outside this library. Members (a) and (b) were released in v0.34.0 but the consumer is still on 0.22.2 and its S13.101 slice has not been built against them, so the real adoption cost is zero. Nothing else changes shape; no stored document, container, schema version or wire byte moves.

Explicitly not built: base_version and its approve-time 409 (doc 20's proposal shape). Mark dropped it on 2026-09-16 — the concurrency token covers the same concern more precisely, since it detects that this proposal moved rather than that the role's version pointer moved, and doc 20 is being amended consumer-side.

Evidence. The Cosmos sources are ADR-PA32's, carried forward unchanged rather than re-fetched (last accessed 2026-09-15, as recorded there): Microsoft Learn, Transactional batch operations in Azure Cosmos DB — batch operations share a partition key and each carries its own status, which is what returns the replaced proposal's new ETag from the allocation batch; Database transactions and optimistic concurrency control — _etag with if-match, rejected with HTTP 412, which is the proposal guard the expected token is compared against. For the classification claim the source is the shipped package itself, inspected 2026-09-16: Microsoft.DurableTask.Abstractions 1.24.2's XML documentation for TaskFailureDetails.IsCausedBy<T> states "Base types are supported" and that an unloadable type returns false — which is both why deriving works and the residual recorded above. Cross-partition query cost is the standard Cosmos behaviour documented alongside those pages and is recorded here as a bounded, deliberate admin-path cost rather than as a new claim.

Release: minor — additive, with the four named source breaks above. New public types (IMappingVersionHistory, MappingVersionSummary, MappingGovernanceRefusalException and the nine refusals), a new optional MappingChangeProposal.ConcurrencyToken, a relaxed MappingProposalQuery, and the token parameter on the four decisions. ContractViolationException becomes unsealed. No stored bytes, container, partition key or schema version changes.

ADR-PA35 — a run completes when its last node does; its contractual data changes only through its nodes

Decided 2026-10-25 (Mark), as the consumer's S13.105; the proposal is frontier-workflow docs/state/proposals/S13.105-cascade-wait.md (its option A, with option C dropped).

After its last node every run waited up to five minutes for ArtifactUpdated — the S2.2 PoC placeholder for a cascade re-trigger (doc 03 §5) — and S13.99 (v0.31.1) shortened that to zero for sandbox runs only. Nothing in a deployment raises the event: no endpoint, no node type, only test suites. So every real run idled five minutes for nothing while holding its one-live-run claim (K9), and a second start was refused for those minutes; the consumer's first UI-started genealogy run spent 300 of its 406 seconds there. The path the event drives is also ungoverned: it records neither the edited content nor who edited it, never sends regenerated sections back through a gate (K5), and drops a second update.

Decision. GraphOrchestratorSteps.CascadeWaitWindow is zero for every run. Changes to a run's contractual data happen only through its nodes: a new run with new input, a gate rejection with its declared rollback, or a signal node (the consumer's S13.45). An edit outside the nodes is explicitly not a feature; if a workload ever needs one it reopens through a new decision, with this reasoning on record.

Replay (ADR-E15 floor). The wait is shortened, not removed — exactly S13.99's mechanism. The SDK still records the timer, so an in-flight run whose history holds the five-minute timer replays against the same action shape: DTF checks the action type at that sequence number, never its fire time. An event already buffered before the wait is still consumed, so the dormant path keeps working for the test suites that raise it in advance; the consumer adds an architecture test that nothing outside its tests raises it. Proof standard: S13.99's — the timer-shape tests (RunCascadeWalkAsync_*, CascadeWaitWindow_IsZeroForEveryRun) plus this argument; a true history-replay test belongs with the consumer's S10.7 infrastructure.

Observable behaviour change, recorded per ADR-E15: a run scheduled by older code but executing this code after its last node completes immediately instead of waiting. Removing the internal ArtifactUpdateWaitWindow and the duplicated sandbox prefix changes no public surface.

Release: minor, v0.40.0 proposed.

ADR-PA36 — governance and config data stay on Cosmos; the governance chain's one partition is a known limit

Decided 2026-10-26 (Mark), as the consumer's S13.56; the assessment is frontier-workflow docs/state/research/S13.56-persistence-fit.md (its recommendation A). This is the short paired note that assessment called for.

Decision. The governance and config class stays on Cosmos under this repo's conventions. The class covers role assignments, roles, security config, model-role config, engagement-type configs and the resource registry. Under the Phase 1 serverless model there is no per-container throughput floor, and the class is small and slow-changing. A second engine would be one more server per tenant deployment. It would not make the K6 write atomic either, since the governance chain stays a Cosmos container. Every store in the class already sits behind a consumer-owned port, so a future engine is a set of adapters. The consumer's reopen triggers are on record there.

The conventions cover it as they stand. Replaces carry If-Match. A version and its :current pointer are one transactional batch with a create-only version, as CosmosMappingProposalStore already does. The consumer fixed its three stores that did not (frontier-workflow S13.56).

Known limit: governance-audit-records has one partition per scope. Every governance record uses the single scope deployment, and the container's TTL is -1. So the whole history lands in one logical partition, which Cosmos caps at 20 GB. At about 2 KB a record (an estimate) that is about 10 million records, so it is not a Phase 1 risk. Hierarchical partition keys alone do not lift it: an append is one transactional batch with the chain head, and a batch needs a single logical partition. Possible levers, none chosen:

  • segment the chain by period, with each segment's head linking to the last record of the previous one;
  • expire hot records once the archival export to governance-audit-records-archive has confirmed them.

Reopen when a deployment's governance partition passes 5 GB, or before a tenant is expected to write more than a million governance records.

No code change. No release.

ADR-PA37 — the dispatcher's rollover threshold is input data

DispatcherOrchestrator called ContinueAsNew after a literal 100 spawns. That number bounds DTF history and costs a generation change each time: too low and an eternal router churns generations, too high and replay cost grows. It is a governance number, and K7 says governance numbers are data (consumer S13.78).

It rides on the input, not in configuration. GraphOrchestratorInput.DispatcherRolloverThreshold (order 8, dispatcher_rollover_threshold) is resolved by the consumer's Host factory from deployment configuration when the dispatcher starts. It is carried across every generation by BuildNextGenerationInput, like RunId. The orchestrator body reads no configuration (hard invariant 2). Children are one-shot runs and never carry it.

It is not part of the definition. It is a deployment-shaped concern, so putting it in the pinned definition would have made it part of definition_hash and of every publish review, for a value no workflow author should own.

Additive and optional (ADR-E15 floor). Absent, it is omitted from the wire, so an input recorded before it keeps its bytes and replays with DefaultContinueAsNewThreshold (100), which is what it ran with. A non-positive value also falls back to the default rather than rolling over on every spawn. Pinned by ContinueAsNew_FiresAtTheInputsThreshold, ContinueAsNew_CarriesTheThreshold_AndChildrenDoNotInheritIt, RolloverThreshold_IsTheDefault_WhenTheInputNamesNoneOrANonPositiveOne and RolloverThreshold_IsOmittedWhenNull_AndLastWhenSet.

ADR-PA38 — contracts as data get their own library, and the checks they pass are fixed here

The consumer's ADR-E27 (S13.116) makes a contract a registry record: a JSON Schema 2020-12 document plus CEL rules, hashed as JCS and immutable once registered. This ADR records where that lives in the platform and the details ADR-E27 left to the build (consumer S13.117, slice 1a; Mark, 2026-10-29).

A thirteenth package, Frontier.Platform.Contracts, in the governance tier. It owns the contract hash (ContractHash), the registration check (IContractRegistrationCheck) and the one validator (IContractValidator). The engine's Orchestration and Compiler will reference it, as they reference Hitl and Resilience. It references only Abstractions and Serialization among platform libraries. The snapshot it produces, ContractSnapshot with ContractRule, lives in Abstractions, so a consumer's POCO-only assembly can carry one. Neither placement inside Orchestration nor inside Serialization was taken: the first would give the interpreter two third-party engines and leave validation without a single owner; the second would break Serialization's references-only-Abstractions rule.

The engines sit behind internal ports. JSON Schema is Corvus.Text.Json.Validator 5.7.9 (TD-18) behind ISchemaEngine, configured with file and HTTP resolution off, format as an annotation and a regex timeout from options. Corvus caches compiled schemas process-wide by URI, so each one is compiled under urn:frontier:contract:{hash} with the cache refreshed; two contracts declaring the same $id stay apart. No Corvus or Celly type is on the public surface.

Corvus's analyzers are removed for every consumer. Corvus.Text.Json ships analyzers (CTJ001) that flag ordinary System.Text.Json code, and ExcludeAssets does not stop them arriving transitively. The package carries a buildTransitive target that removes them after analyzers resolve; the repo's Directory.Build.targets imports the same file for its own projects. The smoke consumer, now isolated from the repo's .targets as it already was from its .props, fails with CTJ001 when the target is removed and passes with it.

Registration, decided here:

  • References stay inside the contract. Any $ref or $dynamicRef not starting with # is refused, whatever the provenance, and such a schema is never compiled. Cross-contract references are not supported in v1; a shared shape is copied under $defs.
  • The schema is validated against the 2020-12 meta-schema before it is compiled. Corvus compiles a malformed keyword ("minimum": "zero") without complaint and ignores it, which would make the constraint silently absent.
  • The content model must be stated (Mark, 2026-10-29). Every object schema must say additionalProperties or unevaluatedProperties; false is the default to aim for, true opts out. Nothing rewrites what the author registered. Branches of allOf, anyOf, oneOf, if, then and else are exempt, since the composing schema states the model.
  • Legibility (ADR-E27 D10) refuses an authored or generated contract and warns on a discovered one. Every example must satisfy the schema; from slice 1b every rule must also pass every example.
  • Compatibility is strict and sound (Mark, 2026-10-29). Within a major, against every earlier minor, a new minor may change only annotations (title, description, examples, $comment, deprecated, readOnly, writeOnly, default, and format and the content* keywords, which are never asserted), remove rules, or reword a rule's message or field path. Anything else is a new major. With closed content models this is what FULL_TRANSITIVE means; it refuses some changes a deeper checker could prove safe, and never accepts an unsafe one.

Validation, decided here: the snapshot's hash is recomputed from its content on every call, and a mismatch is a ContractViolationException (permanent), as is a pinned contract that fails to compile. Payload nesting is bounded at parse (MaxPayloadDepth, default 64). A violation carries the payload location, the failing keyword and the engine's message: Corvus's messages quote the schema, never the instance, and locations are capped at 200 characters, since a location can contain a payload's own property names. At most MaxViolations (default 20) are reported, keeping the deepest failures by evaluation path. A pattern that exceeds RegexMatchTimeoutMilliseconds (default 1,000) refuses the payload; it is the one wall-clock limit, and validation runs inside an activity whose result is recorded, so replay never re-runs it.

CEL rules, decided here (slice 1b): Celly 1.2.0 (TD-17) behind the internal IRuleEngine, with the standard library and no extension libraries.

  • self is typed from the schema (Mark, 2026-10-29). CelSchemaTypes maps an object with properties to a struct named contract.S{n}, an object without to map(string, T), an array to list(T), and anything it cannot type exactly (unions, oneOf, a type list, an anchor $ref) to dyn. The checker therefore refuses a rule naming an undeclared field. Absent fields follow the Kubernetes JSON semantics: has() is false and selecting one is an error.
  • Every JSON number is a double (Mark, 2026-10-29), the CEL spec's JSON mapping. A rule that mixes in an integer literal (self.total + 1) fails the type check at registration.
  • The static ceiling sees sizes. RuleCostHints answers Celly's estimator with maxItems, maxLength and maxProperties, maps each loop variable to the element schema of the range it iterates by reading the syntax tree, and bounds the list a map() or filter() builds by its range. An unbounded estimate is refused, as is one over MaxRuleCost (default 1,000,000, Kubernetes' per-expression limit). Authors bound what their rules iterate.
  • The profile refuses matches() and any timestamp accessor given a time zone. Map ordering needs no check: every map a rule sees is built in ordinal key order.
  • At run time each rule has MaxRuleIterations (default 100,000), a count. False, an error and an exhausted budget are each a violation carrying the rule's own message at its field_path; an evaluation error's text is dropped, since it can quote the payload. Rules run only once the schema passes, so a rule never sees a value of the wrong shape.
  • Conformance evidence is upstream's, checked at each pin (Mark, 2026-10-30; amends the consumer's TD-17, which had the cel-spec suite running in this repo's CI). The suite exists only in the cel-spec and Celly repositories, and no third-party repository code is copied into this one: the only Celly code here is the NuGet package, used under its Apache-2.0 licence. The evidence for the pin is Celly's own CI for the commit its 1.2.0 package was built from (fb0b964; build-test green on Linux, Windows and macOS, 2,456 of 2,456 cel-spec cases, an empty known-failures list). Our own tests run the real package over everything a contract rule can reach. The release routine re-checks the evidence whenever the pin moves. TD-17's trigger to vendor Celly's source if it goes six months without a release we need is unchanged; that would be a decision of its own.
  • Registration runs every schema-valid example through every rule. An example a rule rejects refuses an authored contract and warns on a discovered one. A rule that does not compile refuses any contract.

Pinned by ContractRegistrationCheckTests, ContractCompatibilityTests, ContractLintTests, SchemaReferencesTests, ContractValidatorTests (against the real engine, including a real regex timeout and two contracts with one $id), ContractHashTests and the contract_snapshot.json golden file.

ADR-PA39 — a definition pins its contracts, and a gate's decision is a contract

The consumer's ADR-E27 D13 to D15 put contracts inside the definition, give a gate a typed output and let a data edge project one shape onto another. This ADR records how the platform carries them (consumer S13.117, slice 2a; Mark, 2026-10-30). Slices 2b (the engine) and 2c (the compiler rules) extend it.

The definition embeds what it names. WorkflowDefinition.Contracts holds a ContractSnapshot for every registry ref a node or data edge names: an agent node's input and output, an MCP node's input and output, and a data edge's contract type. A ref is told from a CLR contract name the way data.schema-ref-match already tells them apart, by its /. CLR names are never embedded, and a definition that names no ref leaves the field out. The set is sorted by ref with no repeats, and Validate() refuses one that is not, so the hash cannot depend on the order publish found them in.

Publish and test runs both embed, through IDefinitionContractEmbedder. An engine-owned ref comes from EngineContracts, so a run never depends on the registry holding the engine's own contracts. Every other ref comes from the consumer-owned IContractSnapshotCatalog. A ref that is not registered, is retired, or comes back filed under a different ref stops the publish, and the embedding runs before the proposal is approved, so a failure leaves it in review. A test run embeds too, so it validates against what a published run would.

An MCP node names its contracts on the node (Mark, 2026-10-30). McpToolNode gains optional input_contract_type and output_contract_type, the names an agent node uses, copied from the tool's registry record when the node is designed. The validator then reads every node the same way, and the binding shows on the canvas. Rejected: indexing the embedded set by tool ref, which hides the binding from the author and gives the validator a second lookup path for one node type.

The definition hash moves to JCS (ADR-E27 D15). It is SHA-256 over the RFC 8785 form of the canonical-profile bytes, with definition_hash blank. The profile still writes the typed shell, as the hashing rule requires; JCS fixes the order of what the profile cannot, the embedded schemas. Nothing recomputes a stored hash (publish is the only caller), so versions published before this keep the hash they were recorded with. The test that pinned the old formula now pins the new one.

A projection is data. WorkflowEdge.Projection is a list of ProjectionField: a top-level target field of the consumer's input and exactly one source, an RFC 6901 from pointer into the producer's output ("" is the whole output) or a non-null literal. The consumer receives exactly the projected fields. Only a data edge may carry one, and each target appears once. A list rather than a map keeps the declared order on the wire. Whether the projected shape fits the consumer is the compiler's data.projection-compatible (slice 2c).

frontier/gate-decision/1.0 is a CLR engine type, GateDecision: gate_id, decision (approve, reject, escalate), approver_id, decided_at_utc, and optional notes and rollback_to_node_id. The names follow HitlDecision, which it is built from. Its registry schema is written out in EngineContracts with a description on every property and an example, and tests hold it to the CLR type: the schema passes the registration check as an authored contract, every decision the engine writes validates against it, and its pinned hash equals ContractHash's.

A definition is refused as an agent output contract. CanonicalOutputSchema, which turns a CLR output contract into a provider response format, now refuses WorkflowDefinition as it refuses TypedPayload: embedded schemas and projection literals are free-form JSON with no honest CLR schema, and no agent outputs a definition (the design agent edits one through tool calls). The refused set stays pinned by name.

Everything new is optional, so every older definition serialises to the bytes it had and its golden files are unchanged; no schema version moves. The one break is to two constructors: DefinitionLifecycleService and TestRunService take the embedder, and a consumer must register an IContractSnapshotCatalog.

Found on the way: the design agent's schema describes a list of objects with a coarse token (DecisionNode.Branches already does), so projections reach the designer with no field detail. Designer grounding is the consumer's slice 5.

Pinned by DefinitionContractsTests, DefinitionContractChecksTests, EngineContractsTests, GateDecisionTests, the approve-path and test-run tests, DefinitionValidatorTests, and the workflow_definition_contracts.json and gate_decision.json golden files.

Slice 2b, the agent invoker is transport only (ADR-E27 D7, D8; Mark, 2026-10-30). IAgentInvoker has one non-generic InvokeAsync, which returns the reply text as it arrived in AgentInvocationOutcome.Output. The engine builds the structured-output format and passes it as AgentInvocationRequest.ResponseFormat: CanonicalOutputSchema for a CLR output contract, asked of a model target only, since A2A has no response format. The engine then binds and validates the reply, so a reply that is not JSON, or fails its contract, is a permanent ContractViolationException raised in one place. The reflection over InvokeAsync<TOutput> is gone. Rejected: a second, raw-JSON method for registry contracts beside the generic one, which would leave two transport paths, and validation inside the consumer's invokers, until the last CLR workload contract is re-expressed. This breaks every IAgentInvoker implementation; the consumer's MAF and A2A invokers drop their deserialization and validation when they adopt it.

Slice 2b, registry contracts at agent nodes (ADR-E27 D7, D8, D15). The orchestrator copies the definition's pinned snapshots onto AgentTaskActivityInput.InputContract and OutputContract (optional, so an input recorded before this replays and validates by CLR type). Each snapshot is a few kilobytes of schema, so the copy per call is accepted; fetching from anywhere else would break the pin. The pipeline validates the input before the agent runs, and the dispatcher validates the reply, through IContractValidator. A violation names the contract and carries the validator's bounded messages. A registry reply is stored as received and hashed as JCS. The hash of each registry contract that validated a step rides on the activity result, the StepCompletion and the audit's AgentInvocation (all optional, so every older record keeps its bytes).

A registry schema is lowered to a response format only where every strict mode accepts it. RegistryOutputSchema keeps type, properties, required, additionalProperties, items, enum, const, anyOf, local $ref, $defs, description and title. It drops the annotations and the constraints that only narrow a value (lengths, ranges, pattern, format), because the validator enforces them on the reply. It refuses an object that is open or has an optional property, any other composition or conditional, and any keyword not named here; the call then goes out with no format and the reply is still validated. One rule for every provider, not one per provider, is the conservative reading of D7's projector: it never sends a provider a schema it might reject, at the cost of sending no format for contracts it could have lowered for one of them. Widening it per provider is a later change.

Slice 2b, registry contracts at MCP nodes (ADR-E27 D8, D9). The orchestrator copies the MCP node's pinned snapshots onto McpToolActivityInput as it does for an agent node. The pipeline validates the arguments exactly as the tool receives them, as one JSON object that includes the idempotency_key a write carries, because that object is the call's input; a tool whose contract is closed must declare the key. The result is validated before it is recorded. A sandbox write-fence ack is not the tool's reply, so it is never held to the output contract, and its step records no output contract hash. The MCP step's StepCompletion now names the node's output contract ref instead of an empty string. A node with no refs runs unvalidated, as it did.

Slice 2b, a gate's output and an edge's projection at run time (ADR-E27 D13, D14). When a gate is decided, the orchestrator writes the decision, as frontier/gate-decision/1.0, to the gate's node output, so a data edge from a gate no longer throws. A rejection that loops back overwrites it with the next decision. The bytes come from the recorded decision event, so the write is replay-safe, and a run started before this replays unchanged because no edge could consume a gate's output then. An edge's projection is applied when the next node's input is resolved, for agent and MCP nodes alike, in the orchestrator body (it is pure). It builds an object with exactly the projected fields in declared order. A pointer that finds nothing leaves its target out rather than failing: the consumer's input contract then decides whether the field was optional.

Slice 2c, the compiler rules (ADR-E27 D9, D12, D13, D15). The consumer supplies the data they need through the catalog ports it already implements, so no new port is added: AgentRoleDescriptor gains optional input_contract_ref and output_contract_ref, and DesignerToolDescriptor gains optional contract refs and a ServerDrifted flag, which the design agent never sees. The registry fills them (consumer slices 3 and 4).

  • data.schema-ref-resolves (resourced): every schema ref a node or edge names is registered and not retired, or is engine-owned. It catches at validation what publish's pinning would refuse.
  • data.no-edge-from-gate (pure): D13 has shipped, so the rule keeps its id and now requires a data edge from a gate to carry frontier/gate-decision/1.0.
  • model-role.contracts-match (resourced): a node bound to a role that declares contracts names the same id and major (ADR-E2 D3); a role that declares none leaves the node free.
  • mcp.server-not-drifted (resourced): no node, and no agent's tool list, calls a tool on a server the sweep flagged as drifted.
  • mcp.tool-resolves also holds an mcp_tool node's contract refs to exactly the ones registered for its tool, which is how the node-field binding (Mark, 2026-10-30) stays truthful.

Slice 2c, data.projection-compatible (ADR-E27 D5, D14; resourced). Both ends of a projected edge must be registry contracts (a gate's end is frontier/gate-decision/1.0), since a CLR type has no schema to project from. Each target must be a declared property of the consumer's input. A pointer's value must have exactly that property's shape once annotations are removed: the strict reading of D5, consistent with registration's compatibility check (Mark, 2026-10-29), with no structural subtyping. A literal must satisfy the property's schema, checked by the one validator. Every property the consumer requires must be projected, from a literal or from a value that every valid output has (each step of the pointer a required property; an array index never counts). data.schema-ref-match stops checking the consumer end of a projected edge, whose contract type names the producer's output. The shape questions live in Frontier.Platform.Contracts as ContractShapes, which inlines local references so two contracts laying out $defs differently still compare by what they accept; a reference it cannot inline (recursive, non-local, or with sibling constraints) makes the field uncheckable, which is reported as a misfit.

ADR-PA40 — a role is a governed definition, and an agent-backed role's mapping needs evidence for its contracts

The consumer's ADR-E27 D12 lifts the frozen four-role catalogue (C-3): roles become data, created and changed by a proposal a second principal approves. D16 makes a provider eligible for an agent-backed role only with eval evidence for that exact contract hash. Until now the catalogue was the code constant Phase1RoleCatalogue, RoleDefinition had no backing or contracts, and nothing read EvaluationEvidenceRef. This ADR records how the platform carries D12 and D16 (consumer S13.117, slice 4; Mark, 2026-10-30). It ships in v0.45.0.

Definitions live in ModelRoleConfig, beside the mappings (Mark, 2026-10-30). A role definition is stored in model-role-config under the role's /role_id partition, and is governed by a definition-proposal service that mirrors MappingGovernanceService (ADR-PA32, ADR-PA34). The consumer's resource registry was rejected as the home: its ADR-CD9 lifecycle is admin-gated with no second approver, and a port reading it would make this library's resolver and boot check depend on consumer data. Co-location also keeps one role's definition, mappings and proposals in one logical partition, the scope of a Cosmos transactional batch (Microsoft Learn).

The record's fields. RoleDefinition keeps role_id, description, stakes and requirements, and gains:

  • backing, a RoleBacking smart enum, model or agent;
  • input_contract_ref and output_contract_ref, ADR-E2 schema refs ({namespace}/{name}/{major}.{minor});
  • input_contract_hash and output_contract_hash, stamped by approval, never taken from a caller;
  • definition_version, approved_by and effective_from_utc, stamped by approval.

An agent-backed role must declare both refs. A model-backed role may declare either, both or none (ADR-E27 Q1). requirements describe a model, so they are required for a model-backed role and optional for an agent-backed one. A role carries no instructions_ref; doc 20's proposed shape showed one, and inheritance from a role was never specified. description stays because the designer's catalogue matches node intent against it, and stakes because it drives governance posture.

Backing is declared and immutable. A definition proposal that changes an existing role's backing is refused; moving between model and agent means a new role. A declared backing is what makes "an agent-backed role must declare contracts" checkable when a definition is proposed, and immutability removes the case of a live chain whose kind no longer matches its role. A mapping proposal whose chain kind (ChainShape, ADR-PA27) differs from the role's backing is refused, which needs the role to have a current definition first.

A role id is lowercase kebab-case (^[a-z0-9]+(-[a-z0-9]+)*$), at most 64 characters, and so never contains :, the separator in every model-role-config document id. It is checked at propose.

Documents and versions. In the role's partition, beside ADR-PA32's {roleId}:v{n}, {roleId}:current and {roleId}:proposal:{id}:

  • {roleId}:definition:v{n}, doc_type role_definition, append-only;
  • {roleId}:definition:current, doc_type role_definition_current, the pointer;
  • {roleId}:definition-proposal:{id}, doc_type role_definition_proposal, the one mutable kind.

None of these ids starts with {roleId}:v, and no definition document carries mapping_version, so the mapping-version queries, which select on that prefix and that property, are unaffected; a test pins it. definition_version is allocated as a mapping version is: max + 1, created create-only inside the transactional batch that replaces the proposal under its ETag and upserts the pointer, with ADR-PA32's re-read and retry on 409. A new role's first approved definition is v1.

Proposals mirror mappings, minus the rings. RoleDefinitionProposal is an IVersionedContract and reuses MappingProposalState, but enters only pending_approval, approved, rejected and withdrawn. The rules are the mapping rules: one undecided proposal per role; a reason on every decision; a distinct approver for approve and reject, compared case-insensitively; withdrawal by the proposer only; an ETag concurrency token refused by name when stale, never retried (ADR-PA34). Each decision goes through the existing IMappingDecisionRecorder before it happens, with a compensating record if the write then fails (ADR-PA30's order), under four new event types: model_role_definition_proposed, _approved, _rejected and _withdrawn. Their FromVersion and ToVersion are definition versions. The subject stays the role, so the consumer's governance screen filters them with the mapping events. The two-person rule is the standard separation-of-duties control (NIST SP 800-53 Rev. 5, AC-5; NIST).

No promote and no rollback for definitions (Mark, 2026-10-30). Rings describe traffic, and a definition serves none: it changes only what publish-time rules and the designer see. Pinned runs embed their contracts (ADR-PA39), so the emergency lever rollback exists for (ADR-M3) does not apply, and an unapproved pointer move would skip the second principal D12 requires. To revert, propose the old definition again.

Contract refs are resolved through the one contract port, moved down a tier. Propose refuses a ref that is not registered or is retired, and approval resolves both refs again and stamps their hashes; a ref retired between propose and approve is refused there. That is a genuine need for ModelRoleConfig to resolve a ref: a hash the service stamps must come from the registry, not from the caller, by ADR-PA32's rule for every stamped field. ModelRoleConfig is governance-tier and may not reference the Compiler, where IContractSnapshotCatalog lives. So IContractSnapshotCatalog and RegisteredContract move to Frontier.Platform.Abstractions, beside the ContractSnapshot they return, with their names and members unchanged, in the Frontier.Platform.Abstractions namespace. The Compiler keeps consuming the same port, and the consumer keeps one Host adapter over its registry, registered once. Rejected:

  • a second port, IRoleContractCatalog, in ModelRoleConfig, and a third for the designer: three ports over one store that could drift;
  • a type forward from the Compiler, which would keep the Compiler's namespace inside the kernel;
  • resolving only in the compiler tier (model-role.contracts-match), which checks a node against its role but cannot stamp a hash onto a governed record.

The move is a source break of one using for an implementer, and is marked as such in the PR that makes it. It adds nothing third-party to Abstractions (ADR-PA1). A designer or other platform need for a registry contract by ref should take this same port.

Evidence on mapping proposals (D16, Q4). evaluation_evidence_ref takes the form eval-run:{manual|kit}:{id} and is checked by prefix and a non-blank id; no eval store exists until the consumer's S13.137, which turns manual into a refusal in code. It is required for an agent-backed role and recorded when supplied for a model-backed one. A mapping proposal stamps the role's current input and output contract hashes onto itself; approval copies the ref and the hashes onto the version it mints (ADR-E27's settled note). Approval is refused when the role's current hashes are no longer the ones stamped, because a new contract version re-opens eligibility. The new members on RoleMapping and the proposal document are optional, so every stored document keeps its bytes. Each refusal has its own type deriving from MappingGovernanceRefusalException (ADR-PA34):

Refusal Means Consumer maps to
EvaluationEvidenceRequiredException An agent-backed role's proposal has no ref, or a malformed one 400 evaluation_evidence_required
EvaluationEvidenceStaleException The role's contract hashes moved since the proposal stamped them 409 evaluation_evidence_stale
ChainBackingMismatchException The chain's kind is not the role's backing 400
InvalidRoleDefinitionException A bad role id, an agent-backed role without both refs, a malformed ref, missing requirements on a model role 400
UnknownRoleContractException A ref that is not registered, or is retired 400
RoleBackingChangeException A proposal changes an existing role's backing 409
UnknownRoleDefinitionException The role has no current definition 404

Details settled while building it (consumer S13.117; to confirm):

  • Approve and promote both check again. Each re-reads the role's current definition and runs the propose checks again, so a proposal raised before v0.45.0 is still checked against the role's backing. Promote mints a fleet version, which is a new eligibility decision, so stale evidence is refused there as well as at approve.
  • Staleness applies only to a proposal that carries evidence. A model-backed proposal without evidence has nothing to go stale.
  • A malformed ref is refused whatever the backing, as EvaluationEvidenceRequiredException. The S13.137 resolver then never meets a stored ref it cannot parse.
  • The hashes are named input_contract_hash and output_contract_hash on the version and the proposal, matching the definition's names.
  • No new port. The hashes come from the stored definition through the library's own definition store, so mapping governance needs nothing new in composition.
  • D3's signal is public as EvaluationEvidence.IsEligibilityReopened(role, mapping). It is true when an agent-backed role's current hashes are not the ones its mapping was proposed against. EvaluationEvidence.IsWellFormed exposes the grammar the same way, so the consumer restates neither.
  • The compiler reuses RoleBacking. AgentRoleDescriptor.Backing is the ModelRoleConfig smart enum (the Compiler already references that library), serialized as backing. It defaults to model, so a catalogue that does not say gets the stricter reading.
  • agent.instructions-resolve reads the agent-role catalogue. It takes IAgentRoleCatalog alongside IInstructionCatalog, a constructor change. A role the catalogue does not know is read as model-backed, so its node must name a ref (model-role.roles-exist reports the unknown role).
  • A ref a node does name is still resolved, whatever the backing, and a blank ref is refused on any role: absent is null, never "".
  • The activity input carries the absence as null. AgentTaskActivityInput.InstructionsRef is string?, omitted when null, so an input recorded with a ref replays with its bytes. The pipeline decides after model resolution: a named ref is resolved; no ref on an AgentEntry target invokes with empty instructions and never calls IInstructionsResolver; no ref on a model target is a ContractViolationException raised before admission. A blank ref still goes to the resolver, as before; only null means absent.

A contract change leaves the live mapping serving (Mark, 2026-10-30). When a definition change moves an agent-backed role's contract hash, the mapping evaluated against the old hash keeps serving, the consumer's D3 screen flags the role as needing new evidence, and the next mapping proposal must bring evidence for the new hash. Nothing switches automatically (ADR-M2), and in-flight runs are unaffected because they embed their contracts. Refusing the stale mapping at run time would fail live runs on a governance edit.

instructions_ref becomes optional on the node (Mark, 2026-10-30). AgentTaskNode.InstructionsRef becomes string?, omitted when null; stored definitions serialize to the bytes they had, so their hashes hold. This is a public API break in Model, Compiler and Orchestration. AgentRoleDescriptor gains Backing; agent.instructions-resolve exempts a node on an agent-backed role and still refuses a missing ref on a model-backed one, and the design agent is told so. At run time a missing ref with a model target is a permanent contract violation; an agent target runs without instructions, as the A2A path already does.

Migration: the four roles, as they are (Mark, 2026-10-30). deep-reasoning, fast, structured-extraction and embeddings migrate as model-backed v1 definitions with no contracts, field for field from Phase1RoleCatalogue. The consumer's seed writes them, attributed to a migration principal, as it writes the governed mapping pointers. The platform never writes governed data at boot, and there is no fallback to the constant when none is stored: RoleCatalogueCheck fails the boot when a referenced role has no current definition, which is the only way a missing migration surfaces. CosmosRoleRegistry.GetCatalogueAsync reads the current definitions with a query across role partitions. The container is small, and a cross-partition query on one physical partition costs about what an in-partition one does (Microsoft Learn), so it is not cached in this release. Phase1RoleCatalogue stays as the migration source, marked [Obsolete] as no longer the catalogue. A local stack whose fast or structured-extraction mapping serves an agent chain is rolled back to the v1 model chain by hand; the consumer creates proper agent-backed roles for those agents with their contracts (its slice 6).

Left to the consumer: the doc 20 routes, frozen as written (GET /api/model-roles/definitions, GET and POST /api/model-roles/definition-proposals, and POST /api/model-roles/{roleId}/definition-proposals/{proposalId}/approve, /reject and /withdraw); the four event types in its governance catalogue; the Host adapter over its registry; and withholding an agent-backed role with no active mapping from the designer, so model-role.roles-exist catches it at publish.

Pinned, as the stack lands, by the role-definition golden files and governance tests, the mapping-history isolation test, the evidence and staleness tests, the instructions-optional compiler and pipeline tests, and the replay test of a run recorded with an instructions_ref.

Addendum (v0.46.0): the design agent sees stakes. v0.45.0 gave AgentRoleDescriptor the role's backing and contract refs but not its stakes, so the design agent chose a role from its description alone. The descriptor gains an optional stakes, which the consumer's catalogue fills from the stored definition, and the prompt says what each level means. It is optional and omitted when null, so a catalogue that does not supply it produces the same prompt as before. Stakes still drives governance posture; showing it to the design agent changes no rule. Mark chose this on 2026-10-31 over deferring it until a designer eval asked for it.

ADR-PA41 — an MCP node pins whether it writes, the designer copies what the registry holds, and the design agent reads contract annotations

The consumer's ADR-E27 (contracts as data) makes an MCP tool's write flag governed registry data (D11), gives an mcp_tool node the contract refs its tool was registered with (D9, here ADR-PA39), and promises that the designer and the design agent read the same contract annotations (A3-R16, the consumer's contract-grounding requirement). This ADR records the platform's half, shipped in v0.45.0 beside the roles work in ADR-PA40 (consumer S13.117, slices 3 and 5; Mark, 2026-10-30).

Whether an MCP node writes is pinned in the definition (Mark, 2026-10-30; consumer register S3-1). McpToolNode gains an optional writes (bool?, after output_contract_type, left out when null), copied from the tool's registry record when the node is designed. The orchestrator uses node.Writes when it is present and asks IMcpWriteClassifier only when it is not. true gives the step its idempotency key and the mcp-write retry profile; false gives no key and the mcp-read profile. A node's own retry spec still wins. The sandbox's write fence is applied by the consumer's tool catalogue when the tool is resolved, not here; making it follow the pinned flag is the consumer's slice 3 change.

  • Why: the classifier is called inside the orchestrator body, so its answer must not change across replays of one run. An answer read from the registry can change: McpToolRef carries no server version, and the consumer resolves a tool on the newest active version, which a new registration replaces mid-run. Pinning the flag is ADR-E27 D15's rule applied to one more governed fact: what runs is what was published, and replay re-reads it from the recorded input.
  • Old definitions replay unchanged. A definition published before this has no writes, keeps its bytes and golden files, and takes the classifier path as before; no schema version moves. IMcpWriteClassifier keeps its purity contract and now answers only for those definitions.
  • Rejected: a consumer classifier over a map loaded from the registry at worker start, frozen by refusing any registration that changes a tool's flag. A reload mid-run breaks the port's contract, and the freeze stops a governed field from ever changing in a new version. Also rejected: leaving the hard-coded classifier in place until a later release.
  • DesignerToolDescriptor gains an optional writes: the registry's value for the tool, or null when the registry holds none. The design agent is shown it, because a writing node needs an idempotency_key_spec. mcp.write-idempotency still requires a spec on every mcp_tool node; a read exemption on the pinned flag is a later change.
  • mcp.tool-resolves holds the node's writes to exactly the registry's value, as it already holds the contract refs (ADR-PA39, slice 2c). Null on the node passes only when the registry holds none.
  • An agent node's tool_refs are not pinned this way. Their write flags and schemas stay with the consumer at invocation (consumer register S3-9); per-run pinning of agent tools is a recorded lever.

The designer copies the tool's registry record onto the node. ADR-PA39 said an mcp_tool node's contract refs are copied from the tool's registry record when the node is designed, but no code did it, so a node could be bound only by hand-written JSON. One pure function now does it: for each mcp_tool node whose tool_ref the tool catalogue resolves, it sets input_contract_type, output_contract_type and writes to the descriptor's values, overwriting whatever the node said. A node whose tool does not resolve is left alone, and mcp.tool-resolves reports it. The registry is the authority and the node holds a copy, so there is nothing to merge.

  • Where it runs: on every proposal the design agent returns, the first attempt and the repair attempt alike, before the proposal is validated, diffed or merged. The diff the designer reviews therefore shows the copied values, and the repair pass is never spent on fields the agent cannot know. The function is public, so the consumer can apply the same rule wherever else it builds or rewrites a definition (its migration of existing definitions, for one).
  • Not at publish. Publish validates; it does not rewrite. A reviewed proposal is published as it was reviewed, and a registry change after review shows up as an mcp.tool-resolves finding, not a silent edit. ADR-PA39's embedding at publish refuses in the same way.
  • Not on a plain draft save. SaveDraftAsync returns a handle, not the saved definition, so a copy made there would be invisible to the editor that sent it. The consumer's Inspector shows these fields read-only (consumer register S5-19).
  • A tool with no outputSchema has no output contract ref (consumer register S3-2), so the copy leaves output_contract_type null and the result runs unvalidated, as ADR-PA39 already allows.

The design agent reads contract annotations (consumer register S5-1, S5-2). ADR-PA39 left designer grounding to the consumer's slice 5; its agent half lives in the platform prompt, so it moves here. The "Available contracts" block keeps the CLR contract names it lists today and adds, for each registry contract, the text the consumer's contract panel shows: its ref, its contract-level description, each property's path and description, its examples, and each rule's message with its field path. The tool and role lists already carry their contract refs (DesignerToolDescriptor, AgentRoleDescriptor), and the prompt now says what they mean:

  • an agent_task bound to a role that declares contracts names those same refs (model-role.contracts-match);
  • an MCP tool with no output contract ref is marked as returning any JSON;
  • an mcp_tool node's contract refs and writes are copied by the designer, so the agent need not author them.
  • Where the annotations come from: IContractSnapshotCatalog, the one contract port (consumer register, the collapse of the contract-lookup ports). It gains a ListAsync(CancellationToken) that returns every registered contract that is not retired. A retired contract cannot be named by a new publish, so the agent is never offered one. This is a break for the port's implementer, the consumer's one adapter over its registry. If ADR-PA40 moves the port to a lower tier, it keeps its name and this member moves with it.
  • A discovered contract's gaps are marked. A contract an MCP server supplied may lack descriptions or examples, because the registration lint only warns for it (ADR-E27 D10). The prompt marks such a contract and its undescribed properties. The gaps are found by running the registration lint itself, exposed from Frontier.Platform.Contracts as a pure function over a snapshot, so the prompt and registration can never disagree about what a gap is.
  • The text is stable. Contracts are listed in ordinal ref order, and annotations sit inside the contract hash, so the block changes only when a contract version is registered or retired.
  • No cap yet. Every listed contract is rendered in full. A catalogue too large for the prompt would need a cap or retrieval; that is a recorded lever, not built now.
  • Adding the port member and changing the prompt are the workflow.compiler! break. The prompt's golden snapshot changes with it.

ADR-E27 D9's exporter check: what JsonSchemaExporter makes of the canonical profile's types. D9 has .NET contracts generated with JsonSchemaExporter and then registered. A probe record (2026-10-30) with a fixed-precision decimal, a decimal with no declared scale, a DateTime, an EngagementId, a smart enum, a plain enum and a nullable string showed the following.

  • The raw exporter cannot see the profile's converters. Every property a converter owns (both decimals, the DateTime, the EngagementId and the smart enum) exports as true, which accepts anything. A [Description] is ignored, no content model is stated, and the root is typed as object-or-null.
  • CanonicalOutputSchema, the platform's converter-aware export, fixes most of it but not all. It rewrites the decimals, the DateTime and the smart enum into their wire schemas. It leaves EngagementId as true. And once a property carries a [Description], the export arrives as a description-only object rather than true, the rewrite never fires, and the property again accepts anything. No CLR contract in either repo uses [Description] today, so no response format sent to a provider is affected. A generated contract needs descriptions, though, so the generated path would hit this on its first property.
  • Registration still refuses every one of these exports. Each fails the lint for a generated contract (no description or examples, content model unstated), so nothing loose registers by accident. But a schema that carries the descriptions, examples and closed objects the lint asks for would still pass with its converter-owned properties open. The lint checks legibility; it cannot know the wire format.
  • Decided: the check becomes a test over the probe. It asserts that CanonicalOutputSchema gives every converter-owned property its wire schema, with or without a [Description]. And once the contract-level description, examples and closed content model are added, it asserts the export passes IContractRegistrationCheck as a generated contract. CanonicalOutputSchema's rewrite is corrected in the same change to recognise the description-only node and to give EngagementId its string schema. For every contract that exports today, its output is unchanged.
  • Not decided here: whether the platform also ships a helper that generates a registrable contract from a CLR type, closing its objects and taking examples from the caller. Until then the generator in an agent's repository adds those, and the test above is what holds them to the wire format.

Each part is pinned by the PR that builds it: McpToolNode's golden files (an unchanged definition keeps its bytes; a new golden pins writes), a replay test of a recorded run without the field next to a run with true and with false, the mcp.tool-resolves rule tests, the stamping function's tests and the design-turn tests, the ChatDesignerService prompt tests and golden snapshot, and the exporter probe test.

An MCP node's output contract is held to the tool's structuredContent (Mark, 2026-10-30; found by the consumer's slice 3 team). The MCP specification (2025-06-18, Tools, "Structured Content" and "Output Schema") has a tool that declares an outputSchema return its result as a JSON object in the CallToolResult's structuredContent, and says servers MUST return structured results that conform to that schema and clients SHOULD validate them against it. The same result carries content blocks (for backwards compatibility, a tool SHOULD also put the serialized JSON in a text block) and an optional isError. The consumer's tool adapter, the MCP C# SDK's McpClientTool, hands the engine that whole CallToolResult as JSON. Slice 2b validated the whole object, so every conforming reply failed its output contract, permanently.

  • What changed: when the node pins an output contract (output_contract_type, so McpToolActivityInput.OutputContract is set) and the reply is not the sandbox's simulated ack, the pipeline takes structuredContent out of the reply, validates it against the pinned contract, and records it as the step's output: output_payload is its canonical JSON in the tool's key order, and output_hash is taken over its RFC 8785 form, as for any payload (ADR-E2 decision 2). The content blocks are not recorded, because what the next node consumes is the value the contract describes.
  • No structured result is a contract violation. A reply with no structuredContent (or a null one), or one that is not a CallToolResult object at all, is a permanent ContractViolationException naming the contract, whose one violation says the result has no structuredContent and that a tool declaring an outputSchema must return it. It is never retried: a contract ref is pinned only for a tool registered with an outputSchema (consumer register S3-2), so the tool broke its own declaration.
  • isError keeps today's handling. A result with isError: true is held whole to the pinned contract, as before, so it still fails as a contract violation. Classifying a tool-level error on its own (transient or permanent, with the tool's own message) is a recorded lever, not built now.
  • The engine reads a JSON shape, not an SDK type. It looks up structuredContent and isError by their wire names on the reply's canonical JSON. No MCP SDK type enters the engine, and a consumer adapter that produces the same JSON shape any other way works the same.
  • A node with no output contract is unchanged. The whole reply is recorded with the same bytes and hash as before, and the sandbox ack is still recognised on the whole reply and never held to a contract. Nothing recorded changes shape, so no activity contract, golden file or replay moves.
  • Pinned by the pipeline tests: a conforming CallToolResult records its structuredContent and hashes its JCS form; a reply with no structured result, a null one, a bare object or a scalar, and a null reply are refused with that message; isError: true is held whole; isError: false records its structuredContent; and a node with no output contract records the whole result unchanged.

The signed audit records each MCP step and the contract hashes that validated it (Mark, 2026-10-30). ADR-E27 D15 says the audit records the contract hash that validated each step. Slice 2b put those hashes on AgentInvocation, but the signed AuditRecord held agent invocations only, so an mcp_tool step's hashes reached the snapshot and never the signed record.

  • What is recorded: AuditRecord.McpToolInvocations (mcp_tool_invocations, after dynamic_context_hash), a list of McpToolInvocation: correlation_id, node_id, artifact_key, tool_ref, input_contract_type, input_hash, output_contract_type, output_hash, input_contract_hash, output_contract_hash, simulated and completed_at_utc. Hashes, never payloads (doc 05 §6). A node that names no output contract records none rather than the step's empty name, and a write-fenced call is simulated: true with no output contract hash, as its step already has. The name follows AgentInvocation; it is not a ToolCall, which is a call an agent made inside its invocation.
  • Signed, through the existing path. SignedAuditRecord carries the field after dynamic_context_hash, and AuditRecordHasher copies it both ways, so it sits inside record_hash and an edit to any entry fails the signature. Nothing else in the signing path moved.
  • Where it comes from: the final snapshot's completed steps, the DTF-side evidence the consolidator already reads for the timeline. An MCP step is not a model call, so it stages no telemetry. The step therefore now names, all optional: tool_ref and input_contract_type, copied from the node in the orchestrator body (replay-safe: the definition rides inline), input_hash from the activity result, and simulated (true or absent). Only MCP steps set them.
  • The arguments are hashed. No hash of an MCP call's arguments existed. The pipeline now hashes the arguments exactly as the tool received them, the object it already validates, idempotency key included, over their RFC 8785 form (ADR-E2 decision 2), as McpToolActivityResult.InputHash (optional, so a result recorded before replays with none).
  • Older records keep their bytes. The field is omitted when an execution ran no MCP step and is absent from every record signed before it, so those records recompute to exactly their stored bytes and verify unchanged. An MCP step recorded before steps named their tool has no entry; its task_completed event is still on the timeline. No schema version moves: this is an additive, optional change, the canonical profile's minor-change rule, as sandbox and the context pin were.
  • Pinned by the new audit_record_mcp_tool_invocations.json, signed_audit_record_mcp_tool_invocations.json and execution_snapshot_mcp_step.json golden files (every older golden unchanged); a test that the two older signed goldens recompute to their stored bytes; a verifier test that a record with MCP steps verifies and an edited contract hash breaks it; the signed-shape parity test; and the projector, consolidator, walk and pipeline tests.

ADR-PA42 — an agent node pins its tools' contracts and write flags

ADR-PA41 left an agent node's tool_refs unpinned: their schemas and write flags stayed with the consumer at invocation, resolved on the newest active registry version, and per-run pinning was a recorded lever. Consumer task S13.144 pulls that lever (Mark, 2026-11-01; consumer decision register for S13.144, items 1 to 7). It ships in two PRs: PR1 (workflow.model and workflow.compiler, additive) and PR2 (workflow.orchestration!). This ADR records both designs; PR1 builds the first half.

The tool-to-contract mapping lives on the node (register item 1). AgentTaskNode gains an optional tool_contracts (after tool_refs, left out when null): a list of AgentToolContract, one entry per distinct tool_refs entry in that order, each {tool_ref, input_contract_type, output_contract_type, writes}. Input and output contracts and the write flag are all pinned (item 2).

  • Old definitions keep their bytes. A definition published before the pins has no tool_contracts, keeps its golden files and its hash, and no schema version moves: an additive, optional field under the canonical profile's minor-change rule, as writes was on mcp_tool (ADR-PA41). Such a definition runs as today: its tools resolve on the newest active registry version, and an unpinned write is still treated as a write (item 4).
  • A tool with no discovered contract pins null (item 7). The precedent is the mcp_tool node: a tool registered before contracts were data (consumer S13.117) has no contract ref, so the node holds null and mcp.tool-resolves passes null only against null. An agent's entry does the same, so input_contract_type is nullable on the entry, though the register's sketch showed it required; the entry still exists, because it pins writes, and because a tool_ref without one is refused. A tool with no outputSchema likewise pins no output contract (consumer register S3-2).

The designer copies the registry's values (item 1). McpToolRegistryStamp.Apply, the one function ADR-PA41 made for mcp_tool nodes, now also rebuilds each agent node's tool_contracts: a tool the catalogue resolves gets its DesignerToolDescriptor's contract refs and write flag, nulls included; a tool it does not resolve keeps whatever entry the node gave it, for mcp.tool-resolves to report; and entries for tools the node no longer lists are dropped. An agent node with no tools and no pins is returned as it is, and one left with no pins gets null, never an empty list, so its bytes do not change. It runs where ADR-PA41's stamp runs: on every proposal the design agent returns, before it is validated, diffed or merged; never at publish, never on a plain draft save. A consumer applying the function to existing definitions (a migration, say) now pins their agents' tools too, which is the intent.

mcp.tool-resolves holds the pins to the registry (item 1). For each agent tool_refs entry that resolves, the node must hold exactly one entry, and its three fields must equal the registry's. The findings are: no entry (tool_contracts); a field that differs (tool_contracts[i].input_contract_type, .output_contract_type, .writes, with the same messages as the mcp_tool checks); and an entry for a tool tool_refs does not list, or a second entry for one tool (tool_contracts[i]). An unresolvable tool_ref is reported once, as unresolved.

  • "On newly compiled definitions." The rule runs only where definitions are compiled: design-time validation and publish. A published definition is immutable and never revalidated, so the refusal reaches only new work; a stored draft that lists tools must be re-stamped (a design turn, or the consumer applying McpToolRegistryStamp.Apply) before it publishes, as unpinned mcp_tool drafts had to under ADR-PA41.
  • The stray and duplicate checks are a minor detail settled here: a stray entry would embed a contract no step uses, and a duplicate would make "the" pin ambiguous.

Publish embeds the pinned contracts (item 2). DefinitionContractRefs.Collect adds every schema ref an agent's tool_contracts name, so the existing embedder (ADR-PA39) writes their snapshots into WorkflowDefinition.Contracts, and refuses to publish when one is unregistered or retired. A run therefore holds the exact contract versions its agent's tools were designed against.

What PR2 does (workflow.orchestration!). Decided now, built in the next PR.

  • The orchestrator copies the node's pins onto AgentTaskActivityInput as a new optional member, omitted when null, so every recorded input replays byte-identically; the PR proves it with a golden and a replay test.
  • IMcpToolCatalog takes the pins, so the consumer's catalogue resolves each pinned tool against its pinned contracts and write flag rather than the newest registry version. That is the break for the port's one implementer, the consumer's adapter (consumer follow-up after v0.47.0).
  • The tool description shown to the model is the pinned contract's own description. Annotations sit inside the contract hash (consumer ADR-E27 Q2), so what the model reads is pinned with it.
  • Pin only (item 3): the engine does not validate an agent's tool-call arguments or results against the pinned contracts in this task. That is a separate, later task.
  • The mcp_tool half-pin gap closes (item 5): the sandbox's write fence follows the node's pinned writes, not the newest registry version's flag. A node with no pin keeps today's behaviour.
  • Endpoint resolution stays on the newest active server version (item 6): an endpoint is not a contract, so it is not pinned.

Not changed. The design agent's prompt is unchanged: the stamp overwrites whatever the agent writes in tool_contracts, so it never needs to author them. Saying so in the prompt, as ADR-PA41 did for mcp_tool nodes, is a later wording change with its own prompt-snapshot update.

Pinned by PR1's tests: the new workflow_definition_tool_contracts.json golden (every older definition golden unchanged, which is the compatibility claim); the stamp tests (order, nulls, unresolved and unlisted tools, an untouched tool-less node); the design-turn test that a proposed agent is pinned before validation; the rule tests for exact, missing, differing, stray and duplicate pins; and the Collect test for an agent's pinned refs.

PR2 as built (workflow.orchestration!). The second half, as decided above (Mark, 2026-11-01; consumer S13.144, register items 2 to 6).

  • One pin type for both step kinds. McpToolPin {tool_ref, input_contract, output_contract, writes} carries the snapshots themselves, not refs: the orchestrator resolves each ref through the existing PinnedContract lookup over WorkflowDefinition.Contracts, so the activity and the catalogue never fetch a contract. Each field stands alone: null means nothing is pinned for that fact (a tool registered before contracts were data, a tool with no output schema, a definition published before writes), and the catalogue resolves that fact as before.
  • Agent steps. AgentTaskActivityInput gains tool_pins (order 17, after output_contract), one pin per tool_contracts entry in its order, null when the node has none. Left out when null, so every input recorded before it keeps its bytes.
  • mcp_tool steps (item 5). The orchestrator already decides the idempotency key and retry profile from the node's writes (ADR-PA41); the fence did not, because the consumer's catalogue classified the tool itself on the newest registry version. McpToolActivityInput gains writes (the node's own value, never the classifier's fallback, so an unpinned node's input keeps its bytes), and the pipeline hands the catalogue one pin built from it and the node's two pinned snapshots. Its members also gain [JsonPropertyOrder] in their declaration order, which the canonical profile requires and which moves no byte.
  • The port (items 2, 4, 6). IMcpToolCatalog.ResolveAsync(toolRefs, pins, engagementId, ct): the new pins (nullable) sits between the refs and the engagement. A pinned tool is built from its pinned input contract, its schema and its description (annotations are inside the hash, consumer ADR-E27 Q2), and fenced in a sandbox by the pinned flag; only a null fact, an unpinned tool or a null pins falls back to the newest active version, where an unclassifiable tool is still treated as a write. Endpoints stay on the newest active version. A pin list rather than a request object keeps the break to one added argument for the port's one implementer.
  • Pin only (item 3). Nothing in the engine validates an agent's tool-call arguments or results against the pins.
  • Breaking: the port signature, for the consumer's catalogue (and the smoke consumer, updated here). The activity inputs change only additively.

Pinned by PR2's tests: the pre-change wire tests for both activity inputs (null reads, bytes unchanged, the new member written last); the replay tests that a recorded definition hands its activity the same pins, or the same writes, on every replay, and none when it was published without them; the step tests that each pin resolves to the embedded snapshot; and the pipeline tests that both pipelines hand the catalogue their pins.

ADR-PA43 — the contract validator's budgets are a governed record, pinned per run

The consumer's ADR-E27 D2 calls the validator's budgets governance data: a static cost ceiling checked at registration and a count-based run-time budget, never wall-clock. Until now all four were deployment configuration (ContractsOptions), read on every call, and the iteration budget was baked into each contract's compilation. This ADR records the platform's half of making them a governed record (consumer S13.140; Mark, 2026-11-01, register items 1, 2, 6 and 7). The store, the change control, the permission and resolving the record at run start are the consumer's.

One record, in Abstractions. ContractBudgets (schema_version "1.0", then max_rule_cost, max_rule_iterations, max_payload_depth, max_violations, all required) is an IVersionedContract in Frontier.Platform.Abstractions. The validator in Contracts takes it and Workflow.Orchestration carries it, and the consumer's store will hold it, so it lives below all of them. ContractBudgets.Default holds today's defaults (1,000,000; 100,000; 64; 20), and ContractsOptions now takes its defaults and range ceilings from it, so the two cannot drift. Validate() refuses a value below 1, a depth over 256 or a violation cap over 1,000, the ranges ContractsOptions already enforced.

  • No wall-clock field. RegexMatchTimeoutMilliseconds stays in ContractsOptions (register item 7). It is the one time limit, it describes the deployment's hardware rather than a policy, and it only ever refuses a payload.
  • Deployment-wide only (register item 6). There is no per-engagement-type layering, so the record has no key beyond what the consumer's store gives it.

The validator and the registration check take budgets per call. IContractValidator gains Validate(contract, payload, budgets) for bytes and for a parsed element, and IContractRegistrationCheck gains Check(request, registered, budgets). The existing overloads are unchanged in behaviour: they build the record from ContractsOptions, so a caller that never passes one sees exactly what it saw before. An out-of-range record is refused with a permanent ContractViolationException before it is used.

  • The registration overload is needed for the ceiling to be governed at all. The cost ceiling is checked only at registration (next point), and registration is platform code, so without this overload the governed max_rule_cost would have no effect. The examples run under the same record's iteration budget, so a contract's own examples are checked under the budget it will run with.
  • Adding members to these interfaces is the contracts! break. Neither is a consumer-owned port, and neither has an implementer outside this repository, but a test double that implements either must add the overloads (ADR-PA41 treats a new member the same way).

The cost ceiling is checked at registration only (register item 2, ADR-E27 D2's text). At run time the validator compiles a pinned contract with no ceiling. It keeps refusing a rule whose cost the schema leaves unbounded, because such a rule has no ceiling at all. A contract registered under one ceiling therefore keeps running after the ceiling is lowered; the ceiling governs what may be registered, not what was.

The compilation holds no budget. The validator's cache is keyed by contract hash, so a budget baked into a compilation would have served the first caller's budget to every later one. ICompiledRules.Evaluate now takes the iteration budget beside the violation cap, and the depth limit is applied per call, so one compilation serves every run's record. CellyRuleEngine no longer reads options.

A run pins its record at start (register item 1). GraphOrchestratorInput gains an optional contract_budgets (after dispatcher_rollover_threshold, omitted when null). The orchestrator copies it onto every AgentTaskActivityInput (after output_contract) and every McpToolActivityInput (last), the two activities that validate, and DispatcherSteps carries it to each child and into the next generation's input at ContinueAsNew. The pipelines pass it to the validator for the input, the agent's reply, and an MCP call's arguments and result. No step reads a store, and the orchestrator body only copies a field it was given (hard invariant 2).

  • Absent means today's behaviour. An input recorded before the field, and a run the consumer starts without one, carries null, and every step validates through the existing overloads under ContractsOptions. Nothing recorded changes shape: no schema version moves and no golden file changes.
  • It is carried whole. A run never checks max_rule_cost, but it carries the whole record so its inputs name exactly the record it ran under.
  • The port is the consumer's. No platform caller resolves the record, so the platform defines no port for it (register's platform scope). The consumer's Host factory resolves it once and sets the field.

Pinned by contract_budgets.json (a new golden; every other golden unchanged), a replay test that an orchestration input recorded without the field deserializes and runs twice to byte-identical agent activity inputs naming no budgets, byte-identity tests of GraphOrchestratorInput, AgentTaskActivityInput and McpToolActivityInput recorded without the field, the walk and dispatcher tests that carry the record, the pipeline tests that validate under it, and the validator and registration tests: one compilation across two budgets, the iteration budget and violation cap per call, no ceiling at run time, an unbounded rule still refused, and the ceiling and iteration budget applied at registration.

ADR-PA44 — the host build stamp is the worker's, through a port the consumer must register

ADR-E15 D1/D3 (the consumer's record of which code ran each step) stamps every agent and tool activity result with a host build. The platform read it from its own assembly, Frontier.Platform.Workflow.Orchestration, so two worker deploys on one platform version stamped the same value and could not be told apart (consumer S13.182).

The stamp comes from IHostBuildStamp, a consumer-owned port the engine does not register. Only the worker's composition root knows the worker's build, and a platform default would bring the silent wrong answer back. HostBuildStamp.FromAssembly builds one from the assembly the consumer names (its informational version, else its assembly version, else "unknown"), resolved once.

  • Read activity-side only. The two pipelines read it when they build a result; an orchestrator body never does, so a recorded result replays the value it recorded. Pinned by OrchestratorBodiesNeverReadTheHostBuildStamp.
  • "Never a platform assembly" is documented, not enforced. A name check cannot tell a platform package from a worker: this repository's own sample worker is Frontier.Platform.SmokeConsumer.

Consumers must register an IHostBuildStamp: that is the one adoption step this release requires. The public API change is additive (one interface, one static class), so the commit is not scoped !, following the ADR-PA32 precedent for a newly required port (IMappingDecisionRecorder). Without the registration, resolving either pipeline fails naming the port (HostBuildStampRegistrationTests); with ValidateOnBuild building the provider fails, and otherwise the first agent or tool activity fails. No recorded shape changes: host_build was already on both results, no golden file changes and no schema version moves.

ADR-PA45 — the signed audit record names the worker build and the run's generation

ADR-E15 D3 (the consumer's pin set) promises that "what exactly was this execution running?" can be answered from the signed audit record alone. The record could not answer it: host_build was on the activity results and the snapshot's steps, but AgentInvocation and AuditRecord had no such member (consumer S13.183).

Three additive, omit-null members, all covered by record_hash.

  • AgentInvocation.host_build (order 19), staged on AuditTelemetryRecord.host_build (order 23) by the agent pipeline from the same IHostBuildStamp value its result carries, and copied by the consolidator's projection.
  • McpToolInvocation.host_build (order 12), copied from the step's recorded StepCompletion.HostBuild.
  • AuditRecord.generation / SignedAuditRecord.generation (orders 18 and 22, after every existing member), the integer compatibility generation the run started on (ADR-E15 amendment, Decision 1). Nothing writes it yet. Its source, the generation recorded on the execution snapshot, is consumer S13.184; the consolidator copies it when that lands. Carrying the member now keeps S13.184 to wiring, not a second audit-shape change.

No schema version moves, per the minor-change rule: records signed before these members recompute to their stored bytes (RecordSignedBeforeHostBuildAndGeneration_RecomputesToItsStoredBytes), and every older golden file is unchanged. Pinned by the new audit_record_host_build_generation.json and signed_audit_record_host_build_generation.json, and the verifier test edits each of the three members (agent host_build, MCP host_build, generation) and sees the signature fail.

Verifiers adopt this release no later than the workers that write it. The canonical profile skips a member its contract does not declare, so a reader built against an older platform version reads a new record without the three members, recomputes different bytes and reports the signature invalid (Verify_RecordReadWithoutTheNewMembers_FailsTheSignature reproduces that read by stripping them). The rule is a deployment ordering, and no check in this repo can enforce it: the stale reader is an already-shipped package that never sees this code, and nothing in the platform knows which versions a consumer runs side by side. The consumer meets it by moving every process that verifies and every worker to the same FrontierPlatformVersion in one bump, which its lockstep pin already does.

ADR-PA46 — a failed or terminated run gets a signed, chained audit record

ConsolidateAuditActivity ran only on the completed path, so a run that failed, or was ended by the consumer's terminate (its S13.149), left no signed, hash-chained record of what it did (consumer S13.240, from the 2026-11-07 as-built survey; Mark decided 2026-11-07 to build it).

Where each record is written.

  • Failed: on the orchestrator's failure path, through the same activity. After the drain (ADR-5 Decision 4), ThrowIfFailedAsync writes the paused_on_failure checkpoint as before, then calls ConsolidateAuditActivity with ConsolidateAuditInput.final_status = failed, then rethrows the node's failure. The orchestration does end failed, and the checkpoint stays paused_on_failure: the consumer's projection, recovery sweep and B3 failure band read that status, and the record attests the outcome, not the checkpoint. The body stays pure: the consolidation is an activity, and the start time is the one the orchestrator captured from context.CurrentUtcDateTime at its start, the same value the completed path's record carries.
  • If the failure path's audit activity fails after its retries, it is swallowed. The run failed because of its node, and that failure is what DTF must record and what the consumer's GetFailureInfoAsync classifies. An audit failure would replace it with an unclassified one. The missing record stays detectable: the run is terminal and has no audit-records entry.
  • Terminated: by whoever ends the run. A terminated orchestration runs no further activities, so the consumer's terminate route closes the record after the DTF terminate. The existing seam is enough and nothing new was added to it: write the terminated snapshot, then IAuditConsolidator.ConsolidateAsync (with final_status = terminated or null), then IAuditSigner.SignAsync. IAuditConsolidator's doc comment says this.
  • Only the node-failure path writes a record. A throw elsewhere in the body (an unsupported definition, an unmapped role at pinning, a snapshot write that fails) writes no paused_on_failure checkpoint, so there is no failure to attest; those runs still end without a record, as before (RunAsync_FailsOutsideTheNodeDrain_ConsolidatesNoAudit, which also fails the paused_on_failure write itself). Recording them is deferred.

The chain stays unforked. All three outcomes go through IAuditSigner.SignAsync, the guarded per-engagement append of ADR-PA31. audit-records is create-only per execution, so if a failed run's record and a terminate's record ever race for the same execution, the second is refused with "already exists" and the chain keeps one. AuditOutcomeTests signs a mix of completed, failed and terminated records on one engagement and verifies one linear chain in which every record verifies.

What the record says. Two additive, omit-null members, both covered by record_hash:

  • AuditRecord.failure / SignedAuditRecord.failure (orders 19 and 23): FailureRecord, the doc 10 §3 classification (required), and the node_id, exception_type and bounded message of the checkpoint's failure_detail (S13.120) when it recorded one.
  • AuditRecord.termination / SignedAuditRecord.termination (orders 20 and 24): TerminationRecord, terminated_by, reason and terminated_at_utc from the terminated snapshot (ADR-PA26, 2026-11-06).
  • The consolidator copies each from the snapshot whenever the snapshot holds it, so a run that paused on a failure and was then terminated keeps both facts. The closing execution_completed event names the attested status.
  • Validate() on both shapes requires failure with a classification when final_status is failed, and termination with an actor and a reason when it is terminated. No other status is checked.
  • The consolidator refuses to attest failed or terminated when the latest snapshot does not back the claim, with a permanent ContractViolationException. The usual cause is a terminate that consolidates before it writes its terminated snapshot, and an append-only store cannot take the claim back.

ConsolidateAuditInput.final_status (order 6) is additive and optional under the ADR-E15 floor. Null, and omitted on the wire, means the snapshot's own status, which is what every recorded input meant. The completed path leaves it null, so its recorded bytes are unchanged. No schema version moves: every older golden recomputes to its stored bytes (RecordSignedBeforeFailureAndTermination_RecomputesToItsStoredBytes), and four new goldens pin the new shapes. activity-shapes.json records the change as additive in the current generation.

Replay, and the skew this accepts (ADR-E15). The new activity call sits after the failure checkpoint and before the throw, which happen in one episode, so no recorded history ends between them. A run that reaches its failure on the new code schedules the call as a new action. A run already failed is complete and is never replayed. The new replay test runs the failure path on the DTS emulator, with the sibling branch still in flight so each step lands in a later, replaying episode. The existing replay tests pass unchanged. Residual skew, accepted and recorded, not observed: an old worker can pick up a run whose history already holds the audit call a new worker scheduled. The old code throws the node's failure where that history expects the call. Either way the run ends failed, but whether the record lands, and whether the SDK reports the node's failure or a replay mismatch, has not been tested; no test here mixes worker versions. Deploying workers in one step, as the consumer's lockstep pin does, closes the window.

Verifiers adopt this release no later than the workers that write it, for the reason ADR-PA45 gives: a reader without the two members reads a failed or terminated record without them, and fails its signature.

The public API change is additive: two records, two members on each audit record shape and one on ConsolidateAuditInput. No interface gains a member, so the commit is not scoped !.

ADR-PA47 — a failed run ends failed; paused_on_failure is never written again

Revises the consumer's ADR-5 Decision 4 (S13.7i), which ended a failed run on a paused_on_failure checkpoint. Consumer task S13.272, found in its S13.149 live check on 2026-11-10; Mark decided the same day that a failed run is honestly terminal.

Why the status was wrong. ThrowIfFailedAsync wrote paused_on_failure, then rethrew, so the scheduler marked the instance Failed. Nothing resumes such a run: no resume route or event exists, and the orchestration has already ended. So the checkpoint described a run that could carry on when it could not. The consumer read the word literally: its live-runs projection and terminate route counted the run as live, its recovery sweep never looked at it again, and its start check asked the scheduler, which allowed a new start. Four local runs were stuck like this. Docs 03 §9 and 07 §5 promised a resume event; doc 02, ADR-5 D4 and doc 19 B3 described a failure with no user retry. The code matched the second set.

Decision.

  1. The orchestrator writes failed. After the drain (ADR-5 D4's drain is unchanged: siblings finish, no new node starts), the last checkpoint is failed, carrying what paused_on_failure carried: the failing node as current_node_id, the doc 10 §3 failure_classification, and the failure_detail of S13.120. ADR-PA46's audit call and the rethrow follow as before.
  2. A failed snapshot must say what kind of failure. ExecutionSnapshot.Validate() requires failure_classification for failed, as it did for paused_on_failure. Nothing wrote a failed snapshot before this change, so no stored snapshot starts failing validation.
  3. paused_on_failure stays readable and is never written. The value stays in ExecutionStatus, so snapshots, live-runs documents and activity inputs recorded before this change still deserialize (ADR-E15: wire shapes only grow). It is [Obsolete], so new code that names it fails the build unless it says, in a scoped pragma, that it is reading old data. Its removal waits for a phase boundary, after the consumer's reconcile has rewritten every stored one.
  4. Recovery is a new run. A failed run is not resumed. To try again after the cause is fixed (a raised budget, a lifted suspension, a corrected contract), the operator starts a new run, which the one-live-run rule allows because the failed one is no longer live.
  5. Readers treat both statuses as one fact. TestRunExecution maps failed and the legacy status to the same terminal outcome and message ("failed permanently at node … (classification)"). The node is exact (failure_node_attributed) only when the checkpoint records its failure detail, which the orchestrator writes from the failure it observed. A checkpoint a consumer heals from the scheduler's view (its recovery sweep, or its sandbox poll) has no detail, and its node is only the last completed one. This narrows S13.26 for legacy checkpoints: the status alone used to count as exact, but the consumer's sandbox poll wrote it with the last completed node, so it never proved that.

What it does not change. ConsolidateAuditInput.final_status = failed is still sent, so the activity's recorded bytes are unchanged; the record attests failed, now matching its checkpoint. Activity names, event names and wire shapes do not change (activity-shapes.json is untouched: the enum keeps its seven values). No schema version moves. The existing paused-on-failure goldens are unchanged, and execution_snapshot_failed.json pins the new checkpoint.

Replay and skew (ADR-E15). The change is an activity input value, which replay does not compare: the snapshot activity is scheduled at the same point with the same name. A run already failed is complete and never replays. Accepted and recorded: a run that failed on an old worker keeps its paused_on_failure checkpoint; the consumer's reconcile rewrites it. The replay test's assertion on the final checkpoint's status changes from paused_on_failure to failed; that assertion records what the run wrote, and is not the replay-determinism check, which is unchanged.

The consumer's half (S13.272). It drops paused_on_failure from its live sets and terminate route, writes failed from its recovery sweep, and runs a reconcile that rewrites each stored paused_on_failure checkpoint whose instance the scheduler reports ended, or has no record of, as failed.

Evidence (P1, accessed 2026-11-12). Every durable-execution engine checked treats a failed run as closed, and recovers it by an explicit new action, not a resume:

  • Temporal: Failed is a Closed status, an execution that "cannot make further progress"; reset ends the run and starts a new one from a chosen history point (docs.temporal.io/workflow-execution, docs.temporal.io/kb/failures).
  • Azure Durable Functions / DTF: Failed is a final runtime status (the status API answers 200, "completed or failed"); rewind back to running is still a preview (learn.microsoft.com/azure/azure-functions/durable/durable-functions-http-api).
  • AWS Step Functions: a failed Standard execution stays FAILED; redrive is an explicit API that restarts it from the failed step (docs.aws.amazon.com/step-functions/latest/dg/redrive-executions.html). None of them reports a failed run as paused. This platform has no rewind or redrive; if one is ever built, it is a new decision and a new status, not a revival of this one.

The public API does not change: [Obsolete] adds an attribute, not a member, and the new ExecutionFailureRule is internal. So the commit is not scoped !, following #60, which shipped [Obsolete] members the same way: ! marks a removed or changed member, and nothing is removed. Consumers that name ExecutionStatus.PausedOnFailure get a CS0618 warning on upgrade, which -warnaserror makes an error. That is the point, since each such site has to decide whether it is reading old data. The [Obsolete] message names the replacement (Failed) and the version (v0.57.0), as the deprecation policy above requires; the value is removed only in a major version.

ADR-PA48 — runtime HTTP clients get a timeout, a breaker and a bulkhead per server, and never retry

Consumer task S13.246. Its runtime HTTP clients, mcp-runtime (MCP tool calls) and a2a-agent (A2A agent calls), had no timeout beyond .NET's 100 s default, no breaker and no concurrency limit. Mark decided on 2026-11-12 that they get all three and no HTTP retry, and on 2026-11-16 that this lives here, not in Microsoft.Extensions.Http.Resilience in the consumer.

Why no retry. An MCP connection carries writes as well as reads, and an HTTP handler cannot tell them apart; doc 10 §4 makes mcp-write refuse a write without an idempotency key, and an agent's writes carry none. A2A SendMessage is not idempotent, so a retry is a second paid run (consumer S13.81). And two loops already retry above the call: an mcp_tool node's activity retry and the agent loop's tool-error handling. A third loop would multiply attempts.

Why here and not Microsoft.Extensions.Http.Resilience. That package brings its own outcome predicate (5xx, 408, 429, HttpRequestException, TimeoutRejectedException): a second taxonomy beside FailureClassifier, which doc 10 §1 forbids. Its options bind from configuration and reload, so a deployment could loosen a breaker or turn retry back on without a profile version, against K7 ("governance is data"): a policy change is a catalogue change here. And Polly is reached only through this library.

Decision.

  1. Two data-only profiles, which are not node profiles. mcp-transport (30 s per attempt) and a2a-transport (80 s), both v1, one inner attempt, one outer attempt, and mcp-read's breaker (ratio 0.5, minimum 10, 30 s window, 60 s break) and bulkhead limits (24 concurrent, 48 queued) with the bulkhead's scope authority, because that is where it applies. They live in Phase1ResilienceProfileCatalogue.HttpTransportByProfileId, not in ByProfileId: a workflow node cannot name one as its retry profile, IResiliencePolicyProvider.GetPipeline/GetTaskOptions refuse them, and so does any rule that lists ByProfileId (the consumer's resilience.profile-exists). The handler factory resolves only this set, so it refuses every node profile, all of which retry or (none) were not designed for HTTP. TimeoutHierarchyCheck covers both sets; the transport totals, 90 s and 240 s, pass. none was not reused: its breaker (minimum throughput 1,000,000) never opens.
  2. An HTTP pipeline without retry. ResiliencePipeline<HttpResponseMessage>, composed as doc 10 §4's order minus the retry: Timeout(total) → Bulkhead → CircuitBreaker → Timeout(per-attempt). The total timeout still earns its place: it bounds the wait in the bulkhead's queue. The bulkhead sits outside the breaker, so saturation rejections never open it. No retry strategy exists to configure: every transport profile makes one attempt (a test pins it), because a request body may not be replayable and the HTTP layer must not repeat a write.
  3. One taxonomy. The breaker counts an exception IFailureClassifier calls retryable, or a response whose status FailureClassifier.IsTransientHttpStatus lists — the doc 10 §3 row 2 statuses ClassifyHttp already used (429, 500, 502, 503, 529), now one shared list. A counted response is returned to the caller, not thrown; it only counts. A cancellation the caller asked for never counts. A per-attempt timeout does (TimeoutRejectedException, transient network).
  4. One breaker and one bulkhead per server. A DelegatingHandler picks the pipeline by the request URI's authority. Pipelines are cached in ResiliencePolicyProvider per (profile, client, authority), not in the handler, so IHttpClientFactory's handler rotation never resets a breaker.
  5. Named outcomes. An open breaker throws BrokenCircuitException (transient circuit_open) and a full bulkhead RateLimiterRejectedException (transient bulkhead_rejected); the classifier already mapped both, so neither is unclassified.
  6. One transition stream. Each server's breaker is tracked by CircuitStateProvider with the client name as provider and the authority as modelId. CircuitTransition's wire shape is unchanged; that the consumer's S13.188/D4 metric labels the field "model" is the consumer's naming to settle.
  7. The surface. A sibling interface, IHttpResilienceHandlerFactory.CreateHandler(profileName, clientName) → DelegatingHandler, registered by AddFrontierResilience. DelegatingHandler is a BCL type, so Resilience takes no Microsoft.Extensions.Http dependency; the consumer adds it with AddHttpMessageHandler. It is not a member of IResiliencePolicyProvider, which is consulted from orchestrator bodies and has its own implementers; one capability per interface.

What it does not change. No existing profile, pipeline or wire shape moves. ClassifyHttp's results are identical. The node-facing ByProfileId keeps its seven profiles. The commit is additive (no !).

Known limits, accepted. Pipelines, with their bulkheads and breakers, are cached per (profile, client, authority) for the worker's lifetime: the cache is never evicted and nothing is disposed, which is bounded by the registered servers. HttpClient.Timeout (100 s by default, under a2a-transport's 240 s total) cancels the handler's token, so the breaker sees it as the caller's cancellation and never counts it; the README tells consumers to set it to Timeout.InfiniteTimeSpan. The per-attempt timeout bounds the time to the response headers: once the handler returns, a streamed body (an MCP text/event-stream reply, an A2A stream) is read outside the pipeline, and the activity timeout bounds it. 504 and 408 are not in doc 10 §3 row 2, so they do not count toward the breaker (superseded by the 2026-11-17 amendment below: both are now transient and count). The classifier does not walk inner exceptions, so a client SDK that wraps BrokenCircuitException would classify unclassified; the consumer checks its MCP and A2A clients (partly superseded by the 2026-11-17 amendment: it now looks one level inside an HttpRequestException for a network policy refusal, and only for that; a wrapped BrokenCircuitException is still unclassified).

Evidence (P1, accessed 2026-11-16).

  • Microsoft, Build resilient HTTP apps (learn.microsoft.com/dotnet/core/resilience/http-resilience, ms.date 2026-02-24, updated 2026-03-30): "By default, the standard resilience handler is configured to make retries for all HTTP methods", and "if a POST request inserts a new record to a database, then making retries for such a request could lead to data duplication", offering DisableForUnsafeHttpMethods. The MCP Streamable HTTP transport sends every client message as a POST (modelcontextprotocol.io/specification/2025-06-18/basic/transports: "Every JSON-RPC message sent from the client MUST be a new HTTP POST request"), so that switch would disable retry for all MCP traffic anyway; making one attempt is the same outcome, stated as data.
  • The same page's standard pipeline is rate limiter → total timeout → retry → circuit breaker → attempt timeout; without a retry, its order and doc 10 §4's coincide.
  • Polly v8, Circuit breaker (pollydocs.org/strategies/circuit-breaker, undated): ShouldHandle may handle results as well as exceptions; "The circuit breaker returns the result / exception during the sampling period"; "Once the strategy opens the circuit, every subsequent call will be shortcut with a BrokenCircuitException." Its anti-patterns prefer SelectPipelineByAuthority, by which "the resilience handler caches and assigns" a pipeline to "each authority (scheme + host + port) that is extracted from HTTP request message", over a hand-kept collection the caller must look up; the handler here does that lookup itself, keyed on Uri.Authority (host, and port when not the default). Unlike Polly's key, the scheme is not part of it, so http and https to one host share a breaker; registered servers use one scheme each.

ADR-PA48 — amended 2026-11-17: a network policy refusal is permanent and never counts; 504 and 408 are transient

Consumer tasks S13.300 and S13.301 (Mark, 2026-11-17). Both revise this ADR's known limits.

S13.300 — a policy refusal is permanent. The consumer's network guard (its Registry's NetworkAddressPolicy, run from a SocketsHttpHandler.ConnectCallback) refuses private and otherwise disallowed addresses. SocketsHttpHandler wraps whatever the callback throws in an HttpRequestException with HttpRequestError.ConnectionError and no status code, which the classifier called transient network; a probe on 2026-11-17 showed calls 0–9 classified network and call 10 circuit_open, so ten refusals opened the breaker of a server the policy will never let anyone reach, and the activity retried each one. A refusal is the same on every attempt and is not the server's failure.

  1. A platform type. Frontier.Platform.Abstractions.NetworkPolicyRefusedException (sealed, the three CA1032 constructors). Abstractions, not Resilience: the library-boundaries ownership map puts the permanent-failure exceptions there beside ContractViolationException, BudgetExceededException and GuardrailsSuspendedException; the consumer library that throws it (its Registry) references Serialization and Contracts but not Resilience, and every package carries Abstractions; and the outer retry loop matches it by type name exactly as it matches the other three. The platform cannot name a consumer type, so the consumer's guard throws this one.

  2. Classification. FailureClassifier returns permanent policy_refused for the type thrown bare, and for an HttpRequestException whose direct inner exception is one (PolicyRefusal), checked before the status-code rows. The walk stops at that one level: it is the only wrapping the BCL applies (verified 2026-11-17 against .NET 10.0.8: a SocketsHttpHandler whose callback throws yields an HttpRequestException with a null status and the callback's exception as its inner exception, and no further nesting; SendAsync_TwentyPolicyRefusals_AreNotRetriedAndLeaveTheBreakerClosed pins it with a real SocketsHttpHandler). A deeper walk would let any exception that happened to carry a refusal in its chain skip retry, so a consumer that wraps the refusal in its own exception gets network, as a test pins. The reason code follows doc 10 §3's snake_case vocabulary beside contract_violation and guardrail; the class is Permanent, the existing permanent shape.

  3. No breaker counts it. The transport breaker counts what the classifier calls retryable, so it follows from (2). A node profile's breaker counted every exception but a cancellation (Polly's default), so it now has an explicit predicate (NodeBreakerOutcome) that is Polly's default minus a refusal; every other exception, permanent ones included, still counts. The node retry is classifier-gated, so it stops retrying a refusal. The outer DTF loop refuses to re-run a chain carrying the type at any level, as it does for the other three permanent types; it sees only type names, so it walks the whole chain where the inner classifier looks one level deep. A refusal a consumer nests deeper is therefore retried inside the activity but not re-run across activities; throw it from the callback directly and both agree.

  4. The orchestrator classifies it. GraphOrchestratorSteps.ClassifyFailure, which names the failed checkpoint's failure_classification, gains a policy_refused row beside contract_violation and guardrail, for the type thrown in the body and for a details chain carrying it.

  5. Found along the way, fixed: IsCausedBy<T> in the orchestrator body. DTF's TaskFailureDetails.IsCausedBy<T> resolves the recorded type name across the worker's loaded assemblies and throws AmbiguousMatchException for a type-forwarded BCL type, because System.Net.Http.HttpRequestException resolves through netstandard and through System.Net.Http. Two body paths called it on chains that can carry one, and both threw for every activity failure that was an HttpRequestException, long before this change:

    • the outer retry handler, ResiliencePolicyProvider.HandleOuterRetryFailure. DurableTask.Core 3.11.2's RetryInterceptor.ComputeNextDelay catches a throwing handler and returns TimeSpan.Zero (per the 2026-11-17 PR verification of that package), so the failure was never re-run;
    • the failure path's classification, GraphOrchestratorSteps.ClassifyFailureDetails (reached from ThrowIfFailedAsync), so the run faulted with AmbiguousMatchException before its failed checkpoint and its signed failed-audit consolidation (ADR-PA46) were written. A unit test and a DTS-emulator replay test each reproduced that against the old code, and pass now.

    Both now match by exact full type name, ordinal, loading nothing (TaskFailureCause in Resilience, FailureTypeName in Workflow.Orchestration). That is deterministic: the answer is a pure function of the recorded history, where IsCausedBy's depends on which assemblies the worker happens to have loaded, which no orchestrator-body decision may. An empty recorded type name (one a proto-sourced failure can carry) matches nothing; DTF guards it the same way. Three of the four targets are sealed (BudgetExceededException, GuardrailsSuspendedException, NetworkPolicyRefusedException), so for them the exact name is the whole rule. ContractViolationException is not (ADR-PA34 opened it for derivation): a derived type crossing an activity boundary is no longer recognised by the outer loop or the orchestrator's classification, so the outer loop would re-run it and the checkpoint would say unclassified. The platform's only derived types are ModelRoleConfig's governance refusals (MappingGovernanceRefusalException and its subclasses), and the consumer reaches those services only from its API controllers (ModelRolesController, RoleDefinitionsController), never from an activity, so nothing changes today. Recognising a derived type would need its type loaded, which is exactly the dependency removed; an activity must throw ContractViolationException itself. The live-exception classifier, FailureClassifier, still honours derived types. A test pins DTF's own throw, so a fixed DTF shows up.

    Two new behaviours follow, both orchestrator decisions:

    • An HttpRequestException activity failure is now re-run up to the profile's outerRetry.maxAttempts (it was never re-run). That is what doc 10 §3 states as built (frontier-workflow, docs/10-resilience-library.md, the S13.247 correction): the outer loop refuses only the named permanent types, and "every other failure, an unmapped one included, is re-run up to the profile's outerRetry.maxAttempts". Not re-running it was the bug, not a design; Mark to confirm.
    • Such a run now ends on the failure path, with its failed checkpoint and failed audit record, instead of faulting without them.

    Skew (ADR-E15 style), accepted and recorded. A run in flight when a worker upgrades, whose history already holds an HttpRequestException TaskFailed, replays differently: the retry handler now asks for a retry timer its history lacks, and the failure path now schedules the checkpoint and audit activities where the old run faulted. Either can surface as a non-determinism failure on replay. No deployed environment exists (the consumer is pre-production), so the exposure is local development runs only; drain or terminate those before upgrading. Nothing else is version-gated.

    Not fixed here, latent the same way: the consumer's OrchestrationFactory.ClassifyFailure (frontier-workflow src/Frontier.Reason.Workflow.Integration.Host/OrchestrationFactory.cs, client side) calls IsCausedBy<T> on a faulted orchestration's inner failure, and an HttpRequestException there throws.

S13.301 — 504 and 408 are transient. FailureClassifier.IsTransientHttpStatus adds 504 (Gateway Timeout) and 408 (Request Timeout) to doc 10 §3 row 2's 429, 500, 502, 503 and 529. One list feeds both uses, so a thrown 504/408 classifies transient provider_unavailable (it was permanent unclassified) and the activity retries it, and a returned one counts toward the transport breaker (it did not). Both mean "the server, or one in front of it, timed out": the same request may succeed next time. 501 and 505 stay out: they say the request will never succeed there. Doc 10 §3 row 2 (frontier-workflow) needs the two statuses added; this amendment is the platform's record until it is.

Evidence (P1, accessed 2026-11-17).

  • Microsoft.Extensions.Http.Resilience 10.7.0 (the package in the local NuGet cache), exercised directly: HttpClientResiliencePredicates.IsTransient returns true for 408, 429, 500, 501, 502, 503, 504, 505 and 529, false for 400, 404 and 499, and true for an HttpRequestException with a null status, whatever its inner exception. Its XML doc for IsTransientHttpFailure says it "uses approach proposed by Polly" and links Polly.Extensions.Http's HttpPolicyExtensions.cs (HandleTransientHttpError: 5xx and 408). So Polly's HTTP transient set includes 408 and 504; we adopt those two and not the whole 5xx range, and we do not adopt its "every HttpRequestException" rule, which is what would call a refusal transient.
  • The SocketsHttpHandler wrapping above, observed with the same probe on .NET 10.0.8.

What it does not change. No profile, pipeline order or wire shape moves; FailureClassification and ExecutionSnapshot are unchanged (policy_refused is a new value of an existing string field); the only new public member is the exception type. Behaviour changes, all listed above: a refusal is permanent and never counts toward a breaker; 504/408 are transient and count; an HttpRequestException activity failure is re-run by the outer loop and its run ends failed with a checkpoint and an audit record rather than faulting; a type derived from ContractViolationException is no longer recognised across an activity boundary. Additive surface (no !); release minor, v0.59.0 proposed.

What the consumer does. After bumping: its connect-time guard throws NetworkPolicyRefusedException (not CardFetchException) from the ConnectCallback, with a message naming the host and the rule; the registration-time card fetch (HttpServerCardFetcher, whose filter today is ex.InnerException is CardFetchException) matches an inner NetworkPolicyRefusedException instead and still maps it to its own CardFetchException. Its "resolved to no addresses" case is the consumer's to place: a DNS answer is not a policy decision, and left as it is it stays transient network. It adds tests that a refused runtime MCP/A2A call classifies policy_refused, that twenty leave the server's breaker closed and are not re-run by the activity, and that a returned 504/408 is retried; it moves OrchestrationFactory.ClassifyFailure to the same exact-name match and gives it a policy_refused row; and it amends doc 10 §3 (the two statuses in row 2, a policy_refused row, and the outer loop's fourth permanent type).