fix(metadata-fs): FileSystemRepository.close() terminates every live watch() iterator (#11127)

[os-zhuang]

Fixes#11127

Before → after

Before.FileSystemRepository.close() retired the chokidar watcher and the resync sweep and stopped there. It never reached this.broker, and the broker had no teardown of its own — subscribe/unsubscribe add to and delete from a plain Set, and nothing else emptied it. Each watch() iterator parks its pending next() on a waiter that only two things can settle: a broker push, or the iterator's own terminator, which ran from iterator.return()/throw() and from nowhere else. After close() the chokidar source was gone so no push could arrive, and the subscriber was still registered with nothing left to run its terminator. A parked next() never settled.

Unlike the sibling defect in SysMetadataRepository (#11021), this was not filter-dependent — there was no drain attempt at all, so every subscription shape hung, watch({}) included. MetadataManager.startRepositoryWatch(), which awaits iter.next() in a while loop, is exactly the shape that hung.

After. The broker holds each subscription's terminator next to its event sink, and close() runs every terminator — the same routine the consumer's own iterator.return() runs. A parked next() settles with { value: undefined, done: true }, and so does every later one. Shutdown is deliberately not delivered as an event: a synthetic drain event is subject to the very filters watch() applies to real ones, and delivering an event has never ended an iterator (invariant 8). Termination runs beforeawait watcher.close(), so a rejecting watcher.close() cannot leave a consumer's for await parked.

Measured, same test file both times (packages/metadata-fs/test/close-terminates-watch.test.ts, committed red at 3e545f41 before the fix):

	metadata-fs suite
baseline, unmodified source	Tests 9 failed | 56 passed (65) — every one of the nine new cases returned Symbol(still-pending) 2s after close()
after the fix (609147d8)	Tests 65 passed (65)

Invariant 8's exception text — yes, it needed updating

Invariant 8 in packages/metadata-core/src/repository.ts named FileSystemRepository as the one measured non-conformance among today's three implementations. That sentence is stale as of this PR, so it is rewritten in the same change: the row now records that SysMetadataRepository conforms (#11021), FileSystemRepository conforms (#11127), InMemoryRepository offers no repository-level shutdown at all — no declared exceptions — plus a line saying a new implementation offering close() joins that list or it does not conform. No semantics were touched: the MUST, the MUST NOT, and the "events queued at that moment MAY be dropped" allowance are unchanged.

The implementation was cross-checked against SysMetadataRepository's post-#11021 shape and deliberately mirrors it — WatchSubscription { dispatch, terminate } there, BrokerSubscriber { push, terminate } here; snapshot-then-clear before terminating in both, so a terminate() that unregisters itself cannot make the set skip its neighbour; try/catch per terminator in both, so one wedged consumer cannot strand the rest. That symmetry is the whole reason the invariant exists.

One bounded repair beyond the parked-iterator case, named here because it is not in the card's text

watch() returns a deferred iterable: the subscriber is registered only once the eager log read resolves. A close() landing inside that window swept a broker the subscription had not yet joined, so the subscription arrived afterwards and parked forever — the same defect by a different route, in the same function, and a case the card's own acceptance shape cannot reach. watch() now carries the close generation it was opened under (arrivesClosed), and a subscription that arrives after a shutdown terminates on arrival. A counter rather than a boolean because start() may follow close() — a restart must not poison the watchers opened after it.

It is load-bearing, not decoration. Ablation (arrivesClosed wiring deleted, terminateAll() kept): mutation confirmed on disk (arrivesClosed occurrences 1 → 0, git diff showing the single deleted line), no dist involved — the pin imports ../src/index.js, and the one package-name import (@objectstack/metadata-core) is untouched by the mutation. Result: Tests 1 failed \| 64 passed — exactly the deferred-window case, no other. Restore leg confirmed (arrivesClosed back to 1, git status clean).

Verification — all at 609147d8, the head of this branch

• pnpm --filter @objectstack/metadata-fs test → 65 passed (8 files); baseline on the same committed pin → 9 failed / 56 passed.
• pnpm --filter @objectstack/metadata-fs --filter @objectstack/metadata-core typecheck → both Done (each runs tsc --noEmit && tsc --noEmit -p tsconfig.test.json).
• Downstream behaviour (... prefix = dependents): the FS-repo consumers in @objectstack/metadata, including the real-LiteKernel shutdown test that drives close() through MetadataPlugin.destroy() — metadata-repository-fs-dot-root, plugin-shutdown-releases-repository, plugin-no-metadata-root-on-boot → 10 passed (3 files).
• Published type surface is unchanged, measured rather than asserted: built dist/index.d.ts at this HEAD vs. at origin/main's packages/metadata-fs/src — the only non-comment line in the diff is private closeGeneration;. EventBroker/BrokerSubscriber stay module-internal (index.ts exports ./repository.js, JsonlLog, FsLayout only), and nothing in the repo extends or structurally implements FileSystemRepository.
• Gates, derived from the real change set with node scripts/pm/dispatch-gates.mjs (not from a hand-built diff), each read from the gate's own verdict line — all green: check:nul-bytes · check:changeset-gate-self-tests · check:objectui-changeset · check:slot-lookup ("ratchet holds … none new") · check:test-source-alias · check:type-source-resolution · check-adr-0087-registration · check-changeset-no-major ("introduces no major bump") · check-ci-filter-parity · check-empty-changeset · check-plugin-teardown-shape · check-affected-docs · and the convention-triggered set for a new test file: check:query-options-erasure · check:engine-double-contract ("OK — 384 pinned") · check:where-matcher · check:type-check-coverage.

Two declared narrowings

1. pnpm lint repo-wide is CI's run. Locally: eslint --no-inline-config over the 5 changed source files → 0 errors, 0 warnings, 5 of 5 actually linted (count read from --format json, so none was silently ignored). Untouched files cannot move: this repo runs one eslint.config.mjs which never enables type-aware linting for any file ("no parserOptions.project, no typed @typescript-eslint rules", the config's own words at line 328), so no verdict elsewhere is a function of this diff.
2. check:type-check-debt --re-measure not run locally — it requires the whole workspace built, which does not fit the container's foreground ceiling. Its population is the ledger literals in scripts/check-type-check-coverage.mjs (DEBT at line 495, TEST_DEBT at 709), and neither touched package appears in either — @objectstack/metadata-fs and @objectstack/metadata-core both type-check at zero residue and carry no entry, so no counted number is a function of this diff. The one route by which a ledgered dependent (@objectstack/metadata) could drift is the published .d.ts, measured unchanged above. The structural half, check:type-check-coverage — the one a new test file outside every tsc program moves — ran green.

Not in scope

No new test declares an engine double, so assertEngineUpdateDispatch/assertEngineDeleteDispatch are not involved. packages/spec, driver-sql, packages/core/src/fallbacks/** and content/docs/releases/ are untouched. No test was skipped, disabled or quarantined; no ratchet ceiling was raised.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/metadata-core, @objectstack/metadata-fs, touching 9 documentable anchor(s).

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/concepts/metadata-lifecycle.mdx(via FileSystemRepository (symbol))

What this run could not see

• 1 changed file(s) yielded no anchor (packages/metadata-core/src/repository.ts) — pages documenting those are invisible to this run
• 3 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 45 of 221 client-bound route-ledger rows — the other 176 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run: node scripts/docs-audit/affected-docs.mjs --bridge-coverage

Coarse fallback — 3 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 52a41b72ee01bc24bdd6ac8eb1a37485eb2b4946 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 10783626122ea976d25f2944fc7cee9a847905bd — the merge of head 609147d823d39248d3da7536d80f5d8a7246aa54 into base 52a41b72ee01bc24bdd6ac8eb1a37485eb2b4946, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 10783626122ea976d25f2944fc7cee9a847905bd && git checkout 10783626122ea976d25f2944fc7cee9a847905bd
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 52a41b72ee01bc24bdd6ac8eb1a37485eb2b4946 609147d823d39248d3da7536d80f5d8a7246aa54 && git checkout -B drift-repro 52a41b72ee01bc24bdd6ac8eb1a37485eb2b4946 && git merge --no-ff 609147d823d39248d3da7536d80f5d8a7246aa54
node scripts/docs-audit/affected-docs.mjs --json 52a41b72ee01bc24bdd6ac8eb1a37485eb2b4946

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 52a41b72ee01bc24bdd6ac8eb1a37485eb2b4946 → pass the list as
args.docs, on the commit named under Which tree this was computed on.