Skip to content

fix(core): read AgentRun ledgers written by any version - #1986

Merged
Astro-Han merged 1 commit into
mainfrom
fix/agent-run-accept-unknown-event-types
Aug 3, 2026
Merged

fix(core): read AgentRun ledgers written by any version#1986
Astro-Han merged 1 commit into
mainfrom
fix/agent-run-accept-unknown-event-types

Conversation

@Astro-Han

@Astro-HanAstro-Han commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Summary

AGENT_RUN_EVENT_TYPES served two roles at once: the set of event types this build writes, and the set a reader accepts. The AgentRun ledger is append-only and outlives the build that wrote it, so those cannot be the same set. #1755 retired the usage_recorded writer and deleted its entry in one commit; the next build then could not decode records the previous one had already persisted, and the desktop app failed to start (#1942).

Only the write side can be a closed set:

  • Reads take type as an open string. The envelope around it is still validated exactly, so a damaged record is still rejected — tolerating an unknown type is not tolerating an unreadable one.
  • Appends take EmittedAgentRunEvent, so a misspelled or retired type fails to compile at the call that would persist it.

That is what makes retiring a writer safe, and it is why usage_recorded is gone again. #1945 stopped the crash the only way the old shape allowed: by putting a type nothing writes back into the catalogue this build writes from. With the two contracts separated, the tombstone is unnecessary and the entry can be removed for real.

A conversation copy now drops an event this build does not emit rather than carrying its unrewritten source-owned ids into the target — the rewriters cannot inspect a payload they do not know.

Closes#1942.

Verification

  • npm run lint, npm run format:check, full npm run build — clean.
  • @maka/core 753/753, @maka/headless 1314/1314 pass.
  • @maka/storage and @maka/runtime: the 7 storage (schema migration/backup) and 4 runtime (macOS /var/private/var realpath) failures reproduce identically on main — verified by running the same suites in a clean main checkout, where storage in fact fails 9.

Mutation-tested every new assertion, each confirmed to go red:

MutationResult
Restore the closed-set check in decodeAgentRunEvent (i.e. reintroduce #1942)core contract + storage cross-version read fail
Widen appendEvent back to AgentRunEventTS2578: Unused '@ts-expect-error' directive — build fails
Remove the blank-type guardcore envelope-rejection test fails
Remove the unknown-type filter in conversation-copycopy test fails

Root cause

A write-side catalogue was used as a read-side contract. Backward compatibility can be enforced by discipline at the writer; forward compatibility cannot, because the writing version does not exist yet when the reader ships. The reader must therefore be tolerant of type by construction, which is the only part of the record whose value space legitimately grows across versions.

Review focus

harbor-cell.ts constructs two records (trace_write_failed, event_corrupt) that are persisted to a benchmark artifact; both now carry the write contract, so a typo there is a compile error rather than a downstream "corrupt artifact" diagnostic that points at the wrong cause.

@Astro-Han
Astro-Hanforce-pushed the fix/agent-run-accept-unknown-event-types branch from 0ed617e to 183fb5eCompareAugust 3, 2026 12:07
@Astro-HanAstro-Han reopened this Aug 3, 2026
@Astro-Han
Astro-Hanforce-pushed the fix/agent-run-accept-unknown-event-types branch from 6550ad3 to 14adedeCompareAugust 3, 2026 13:27
`AGENT_RUN_EVENT_TYPES` was both the set this build writes and the set a reader accepts.
The ledger is append-only and outlives the build that wrote it, so retiring a writer and
deleting its entry in one commit (#1755) left the next build unable to decode records the
previous one had persisted, and the desktop app failed to start (#1942).
Only the write side can be a closed set. Reads take `type` as an open string with the
envelope around it still validated, so a damaged record is still rejected; appends take
`EmittedAgentRunEvent`, so a misspelled or retired type fails to compile at the call that
would persist it. That makes retiring a writer safe, which is why `usage_recorded` is gone
again: #1945 could only fix the crash by adding a type nothing writes back to the catalogue
this build writes from.
A copy drops an event this build does not emit rather than carrying its unrewritten
source-owned ids into the target, since the rewriters cannot inspect a payload they do not
know.
@Astro-Han
Astro-Hanforce-pushed the fix/agent-run-accept-unknown-event-types branch from 14adede to 71a1509CompareAugust 3, 2026 15:15
@Astro-Han
Astro-Han marked this pull request as ready for review August 3, 2026 15:25
@Astro-Han
Astro-Han merged commit 3952883 into mainAug 3, 2026
18 of 20 checks passed
@Astro-Han
Astro-Han deleted the fix/agent-run-accept-unknown-event-types branch August 3, 2026 15:27
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

AgentRun events.jsonl records type=usage_recorded which is missing from AGENT_RUN_EVENT_TYPES → strict decode fails, desktop app won't start

1 participant

@Astro-Han