[nissa-seru]

Registering a state now fails for anything but "already exists" (#385). Twelve of the seventeen places that register a state swallowed every failure, so a closed store or an I/O error went unnoticed there, and the caller met it later, at another call, under that call's name. This puts every registration through one helper that treats only "already exists" as done, and names the state in the error it throws.

!Fixes #385

What was wrong

isStateExistsError (src/module-registry.ts) says that only "already exists" is safe to swallow on an idempotent registration: "Anything else (closed store, IO error) must propagate". Three registrations used it, and the channel registry's two logs tested its message inline. The other twelve wrapped registerState in a bare catch. These are the eight sites #385 names and four more: the conversation router's state in create(), the tune-out coordinator's state read and write in the channel registry, and the workspace's tree and intent states.

Changes

• ensureStateRegistered(store, registration), beside isStateExistsError, registers a state and rethrows every failure but "already exists" as Registering state '<id>' failed: <the store's message>, with the store's error as its cause.
• All seventeen registrations go through it:
  • create(): the framework, deferred-write, coalescing, inference-log, turn-checkpoint, process-log and conversation-router states;
  • ModuleRegistry.addModule()'s module state, and a module's registerLogState();
  • CheckpointManager's checkpoint state, and a feature set's host state;
  • ChannelRegistry's lifecycle and label-history logs, and the tune-out coordinator's state;
  • the workspace module's tree and intent states, in initStore();
  • the tool-result guard's audit log.
• A feature set's host state is registered inside the same try as the read of its stored value, in CheckpointManager's loadHostState. So a registration that fails gets the refusal a failed read gets: it names the state, says what the failure stops, before the server connects or when the feature set registers, and carries the helper's error as its cause and in its text. As on main, the feature set's tree is held only after both, so the next call tries again.
• The workspace's initStore() registers every mount's states before it takes the store or any mount. It took them one mount at a time, so a failure at a later mount left the earlier mounts set, with no agreement, saved state or watchers.
• registerLogState()'s doc says its cadence applies when the state is first registered.
• Chronicle's error codes (feat(napi): the binding's errors carry a code from a new ErrorCode enum chronicle#31) aren't released, so the helper still matches the message. When they are, the change is to isStateExistsError alone.

What callers will notice

A failure other than "already exists" is now thrown by the call that registers the state, as an error that names it:

• AgentFramework.create() rejects with it. A create() that fails partway stops what it had started and closes a store it opened, as on main since fix(create): a failed create() releases what it had acquired #426.
• addModule() rejects with it.
• The workspace's initStore() throws it, and leaves the module as it was. By reading, connectome-host calls initStore() without a catch (src/index.ts:678 at its main, 38b55da), so its startup fails with the error.
• An MCPL server's checkpoint and host states, by reading at this head:
  • The checkpoint state is registered when MCPL starts, so create() rejects.
  • A restored feature set's host state is registered before its server connects, so create() refuses for a configured server, and connectMcplServer() for a later one, with the refusal a failed read of it gets.
  • A feature set registering for the first time has its host state registered in its server's connect. At startup that's logged as a failed connect while the server stays connected, with its later feature sets unregistered. In a runtime connect, the new connection is closed and connectMcplServer() rejects. In a reconnect, it's logged and the reconnect goes on.
  • The next call registers it, such as a reconnect's re-run, for a feature set whose host state couldn't be registered.
• By reading, the tune-out coordinator's state throws it when the state is written, and a failed read of it is still taken as no dispositions, as under Not covered.

By reading chronicle 0.4.0, which this release depends on, the one failure these registrations swallowed there is a closed store, and the tests show a closed store's failure thrown. Before, the next call on that state failed under its own name, if one came. A registration the store answers with "already exists", as on any restart with an existing store, is still taken as done. By reading, a chronicle whose registerState can fail an existing state on checkpoint I/O (anima-research/chronicle#22) would make a restart fail at create(), addModule(), initStore() or an MCPL registration, where main swallowed it.

What each part is for

The change is for one thing: a state registration that fails for anything but "already exists" fails at the call that registers it, naming the state, instead of surfacing later at another call under that call's name.

• ensureStateRegistered, one helper for all seventeen registrations: the rule isStateExistsError already stated lives in one place, and when chronicle's error codes are released, the change is to isStateExistsError alone. Weighed: putting isStateExistsError into each of the twelve catch-alls. That fixes the same sites, but leaves seventeen copies of one rule. The twelve came about that way, beside the five that already did it right.
• The error names the state and keeps the store's error as its cause, so whoever meets the failure knows which registration it was, rather than reading the store's message alone.
• One order changes, because a registration there can now throw (the workspace's initStore()): it took each mount before registering the next mount's states, a registration that swallowed its failure, so the order changed nothing. Now a failure there would leave earlier mounts taken with no agreement. Registering first lets the next call try again. A feature set's host state was already registered and read before its tree was held on main. Its registration moves into the read's try, so that its failure says what it stops, as a failed read does. The two latches, registerLogState()'s and the tool-result guard's, already registered first and rethrew on main, and their removals now pin that order.
• registerLogState()'s doc says its cadence applies when the state is first registered, and that a registration that fails throws, naming the state, and leaves the name unregistered.
• The test that src has no registerState call outside the helper: it reads the source rather than behaviour, and would fail a registration written correctly another way. It's kept because it's the only check that reaches a registration added later, which is how the catch-alls came about.

Cut before this pass: the round's first build also opened the workspace's disk agreement before initStore() took the store, so that a failed read of it left the module as it was too. No test pinned it, so it came out. Cut by this pass: nothing.

Evidence

On Linux, from a fresh install with chronicle 0.4.0, context-manager 0.14.1 and membrane 0.5.87.

At 5a8192983, this head. It merges main at 77066360 as bf27f3be1, then makes the host-state refusal change above:

• The tests that reach these paths: 21 files (this PR's, boot-state-read-errors, the checkpoint, workspace, tool-result-guard and code-execution files among them) pass 784/784 at bf27f3be1, on Node 24.22.0 and on Node 20.20.2 with --test-force-exit. At 5a8192983, state-registration-errors, boot-state-read-errors, checkpoint-attribution and mcpl-reconnect-reregistration pass 71/71 on both. Typecheck and build are clean at both.
• Red-first for the refusal change: with bf27f3be1's checkpoint-manager.ts and this head's tests, the two host-state registration tests fail, and so do the three that read the host-state refusal's text.
• CI at this head: the four Build & Test jobs, Node 20 and 24 on Ubuntu and on macOS, each running the whole suite through npm test, and the packed-install check, all passed.

At 1c6e2058, before the merge, after an internal review of 13ddda9c:

• The tests: test/state-registration-errors.test.ts passed 25/25 on Node 24.22.0 and on Node 20.20.2. It injects an I/O error into one registration at a time through each entry point above, and checks that the error names the state. It also checks the helper on both paths, against the store's own answer to a second registration and against a real closed store; that a feature set, a module's log state and the guard's audit state each register on the next call after a failed one; that a failed initStore() takes no mount; and that src has no registerState call outside the helper.
• Red-first: with the first commit's three changed sources and that head's tests, 23 of the 25 failed: every test that reads a registration's error, since the error now names the state, and that round's new ones. The two that passed are the "already exists" test and the source check.
• Removals: each of 8 pieces, taken out alone, failed a test. They are the helper naming the state and keeping the cause; the feature set recorded only after its registration; the mounts taken only after every registration; both latches, registerLogState()'s and the guard's, set only after their registrations; and neither of those two registrations swallowing its failure.
• The full suite, each file run on its own: Node 24.22.0 unforced, 2,397/2,397 in 151 files. With --test-force-exit, Node 20.20.2 also counted 2,397/2,397, and Node 24.22.0 counted 2,379/2,379: it cut history-module-realstore (20 of 28) and history-module-ux (16 of 26) short, each of which passes whole unforced (npm test's --test-force-exit can end a test file before its tests report, so a short run still passes #294). Typecheck and build were clean.

At 13ddda9c, the first commit:

• The tests: the file passed 20/20 on Node 24.22.0 and Node 20.20.2.
• Red-first: with main's sources and only the helper added, 14 of the 20 failed. The six that passed pinned what main already did right: the helper's two tests, and the turn-checkpoint, module log, channel lifecycle and label-history registrations.
• Removals: each of 19 pieces, removed alone, failed a test. Each of the twelve catch-alls, put back, failed its own entry point's test and the source check. Each of the five registrations that already rethrew, written back as its own correct try, failed the source check. The helper swallowing everything failed 18, and the helper refusing "already exists" failed its own test.

Not covered

• Reads that turn a failure into empty state are a separate defect. By reading at this head, the tune-out coordinator's readDispositions caches {} after any failed read, and its next write puts that back. With this change a read's failed registration reaches that catch too; on chronicle 0.4.0 that failure is a closed store, where main's read failed as well. The conversation router's generation read swallows a failure too. Both are left for a change of their own.
• An MCPL startup connect or reconnect whose setup fails after its connection is made: by reading, the server stays connected, with its later feature sets unregistered. That predates this change for any setup step after the connection, and is left for a change of its own.
• addModule() keeps a module whose start() rejects, as it does for any start() failure. That's left for a change of its own.

Read by Gordon-2414 (Claude Opus 5.5). He read the change whole, the first commit and the round, at 1c6e2058, and checked the receipts above against the text. Then he read the merge of main (bf27f3be1, the remerge diff and this change against main) and the refusal change (5a8192983).

We won't merge this before 05:00 UTC on October 18, or before our pre-merge checks pass on its merge with the then-current main, and a line here asking us to wait holds it.

Written by Ada-1017.

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge; no new blocking issue was found.

Summary

Routes state registrations through ensureStateRegistered. Existing states remain a successful result; other failures name the state and retain the original error as their cause.

• State registration failures now name the state and reach the call that registered it.
• Workspace mounts are added only after all their states register.
• Feature sets are recorded only after their host state is ready.

nissa-seru explicitly leaves failed-start cleanup (#389), reads that treat errors as empty state, partial MCPL setup, and modules retained after start() fails for separate changes. The source-only check is intentionally kept to catch later registrations outside the helper.

Tests were inspected, not run.

_{Reviews (2) · Last reviewed commit: "fix(store): a failed registration names ..." · Reviewed by Greptile}