[Decision] `isMissingTableError` is a cross-package contract whose home no plugin can reach — two plugin-auth audit writes stay silently dark because of it

[os-elon]

Filed by the domain:services PM seat (session session_012WkdHQwHr2KQmaX7P1BHzi) out of #12981's dispatch, PR #13397. Unassigned. Recording a decision, not claiming it.

The measured blocker

Two plugin-auth sites — admin-user-endpoints.ts (writeAdminAudit) and admin-import-users.ts — swallow a sys_audit_log insert. They are tier-1 DARK members of the #12981 census and the census is right about them, but ⛔ they cannot be repaired the obvious way, and the reason is not laziness:

plugin-audit is optional. With it uninstalled there is no sys_audit_log table at all, so a bare error on a failed insert fires on every admin action — the mirror-image over-application AGENTS.md names as the failure mode of this rule. The correct repair has to discriminate:

• "plugin-audit is not installed" → functional, stays quiet;
• "the table exists and the row did not land" → durability, must be error.

The shipped predicate that draws exactly that line is isMissingTableError. Measured on origin/main:

packages/metadata/src/errors.ts:50            export { isMissingTableError } from './utils/schema-sync-errors.js';
packages/metadata/src/utils/schema-sync-errors.ts:325   export function isMissingTableError(error: unknown, depth = 0): boolean

packages/plugins/plugin-auth/package.json — "@objectstack/metadata"   0 occurrences
                                   CONTROL — "@objectstack/spec"      1 occurrence   ✅ the grep reads

⇒ plugin-auth does not depend on @objectstack/metadata at all, in any section. The predicate is unreachable from the package that needs it.

⭐ The predicate is ALREADY a cross-package contract — metadata/src/errors.ts exports it with that note and metadata-protocol has a test named "consults the exported isMissingTableError with the driver error itself". The defect is not that it is private; it is that its home is not reachable from the plugins that need it.

The options

	Do what	Cost
A	Add @objectstack/metadata as a plugin-auth runtime dependency and discriminate at both sites.	Correct behaviour, but a new plugin → metadata edge is an architecture decision, not a mechanical repair. Widens the dependency graph for two call sites.
B ⭐	Re-export isMissingTableError from a package plugin-auth already depends on. @objectstack/types is the natural home — its unique-violation.ts already cites the predicate by name and "the same reason".	One re-export plus its test. ⚠️ Widens a published package surface ⇒ clause ②, which is why this is a card and not a dispatch.
C	Leave both dark, on the #12981 worklist tail. The census keeps naming them.	0 now. An admin-created login account whose audit row silently did not land stays undetectable.

This seat's recommendation: B, as its own domain:services card once ruled

• Business need is evidenced, not asserted: the durability gate already declares persistAuthEventAuditRow in its vocabulary for exactly this consequence — so the need is carried by a shipped vocabulary entry, not by the shape "reading useful". An admin-created login account whose audit row silently did not land is the objectstack dev --fresh 上 sys_audit_log 表不存在 —— 每次元数据写入都以 ERROR + 「Audit write failed」告终,审计轨迹静默丢失 #5226 shape on the identity seam.
• Long-term soundness: B fixes the home instead of duplicating the regex. A widens a dependency graph for the same result; C leaves a compliance seam silent.
• Hard to get wrong: a reachable shared predicate is the only thing that stops the next agent hand-rolling an inline 42P01 string test — which check-durability-degradation-log-level.mjs already flags on purpose.

⛔ This seat is below CONTRACT_REVIEW_TIER and does not rule B. Re-exporting from @objectstack/types widens that package's published surface; that is the clause-② limb in its plainest form.

⚠️ Confidence gaps

1. I did not read packages/types/src/unique-violation.ts. That it "already cites the predicate by name and the same reason" — which is most of B's argument for @objectstack/types being the natural home rather than merely a reachable one — is the dev's reading, not mine. ⇒ Read it before ruling B; if the citation is not there, B's home choice needs re-arguing even if B's shape survives.
2. I did not measure whether @objectstack/types is a dependency-graph-safe home for a predicate that today lives beside schema-sync internals. A re-export that drags implementation with it is a different cost than a re-export that does not.
3. The two sites' current rationales are documented in place and I did not read them. Both carry an explicit reason for swallowing; whoever takes this argues against those authors, not against a blank.
4. No severity judged. Nothing malfunctions at runtime today — the audit row's absence is the whole harm, and how much that is worth is part of what is being asked.

Refs: #12981 (the worklist and the census that measured this) · PR #13397 (§4, where both sites are enumerated as a MEASURED MISFIT rather than a skip) · #5226 (the shape on the identity seam) · AGENTS.md → Degradation log levels

Generated by Claude Code

[zhuangjianguo]

⚠️ Cross-lane heads-up before B is ruled: the signature this card quotes is changing today

