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.
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.
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.
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.
ContractTypeSetTestsarrived 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.
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.
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.
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.
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.
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.
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.
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.
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 —
AuditSignerderives the audit record's partition key from it,CosmosAuditRecordStorederives the partition key it reads by,AuditConsolidatorwrites 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.
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.
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.
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.
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.
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.
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.
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.
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.
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;RunIdandStartedAtUtcare 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.
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).
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. |
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.
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.
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.
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.
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.
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.RecordUsageAsyncrefuses usage whose currency differs from the engagement's recorded usage, before storing it;CosmosBudgetLedger.RecordUsageAsyncrefuses usage whose currency differs from the ledger document'scurrency. One currency per engagement makes every scope aggregate (invocation, execution, engagement) single-currency by construction. - hierarchy aggregation —
BudgetHierarchy.BudgetHasCapacitychecks, before adding, that the scope ceiling, the snapshot's accumulated cost and the estimate share a currency. A snapshot with nothing recorded has anullcurrency and combines with anything. A ceiling with no currency is refused. - admission —
AdmissionController.Admitrefuses 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.
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.
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.
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.
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.
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.
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 fromcancelled, which no person asked for by name.ExecutionSnapshotgainsterminated_by,termination_reasonandterminated_at_utc(orders 24–26).Validate()requires all three on a terminated snapshot, as it requiresfailure_classificationon apaused_on_failureone. 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 assystem: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 gainswithdrawn_byandwithdrawal_reason(orders 12–13, afterttl).- The sandbox test-run mapping treats
terminatedas terminal, likecancelled.
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.
IApprovalStoregainsWithdrawAsync(engagementId, approvalId, withdrawnBy, withdrawalReason)andEscalateAsync(engagementId, approvalId). Both return anApprovalTransitionResult, which isapplied,refusedwith the stored record, ornot_found.- They run over the same read, check and replace loop as
DecideAsync, nowApprovalTransitioner. 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:
pendingandescalated. - An escalation accepts
pending,escalated(a retried activity) and adecidedrequest whose decision is the approver's ownescalate. That last case is what the unguarded write did: the approver's escalate is recorded throughDecideAsync, 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. EscalateApprovalActivitynow writes throughEscalateAsyncand 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, thewithdrawnstatus value and the two optional withdrawal members, asactivity-shapes.jsonrecords.- Each transition names the statuses it accepts, so a status added later is refused by construction.
ApprovalStatusTransitionsTestsclassifies every value ofApprovalRequestStatus.Listin one explicit table and fails when a value is missing from it. - The scripted
ApprovalLifecycleTestsdrive 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.
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.
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.
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.
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_hashfrom stored fields withoutput_hashas 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 bycorrelation_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. Nohash_algorithmfield was added; that would be a schema change acrossStepCompletionand 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_hashvalues 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-archivehas 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.
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.
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
$refor$dynamicRefnot 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
additionalPropertiesorunevaluatedProperties;falseis the default to aim for,trueopts out. Nothing rewrites what the author registered. Branches ofallOf,anyOf,oneOf,if,thenandelseare 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, andformatand thecontent*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.
selfis typed from the schema (Mark, 2026-10-29).CelSchemaTypesmaps an object withpropertiesto a struct namedcontract.S{n}, an object without tomap(string, T), an array tolist(T), and anything it cannot type exactly (unions,oneOf, a type list, an anchor$ref) todyn. 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.
RuleCostHintsanswers Celly's estimator withmaxItems,maxLengthandmaxProperties, maps each loop variable to the element schema of the range it iterates by reading the syntax tree, and bounds the list amap()orfilter()builds by its range. An unbounded estimate is refused, as is one overMaxRuleCost(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 itsfield_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.
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 carryfrontier/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-resolvesalso holds anmcp_toolnode'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, aRoleBackingsmart enum,modeloragent;input_contract_refandoutput_contract_ref, ADR-E2 schema refs ({namespace}/{name}/{major}.{minor});input_contract_hashandoutput_contract_hash, stamped by approval, never taken from a caller;definition_version,approved_byandeffective_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_typerole_definition, append-only;{roleId}:definition:current,doc_typerole_definition_current, the pointer;{roleId}:definition-proposal:{id},doc_typerole_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_hashandoutput_contract_hashon 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.IsWellFormedexposes the grammar the same way, so the consumer restates neither. - The compiler reuses
RoleBacking.AgentRoleDescriptor.Backingis the ModelRoleConfig smart enum (the Compiler already references that library), serialized asbacking. It defaults tomodel, so a catalogue that does not say gets the stricter reading. agent.instructions-resolvereads the agent-role catalogue. It takesIAgentRoleCatalogalongsideIInstructionCatalog, 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-existreports 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.InstructionsRefisstring?, 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 anAgentEntrytarget invokes with empty instructions and never callsIInstructionsResolver; no ref on a model target is aContractViolationExceptionraised 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:
McpToolRefcarries 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.IMcpWriteClassifierkeeps 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.
DesignerToolDescriptorgains an optionalwrites: 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 anidempotency_key_spec.mcp.write-idempotencystill requires a spec on everymcp_toolnode; a read exemption on the pinned flag is a later change.mcp.tool-resolvesholds the node'swritesto 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_refsare 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-resolvesfinding, not a silent edit. ADR-PA39's embedding at publish refuses in the same way. - Not on a plain draft save.
SaveDraftAsyncreturns 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
outputSchemahas no output contract ref (consumer register S3-2), so the copy leavesoutput_contract_typenull 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_taskbound 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_toolnode's contract refs andwritesare 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 aListAsync(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.Contractsas 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, theEngagementIdand the smart enum) exports astrue, 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, theDateTimeand the smart enum into their wire schemas. It leavesEngagementIdastrue. And once a property carries a[Description], the export arrives as a description-only object rather thantrue, 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
CanonicalOutputSchemagives 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 passesIContractRegistrationCheckas a generated contract.CanonicalOutputSchema's rewrite is corrected in the same change to recognise the description-only node and to giveEngagementIdits 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, soMcpToolActivityInput.OutputContractis set) and the reply is not the sandbox's simulated ack, the pipeline takesstructuredContentout of the reply, validates it against the pinned contract, and records it as the step's output:output_payloadis its canonical JSON in the tool's key order, andoutput_hashis taken over its RFC 8785 form, as for any payload (ADR-E2 decision 2). Thecontentblocks 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 aCallToolResultobject at all, is a permanentContractViolationExceptionnaming the contract, whose one violation says the result has nostructuredContentand that a tool declaring anoutputSchemamust return it. It is never retried: a contract ref is pinned only for a tool registered with anoutputSchema(consumer register S3-2), so the tool broke its own declaration. isErrorkeeps today's handling. A result withisError: trueis 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
structuredContentandisErrorby 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
CallToolResultrecords itsstructuredContentand 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: trueis held whole;isError: falserecords itsstructuredContent; 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, afterdynamic_context_hash), a list ofMcpToolInvocation:correlation_id,node_id,artifact_key,tool_ref,input_contract_type,input_hash,output_contract_type,output_hash,input_contract_hash,output_contract_hash,simulatedandcompleted_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 issimulated: truewith no output contract hash, as its step already has. The name followsAgentInvocation; it is not aToolCall, which is a call an agent made inside its invocation. - Signed, through the existing path.
SignedAuditRecordcarries the field afterdynamic_context_hash, andAuditRecordHashercopies it both ways, so it sits insiderecord_hashand 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_refandinput_contract_type, copied from the node in the orchestrator body (replay-safe: the definition rides inline),input_hashfrom the activity result, andsimulated(trueor 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_completedevent is still on the timeline. No schema version moves: this is an additive, optional change, the canonical profile's minor-change rule, assandboxand the context pin were. - Pinned by the new
audit_record_mcp_tool_invocations.json,signed_audit_record_mcp_tool_invocations.jsonandexecution_snapshot_mcp_step.jsongolden 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-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, aswriteswas onmcp_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_toolnode: a tool registered before contracts were data (consumer S13.117) has no contract ref, so the node holds null andmcp.tool-resolvespasses null only against null. An agent's entry does the same, soinput_contract_typeis nullable on the entry, though the register's sketch showed it required; the entry still exists, because it pinswrites, and because a tool_ref without one is refused. A tool with nooutputSchemalikewise 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 unpinnedmcp_tooldrafts 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
AgentTaskActivityInputas 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. IMcpToolCatalogtakes 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_toolhalf-pin gap closes (item 5): the sandbox's write fence follows the node's pinnedwrites, 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 existingPinnedContractlookup overWorkflowDefinition.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 beforewrites), and the catalogue resolves that fact as before. - Agent steps.
AgentTaskActivityInputgainstool_pins(order 17, afteroutput_contract), one pin pertool_contractsentry in its order, null when the node has none. Left out when null, so every input recorded before it keeps its bytes. mcp_toolsteps (item 5). The orchestrator already decides the idempotency key and retry profile from the node'swrites(ADR-PA41); the fence did not, because the consumer's catalogue classified the tool itself on the newest registry version.McpToolActivityInputgainswrites(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 newpins(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 nullpinsfalls 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.
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.
RegexMatchTimeoutMillisecondsstays inContractsOptions(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_costwould 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-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-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 onAuditTelemetryRecord.host_build(order 23) by the agent pipeline from the sameIHostBuildStampvalue its result carries, and copied by the consolidator's projection.McpToolInvocation.host_build(order 12), copied from the step's recordedStepCompletion.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.
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),
ThrowIfFailedAsyncwrites thepaused_on_failurecheckpoint as before, then callsConsolidateAuditActivitywithConsolidateAuditInput.final_status = failed, then rethrows the node's failure. The orchestration does end failed, and the checkpoint stayspaused_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 fromcontext.CurrentUtcDateTimeat 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
GetFailureInfoAsyncclassifies. An audit failure would replace it with an unclassified one. The missing record stays detectable: the run is terminal and has noaudit-recordsentry. - 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
terminatedsnapshot, thenIAuditConsolidator.ConsolidateAsync(withfinal_status = terminatedor null), thenIAuditSigner.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_failurecheckpoint, so there is no failure to attest; those runs still end without a record, as before (RunAsync_FailsOutsideTheNodeDrain_ConsolidatesNoAudit, which also fails thepaused_on_failurewrite 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 §3classification(required), and thenode_id,exception_typeand boundedmessageof the checkpoint'sfailure_detail(S13.120) when it recorded one.AuditRecord.termination/SignedAuditRecord.termination(orders 20 and 24):TerminationRecord,terminated_by,reasonandterminated_at_utcfrom 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_completedevent names the attested status. Validate()on both shapes requiresfailurewith a classification whenfinal_statusisfailed, andterminationwith an actor and a reason when it isterminated. No other status is checked.- The consolidator refuses to attest
failedorterminatedwhen the latest snapshot does not back the claim, with a permanentContractViolationException. 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 !.
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.
- The orchestrator writes
failed. After the drain (ADR-5 D4's drain is unchanged: siblings finish, no new node starts), the last checkpoint isfailed, carrying whatpaused_on_failurecarried: the failing node ascurrent_node_id, the doc 10 §3failure_classification, and thefailure_detailof S13.120. ADR-PA46's audit call and the rethrow follow as before. - A failed snapshot must say what kind of failure.
ExecutionSnapshot.Validate()requiresfailure_classificationforfailed, as it did forpaused_on_failure. Nothing wrote afailedsnapshot before this change, so no stored snapshot starts failing validation. paused_on_failurestays readable and is never written. The value stays inExecutionStatus, 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.- 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.
- Readers treat both statuses as one fact.
TestRunExecutionmapsfailedand 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:
Failedis 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.
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.
- Two data-only profiles, which are not node profiles.
mcp-transport(30 s per attempt) anda2a-transport(80 s), both v1, one inner attempt, one outer attempt, andmcp-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 scopeauthority, because that is where it applies. They live inPhase1ResilienceProfileCatalogue.HttpTransportByProfileId, not inByProfileId: a workflow node cannot name one as its retry profile,IResiliencePolicyProvider.GetPipeline/GetTaskOptionsrefuse them, and so does any rule that listsByProfileId(the consumer'sresilience.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.TimeoutHierarchyCheckcovers both sets; the transport totals, 90 s and 240 s, pass.nonewas not reused: its breaker (minimum throughput 1,000,000) never opens. - 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. - One taxonomy. The breaker counts an exception
IFailureClassifiercalls retryable, or a response whose statusFailureClassifier.IsTransientHttpStatuslists — the doc 10 §3 row 2 statusesClassifyHttpalready 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, transientnetwork). - One breaker and one bulkhead per server. A
DelegatingHandlerpicks the pipeline by the request URI's authority. Pipelines are cached inResiliencePolicyProviderper (profile, client, authority), not in the handler, soIHttpClientFactory's handler rotation never resets a breaker. - Named outcomes. An open breaker throws
BrokenCircuitException(transientcircuit_open) and a full bulkheadRateLimiterRejectedException(transientbulkhead_rejected); the classifier already mapped both, so neither isunclassified. - One transition stream. Each server's breaker is tracked by
CircuitStateProviderwith the client name asproviderand the authority asmodelId.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. - The surface. A sibling interface,
IHttpResilienceHandlerFactory.CreateHandler(profileName, clientName) → DelegatingHandler, registered byAddFrontierResilience.DelegatingHandleris a BCL type, so Resilience takes noMicrosoft.Extensions.Httpdependency; the consumer adds it withAddHttpMessageHandler. It is not a member ofIResiliencePolicyProvider, 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):
ShouldHandlemay 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 preferSelectPipelineByAuthority, 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 onUri.Authority(host, and port when not the default). Unlike Polly's key, the scheme is not part of it, sohttpandhttpsto 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.
-
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 besideContractViolationException,BudgetExceededExceptionandGuardrailsSuspendedException; 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. -
Classification.
FailureClassifierreturns permanentpolicy_refusedfor the type thrown bare, and for anHttpRequestExceptionwhose 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: aSocketsHttpHandlerwhose callback throws yields anHttpRequestExceptionwith a null status and the callback's exception as its inner exception, and no further nesting;SendAsync_TwentyPolicyRefusals_AreNotRetriedAndLeaveTheBreakerClosedpins it with a realSocketsHttpHandler). 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 getsnetwork, as a test pins. The reason code follows doc 10 §3's snake_case vocabulary besidecontract_violationandguardrail; the class isPermanent, the existing permanent shape. -
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. -
The orchestrator classifies it.
GraphOrchestratorSteps.ClassifyFailure, which names the failed checkpoint'sfailure_classification, gains apolicy_refusedrow besidecontract_violationandguardrail, for the type thrown in the body and for a details chain carrying it. -
Found along the way, fixed:
IsCausedBy<T>in the orchestrator body. DTF'sTaskFailureDetails.IsCausedBy<T>resolves the recorded type name across the worker's loaded assemblies and throwsAmbiguousMatchExceptionfor a type-forwarded BCL type, becauseSystem.Net.Http.HttpRequestExceptionresolves throughnetstandardand throughSystem.Net.Http. Two body paths called it on chains that can carry one, and both threw for every activity failure that was anHttpRequestException, long before this change:- the outer retry handler,
ResiliencePolicyProvider.HandleOuterRetryFailure. DurableTask.Core 3.11.2'sRetryInterceptor.ComputeNextDelaycatches a throwing handler and returnsTimeSpan.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 fromThrowIfFailedAsync), so the run faulted withAmbiguousMatchExceptionbefore itsfailedcheckpoint 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 (
TaskFailureCausein Resilience,FailureTypeNamein Workflow.Orchestration). That is deterministic: the answer is a pure function of the recorded history, whereIsCausedBy'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.ContractViolationExceptionis 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 sayunclassified. The platform's only derived types are ModelRoleConfig's governance refusals (MappingGovernanceRefusalExceptionand 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 throwContractViolationExceptionitself. 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
HttpRequestExceptionactivity failure is now re-run up to the profile'souterRetry.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'souterRetry.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
failedcheckpoint 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
HttpRequestExceptionTaskFailed, 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-workflowsrc/Frontier.Reason.Workflow.Integration.Host/OrchestrationFactory.cs, client side) callsIsCausedBy<T>on a faulted orchestration's inner failure, and anHttpRequestExceptionthere throws. - the outer retry handler,
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.Resilience10.7.0 (the package in the local NuGet cache), exercised directly:HttpClientResiliencePredicates.IsTransientreturns true for 408, 429, 500, 501, 502, 503, 504, 505 and 529, false for 400, 404 and 499, and true for anHttpRequestExceptionwith a null status, whatever its inner exception. Its XML doc forIsTransientHttpFailuresays it "uses approach proposed by Polly" and linksPolly.Extensions.Http'sHttpPolicyExtensions.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 "everyHttpRequestException" rule, which is what would call a refusal transient.- The
SocketsHttpHandlerwrapping 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).