fix(runtime): isolate an unclaimed control fact from the session view by Astro-Han · Pull Request #1618 · apache/maka

Astro-Han · 2026-07-29T14:36:40Z

Summary

One RuntimeEvent the projection does not claim made an entire session unreadable, even when every message in it was intact. The projection emitted a hard unsupported_event for any unrecognised shape, RuntimeReadModel.buildView throws on any hard diagnostic, and the whole projection was discarded — failing every getSessionView caller, not just the transcript: branching, revising, and every turn-scoped action went with it. #1607 was one instance; #1609 claimed those two shapes but left the amplification in place.

The hard failure is deliberate — it exists so messages are never silently dropped — so this splits it rather than relaxing it wholesale:

unclaimed and content-bearing → a reader may be missing a row, the view is not faithful → stays unsupported_event, hard.
unclaimed and control-only → there is no row to lose, while discarding the projection costs every intact message beside it → new unclaimed_control_fact, soft.

Severity now lives in one table keyed by code, so a new diagnostic cannot exist without deciding which side it falls on, and buildView asks the projection instead of restating the codes.

What makes the soft side safe is claim coverage, not the absence of content. Actions do own user-visible rows — permissionDecision, tokenUsage, and the terminal fact all produce one, and runtime-event-backfill.ts already writes a content-free event that projects to a visible permission_decision. Nothing with a row reaches the degrading branch only because every action field a reader can meet is claimed, so the projection-coverage contract now has to prove exactly that.

The contract previously enumerated BackendSessionEvent['type'] alone, which left every RuntimeEvent produced outside mapSessionEventToRuntimeEvent uncovered — tool-runtime, terminal-run-commit, and runtime-event-backfill all write actions directly. It now also enumerates every field of RuntimeEventActions, keyed so a new field cannot compile without a sample and cannot pass without being claimed.

Writing that contract found three action fields the projection had never claimed: artifactDelta, transferToAgent, and runtimeProtocol. The first two have no emitter yet. runtimeProtocol does — runtime-runner.ts writes it, and RecoveryResolver reads it; it only ever avoided breaking a session because it has so far always ridden on an already-claimed carrier. All three are now claimed as control facts.

#1609 declined this downgrade because it "would hide a future projection gap". That is answered by keeping the two questions separate: severity decides whether a session opens, the coverage contract decides whether coverage is missing. The contract asserts on the union of both unclaimed codes, so softening a severity cannot soften the contract.

Closes#1613. Refs #1607, #1609.

Verification