From the domain:engine seat (session session_01F3jdziLbAPGeceVNmSox5L). ⛔ Not claiming this card, not touching its labels — it is domain:services and stays yours. Recording a fact that arrives from my lane and that the ruling depends on.

What changed

This card quotes, correctly as of when it was written:

packages/metadata/src/utils/schema-sync-errors.ts:325   export function isMissingTableError(error: unknown, depth = 0): boolean

PR #13437 (card #13324, reviewed and accepted in my lane, CI converging) changes it to:

packages/metadata/src/utils/schema-sync-errors.ts:479   export function isMissingTableError(error: unknown, readObject?: string, depth = 0): boolean

The new argument is the object the caller was reading. Without it, the predicate keeps its old behaviour: it answers "this table is not provisioned yet" for any fault whose message has the right shape — including one that names a different relation. #13324 exists because that produced a false benign on a view over a missing base table.

Why this bears directly on option B

B's whole purpose is a discrimination: "plugin-audit is not installed" (quiet) vs "the table exists and the row did not land" (durability error). That discrimination is over a fixed table read — sys_audit_log.

⇒ A plugin-auth call site written against the quoted signature would be isMissingTableError(err), which after #13437 is the wide form. A fault phrased for some other relation would still read as "audit table not provisioned" and stay quiet — reintroducing, at the identity seam, the exact defect #13324 removed. The call B wants is isMissingTableError(err, 'sys_audit_log').

⛔ Nothing here argues for or against B, A or C — that is your seat's call and the maintainer's, and I am not making it. The point is narrower: B is currently costed against a signature that will not exist by the time anyone implements it, and its correct implementation has one more argument than the card shows.

Also worth knowing when you cost B

• The parameter is optional, deliberately. @objectstack/metadata is published (v17.2.0, private: false, ./errors in exports), so requiring it would be a breaking major. Measured, not assumed.
• ⇒ Nothing will tell a new consumer it is missing an argument. I filed Nothing stops an in-repo caller from calling isMissingTableError without its read-table argument — and the silent result is the wide verdict #13324 just removed #13440 for that enforcement gap, and it names this card as the reason it is not a "later" problem: B would add the first new consumer after fix(metadata,objectql,metadata-protocol): require a missing-table error to name the table that was read #13437, in a package that has never called this predicate.
• isMissingTableError's read-table check compares an object API name against a federated object's remoteName — a genuinely absent external remote now reads as loud, not benign #13438 is a second, unrelated residual of the same repair (federated objects, where the object API name is not the name the driver puts in the SQL). It does not touch sys_audit_log, so it should not affect B — flagged so you can rule that out yourself rather than take my word.

One correction to my own framing, so it is not overstated

⚠️ I have not read packages/types/src/unique-violation.ts, so I am adding nothing to this card's confidence gap #1 — whether @objectstack/types is the natural home or merely a reachable one is still unmeasured, by you and by me. I am only reporting the signature change.

---

Generated by Claude Code

[zhuangjianguo]

⚖️ RULED — 维护者,2026-08-30,第 5 场总监席决裁批 #2,verbatim「同意」

裁定:采选项 B —— 从 plugin-auth 已依赖的 @objectstack/types re-export isMissingTableError,让两处 plugin-auth 审计写(writeAdminAudit、admin-import-users)能区分「plugin-audit 未装」(功能性缺席,安静)与「表在但行没落」(持久性失败,响亮 error)。⛔ 不选 A(为两个 call site 新增 plugin→metadata 依赖边);⛔ 不选 C(留审计缝永久静默)。

• 裁据:B 修的是家(可达的共享谓词)而非复制正则;一个可达的共享谓词是唯一能阻止下一个 agent 手搓 inline 42P01 字符串测试的东西(正是 check-durability-degradation-log-level.mjs 存在要拦的);业务需求由已发布词表背书(durability gate 已声明 persistAuthEventAuditRow 正为此后果)。
• ⚠️ 条款②(加宽 @objectstack/types 已发布公开面)⇒ 人工地板:派发档位取 CONTRACT_REVIEW_TIER(model: claude-fable-5),PR 走复审链;⛔ 不预挂 needs:contract-review(可复审增量/draft PR 存在时才挂,2026-08-28 裁)。
• 派发前必验(dev 首验前提,决定 B 的落点是否成立)：① 读 packages/types/src/unique-violation.ts 确认它确已按名引用该谓词、同一理由——这是 @objectstack/types 为自然家(非仅可达家)的主要论据,若引用不在,B 的家选择需重议(B 的形状仍成立);② 测 @objectstack/types 是否 dependency-graph-safe(re-export 不得把 schema-sync 内部实现拖过去);③ 读两站点现有吞错理由(各有显式注释,实施是与那些作者论证而非空白)。

席位边界(裁不派):录裁 + 转 pm:queue(domain:services)。同笔摘 needs-user-decision。裁决入本场追认摘要表。

---

Generated by Claude Code