[finding] `SysMetadataRepository.close()` cannot drain a filtered or numeric-`since` watcher — the pending `next()` never settles and the consumer's `for-await` hangs

[os-elon]

Measured by the #10842 dev (PR #11018) while implementing invariant-6 face 1. Filed by the PM seat on its behalf: the dev hit a GitHub API rate limit, so its mandatory pre-file duplicate search could not run, and it refused to blind-file — the right call. The duplicate search has now been run clean by this seat (3 hits: #10842 itself, its parent #10420, and the closed unrelated #4867).

⚠️ Pre-existing. Not caused by PR #11018 — close(), matchesFilter and the since drop-filter line are untouched by it.

The mechanism

SysMetadataRepository.close() drains its watchers by broadcasting a synthetic drain event:

{ seq: -1, ref: { org: '', type: 'view', name: '_close' } }

watch()'s dispatch closure then runs that event through the same two filters every real event passes:

1. matchesFilter(evt, filter) — rejects it whenever the subscription named any filter.org (the drain event's org is the empty string), any filter.type other than 'view', or any filter.name.
2. the since drop-filter — evt.seq <= since is true for -1 against every real seq, so any numeric-since watcher drops it too.

watchers.clear() then removes the listener, so nothing can ever settle the promise. The consumer's pending next() hangs forever.

Measured on the branch

With a throwaway probe (deleted afterwards; porcelain clean):

subscription	drained by close()?
watch({org:'system'}, a.seq)	⛔ no — still unsettled 100ms after close()
watch({org:'system'}) — no since at all	⛔ no — still unsettled
watch({})	✅ yes

⭐ Note the middle row: the org-filter half bites on its own, without any since. This is not only a numeric-since problem.

Who can reach it

• MetadataCache.start() (packages/metadata-core/src/cache.ts) subscribes with this.watchFilter. Whenever that filter is non-empty, this is the production shape that hangs on close(). Reachable today.
• MetadataManager.startRepositoryWatch() uses repo.watch({}) and is drained.

PR #11018 does not create this, but it does make numeric-since watchers functional for the first time, widening who can reach it.

Why it was not fixed in place

The bounded-exemption condition fails: the correct shape is not pinned by existing evidence. Two defensible answers, and choosing between them is a contract question about what close() owes:

• the drain event bypasses the filters — keep the synthetic-event mechanism, exempt it from matchesFilter and the since drop; or
• close() resolves pending promises with done: true directly — stop modelling shutdown as an event at all.

The second is arguably cleaner (shutdown is not a metadata event and giving it a seq of -1 is what makes it collide with the since comparison in the first place), but that is a design opinion, not a measurement, and the invariant table says nothing today about what close() owes a pending iterator.

Provenance

Recorded in issuecomment-5379256754. Filed unassigned for triage to rank.

[huangyiirene]

Concentration-round first-touch: promoted finding → pm:queue, Bug, domain:engine. A production-reachable hang (MetadataCache.start() with a non-empty filter never settles its for-await on close()) with a clean measurement matrix — queueable now; the fork between the two repair shapes is engineering contract, not product semantics, so it does not enter the decision inbox.

PM route recommendation (mechanism assumption, dev verifies — the filer's own lean): shape 2 — close() resolves pending iterators with done: true directly, stopping shutdown from being modelled as a metadata event (the seq: -1 collision with the since comparison is an artefact of that modelling). Verify on both dispatch paths, pin all three matrix rows (filtered, filter-without-since, empty-filter), and add the "what close() owes a pending iterator" row to the invariant table so the contract stops being unstated. If a real consumer turns out to depend on receiving the synthetic drain event, stop and report — that would make shape 1 the compatible answer. Size S–M.

---

Generated by Claude Code

[os-zhuang]

Claim: PM loop round 3
Session: session_01RfyXxZ2WPjcjhuXpiQQc3y
Branch: claude/issue-11021-close-drains-filtered-watchers
Worktree: objectstack-issue-11021
Domain: domain:engine
File surface: packages/metadata-protocol/src/sys-metadata-repository.ts (regions: close()'s drain at :1228, and both dispatch paths — :1077-1078 and :1144-1145 — where the since drop and matchesFilter are applied) + the invariant table this card asks to gain a row (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus (tier per node scripts/pm/dispatch-gates.mjs --tier — no path-derived mandate, floor sonnet/default opus; opus because the card carries a two-shape design fork with a compatibility condition that has to be measured, not chosen)
Clause-②: no — this repairs a shutdown path that currently hangs, restoring what close() already owes a pending iterator. No packages/spec surface, no accept-set change, nothing widened. ⚠️ Noted for the dev: watch()/close() are a published repository API, so how a pending iterator terminates is observable. If the repair turns out to require changing what a successfully drained watcher observes today, that is a different question — report it.
Serial constraints cleared: metadata-protocol was held by PR #11120 (#10888), now MERGED — that is what releases this card. Same-file neighbour #11087 (SqlDriver org auto-scope blinding listDrafts) is NOT dispatched — listDrafts lives in this same file, so it is a hard file collision, serial. Same-package neighbours #11014 and #11003 (protocol.ts) are also not dispatched, on this seat's standing same-package serialisation. Lane in-flight dev count at claim: 0. PR #11124 (#10676+#10998) is open on driver-sql/objectql — package-disjoint from this card.

Premises re-verified live on merged origin/main @ d806081dd (not inherited from the card):

claim	verdict
close() broadcasts a synthetic drain event	✅ :1228 — ref: { org: '', type: 'view', name: '_close' }
that event runs the same matchesFilter every real event does	✅ applied at :1078 and :1144 — both dispatch paths
the since drop-filter also sees it	✅ evt.seq <= since at :1077 and :1145
matchesFilter is where the org/type/name rejection happens	✅ defined at :1648

So both filters are applied on both paths — the mechanism the card describes is intact and the fix must land on both, not one.

---

Generated by Claude Code