@maka/runtime full suite: 2795 tests, 2786 pass, 0 fail, 9 skipped. @maka/headless 1428 pass, CLI 668 pass, 0 fail.
End-to-end reproduction: a backend emits a SessionEvent variant the mapping was never taught, the turn completes through a real sendMessage, and the session reads back intact with the unclaimed event reported as one unclaimed_control_fact. Reverting the fallback to always-hard makes it fail with the original RuntimeReadModelError.
Its counterpart pins the caller: appending a content-bearing unclaimed event to a completed run's ledger must make getSessionView throw. Verified to bite by making the fallback unconditionally soft.
The coverage contract was checked in both directions: removing the runtimeProtocol claim fails it at runtime; removing its table entry fails compilation with TS2741.
The unclaimed predicate is now asserted through itself, so dropping unclaimed_control_fact from it can no longer silently narrow both contracts to unsupported_event.
Claim strictness is untouched: fix(runtime): reload completed sessions after sandbox boundary decisions #1609's eight malformed-boundary counter-examples still assert the event stays unclaimed; only its severity moved.
Test-merged with fix/sandbox-boundary-pending-restart (fix: let a pending sandbox boundary request survive a host restart #1612), which touches the same file: auto-merges clean, combined suite green.
npm run format, npm run lint, npm run typecheck --workspaces clean. Not run: desktop E2E — this change does not reach renderer or main.

Review focus

A malformed control fact — one that half-matches a known shape — is soft alongside a genuinely unknown one. The read model is not the enforcement authority (boundary enforcement has its own durable revisions) and an unopenable session is the worst answer available, but if ledger corruption should outrank forward compatibility that argues for a third severity tier, which this PR does not add.

stateDelta is an open record, so the contract can only cover the field's existence, not new keys inside the delta. That limit is recorded in the table rather than papered over.

artifactDelta and transferToAgent are claimed as silent control facts before either has an emitter. If a hand-off should eventually render as a visible row, that claim is where it has to change.

RuntimeReadModel decided which projection diagnostics are fatal by restating their codes, so the projection declared the diagnostics and its caller declared what they mean. Move that decision next to the codes as a table keyed by `RuntimeEventReadModelDiagnosticCode`: a new diagnostic cannot compile without saying whether it means a user-visible row may be missing. The caller and the persisted-compat test now ask that authority instead of listing codes. No behavior change — the table restates today's hard set exactly.

One RuntimeEvent the projection did not claim made an entire session unreadable. The catch-all emitted a hard `unsupported_event`, RuntimeReadModel threw on it, and the whole projection went with it — so getMessages, listTurns, branching, revising and every turn-scoped action failed over a fact that owns no chat row. #1607 was one instance; #1609 claimed those two shapes but left the amplification in place. Split the catch-all on the RuntimeEvent's own structure: `content` is its message payload, `actions` its control intent. Every row this projection emits from an unclaimed shape would have come from content, so a content-bearing event stays hard — "a message is never silently dropped" is the invariant the hard failure exists for. A control-only fact has nothing to lose, so it becomes `unclaimed_control_fact` and degrades the view instead of discarding it. A projector that tried to build a row and failed still reports its own hard diagnostic, so this softens nothing that attempted a message. A future gap is still caught before a user meets it. The projection-coverage contract now asserts on the unclaimed codes at either severity rather than the hard one alone, so a new SessionEvent variant with no claim still fails CI, and AiSdkFlow's exhaustiveness guard is what a variant becomes: a content-free control fact that lands on the degradable side by construction. Fixes#1613

…meet The soft path rests on a premise that was not machine-checked: an unclaimed content-free event degrades the view instead of withholding it, which is only safe while no unclaimed action can owe a row. `content === undefined` does not prove that on its own — permissionDecision, tokenUsage and the terminal fact all produce rows, and runtime-event-backfill already writes a content-free event that becomes a visible `permission_decision`. What actually holds the rule up is claim coverage, so make coverage the thing that is proven. The SessionEvent contract only covers events built by `mapSessionEventToRuntimeEvent`; tool-runtime, terminal-run-commit and the backfill write RuntimeEvents directly, so a new action field on those paths was invisible to it. A second contract keyed on `RuntimeEventActions` gives every field a reachable sample typed to its own key: a new field cannot compile without one and cannot pass without being claimed. Writing it found three fields the projection never claimed — `artifactDelta`, `transferToAgent` and `runtimeProtocol`, the last of which real emitters already write. All three are control-only, so claim them, and say in the fallback what the rule actually depends on.

Two regressions the suite could not see. The unmapped-SessionEvent test compared the raw code string, so dropping `unclaimed_control_fact` from `isUnclaimedRuntimeEventDiagnostic` would have quietly narrowed the coverage contract to `unsupported_event` with every test still green; it now filters through the predicate itself. And the hard side was only asserted inside the projector, so a caller that stopped enforcing the policy went unnoticed: append a content-bearing unclaimed event to a completed run's ledger and getSessionView must still refuse the view — the counterpart of the soft reproduction beside it.

Astro-Han · 2026-07-29T14:36:40Z

Summary

One RuntimeEvent the projection does not claim made an entire session unreadable, even when every message in it was intact. The projection emitted a hard unsupported_event for any unrecognised shape, RuntimeReadModel.buildView throws on any hard diagnostic, and the whole projection was discarded — failing every getSessionView caller, not just the transcript: branching, revising, and every turn-scoped action went with it. #1607 was one instance; #1609 claimed those two shapes but left the amplification in place.

The hard failure is deliberate — it exists so messages are never silently dropped — so this splits it rather than relaxing it wholesale:

unclaimed and content-bearing → a reader may be missing a row, the view is not faithful → stays unsupported_event, hard.
unclaimed and control-only → there is no row to lose, while discarding the projection costs every intact message beside it → new unclaimed_control_fact, soft.

Severity now lives in one table keyed by code, so a new diagnostic cannot exist without deciding which side it falls on, and buildView asks the projection instead of restating the codes.

What makes the soft side safe is claim coverage, not the absence of content. Actions do own user-visible rows — permissionDecision, tokenUsage, and the terminal fact all produce one, and runtime-event-backfill.ts already writes a content-free event that projects to a visible permission_decision. Nothing with a row reaches the degrading branch only because every action field a reader can meet is claimed, so the projection-coverage contract now has to prove exactly that.

The contract previously enumerated BackendSessionEvent['type'] alone, which left every RuntimeEvent produced outside mapSessionEventToRuntimeEvent uncovered — tool-runtime, terminal-run-commit, and runtime-event-backfill all write actions directly. It now also enumerates every field of RuntimeEventActions, keyed so a new field cannot compile without a sample and cannot pass without being claimed.

Writing that contract found three action fields the projection had never claimed: artifactDelta, transferToAgent, and runtimeProtocol. The first two have no emitter yet. runtimeProtocol does — runtime-runner.ts writes it, and RecoveryResolver reads it; it only ever avoided breaking a session because it has so far always ridden on an already-claimed carrier. All three are now claimed as control facts.

#1609 declined this downgrade because it "would hide a future projection gap". That is answered by keeping the two questions separate: severity decides whether a session opens, the coverage contract decides whether coverage is missing. The contract asserts on the union of both unclaimed codes, so softening a severity cannot soften the contract.

Closes#1613. Refs #1607, #1609.

Verification

@maka/runtime full suite: 2795 tests, 2786 pass, 0 fail, 9 skipped. @maka/headless 1428 pass, CLI 668 pass, 0 fail.
End-to-end reproduction: a backend emits a SessionEvent variant the mapping was never taught, the turn completes through a real sendMessage, and the session reads back intact with the unclaimed event reported as one unclaimed_control_fact. Reverting the fallback to always-hard makes it fail with the original RuntimeReadModelError.
Its counterpart pins the caller: appending a content-bearing unclaimed event to a completed run's ledger must make getSessionView throw. Verified to bite by making the fallback unconditionally soft.
The coverage contract was checked in both directions: removing the runtimeProtocol claim fails it at runtime; removing its table entry fails compilation with TS2741.
The unclaimed predicate is now asserted through itself, so dropping unclaimed_control_fact from it can no longer silently narrow both contracts to unsupported_event.
Claim strictness is untouched: fix(runtime): reload completed sessions after sandbox boundary decisions #1609's eight malformed-boundary counter-examples still assert the event stays unclaimed; only its severity moved.
Test-merged with fix/sandbox-boundary-pending-restart (fix: let a pending sandbox boundary request survive a host restart #1612), which touches the same file: auto-merges clean, combined suite green.
npm run format, npm run lint, npm run typecheck --workspaces clean. Not run: desktop E2E — this change does not reach renderer or main.

Review focus

A malformed control fact — one that half-matches a known shape — is soft alongside a genuinely unknown one. The read model is not the enforcement authority (boundary enforcement has its own durable revisions) and an unopenable session is the worst answer available, but if ledger corruption should outrank forward compatibility that argues for a third severity tier, which this PR does not add.

stateDelta is an open record, so the contract can only cover the field's existence, not new keys inside the delta. That limit is recorded in the table rather than papered over.

artifactDelta and transferToAgent are claimed as silent control facts before either has an emitter. If a hand-off should eventually render as a visible row, that claim is where it has to change.

RuntimeReadModel decided which projection diagnostics are fatal by restating their codes, so the projection declared the diagnostics and its caller declared what they mean. Move that decision next to the codes as a table keyed by `RuntimeEventReadModelDiagnosticCode`: a new diagnostic cannot compile without saying whether it means a user-visible row may be missing. The caller and the persisted-compat test now ask that authority instead of listing codes. No behavior change — the table restates today's hard set exactly.

One RuntimeEvent the projection did not claim made an entire session unreadable. The catch-all emitted a hard `unsupported_event`, RuntimeReadModel threw on it, and the whole projection went with it — so getMessages, listTurns, branching, revising and every turn-scoped action failed over a fact that owns no chat row. #1607 was one instance; #1609 claimed those two shapes but left the amplification in place. Split the catch-all on the RuntimeEvent's own structure: `content` is its message payload, `actions` its control intent. Every row this projection emits from an unclaimed shape would have come from content, so a content-bearing event stays hard — "a message is never silently dropped" is the invariant the hard failure exists for. A control-only fact has nothing to lose, so it becomes `unclaimed_control_fact` and degrades the view instead of discarding it. A projector that tried to build a row and failed still reports its own hard diagnostic, so this softens nothing that attempted a message. A future gap is still caught before a user meets it. The projection-coverage contract now asserts on the unclaimed codes at either severity rather than the hard one alone, so a new SessionEvent variant with no claim still fails CI, and AiSdkFlow's exhaustiveness guard is what a variant becomes: a content-free control fact that lands on the degradable side by construction. Fixes#1613

…meet The soft path rests on a premise that was not machine-checked: an unclaimed content-free event degrades the view instead of withholding it, which is only safe while no unclaimed action can owe a row. `content === undefined` does not prove that on its own — permissionDecision, tokenUsage and the terminal fact all produce rows, and runtime-event-backfill already writes a content-free event that becomes a visible `permission_decision`. What actually holds the rule up is claim coverage, so make coverage the thing that is proven. The SessionEvent contract only covers events built by `mapSessionEventToRuntimeEvent`; tool-runtime, terminal-run-commit and the backfill write RuntimeEvents directly, so a new action field on those paths was invisible to it. A second contract keyed on `RuntimeEventActions` gives every field a reachable sample typed to its own key: a new field cannot compile without one and cannot pass without being claimed. Writing it found three fields the projection never claimed — `artifactDelta`, `transferToAgent` and `runtimeProtocol`, the last of which real emitters already write. All three are control-only, so claim them, and say in the fallback what the rule actually depends on.

Two regressions the suite could not see. The unmapped-SessionEvent test compared the raw code string, so dropping `unclaimed_control_fact` from `isUnclaimedRuntimeEventDiagnostic` would have quietly narrowed the coverage contract to `unsupported_event` with every test still green; it now filters through the predicate itself. And the hard side was only asserted inside the projector, so a caller that stopped enforcing the policy went unnoticed: append a content-bearing unclaimed event to a completed run's ledger and getSessionView must still refuse the view — the counterpart of the soft reproduction beside it.

Astro-Han · 2026-07-29T14:36:40Z

Summary

One RuntimeEvent the projection does not claim made an entire session unreadable, even when every message in it was intact. The projection emitted a hard unsupported_event for any unrecognised shape, RuntimeReadModel.buildView throws on any hard diagnostic, and the whole projection was discarded — failing every getSessionView caller, not just the transcript: branching, revising, and every turn-scoped action went with it. #1607 was one instance; #1609 claimed those two shapes but left the amplification in place.

The hard failure is deliberate — it exists so messages are never silently dropped — so this splits it rather than relaxing it wholesale:

unclaimed and content-bearing → a reader may be missing a row, the view is not faithful → stays unsupported_event, hard.
unclaimed and control-only → there is no row to lose, while discarding the projection costs every intact message beside it → new unclaimed_control_fact, soft.

Severity now lives in one table keyed by code, so a new diagnostic cannot exist without deciding which side it falls on, and buildView asks the projection instead of restating the codes.

What makes the soft side safe is claim coverage, not the absence of content. Actions do own user-visible rows — permissionDecision, tokenUsage, and the terminal fact all produce one, and runtime-event-backfill.ts already writes a content-free event that projects to a visible permission_decision. Nothing with a row reaches the degrading branch only because every action field a reader can meet is claimed, so the projection-coverage contract now has to prove exactly that.

The contract previously enumerated BackendSessionEvent['type'] alone, which left every RuntimeEvent produced outside mapSessionEventToRuntimeEvent uncovered — tool-runtime, terminal-run-commit, and runtime-event-backfill all write actions directly. It now also enumerates every field of RuntimeEventActions, keyed so a new field cannot compile without a sample and cannot pass without being claimed.

Writing that contract found three action fields the projection had never claimed: artifactDelta, transferToAgent, and runtimeProtocol. The first two have no emitter yet. runtimeProtocol does — runtime-runner.ts writes it, and RecoveryResolver reads it; it only ever avoided breaking a session because it has so far always ridden on an already-claimed carrier. All three are now claimed as control facts.

#1609 declined this downgrade because it "would hide a future projection gap". That is answered by keeping the two questions separate: severity decides whether a session opens, the coverage contract decides whether coverage is missing. The contract asserts on the union of both unclaimed codes, so softening a severity cannot soften the contract.

Closes#1613. Refs #1607, #1609.

Verification

@maka/runtime full suite: 2795 tests, 2786 pass, 0 fail, 9 skipped. @maka/headless 1428 pass, CLI 668 pass, 0 fail.
End-to-end reproduction: a backend emits a SessionEvent variant the mapping was never taught, the turn completes through a real sendMessage, and the session reads back intact with the unclaimed event reported as one unclaimed_control_fact. Reverting the fallback to always-hard makes it fail with the original RuntimeReadModelError.
Its counterpart pins the caller: appending a content-bearing unclaimed event to a completed run's ledger must make getSessionView throw. Verified to bite by making the fallback unconditionally soft.
The coverage contract was checked in both directions: removing the runtimeProtocol claim fails it at runtime; removing its table entry fails compilation with TS2741.
The unclaimed predicate is now asserted through itself, so dropping unclaimed_control_fact from it can no longer silently narrow both contracts to unsupported_event.
Claim strictness is untouched: fix(runtime): reload completed sessions after sandbox boundary decisions #1609's eight malformed-boundary counter-examples still assert the event stays unclaimed; only its severity moved.
Test-merged with fix/sandbox-boundary-pending-restart (fix: let a pending sandbox boundary request survive a host restart #1612), which touches the same file: auto-merges clean, combined suite green.
npm run format, npm run lint, npm run typecheck --workspaces clean. Not run: desktop E2E — this change does not reach renderer or main.

Review focus

A malformed control fact — one that half-matches a known shape — is soft alongside a genuinely unknown one. The read model is not the enforcement authority (boundary enforcement has its own durable revisions) and an unopenable session is the worst answer available, but if ledger corruption should outrank forward compatibility that argues for a third severity tier, which this PR does not add.

stateDelta is an open record, so the contract can only cover the field's existence, not new keys inside the delta. That limit is recorded in the table rather than papered over.

artifactDelta and transferToAgent are claimed as silent control facts before either has an emitter. If a hand-off should eventually render as a visible row, that claim is where it has to change.

RuntimeReadModel decided which projection diagnostics are fatal by restating their codes, so the projection declared the diagnostics and its caller declared what they mean. Move that decision next to the codes as a table keyed by `RuntimeEventReadModelDiagnosticCode`: a new diagnostic cannot compile without saying whether it means a user-visible row may be missing. The caller and the persisted-compat test now ask that authority instead of listing codes. No behavior change — the table restates today's hard set exactly.

One RuntimeEvent the projection did not claim made an entire session unreadable. The catch-all emitted a hard `unsupported_event`, RuntimeReadModel threw on it, and the whole projection went with it — so getMessages, listTurns, branching, revising and every turn-scoped action failed over a fact that owns no chat row. #1607 was one instance; #1609 claimed those two shapes but left the amplification in place. Split the catch-all on the RuntimeEvent's own structure: `content` is its message payload, `actions` its control intent. Every row this projection emits from an unclaimed shape would have come from content, so a content-bearing event stays hard — "a message is never silently dropped" is the invariant the hard failure exists for. A control-only fact has nothing to lose, so it becomes `unclaimed_control_fact` and degrades the view instead of discarding it. A projector that tried to build a row and failed still reports its own hard diagnostic, so this softens nothing that attempted a message. A future gap is still caught before a user meets it. The projection-coverage contract now asserts on the unclaimed codes at either severity rather than the hard one alone, so a new SessionEvent variant with no claim still fails CI, and AiSdkFlow's exhaustiveness guard is what a variant becomes: a content-free control fact that lands on the degradable side by construction. Fixes#1613

…meet The soft path rests on a premise that was not machine-checked: an unclaimed content-free event degrades the view instead of withholding it, which is only safe while no unclaimed action can owe a row. `content === undefined` does not prove that on its own — permissionDecision, tokenUsage and the terminal fact all produce rows, and runtime-event-backfill already writes a content-free event that becomes a visible `permission_decision`. What actually holds the rule up is claim coverage, so make coverage the thing that is proven. The SessionEvent contract only covers events built by `mapSessionEventToRuntimeEvent`; tool-runtime, terminal-run-commit and the backfill write RuntimeEvents directly, so a new action field on those paths was invisible to it. A second contract keyed on `RuntimeEventActions` gives every field a reachable sample typed to its own key: a new field cannot compile without one and cannot pass without being claimed. Writing it found three fields the projection never claimed — `artifactDelta`, `transferToAgent` and `runtimeProtocol`, the last of which real emitters already write. All three are control-only, so claim them, and say in the fallback what the rule actually depends on.

Two regressions the suite could not see. The unmapped-SessionEvent test compared the raw code string, so dropping `unclaimed_control_fact` from `isUnclaimedRuntimeEventDiagnostic` would have quietly narrowed the coverage contract to `unsupported_event` with every test still green; it now filters through the predicate itself. And the hard side was only asserted inside the projector, so a caller that stopped enforcing the policy went unnoticed: append a content-bearing unclaimed event to a completed run's ledger and getSessionView must still refuse the view — the counterpart of the soft reproduction beside it.

Astro-Han · 2026-07-29T14:36:40Z

Summary

One RuntimeEvent the projection does not claim made an entire session unreadable, even when every message in it was intact. The projection emitted a hard unsupported_event for any unrecognised shape, RuntimeReadModel.buildView throws on any hard diagnostic, and the whole projection was discarded — failing every getSessionView caller, not just the transcript: branching, revising, and every turn-scoped action went with it. #1607 was one instance; #1609 claimed those two shapes but left the amplification in place.

The hard failure is deliberate — it exists so messages are never silently dropped — so this splits it rather than relaxing it wholesale:

unclaimed and content-bearing → a reader may be missing a row, the view is not faithful → stays unsupported_event, hard.
unclaimed and control-only → there is no row to lose, while discarding the projection costs every intact message beside it → new unclaimed_control_fact, soft.

Severity now lives in one table keyed by code, so a new diagnostic cannot exist without deciding which side it falls on, and buildView asks the projection instead of restating the codes.

What makes the soft side safe is claim coverage, not the absence of content. Actions do own user-visible rows — permissionDecision, tokenUsage, and the terminal fact all produce one, and runtime-event-backfill.ts already writes a content-free event that projects to a visible permission_decision. Nothing with a row reaches the degrading branch only because every action field a reader can meet is claimed, so the projection-coverage contract now has to prove exactly that.

The contract previously enumerated BackendSessionEvent['type'] alone, which left every RuntimeEvent produced outside mapSessionEventToRuntimeEvent uncovered — tool-runtime, terminal-run-commit, and runtime-event-backfill all write actions directly. It now also enumerates every field of RuntimeEventActions, keyed so a new field cannot compile without a sample and cannot pass without being claimed.

Writing that contract found three action fields the projection had never claimed: artifactDelta, transferToAgent, and runtimeProtocol. The first two have no emitter yet. runtimeProtocol does — runtime-runner.ts writes it, and RecoveryResolver reads it; it only ever avoided breaking a session because it has so far always ridden on an already-claimed carrier. All three are now claimed as control facts.

#1609 declined this downgrade because it "would hide a future projection gap". That is answered by keeping the two questions separate: severity decides whether a session opens, the coverage contract decides whether coverage is missing. The contract asserts on the union of both unclaimed codes, so softening a severity cannot soften the contract.

Closes#1613. Refs #1607, #1609.

Verification

@maka/runtime full suite: 2795 tests, 2786 pass, 0 fail, 9 skipped. @maka/headless 1428 pass, CLI 668 pass, 0 fail.
End-to-end reproduction: a backend emits a SessionEvent variant the mapping was never taught, the turn completes through a real sendMessage, and the session reads back intact with the unclaimed event reported as one unclaimed_control_fact. Reverting the fallback to always-hard makes it fail with the original RuntimeReadModelError.
Its counterpart pins the caller: appending a content-bearing unclaimed event to a completed run's ledger must make getSessionView throw. Verified to bite by making the fallback unconditionally soft.
The coverage contract was checked in both directions: removing the runtimeProtocol claim fails it at runtime; removing its table entry fails compilation with TS2741.
The unclaimed predicate is now asserted through itself, so dropping unclaimed_control_fact from it can no longer silently narrow both contracts to unsupported_event.
Claim strictness is untouched: fix(runtime): reload completed sessions after sandbox boundary decisions #1609's eight malformed-boundary counter-examples still assert the event stays unclaimed; only its severity moved.
Test-merged with fix/sandbox-boundary-pending-restart (fix: let a pending sandbox boundary request survive a host restart #1612), which touches the same file: auto-merges clean, combined suite green.
npm run format, npm run lint, npm run typecheck --workspaces clean. Not run: desktop E2E — this change does not reach renderer or main.

Review focus

A malformed control fact — one that half-matches a known shape — is soft alongside a genuinely unknown one. The read model is not the enforcement authority (boundary enforcement has its own durable revisions) and an unopenable session is the worst answer available, but if ledger corruption should outrank forward compatibility that argues for a third severity tier, which this PR does not add.

stateDelta is an open record, so the contract can only cover the field's existence, not new keys inside the delta. That limit is recorded in the table rather than papered over.

artifactDelta and transferToAgent are claimed as silent control facts before either has an emitter. If a hand-off should eventually render as a visible row, that claim is where it has to change.

RuntimeReadModel decided which projection diagnostics are fatal by restating their codes, so the projection declared the diagnostics and its caller declared what they mean. Move that decision next to the codes as a table keyed by `RuntimeEventReadModelDiagnosticCode`: a new diagnostic cannot compile without saying whether it means a user-visible row may be missing. The caller and the persisted-compat test now ask that authority instead of listing codes. No behavior change — the table restates today's hard set exactly.

One RuntimeEvent the projection did not claim made an entire session unreadable. The catch-all emitted a hard `unsupported_event`, RuntimeReadModel threw on it, and the whole projection went with it — so getMessages, listTurns, branching, revising and every turn-scoped action failed over a fact that owns no chat row. #1607 was one instance; #1609 claimed those two shapes but left the amplification in place. Split the catch-all on the RuntimeEvent's own structure: `content` is its message payload, `actions` its control intent. Every row this projection emits from an unclaimed shape would have come from content, so a content-bearing event stays hard — "a message is never silently dropped" is the invariant the hard failure exists for. A control-only fact has nothing to lose, so it becomes `unclaimed_control_fact` and degrades the view instead of discarding it. A projector that tried to build a row and failed still reports its own hard diagnostic, so this softens nothing that attempted a message. A future gap is still caught before a user meets it. The projection-coverage contract now asserts on the unclaimed codes at either severity rather than the hard one alone, so a new SessionEvent variant with no claim still fails CI, and AiSdkFlow's exhaustiveness guard is what a variant becomes: a content-free control fact that lands on the degradable side by construction. Fixes#1613

…meet The soft path rests on a premise that was not machine-checked: an unclaimed content-free event degrades the view instead of withholding it, which is only safe while no unclaimed action can owe a row. `content === undefined` does not prove that on its own — permissionDecision, tokenUsage and the terminal fact all produce rows, and runtime-event-backfill already writes a content-free event that becomes a visible `permission_decision`. What actually holds the rule up is claim coverage, so make coverage the thing that is proven. The SessionEvent contract only covers events built by `mapSessionEventToRuntimeEvent`; tool-runtime, terminal-run-commit and the backfill write RuntimeEvents directly, so a new action field on those paths was invisible to it. A second contract keyed on `RuntimeEventActions` gives every field a reachable sample typed to its own key: a new field cannot compile without one and cannot pass without being claimed. Writing it found three fields the projection never claimed — `artifactDelta`, `transferToAgent` and `runtimeProtocol`, the last of which real emitters already write. All three are control-only, so claim them, and say in the fallback what the rule actually depends on.

Two regressions the suite could not see. The unmapped-SessionEvent test compared the raw code string, so dropping `unclaimed_control_fact` from `isUnclaimedRuntimeEventDiagnostic` would have quietly narrowed the coverage contract to `unsupported_event` with every test still green; it now filters through the predicate itself. And the hard side was only asserted inside the projector, so a caller that stopped enforcing the policy went unnoticed: append a content-bearing unclaimed event to a completed run's ledger and getSessionView must still refuse the view — the counterpart of the soft reproduction beside it.

Astro-Han · 2026-07-29T14:36:40Z

Summary

One RuntimeEvent the projection does not claim made an entire session unreadable, even when every message in it was intact. The projection emitted a hard unsupported_event for any unrecognised shape, RuntimeReadModel.buildView throws on any hard diagnostic, and the whole projection was discarded — failing every getSessionView caller, not just the transcript: branching, revising, and every turn-scoped action went with it. #1607 was one instance; #1609 claimed those two shapes but left the amplification in place.

The hard failure is deliberate — it exists so messages are never silently dropped — so this splits it rather than relaxing it wholesale:

unclaimed and content-bearing → a reader may be missing a row, the view is not faithful → stays unsupported_event, hard.
unclaimed and control-only → there is no row to lose, while discarding the projection costs every intact message beside it → new unclaimed_control_fact, soft.

Severity now lives in one table keyed by code, so a new diagnostic cannot exist without deciding which side it falls on, and buildView asks the projection instead of restating the codes.

What makes the soft side safe is claim coverage, not the absence of content. Actions do own user-visible rows — permissionDecision, tokenUsage, and the terminal fact all produce one, and runtime-event-backfill.ts already writes a content-free event that projects to a visible permission_decision. Nothing with a row reaches the degrading branch only because every action field a reader can meet is claimed, so the projection-coverage contract now has to prove exactly that.

The contract previously enumerated BackendSessionEvent['type'] alone, which left every RuntimeEvent produced outside mapSessionEventToRuntimeEvent uncovered — tool-runtime, terminal-run-commit, and runtime-event-backfill all write actions directly. It now also enumerates every field of RuntimeEventActions, keyed so a new field cannot compile without a sample and cannot pass without being claimed.

Writing that contract found three action fields the projection had never claimed: artifactDelta, transferToAgent, and runtimeProtocol. The first two have no emitter yet. runtimeProtocol does — runtime-runner.ts writes it, and RecoveryResolver reads it; it only ever avoided breaking a session because it has so far always ridden on an already-claimed carrier. All three are now claimed as control facts.

#1609 declined this downgrade because it "would hide a future projection gap". That is answered by keeping the two questions separate: severity decides whether a session opens, the coverage contract decides whether coverage is missing. The contract asserts on the union of both unclaimed codes, so softening a severity cannot soften the contract.

Closes#1613. Refs #1607, #1609.

Verification

@maka/runtime full suite: 2795 tests, 2786 pass, 0 fail, 9 skipped. @maka/headless 1428 pass, CLI 668 pass, 0 fail.
End-to-end reproduction: a backend emits a SessionEvent variant the mapping was never taught, the turn completes through a real sendMessage, and the session reads back intact with the unclaimed event reported as one unclaimed_control_fact. Reverting the fallback to always-hard makes it fail with the original RuntimeReadModelError.
Its counterpart pins the caller: appending a content-bearing unclaimed event to a completed run's ledger must make getSessionView throw. Verified to bite by making the fallback unconditionally soft.
The coverage contract was checked in both directions: removing the runtimeProtocol claim fails it at runtime; removing its table entry fails compilation with TS2741.
The unclaimed predicate is now asserted through itself, so dropping unclaimed_control_fact from it can no longer silently narrow both contracts to unsupported_event.
Claim strictness is untouched: fix(runtime): reload completed sessions after sandbox boundary decisions #1609's eight malformed-boundary counter-examples still assert the event stays unclaimed; only its severity moved.
Test-merged with fix/sandbox-boundary-pending-restart (fix: let a pending sandbox boundary request survive a host restart #1612), which touches the same file: auto-merges clean, combined suite green.
npm run format, npm run lint, npm run typecheck --workspaces clean. Not run: desktop E2E — this change does not reach renderer or main.

Review focus

A malformed control fact — one that half-matches a known shape — is soft alongside a genuinely unknown one. The read model is not the enforcement authority (boundary enforcement has its own durable revisions) and an unopenable session is the worst answer available, but if ledger corruption should outrank forward compatibility that argues for a third severity tier, which this PR does not add.

stateDelta is an open record, so the contract can only cover the field's existence, not new keys inside the delta. That limit is recorded in the table rather than papered over.

artifactDelta and transferToAgent are claimed as silent control facts before either has an emitter. If a hand-off should eventually render as a visible row, that claim is where it has to change.

RuntimeReadModel decided which projection diagnostics are fatal by restating their codes, so the projection declared the diagnostics and its caller declared what they mean. Move that decision next to the codes as a table keyed by `RuntimeEventReadModelDiagnosticCode`: a new diagnostic cannot compile without saying whether it means a user-visible row may be missing. The caller and the persisted-compat test now ask that authority instead of listing codes. No behavior change — the table restates today's hard set exactly.

One RuntimeEvent the projection did not claim made an entire session unreadable. The catch-all emitted a hard `unsupported_event`, RuntimeReadModel threw on it, and the whole projection went with it — so getMessages, listTurns, branching, revising and every turn-scoped action failed over a fact that owns no chat row. #1607 was one instance; #1609 claimed those two shapes but left the amplification in place. Split the catch-all on the RuntimeEvent's own structure: `content` is its message payload, `actions` its control intent. Every row this projection emits from an unclaimed shape would have come from content, so a content-bearing event stays hard — "a message is never silently dropped" is the invariant the hard failure exists for. A control-only fact has nothing to lose, so it becomes `unclaimed_control_fact` and degrades the view instead of discarding it. A projector that tried to build a row and failed still reports its own hard diagnostic, so this softens nothing that attempted a message. A future gap is still caught before a user meets it. The projection-coverage contract now asserts on the unclaimed codes at either severity rather than the hard one alone, so a new SessionEvent variant with no claim still fails CI, and AiSdkFlow's exhaustiveness guard is what a variant becomes: a content-free control fact that lands on the degradable side by construction. Fixes#1613

…meet The soft path rests on a premise that was not machine-checked: an unclaimed content-free event degrades the view instead of withholding it, which is only safe while no unclaimed action can owe a row. `content === undefined` does not prove that on its own — permissionDecision, tokenUsage and the terminal fact all produce rows, and runtime-event-backfill already writes a content-free event that becomes a visible `permission_decision`. What actually holds the rule up is claim coverage, so make coverage the thing that is proven. The SessionEvent contract only covers events built by `mapSessionEventToRuntimeEvent`; tool-runtime, terminal-run-commit and the backfill write RuntimeEvents directly, so a new action field on those paths was invisible to it. A second contract keyed on `RuntimeEventActions` gives every field a reachable sample typed to its own key: a new field cannot compile without one and cannot pass without being claimed. Writing it found three fields the projection never claimed — `artifactDelta`, `transferToAgent` and `runtimeProtocol`, the last of which real emitters already write. All three are control-only, so claim them, and say in the fallback what the rule actually depends on.

Two regressions the suite could not see. The unmapped-SessionEvent test compared the raw code string, so dropping `unclaimed_control_fact` from `isUnclaimedRuntimeEventDiagnostic` would have quietly narrowed the coverage contract to `unsupported_event` with every test still green; it now filters through the predicate itself. And the hard side was only asserted inside the projector, so a caller that stopped enforcing the policy went unnoticed: append a content-bearing unclaimed event to a completed run's ledger and getSessionView must still refuse the view — the counterpart of the soft reproduction beside it.

Astro-Han · 2026-07-29T14:36:40Z

Summary

One RuntimeEvent the projection does not claim made an entire session unreadable, even when every message in it was intact. The projection emitted a hard unsupported_event for any unrecognised shape, RuntimeReadModel.buildView throws on any hard diagnostic, and the whole projection was discarded — failing every getSessionView caller, not just the transcript: branching, revising, and every turn-scoped action went with it. #1607 was one instance; #1609 claimed those two shapes but left the amplification in place.

The hard failure is deliberate — it exists so messages are never silently dropped — so this splits it rather than relaxing it wholesale:

unclaimed and content-bearing → a reader may be missing a row, the view is not faithful → stays unsupported_event, hard.
unclaimed and control-only → there is no row to lose, while discarding the projection costs every intact message beside it → new unclaimed_control_fact, soft.

Severity now lives in one table keyed by code, so a new diagnostic cannot exist without deciding which side it falls on, and buildView asks the projection instead of restating the codes.

What makes the soft side safe is claim coverage, not the absence of content. Actions do own user-visible rows — permissionDecision, tokenUsage, and the terminal fact all produce one, and runtime-event-backfill.ts already writes a content-free event that projects to a visible permission_decision. Nothing with a row reaches the degrading branch only because every action field a reader can meet is claimed, so the projection-coverage contract now has to prove exactly that.

The contract previously enumerated BackendSessionEvent['type'] alone, which left every RuntimeEvent produced outside mapSessionEventToRuntimeEvent uncovered — tool-runtime, terminal-run-commit, and runtime-event-backfill all write actions directly. It now also enumerates every field of RuntimeEventActions, keyed so a new field cannot compile without a sample and cannot pass without being claimed.

Writing that contract found three action fields the projection had never claimed: artifactDelta, transferToAgent, and runtimeProtocol. The first two have no emitter yet. runtimeProtocol does — runtime-runner.ts writes it, and RecoveryResolver reads it; it only ever avoided breaking a session because it has so far always ridden on an already-claimed carrier. All three are now claimed as control facts.

#1609 declined this downgrade because it "would hide a future projection gap". That is answered by keeping the two questions separate: severity decides whether a session opens, the coverage contract decides whether coverage is missing. The contract asserts on the union of both unclaimed codes, so softening a severity cannot soften the contract.

Closes#1613. Refs #1607, #1609.

Verification

@maka/runtime full suite: 2795 tests, 2786 pass, 0 fail, 9 skipped. @maka/headless 1428 pass, CLI 668 pass, 0 fail.
End-to-end reproduction: a backend emits a SessionEvent variant the mapping was never taught, the turn completes through a real sendMessage, and the session reads back intact with the unclaimed event reported as one unclaimed_control_fact. Reverting the fallback to always-hard makes it fail with the original RuntimeReadModelError.
Its counterpart pins the caller: appending a content-bearing unclaimed event to a completed run's ledger must make getSessionView throw. Verified to bite by making the fallback unconditionally soft.
The coverage contract was checked in both directions: removing the runtimeProtocol claim fails it at runtime; removing its table entry fails compilation with TS2741.
The unclaimed predicate is now asserted through itself, so dropping unclaimed_control_fact from it can no longer silently narrow both contracts to unsupported_event.
Claim strictness is untouched: fix(runtime): reload completed sessions after sandbox boundary decisions #1609's eight malformed-boundary counter-examples still assert the event stays unclaimed; only its severity moved.
Test-merged with fix/sandbox-boundary-pending-restart (fix: let a pending sandbox boundary request survive a host restart #1612), which touches the same file: auto-merges clean, combined suite green.
npm run format, npm run lint, npm run typecheck --workspaces clean. Not run: desktop E2E — this change does not reach renderer or main.

Review focus

A malformed control fact — one that half-matches a known shape — is soft alongside a genuinely unknown one. The read model is not the enforcement authority (boundary enforcement has its own durable revisions) and an unopenable session is the worst answer available, but if ledger corruption should outrank forward compatibility that argues for a third severity tier, which this PR does not add.

stateDelta is an open record, so the contract can only cover the field's existence, not new keys inside the delta. That limit is recorded in the table rather than papered over.

artifactDelta and transferToAgent are claimed as silent control facts before either has an emitter. If a hand-off should eventually render as a visible row, that claim is where it has to change.

RuntimeReadModel decided which projection diagnostics are fatal by restating their codes, so the projection declared the diagnostics and its caller declared what they mean. Move that decision next to the codes as a table keyed by `RuntimeEventReadModelDiagnosticCode`: a new diagnostic cannot compile without saying whether it means a user-visible row may be missing. The caller and the persisted-compat test now ask that authority instead of listing codes. No behavior change — the table restates today's hard set exactly.

One RuntimeEvent the projection did not claim made an entire session unreadable. The catch-all emitted a hard `unsupported_event`, RuntimeReadModel threw on it, and the whole projection went with it — so getMessages, listTurns, branching, revising and every turn-scoped action failed over a fact that owns no chat row. #1607 was one instance; #1609 claimed those two shapes but left the amplification in place. Split the catch-all on the RuntimeEvent's own structure: `content` is its message payload, `actions` its control intent. Every row this projection emits from an unclaimed shape would have come from content, so a content-bearing event stays hard — "a message is never silently dropped" is the invariant the hard failure exists for. A control-only fact has nothing to lose, so it becomes `unclaimed_control_fact` and degrades the view instead of discarding it. A projector that tried to build a row and failed still reports its own hard diagnostic, so this softens nothing that attempted a message. A future gap is still caught before a user meets it. The projection-coverage contract now asserts on the unclaimed codes at either severity rather than the hard one alone, so a new SessionEvent variant with no claim still fails CI, and AiSdkFlow's exhaustiveness guard is what a variant becomes: a content-free control fact that lands on the degradable side by construction. Fixes#1613

…meet The soft path rests on a premise that was not machine-checked: an unclaimed content-free event degrades the view instead of withholding it, which is only safe while no unclaimed action can owe a row. `content === undefined` does not prove that on its own — permissionDecision, tokenUsage and the terminal fact all produce rows, and runtime-event-backfill already writes a content-free event that becomes a visible `permission_decision`. What actually holds the rule up is claim coverage, so make coverage the thing that is proven. The SessionEvent contract only covers events built by `mapSessionEventToRuntimeEvent`; tool-runtime, terminal-run-commit and the backfill write RuntimeEvents directly, so a new action field on those paths was invisible to it. A second contract keyed on `RuntimeEventActions` gives every field a reachable sample typed to its own key: a new field cannot compile without one and cannot pass without being claimed. Writing it found three fields the projection never claimed — `artifactDelta`, `transferToAgent` and `runtimeProtocol`, the last of which real emitters already write. All three are control-only, so claim them, and say in the fallback what the rule actually depends on.

Two regressions the suite could not see. The unmapped-SessionEvent test compared the raw code string, so dropping `unclaimed_control_fact` from `isUnclaimedRuntimeEventDiagnostic` would have quietly narrowed the coverage contract to `unsupported_event` with every test still green; it now filters through the predicate itself. And the hard side was only asserted inside the projector, so a caller that stopped enforcing the policy went unnoticed: append a content-bearing unclaimed event to a completed run's ledger and getSessionView must still refuse the view — the counterpart of the soft reproduction beside it.

Astro-Han · 2026-07-29T14:36:40Z

Summary

One RuntimeEvent the projection does not claim made an entire session unreadable, even when every message in it was intact. The projection emitted a hard unsupported_event for any unrecognised shape, RuntimeReadModel.buildView throws on any hard diagnostic, and the whole projection was discarded — failing every getSessionView caller, not just the transcript: branching, revising, and every turn-scoped action went with it. #1607 was one instance; #1609 claimed those two shapes but left the amplification in place.

The hard failure is deliberate — it exists so messages are never silently dropped — so this splits it rather than relaxing it wholesale:

unclaimed and content-bearing → a reader may be missing a row, the view is not faithful → stays unsupported_event, hard.
unclaimed and control-only → there is no row to lose, while discarding the projection costs every intact message beside it → new unclaimed_control_fact, soft.

Severity now lives in one table keyed by code, so a new diagnostic cannot exist without deciding which side it falls on, and buildView asks the projection instead of restating the codes.

What makes the soft side safe is claim coverage, not the absence of content. Actions do own user-visible rows — permissionDecision, tokenUsage, and the terminal fact all produce one, and runtime-event-backfill.ts already writes a content-free event that projects to a visible permission_decision. Nothing with a row reaches the degrading branch only because every action field a reader can meet is claimed, so the projection-coverage contract now has to prove exactly that.

The contract previously enumerated BackendSessionEvent['type'] alone, which left every RuntimeEvent produced outside mapSessionEventToRuntimeEvent uncovered — tool-runtime, terminal-run-commit, and runtime-event-backfill all write actions directly. It now also enumerates every field of RuntimeEventActions, keyed so a new field cannot compile without a sample and cannot pass without being claimed.

Writing that contract found three action fields the projection had never claimed: artifactDelta, transferToAgent, and runtimeProtocol. The first two have no emitter yet. runtimeProtocol does — runtime-runner.ts writes it, and RecoveryResolver reads it; it only ever avoided breaking a session because it has so far always ridden on an already-claimed carrier. All three are now claimed as control facts.

#1609 declined this downgrade because it "would hide a future projection gap". That is answered by keeping the two questions separate: severity decides whether a session opens, the coverage contract decides whether coverage is missing. The contract asserts on the union of both unclaimed codes, so softening a severity cannot soften the contract.

Closes#1613. Refs #1607, #1609.

Verification

@maka/runtime full suite: 2795 tests, 2786 pass, 0 fail, 9 skipped. @maka/headless 1428 pass, CLI 668 pass, 0 fail.
End-to-end reproduction: a backend emits a SessionEvent variant the mapping was never taught, the turn completes through a real sendMessage, and the session reads back intact with the unclaimed event reported as one unclaimed_control_fact. Reverting the fallback to always-hard makes it fail with the original RuntimeReadModelError.
Its counterpart pins the caller: appending a content-bearing unclaimed event to a completed run's ledger must make getSessionView throw. Verified to bite by making the fallback unconditionally soft.
The coverage contract was checked in both directions: removing the runtimeProtocol claim fails it at runtime; removing its table entry fails compilation with TS2741.
The unclaimed predicate is now asserted through itself, so dropping unclaimed_control_fact from it can no longer silently narrow both contracts to unsupported_event.
Claim strictness is untouched: fix(runtime): reload completed sessions after sandbox boundary decisions #1609's eight malformed-boundary counter-examples still assert the event stays unclaimed; only its severity moved.
Test-merged with fix/sandbox-boundary-pending-restart (fix: let a pending sandbox boundary request survive a host restart #1612), which touches the same file: auto-merges clean, combined suite green.
npm run format, npm run lint, npm run typecheck --workspaces clean. Not run: desktop E2E — this change does not reach renderer or main.

Review focus

A malformed control fact — one that half-matches a known shape — is soft alongside a genuinely unknown one. The read model is not the enforcement authority (boundary enforcement has its own durable revisions) and an unopenable session is the worst answer available, but if ledger corruption should outrank forward compatibility that argues for a third severity tier, which this PR does not add.

stateDelta is an open record, so the contract can only cover the field's existence, not new keys inside the delta. That limit is recorded in the table rather than papered over.

artifactDelta and transferToAgent are claimed as silent control facts before either has an emitter. If a hand-off should eventually render as a visible row, that claim is where it has to change.

RuntimeReadModel decided which projection diagnostics are fatal by restating their codes, so the projection declared the diagnostics and its caller declared what they mean. Move that decision next to the codes as a table keyed by `RuntimeEventReadModelDiagnosticCode`: a new diagnostic cannot compile without saying whether it means a user-visible row may be missing. The caller and the persisted-compat test now ask that authority instead of listing codes. No behavior change — the table restates today's hard set exactly.

One RuntimeEvent the projection did not claim made an entire session unreadable. The catch-all emitted a hard `unsupported_event`, RuntimeReadModel threw on it, and the whole projection went with it — so getMessages, listTurns, branching, revising and every turn-scoped action failed over a fact that owns no chat row. #1607 was one instance; #1609 claimed those two shapes but left the amplification in place. Split the catch-all on the RuntimeEvent's own structure: `content` is its message payload, `actions` its control intent. Every row this projection emits from an unclaimed shape would have come from content, so a content-bearing event stays hard — "a message is never silently dropped" is the invariant the hard failure exists for. A control-only fact has nothing to lose, so it becomes `unclaimed_control_fact` and degrades the view instead of discarding it. A projector that tried to build a row and failed still reports its own hard diagnostic, so this softens nothing that attempted a message. A future gap is still caught before a user meets it. The projection-coverage contract now asserts on the unclaimed codes at either severity rather than the hard one alone, so a new SessionEvent variant with no claim still fails CI, and AiSdkFlow's exhaustiveness guard is what a variant becomes: a content-free control fact that lands on the degradable side by construction. Fixes#1613

…meet The soft path rests on a premise that was not machine-checked: an unclaimed content-free event degrades the view instead of withholding it, which is only safe while no unclaimed action can owe a row. `content === undefined` does not prove that on its own — permissionDecision, tokenUsage and the terminal fact all produce rows, and runtime-event-backfill already writes a content-free event that becomes a visible `permission_decision`. What actually holds the rule up is claim coverage, so make coverage the thing that is proven. The SessionEvent contract only covers events built by `mapSessionEventToRuntimeEvent`; tool-runtime, terminal-run-commit and the backfill write RuntimeEvents directly, so a new action field on those paths was invisible to it. A second contract keyed on `RuntimeEventActions` gives every field a reachable sample typed to its own key: a new field cannot compile without one and cannot pass without being claimed. Writing it found three fields the projection never claimed — `artifactDelta`, `transferToAgent` and `runtimeProtocol`, the last of which real emitters already write. All three are control-only, so claim them, and say in the fallback what the rule actually depends on.

Two regressions the suite could not see. The unmapped-SessionEvent test compared the raw code string, so dropping `unclaimed_control_fact` from `isUnclaimedRuntimeEventDiagnostic` would have quietly narrowed the coverage contract to `unsupported_event` with every test still green; it now filters through the predicate itself. And the hard side was only asserted inside the projector, so a caller that stopped enforcing the policy went unnoticed: append a content-bearing unclaimed event to a completed run's ledger and getSessionView must still refuse the view — the counterpart of the soft reproduction beside it.

Astro-Han · 2026-07-29T14:36:40Z

Summary

One RuntimeEvent the projection does not claim made an entire session unreadable, even when every message in it was intact. The projection emitted a hard unsupported_event for any unrecognised shape, RuntimeReadModel.buildView throws on any hard diagnostic, and the whole projection was discarded — failing every getSessionView caller, not just the transcript: branching, revising, and every turn-scoped action went with it. #1607 was one instance; #1609 claimed those two shapes but left the amplification in place.

The hard failure is deliberate — it exists so messages are never silently dropped — so this splits it rather than relaxing it wholesale:

unclaimed and content-bearing → a reader may be missing a row, the view is not faithful → stays unsupported_event, hard.
unclaimed and control-only → there is no row to lose, while discarding the projection costs every intact message beside it → new unclaimed_control_fact, soft.

Severity now lives in one table keyed by code, so a new diagnostic cannot exist without deciding which side it falls on, and buildView asks the projection instead of restating the codes.

What makes the soft side safe is claim coverage, not the absence of content. Actions do own user-visible rows — permissionDecision, tokenUsage, and the terminal fact all produce one, and runtime-event-backfill.ts already writes a content-free event that projects to a visible permission_decision. Nothing with a row reaches the degrading branch only because every action field a reader can meet is claimed, so the projection-coverage contract now has to prove exactly that.

The contract previously enumerated BackendSessionEvent['type'] alone, which left every RuntimeEvent produced outside mapSessionEventToRuntimeEvent uncovered — tool-runtime, terminal-run-commit, and runtime-event-backfill all write actions directly. It now also enumerates every field of RuntimeEventActions, keyed so a new field cannot compile without a sample and cannot pass without being claimed.

Writing that contract found three action fields the projection had never claimed: artifactDelta, transferToAgent, and runtimeProtocol. The first two have no emitter yet. runtimeProtocol does — runtime-runner.ts writes it, and RecoveryResolver reads it; it only ever avoided breaking a session because it has so far always ridden on an already-claimed carrier. All three are now claimed as control facts.

#1609 declined this downgrade because it "would hide a future projection gap". That is answered by keeping the two questions separate: severity decides whether a session opens, the coverage contract decides whether coverage is missing. The contract asserts on the union of both unclaimed codes, so softening a severity cannot soften the contract.

Closes#1613. Refs #1607, #1609.

Verification

@maka/runtime full suite: 2795 tests, 2786 pass, 0 fail, 9 skipped. @maka/headless 1428 pass, CLI 668 pass, 0 fail.
End-to-end reproduction: a backend emits a SessionEvent variant the mapping was never taught, the turn completes through a real sendMessage, and the session reads back intact with the unclaimed event reported as one unclaimed_control_fact. Reverting the fallback to always-hard makes it fail with the original RuntimeReadModelError.
Its counterpart pins the caller: appending a content-bearing unclaimed event to a completed run's ledger must make getSessionView throw. Verified to bite by making the fallback unconditionally soft.
The coverage contract was checked in both directions: removing the runtimeProtocol claim fails it at runtime; removing its table entry fails compilation with TS2741.
The unclaimed predicate is now asserted through itself, so dropping unclaimed_control_fact from it can no longer silently narrow both contracts to unsupported_event.
Claim strictness is untouched: fix(runtime): reload completed sessions after sandbox boundary decisions #1609's eight malformed-boundary counter-examples still assert the event stays unclaimed; only its severity moved.
Test-merged with fix/sandbox-boundary-pending-restart (fix: let a pending sandbox boundary request survive a host restart #1612), which touches the same file: auto-merges clean, combined suite green.
npm run format, npm run lint, npm run typecheck --workspaces clean. Not run: desktop E2E — this change does not reach renderer or main.

Review focus

A malformed control fact — one that half-matches a known shape — is soft alongside a genuinely unknown one. The read model is not the enforcement authority (boundary enforcement has its own durable revisions) and an unopenable session is the worst answer available, but if ledger corruption should outrank forward compatibility that argues for a third severity tier, which this PR does not add.

stateDelta is an open record, so the contract can only cover the field's existence, not new keys inside the delta. That limit is recorded in the table rather than papered over.

artifactDelta and transferToAgent are claimed as silent control facts before either has an emitter. If a hand-off should eventually render as a visible row, that claim is where it has to change.

RuntimeReadModel decided which projection diagnostics are fatal by restating their codes, so the projection declared the diagnostics and its caller declared what they mean. Move that decision next to the codes as a table keyed by `RuntimeEventReadModelDiagnosticCode`: a new diagnostic cannot compile without saying whether it means a user-visible row may be missing. The caller and the persisted-compat test now ask that authority instead of listing codes. No behavior change — the table restates today's hard set exactly.

One RuntimeEvent the projection did not claim made an entire session unreadable. The catch-all emitted a hard `unsupported_event`, RuntimeReadModel threw on it, and the whole projection went with it — so getMessages, listTurns, branching, revising and every turn-scoped action failed over a fact that owns no chat row. #1607 was one instance; #1609 claimed those two shapes but left the amplification in place. Split the catch-all on the RuntimeEvent's own structure: `content` is its message payload, `actions` its control intent. Every row this projection emits from an unclaimed shape would have come from content, so a content-bearing event stays hard — "a message is never silently dropped" is the invariant the hard failure exists for. A control-only fact has nothing to lose, so it becomes `unclaimed_control_fact` and degrades the view instead of discarding it. A projector that tried to build a row and failed still reports its own hard diagnostic, so this softens nothing that attempted a message. A future gap is still caught before a user meets it. The projection-coverage contract now asserts on the unclaimed codes at either severity rather than the hard one alone, so a new SessionEvent variant with no claim still fails CI, and AiSdkFlow's exhaustiveness guard is what a variant becomes: a content-free control fact that lands on the degradable side by construction. Fixes#1613

…meet The soft path rests on a premise that was not machine-checked: an unclaimed content-free event degrades the view instead of withholding it, which is only safe while no unclaimed action can owe a row. `content === undefined` does not prove that on its own — permissionDecision, tokenUsage and the terminal fact all produce rows, and runtime-event-backfill already writes a content-free event that becomes a visible `permission_decision`. What actually holds the rule up is claim coverage, so make coverage the thing that is proven. The SessionEvent contract only covers events built by `mapSessionEventToRuntimeEvent`; tool-runtime, terminal-run-commit and the backfill write RuntimeEvents directly, so a new action field on those paths was invisible to it. A second contract keyed on `RuntimeEventActions` gives every field a reachable sample typed to its own key: a new field cannot compile without one and cannot pass without being claimed. Writing it found three fields the projection never claimed — `artifactDelta`, `transferToAgent` and `runtimeProtocol`, the last of which real emitters already write. All three are control-only, so claim them, and say in the fallback what the rule actually depends on.

Two regressions the suite could not see. The unmapped-SessionEvent test compared the raw code string, so dropping `unclaimed_control_fact` from `isUnclaimedRuntimeEventDiagnostic` would have quietly narrowed the coverage contract to `unsupported_event` with every test still green; it now filters through the predicate itself. And the hard side was only asserted inside the projector, so a caller that stopped enforcing the policy went unnoticed: append a content-bearing unclaimed event to a completed run's ledger and getSessionView must still refuse the view — the counterpart of the soft reproduction beside it.

Astro-Han added 4 commits July 29, 2026 22:27

Astro-Han merged commit 1f43ea7 into mainJul 29, 2026
3 checks passed