docs: propose session-independent execution correlation (#565)

[Yatsuiii]

What

Records the agreed design for #565 in docs/spec/execution-correlation.md.

The document keeps the current identity finding prominent. initialize creates no client negotiated identity. session_id and call_id are gateway generated. workflow_id is supplied by the caller but is not a validated execution identity.

Settled decisions

1. execution_id is a typed AuditEntry field, not a detail key.
2. Collision within one authenticated agent identity is refused.
3. The TRACE Claim does not enumerate execution_id values.
4. Reuse after a terminal outcome is refused with no replay window.
5. execution_id and workflow_id remain independent.

Claim boundary

The document records the boundary raised in trace-spec#66:

attempt identity ≠ logical operation identity ≠ external outcome identity

A shared execution_id establishes correlation only. Treating two requests as the same logical operation also requires an immutable canonical action or intent binding. A different binding under the same identifier is a collision or mutated operation and must be refused. This change does not invent another schema field for that binding.

Correctness requirements

Collision and replay enforcement requires authoritative execution state keyed by authenticated agent identity and execution_id. Reservation must occur atomically before upstream invocation, and terminal state must be durable before later replay classification.

Scope

Documentation only. No running behavior or schema changes are made in this PR.

Verification

1. git diff --check passes.
2. Ruff passes for src/cmcp_runtime, src/cmcp_verify, and tests.
3. MyPy passes for 64 source files.
4. All cited source locations were checked against the current branch.
5. The complete local test command stalled in gateway conformance and was stopped. GitHub CI remains required for the final verdict.

DCO sign off

I certify that I wrote or have the right to submit this contribution and agree to the Developer Certificate of Origin.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[imran-siddique]

Ruling on all five. You were right not to settle them alone, and right that a wrong shape here propagates into #566, #567 and #568.

First, the finding, because it is the part that stands regardless of what happens to the proposal. Verified at pinned 21df5b42: initialize at server.py:449 negotiates a protocol revision and mints nothing, and manager.py:118 is session_id = str(uuid4()), gateway-side. So "MCP session" suggests a client-negotiated identity that does not exist. That is the same discovery your #571 thread reached from the other direction, where call_id is also a fresh server-side uuid4. Three identifiers, none of them correlatable by the caller. Write that down in the document even if everything below changes.

1. Field on AuditEntry, not detail

A field. The schema change is the smaller cost.

detail is where things go when we have not decided what they are. Something the verifier must key on, and that #567 and #568 will both consume, is not that. Putting a correlation identifier in a free-form dict means every consumer re-derives its own expectations about presence, type and absence, and they will not agree.

The append-only hashed structure argues for a field rather than against one: a typed field that is always present, even as null, hashes predictably, while a key that appears in detail only sometimes changes the shape of what is hashed depending on a value's presence.

2. Collision: refuse

Refuse, inside a single agent identity.

A correlation identifier whose collisions are recorded rather than refused is not an identifier, it is a hint, and everything built on it inherits the ambiguity. #568 in particular cannot do anything useful with "these two executions might be the same one".

Refusing is also the honest failure: a caller that reuses an execution_id has a bug or is an attacker, and both should be told immediately rather than discovered by an auditor later.

3. No, the TRACE Claim does not enumerate them

An enumeration is unbounded, grows with session length, and duplicates what the audit chain already orders. The Claim binds the chain; the chain carries the identifiers.

There is also a disclosure argument: a Claim is the artifact most likely to be shared outside the operator, and a list of execution identifiers leaks work volume and shape to a reader entitled only to verify one record.

4. "Refuse reuse after a terminal outcome" is enough. No replay window.

A window is a clock, and a clock is a second source of truth that has to be synchronised, configured and reasoned about at verification time years later. We have just spent a week on what happens when a verifier's clock disagrees with an issuer's.

Terminal outcome is already the boundary this system understands. #571 landed not_attempted and outcome_unknown precisely to make that boundary explicit, so key the refusal on it and inherit the work rather than introducing a parallel notion of expiry.

One consequence to write down: an execution that never reaches a terminal outcome is never reusable and never expires. That is the fail-closed direction and it is correct, but it means a stuck execution holds its identifier permanently, and someone should know that before they see it.

5. Independent of workflow_id

They answer different questions. workflow_id groups work that belongs together by intent; execution_id identifies one unit of work for correlation across requests. Deriving either from the other collapses two questions into one and the collapse is not reversible.

Independent, with the relationship documented rather than encoded. If it turns out every execution_id in practice has exactly one workflow_id, that is an observation worth recording, not a constraint worth enforcing.

What I would like

Fold these into the document as decided rather than open, keep the initialize/uuid4 finding prominent, and mark it agreed rather than proposed. Then it is the thing #566, #567 and #568 build against.

Merging once that lands. Thanks for opening it for argument instead of implementing a guess.

[imran-siddique]

All five landed, and you carried the consequences rather than just the verdicts. That is the difference between a document that records a decision and one that can be built against.

Two places where that shows.

On the replay window. I said key the refusal on terminal outcome and inherit #571's work. You wrote:

This rule includes outcome_unknown: uncertainty must not become permission to repeat an irreversible effect.

That sentence is doing more than the rule I gave you. outcome_unknown is exactly the state where a retry layer is most tempted to try again, and saying plainly that uncertainty is not permission closes the reading where someone treats "we do not know" as "so it probably did not happen".

On the cost of that choice. I asked you to write down that a stuck execution holds its identifier forever, and you did, including the part I had not said:

A stuck execution therefore holds its identifier until an explicit recovery design exists. This is the fail closed result.

Naming that a recovery design does not exist yet, rather than leaving the reader to discover it, is what stops this being rediscovered as a bug in six months.

Two additions I did not ask for and would have wanted.

Scoping collision so the same value under different agent identities does not collide. My ruling said refuse within one agent identity and I did not say what happens across identities; leaving that implicit would have produced a verifier that refuses legitimate values from unrelated agents.

And a missing execution_id recording null in the typed field rather than synthesizing one, which gives consumers the property that matters: "a present value came from the validated caller path." A synthesized identifier would have looked identical to a real one, which is the same class of defect as the reported-but-unenforced fields we have been fixing all week.

Keeping the reasoning on workflow_id rather than only the answer is right too. "If operational evidence later shows a one to one relationship, that is an observation, not a constraint" is the sentence that stops someone encoding the correlation the first time they notice it.

Docs only, real checks green. Merging, and this is now the shape #566, #567 and #568 build against.

Thanks for opening it as a proposal and arguing the shape first. The five questions were the right five, and I would rather answer those than review an implementation of a guess.