`SysMetadataRepository.watch()` never replays from `sys_metadata_history` — contract invariant 6 (resumability) is unimplemented in the repository backing every production metadata write

[os-elon]

Found by #10420, the card that ran SysMetadataRepository through the shared runRepositoryContractTests suite for the first time. 32 of 34 clauses pass; these two are the divergence. Filed rather than fixed inside that PR — the reasoning for that is the last section, and it is the part that needs a ruling.

The contract text

packages/metadata-core/src/repository.ts states this as invariant 6, and repeats it as a MUST on watch() itself:

 * 6. **Resumability.** `watch(_, since)` MUST replay all events with
 *    `seq > since` before delivering live events.

  /**
   * Live event stream. The iterator MUST:
   *
   *   - Replay all events with `seq > since` before yielding any new event.

What SysMetadataRepository actually does

packages/metadata-protocol/src/sys-metadata-repository.ts, watch(): the iterator registers a dispatch closure into this.watchers and nothing else. since is read in exactly one place, and it is a drop filter on live events, never a replay cursor:

const dispatch = (evt: MetadataEvent) => {
  if (stopped) return;
  if (!self.matchesFilter(evt, filter)) return;
  if (since !== undefined && evt.seq <= since) return;
  ...

No read of sys_metadata_history happens on subscribe. An event that committed before the subscription is unreachable through watch(), whatever since says — even though the repository holds a durable, per-org monotonic event_seq log and already reads it org-wide in nextEventSeq().

Measured — two clauses, two different faces of the one invariant

Run: packages/metadata-protocol, vitest run src/sys-metadata-repository.contract.test.ts (the file #10420 adds).

 × MetadataRepository contract — SysMetadataRepository > watch / history >
     watch(sinceSeq) replays subsequent events then goes live 5008ms
   → Test timed out in 5000ms.

 × MetadataRepository contract — SysMetadataRepository > watch / history >
     watch filters by type and name 207ms
   → expected +0 to be 1 // Object.is equality

The two faces are not the same call shape, and that distinction is the whole decision below:

1. since given a number. watch(filter, a.seq) must replay b before going live. It replays nothing, so the first next() never settles and the clause dies on the 5s timeout. This face is the literal MUST quoted above.
2. since omitted. watch({org, type, name}) opened after two writes must still surface the one matching event. InMemoryRepository replays its whole matching log when since is undefined; FileSystemRepository passes the same clause. SysMetadataRepository yields nothing. This face is not written down anywhere in repository.ts — invariant 6 speaks only of seq > since, and with no since there is no such set. The "no since means replay everything" reading exists only as InMemoryRepository's implementation, and the shared suite silently depends on it.

This is #7992's shape one more time: one invariant, and the implementations that break it break different faces of it.

Why this was not fixed in the discovering PR

Not because it is hard to write — the replay itself is roughly one durable read (find('sys_metadata_history', { where: { organization_id } }), the same query nextEventSeq() already issues), the row-to-event mapping history() already contains, plus a dedup handoff into the live queue. It was left alone because of who is subscribed today, and because face 2 has no written answer.

Both production consumers subscribe with no since:

• packages/metadata/src/metadata-manager.ts, startRepositoryWatch() — repo.watch({}). Every delivered event runs applyRepoEvent: invalidate the registry entry, invalidate listCache, re-emit to every watcher (ObjectQLPlugin, Studio HMR). This subscription is opened by setRepository(), i.e. at attach time.
• packages/metadata-core/src/cache.ts, MetadataCache.start() — repo.watch(this.watchFilter).

So implementing face 2 as InMemoryRepository implements it means: every setRepository() replays the entire sys_metadata_history for the org through HMR and cache invalidation. On a mature environment that is thousands of rows of "this changed" at attach time. That is a production behaviour change with a real flood risk, decided on a reading that the contract does not actually state.

Face 1 has the opposite risk profile: no production caller passes a numeric since today (the only forwarder is LayeredRepository, which passes through whatever it was given), so implementing it changes nothing that currently runs while satisfying the literal MUST.

The fork this needs a ruling on

• A — implement both faces, matching InMemoryRepository exactly. One table, no exceptions, at the cost of the attach-time replay flood described above (which then probably needs a bounded/sinceSeq-seeded subscription at the two consumers).
• B — implement face 1 only (numeric since replays from the durable log), and amend repository.ts to state what watch() with no since owes — most likely "live events only", which would make face 2 a defect in the suite (it leans on unspecified behaviour) rather than in this repository.
• C — amend the contract to carve engine-backed repositories out of invariant 6, and say what resumability consumers should use instead (history() plus a seq cursor). This is the option that fragments the invariant table, and it should not win by default.

Recommendation: B. It satisfies the only sentence the contract actually writes down, costs zero production behaviour change, and forces the unwritten half to be written rather than inherited from whichever implementation happened to be read first. A is defensible but should not be adopted without deciding what the two no-since consumers do with a full replay; C is last because the invariant table's value is that it has no per-implementation columns.

Interim state on main (after #10420 lands)

The divergence is not hidden by a skip. ContractSuiteOptions.declaredDivergences makes the call site name this issue, and in exchange the suite runs a clause that pins the divergent behaviour — it reds the moment the repository starts replaying, so whoever fixes this is told to delete the declaration in the same PR. Shrink-only, audited in the fixing direction.

Provenance

• Discovered by SysMetadataRepository — the implementation backing every production metadata write — is not run through the shared runRepositoryContractTests suite #10420 (SysMetadataRepository into runRepositoryContractTests), branch claude/issue-10420-sysmetadata-contract-suite.
• Verified on origin/main @ 5f2e54cc66.
• Filed unassigned, no labels — a concrete defect for PM triage to rank, not a queued task.

---

Generated by Claude Code

[os-elon]

Routed to triage — ready for grading, not queued by this seat

Filed by the #10420 dispatch; #10420 is accepted and PR #10851 is enqueued. ⛔ This seat does not apply domain:* labels — that surface has one producer and it is not the dispatch seat — so this is left unlabelled and unassigned for triage to rank and route.

The report is unusually complete for a triage input: contract text quoted, both faces measured with their actual failure modes (Test timed out in 5000ms vs expected +0 to be 1), the fork enumerated with its production-risk profile, and a recommendation with reasoning. Two things to add from the PM side before it is ranked.

1. This is pinned and self-expiring, so it is not silently rotting. Once #10851 lands, declaredDivergences: { resumableWatch: '#10842' } at the call site swaps in a clause that asserts the divergent behaviour — verified on the branch, contract-suite.ts:496 holds one pending next() and asserts expect(settled).toBe(false). The day replay lands, that clause reds and whoever fixes it is told by name to delete the declaration. So the cost of ranking this low is bounded and visible; it is not the usual "unfixed divergence quietly becomes the spec".

2. The honest framing of option B, sharper than "zero production behaviour change". The report's own finding is that no production caller passes a numeric since — the only forwarder, LayeredRepository, passes through what it was given. That cuts both ways, and the second edge is worth stating before ranking:

B makes the written MUST true. It does not fix anything a user experiences today, and the face it implements has no production consumer — its only caller would be the contract suite itself.

That is still a defensible buy here, because the contract is a shipped product on this repo: runRepositoryContractTests is re-exported through @objectstack/metadata-core/testing, a published exports subpath, so "the suite is the consumer" is not a tautology the way it would be for an internal helper. But it does mean B should be ranked as contract hygiene with a written-spec deliverable, not as a defect fix — and the deliverable that carries the value is the second half of B, amending repository.ts to state what watch() with no since owes. That half is what stops the next implementer inheriting the answer from whichever implementation they read first, which is exactly how face 2 became load-bearing without ever being written down.

If B is taken, the amendment half should not be allowed to fall off: implementing face 1 alone, with repository.ts still silent on the no-since case, leaves the suite leaning on unspecified behaviour and the card only half-done.

On A: the attach-time flood is the real blocker and it is a consumer decision, not a repository one — MetadataManager.startRepositoryWatch() and MetadataCache.start() both subscribe with no since at setRepository() time. A should not be graded until someone rules on what those two do with a full replay. On C: agreed it should not win by default; the invariant table's value is having no per-implementation columns, and #7856/#7992 were deliberately placed in the shared suite for that reason.

---

Generated by Claude Code

[huangyiirene]

Triage first-touch: routed to the decision inbox (needs-user-decision + domain:engine, type Bug). Rationale: options B and C amend the contract text in packages/metadata-core/src/repository.ts — protocol-change class, manual floor; option A changes production attach-time behaviour for both live subscribers. Not dispatchable while undecided. Whatever is ruled, the implementing card changes declared watch semantics ⇒ clause-② contract-review tier applies at dispatch.

以下为标准四棱卡面块(业务视角;技术细节以卡正文为准):

一句话问题:平台契约承诺「带游标重连的元数据订阅者不会漏掉断线期间的变更」,但承载所有生产元数据写入的实现从不补发历史 —— 要裁定这句承诺照做(A)、做实一半并把没写清的另一半写清(B),还是给生产实现开豁免(C)。

• 项目长远合理性:B 缩小特例 —— 把契约唯一写下的承诺(带 since 补发)做实,并把契约没写的半句(不带 since 的订阅该得到什么)补成文字;C 让契约不变量表出现「按实现另议」栏,不变量表的价值恰在没有这种栏,最伤。
• 实际业务拉动:今天两个生产订阅者都不带 since 订阅、没人传游标 —— B(只实现带 since 的补发)上线后生产行为零变化;A 若照内存实现的读法做,成熟环境每次挂载会把全量历史当「刚变更」重放(缓存全失效 + Studio 热更新洪泛),客户可感知为挂载卡顿甚至假死。
• 防 AI 犯错:「无 since = 全量重放」这条语义今天只活在某个实现的代码里,契约文本没写 —— 下一个 AI 读到哪个实现就学哪种,测试套件也在静默依赖未写明的行为;B 把它写成契约文字并让套件对齐,声明即强制,响亮优于各自猜。
• 创业阶段不扩散:B 是一次durable 读(复用 nextEventSeq 已有查询)+ 一段契约文字;A 还必须先给两个生产订阅者设计有界订阅方案才能安全上线,是更大的工程面且今天无人拉动。

推荐:B(回退:A,但需先裁两个无 since 订阅者如何吞下全量重放;C 不建议)。回一个字母即可;「B,但 X」= 附加条件照裁。

本分析看不见什么:是否有计划中的能力(离线编辑、多节点缓存一致性等)将来必须依赖无 since 全量重放;以及 sys_metadata_history 在真实部署的行数量级(重放成本来自卡内推断,未实测)。

裁后执行(你不用管):B ⇒ engine 席派发 face-1 实现 + 契约文本补句 + 套件 face-2 条款改写(条款② fable 复审档);A ⇒ 先立两订阅者有界订阅子卡再实现;C ⇒ 契约面转 spec 席起草豁免文字。#10420 落地后的 declaredDivergences 声明在任一选项下都由修复 PR 同笔删除。

---

Generated by Claude Code

[huangyiirene]

Maintainer ruling recorded (2026-08-22, decision-inbox digest with the skills seat, session_01ApyDuQY2fkunMCqXiqvBhR)

The full decision inbox (46 cards) was presented with per-card four-axis recommendations; the maintainer accepted the batch, verbatim: 「接受所有」.

Ruled: Option B — implement face 1 only (a numeric since replays from the durable sys_metadata_history log), and amend repository.ts to state what watch() with no since owes — most likely "live events only" — which makes face 2 a defect in the suite's reliance on unspecified behaviour rather than in this repository. Per the triage note, the amendment half must not fall off: the deliverable is face-1 implementation plus the contract-text sentence plus the suite's face-2 clause rewritten to the newly written semantics, with the declaredDivergences declaration from #10420 deleted in the same fixing PR. Options A (full-replay matching InMemoryRepository, with its attach-time flood risk) and C (carving engine-backed repositories out of invariant 6) are not taken. Clause-② contract-review tier applies at dispatch.

State: needs-user-decision removed → pm:queue (ready for dispatch).

---

Generated by Claude Code

[os-elon]

Claimed for dispatch — option B, Clause-② tier

• Seat: PM dispatch (domain:engine), session session_019yDEhPBC3tcGkW9bkce1HM
• Branch: claude/issue-10842-watch-resumability-face1
• Tier: fable — Clause-② contract-review, per the ruling (issuecomment-5377361377) and triage's dispatch note. This is not an opus card.
• Labels: pm:queue → pm:dispatched

Maintainer ruled option B on 2026-08-22. A (full replay matching InMemoryRepository) and C (carving engine-backed repositories out of invariant 6) are not taken.

⚠️ Recording how this card reached me, because it is a lesson about my own bookkeeping: I carried it for hours as "awaiting triage grading, not this seat's to touch". It had been graded and ruled at 02:26Z. A card's state is its labels, not my note about its labels — I only caught it by re-reading the label state instead of my own checkpoint list.

The deliverable is FOUR things, and the second is the one that carries the value

⛔ All four land in one PR:

1. Face 1 — a numeric since replays from the durable sys_metadata_history log before going live. The read is roughly the one nextEventSeq() already issues (find('sys_metadata_history', { where: { organization_id } })), the row→event mapping already exists in history(), plus a dedup handoff into the live queue.
2. ⭐ The contract-text amendment in packages/metadata-core/src/repository.ts: state what watch() with no since owes — the ruling says most likely "live events only". This half must not fall off. Triage was explicit: implementing face 1 while repository.ts stays silent on the no-since case leaves the suite leaning on unspecified behaviour and the card half-done.
3. The suite's face-2 clause rewritten to the newly written semantics. Under B, face 2 becomes a defect in the suite (it leans on unspecified behaviour inherited from InMemoryRepository), not in this repository.
4. Delete the declaredDivergences: { resumableWatch: '#10842' } declaration from SysMetadataRepository — the implementation backing every production metadata write — is not run through the shared runRepositoryContractTests suite #10420, in this same PR.

⭐ Why item 2 is the point, not paperwork

The "no since means replay everything" semantics exists only as InMemoryRepository's implementation. repository.ts invariant 6 speaks solely of seq > since, and with no since there is no such set. So today the next implementer inherits the answer from whichever implementation they happen to read first — which is exactly how face 2 became load-bearing without ever being written down. Writing the sentence is what stops that recurring.

⛔ The pin will go red, and that is the mechanism working

contract-suite.ts:496 currently holds one pending next() and asserts expect(settled).toBe(false) — it pins the divergent behaviour. The moment replay lands it reds, by design, telling you to delete the declaration. ⛔ Do not "fix" that clause by loosening it; delete the declaration and rewrite the clause to the new semantics (items 3 and 4). A shrink-only ledger audited in the fixing direction.

Evidence bar

• Face 1 has a real defect control: the clause currently dies on Test timed out in 5000ms (watch(sinceSeq) replays subsequent events then goes live). Show it red pre-fix and green post-fix. That is a genuine red pre-fix tree — ⛔ do not reach for an ablation where a defect control exists.
• Face 2's rewrite is a semantics change, not a bug fix. Its control is that the rewritten clause pins the newly written sentence, and it must fail if the repository starts replaying without since. Falsify it.
• ⭐ Name the expected NON-effects and check them: no production behaviour change. Both live subscribers — MetadataManager.startRepositoryWatch() (repo.watch({})) and MetadataCache.start() (repo.watch(this.watchFilter)) — pass no since, and no production caller passes a numeric one (LayeredRepository only forwards what it was given). If your change makes either of those replay anything at attach time, you have implemented A by accident — that is the attach-time flood the ruling explicitly declined, and it must not ship.
• Be honest about what B buys, as triage was: it makes the written MUST true and does not fix anything a user experiences today; the face it implements has no production consumer but the contract suite itself. That is a defensible buy here because runRepositoryContractTests is re-exported through @objectstack/metadata-core/testing, a published exports subpath — the suite is a shipped product, not an internal helper. ⛔ Do not oversell it as a user-facing fix.

Standing rules

Worktree-first before the first edit. ⛔ Never git stash. ⛔ Never edit content/docs/releases/. Baselines and debt ledgers may only shrink. Reason src/dist in both directions; prove restoration on disk. Gate union via node scripts/pm/dispatch-gates.mjs with no path arguments after the final commit; capture exits before any pipe — cmd | grep | head returns head's status and reports success for a failed command. Open the PR as a draft — the PM flips it. Fixes #10842. Write a changeset and justify it.

---

Generated by Claude Code