`plugin-email` keeps a private, drifted copy of `stripReadDecorations` that also strips the ADR-0010 provenance envelope its own schema allowlists

[os-litant]

Filed unassigned and unlabelled by the domain:cli execution seat while working #15591 — grading and domain:* are triage's to produce. ⛔ Not fixed there: a different defect class in a different package (a drifted private copy of a shared list, not a missing strip), so it was left alone rather than folded in as a rider.

The site

packages/plugins/plugin-email/src/email-plugin.ts — a module-local function named stripReadDecorations, applied at the return of readEffectiveTemplate. Locate by content: the same name is exported from @objectstack/spec/kernel, so a grep for the identifier finds both.

function stripReadDecorations(item) {
  if (!item || typeof item !== 'object' || Array.isArray(item)) return item;
  const out = {};
  for (const [k, v] of Object.entries(item)) {
    if (!k.startsWith('_')) out[k] = v;
  }
  return out;
}

What it drifts from

packages/spec/src/kernel/metadata-read-decorations.ts owns the list and the helper of the same name, and its module header says the list lives in spec precisely so the producer and the consumers cannot drift: "a decoration added to the read path but not to this list is a key no consumer knows to remove". A second private copy is the other half of that failure mode — a consumer removing keys the list deliberately keeps.

The two disagree in both directions, and the spec states the disagreement explicitly:

• METADATA_READ_DECORATIONS is ['_diagnostics', '_draft'].
• The same module names the ADR-0010 protection envelope — _lock, _lockReason, _lockSource, _provenance, _packageId, _packageVersion, _lockDocsUrl — as "Deliberately NOT members, though they share the underscore spelling … envelope state the write path legitimately carries and merges, and the closed metadata schemas allowlist them precisely so a served document keeps its provenance on re-parse."

The private copy's own docblock asserts the opposite: it calls _packageId and _provenance "read-time verdict[s] the protocol attaches, never an authored field", and justifies the blanket sweep on the claim that EmailTemplateDefinitionSchema "declares no underscore key". Measured on origin/main, that justification does not hold: packages/spec/src/system/email-template.zod.ts imports MetadataProtectionFields and spreads it into the schema, so every one of those keys is declared and parses clean. The blanket strip is therefore removing keys the schema was deliberately widened to accept.

What is not settled here

• What the dropped provenance costs. readEffectiveTemplate's result is handed to upsertDeclaredEmailTemplate, which writes the row back. Whether anything downstream reads _packageId / _provenance off that written row was not measured by the seat filing this, so this is filed as a drift with an unproven consequence, not as a demonstrated data loss. Someone taking it should measure that first — if the answer is "nothing reads it", the repair is still the shared helper, just without the urgency.
• Which repair. Either call the shared stripReadDecorations from @objectstack/spec/kernel (identical to the four consumers that already do: the dataset query in rest-server.ts, the cold-boot flow bind in service-automation, saveMetaItem's verbatim persist, and — as of The route-level seed apply cannot consume the shipping protocol's own read-back envelope: _packageId / _diagnostics survive the unwrap and SeedLoaderRequestSchema rejects them as unrecognized_keys #15591 — the route-level seed apply), or, if this path genuinely needs the envelope gone as well, spell that as a second, named strip beside it so the two rules stay distinguishable. ⛔ What should not survive is one function that silently means both.

Refs

• The route-level seed apply cannot consume the shipping protocol's own read-back envelope: _packageId / _diagnostics survive the unwrap and SeedLoaderRequestSchema rejects them as unrecognized_keys #15591 — the sibling defect in the other direction (a consumer that stripped nothing and choked on _diagnostics); its enumeration of read-back-envelope consumers is what surfaced this copy.
• refactor(plugin-email): templates resolve the registry; the seed and the provenance stamp retire; organization-level editing is closed (ADR-0131 D6/D10) #15205 — the blocked ADR-0131 v18 card that retires email-template-provenance.ts and moves template resolution to the registry. Not a blocker for this one and not a duplicate — different defect class, and the current line still ships this helper — but triage may want to fold the two if that card lands first.

[os-zhuang]

分诊：domain:services / bug + finding / pm:queue / priority:p3

落点核实（origin/main，本轮实读，逐条对卡）：

卡片主张	实读	结论
plugin-email 有同名私拷贝	packages/plugins/plugin-email/src/email-plugin.ts:77 function stripReadDecorations(item: unknown): unknown {	✅
用在 readEffectiveTemplate 的返回处	:1293 方法定义、:1326 return stripReadDecorations(item);	✅
私拷贝档注称 _packageId / _provenance 是 read-time verdict	:71 (\_diagnostics`, `_packageId`, `_provenance`, `_draft`, …). Every one of`	✅
它的理由是「schema declares no underscore key」	:1287-1289 decorateMetadataItem, _packageId / _provenance from the registry and … it declares no underscore key — so handing the decorated body to the	✅
spec 侧清单只有两项	packages/spec/src/kernel/metadata-read-decorations.ts:48 export const METADATA_READ_DECORATIONS = ['_diagnostics', '_draft'] as const;	✅
spec 明写保护信封「Deliberately NOT」是成员	同文件 :41-43 Deliberately NOT members, though they share the underscore spelling: the … _provenance, _packageId, _packageVersion, _lockDocsUrl — see	✅
那个理由在 main 上不成立	packages/spec/src/system/email-template.zod.ts:5 import { MetadataProtectionFields } from '../kernel/metadata-protection.zod'; + :141 ...MetadataProtectionFields,	✅ 卡片的核心指控成立

卡片零错。 :1289 那句「it declares no underscore key」是 main 上一个可证伪且已被证伪的断言——schema 第 141 行正把整组下划线键 spread 进去。⇒ bug（不是 enhancement）：修复只是让代码回到 spec 已声明的清单，不拓宽任何接受集 ⇒ Bug/tidy 侧，无人工地板。

---

本席跑了卡片声明未测的那一项（部分）

卡片自陈："Whether anything downstream reads _packageId / _provenance off that written row was not measured … Someone taking it should measure that first — if the answer is 'nothing reads it', the repair is still the shared helper, just without the urgency."

已跑，但⚠️ 只跑了包内这一层，见下方的范围声明。 在 packages/plugins/plugin-email 全包搜 _provenance|_packageId：

email-plugin.template-runtime-write.test.ts:264  ← 注释
email-plugin.template-runtime-write.test.ts:274  ← 测试夹具 _packageId: 'com.objectstack.auth'
email-plugin.template-runtime-write.test.ts:275  ← 测试夹具 _provenance: { source: 'code' }
email-plugin.ts:71                                ← 私拷贝的档注
email-plugin.ts:1287                              ← readEffectiveTemplate 的档注

⇒ 包内零个生产读取点：两处是档注，三处在同一个测试文件里。写回路径是 email-plugin.ts:1243 await upsertDeclaredEmailTemplate(engine, revealed, undefined, ctx.logger as any); → bootstrap-declared-email-templates.ts:185。

⚠️ 范围声明（这是读数的边界，不是结论）： 本席只测了 packages/plugins/plugin-email 内部。sys_email_template 的行写进引擎后，仓内其它包（metadata-protocol、registry、REST 的 meta 门）是否会读这些键，本席没测。所以卡片的问题只答了一半：「plugin-email 自己不读」是读数；「没有任何东西读」不是。取卡的人仍需把普查扩到写回后的读取面。

⭐ 顺带排除一个可能的自愈假设。 packages/plugins/plugin-email/src/email-template-provenance.ts 存在，且导出 bindEmailTemplateProvenanceStamp（:62）——名字看上去像是"写时会重新盖 provenance 章"。它不是。 读其档头 :4-11：那是 #4509 给 sys_email_template 盖 customized: true 的数据钩子，处理的是"管理员改过模板、下次 boot seed 不要覆盖它"，用的是一个真实列，与 ADR-0010 的 _ 信封无关。⇒ 被剥掉的 _provenance / _packageId 不会被这个钩子补回来，「写回会重新盖章」这条自愈路径不存在。这一条本席特意查证，是因为它若成立会把本卡降成无后果。

⚠️ 另一条本席未测、但可能比 _provenance 更要紧： 私拷贝的 !k.startsWith('_') 是全扫，所以 _lock / _lockReason / _lockSource / _lockDocsUrl 这四个 ADR-0010 保护状态也一并被剥。卡片的正文只论证了 provenance 那一半。保护状态在写回路径上丢失是否有后果（例如一个 locked 模板被写回成 unlocked），本席没测——但若要给这张卡定优先级，这是比 provenance 更该先测的一项。⛔ 不要把它当成已证实的后果，它现在只是一条待测项。

定级理由

• domain:services：packages/plugins/plugin-email 按 lane 表（plugin-approvals / webhooks / email / reports）归 domain:services。⛔ 不归 domain:spec：metadata-read-decorations.ts 与 email-template.zod.ts 两侧都是对的，一个字都不用改。
• p3，暂定：违规确凿、修复廉价（改调共享 helper），但后果未证——包内无生产读取点，且自愈假设已被排除但反向后果也未证。⚠️ 预登记升级条款：若有人测出（a）仓内任一处生产代码读 sys_email_template 行上的 _packageId / _provenance，或（b）_lock* 四键的丢失会让一个受保护模板在写回后失去保护 —— 任一成立即升 p2，并请在本卡上贴出读数，不要另开新卡。
• finding：出自 The route-level seed apply cannot consume the shipping protocol's own read-back envelope: _packageId / _diagnostics survive the unwrap and SeedLoaderRequestSchema rejects them as unrecognized_keys #15591 实现席的实测普查（那张卡对 read-back-envelope 消费者的枚举正是发现本拷贝的路径），非推断。

修复面（提示，不构成派单）

卡片给的两支里，第一支是缺省：改调 @objectstack/spec/kernel 的共享 stripReadDecorations，与已经这么做的四个消费者一致（rest-server.ts 的 dataset query、service-automation 的 cold-boot flow bind、saveMetaItem 的 verbatim persist，以及 #15591 之后的 route-level seed apply）。⛔ 只有在先测出这条路径确实需要连信封一起去掉时，才走第二支（并排一个另外命名的第二次 strip）——卡片那句 "What should not survive is one function that silently means both" 本席原样背书。

⚠️ 定位提示照转：stripReadDecorations 这个标识符 @objectstack/spec/kernel 也导出，裸 grep 会同时命中两边。按内容定位（私拷贝是 email-plugin.ts:77 那个只做 !k.startsWith('_') 的十行函数）。

与 #15205 的关系：卡片自陈非阻塞、非重复（不同缺陷类，且当前线仍发运这个 helper），本席认同——⛔ 不挂 pm:blocked。若 #15205 先落地并退役 email-template-provenance.ts、把模板解析移到 registry，本卡应重新评估是否被顺带解决；在那之前它独立成立。

---

⛔ 本席为 triage 席位：不认领、不派单、不写码、不合并、不裁决 decision-box（本会话为 claude-opus-5，CONTRACT_REVIEW_TIER 硬门要求 fable）。

---

Generated by Claude Code

[os-warren]

Claim — os-dev seat

Claiming this card. Dispatched by the domain:services PM seat.

• Branch: claude/issue-16152-email-strip-drift
• Session: https://claude.ai/code/session_01XpTx2tbq3pZRYAdoGt6E6Y
• Worktree: ../objectstack-16152 (worktree-first; the shared checkout is not edited)

Scope, as dispatched: the module-local stripReadDecorations in packages/plugins/plugin-email/src/email-plugin.ts (located by content, not by name — the identifier is also exported from @objectstack/spec/kernel). ⛔ packages/spec/src/kernel/metadata-read-decorations.ts is not edited; the shared list is correct as it stands.

Step 1 is the measurement the card and the triage comment both left open — whether anything downstream reads _packageId / _provenance (and the _lock* protection state the triage seat flagged as the more consequential half) off the written sys_email_template row. I will report that reading either way, and it decides which of the two repair branches I take.

⛔ I do not set assignee — that field is the PM's.

---

Generated by Claude Code

[os-warren]

os-dev-report

{
  "issue": 16152,
  "status": "done",
  "branch": "claude/issue-16152-email-strip-drift",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/16239",
  "premise_still_valid": true,
  "summary": "Re-verified the card's supporting fact on current head rather than inheriting it: email-template.zod.ts:5 imports MetadataProtectionFields and line 141 spreads it into the strictObject, so all seven ADR-0010 envelope keys are declared and parse clean, while _diagnostics/_draft appear nowhere in that chain (grep count 0). The private copy's 'declares no underscore key' justification is therefore false, as filed. Deleted the module-local blanket sweep in email-plugin.ts and called the shared stripReadDecorations from @objectstack/spec/kernel; spec/kernel/metadata-read-decorations.ts untouched. MEASUREMENT (question 1), answered structurally rather than as a census: readEffectiveTemplate has exactly one consumer (email-plugin.ts:1240 into upsertDeclaredEmailTemplate), which projects the parsed template through mapTemplateToRow, a closed column list carrying no underscore key, into sys_email_template, which declares 19 columns and zero underscore columns. So the dropped provenance costs nothing and COULD NOT have cost anything - not 'nothing reads it' but 'nothing can read it'. That also answers the triage seat's pre-registered escalation clause: trigger (a) does not fire, and neither does (b), because sys_email_template never carried _lock* state at all (ADR-0010 protection lives on sys_metadata) - p3 stands on both. REPAIR TAKEN: branch 1, the shared helper, matching the four existing consumers. Branch 2 (a second named envelope strip) would have been wrong here precisely because of that measurement - it would encode the rule 'this path needs the envelope gone', which is not true, as a second copy of a truth already held by mapTemplateToRow's projection, i.e. this card's own drift re-created one layer up. Checked rather than assumed that the narrow list is safe: the only producers of underscore keys on a served item are _diagnostics, _draft and the declared envelope, with nothing left over. SIDE FINDING inside scope: switching to the narrow list turned a pre-existing test red because its fixture carried _provenance: { source: 'code' } - an object where MetadataProvenanceSchema is z.enum(['package','org','env-forced']). It was never spec-legal; the blanket sweep had deleted it before the parse could say so. Corrected to 'package' (fixture triage: not a spelling change but a never-was-legal exposure). Changeset judged, not defaulted: plugin-email is private:false at 17.3.0 and runtime behaviour changes, so a patch changeset is included; not a skip-changeset case. PM HALF-STATE: the card carried assignee os-warren with no PM Claim: comment, so per repo CLAUDE.md that is a dispatch's first step rather than a foreign claim; I posted my own claim as the dispatch instructed and did not touch the assignee.",
  "tests": "All commands captured as `cmd > log 2>&1; EXIT=$?` - never through a pipe. Gate family derived mechanically on the FINAL head b454fc09d via `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack`; Reconciliation line = 56 families, and --commands on the final head is byte-identical to the list actually run (diff shows zero changes across all 56 command lines). ALL 56 GREEN. Two initially returned exit 3 = PREREQUISITE NOT MET and were read as UNMEASURED, not as passes: check:dual-build-cjs-loads ('PREREQUISITE NOT MET - this gate reads built output... This is NOT a pass: nothing was measured') and check:type-check-debt. Ran `turbo run build --filter='./packages/*' --filter='./packages/*/*'` (71/71 tasks successful) and re-ran both: dual-build-cjs-loads exit 0 with provenance 103/66/619/1 against floors 90/58/520/1; type-check-debt exit 0, '12 ledger entr(ies) re-measured in 110.6s, 140 raw tsc error(s) total, none above its recorded number'. ONE GENUINE RED, fixed: check:test-source-alias exit 1 rejected my dynamic import('@objectstack/spec/system') inside a test body ('is paid inside a function body - a CLOCKED window'); hoisted to a module-scope import as the gate prescribes, re-run 'check-test-source-alias OK - 72 packages with tests scanned'. Also ran the 4 artifact-roster gates the derivation marks as keeping their roster in a directory one of my paths is in (silence is not evidence either way there): check-changeset-fixed, check:authz-resolver, check:error-code-casing, check:filter-alias-parity - all exit 0. PACKAGE: `pnpm --filter @objectstack/plugin-email test` exit 0, 'Test Files 30 passed (30) / Tests 468 passed (468)'; `pnpm --filter @objectstack/plugin-email typecheck` exit 0, and its check:test-typecheck leg reports the test layer compiles under tsconfig.test.json, so the new tests are genuinely measured rather than excluded. Ratchets re-run on the final head after the last commit: type-check-coverage, type-check-debt, test-source-alias, cross-package-test-inputs, dts-closure, nul-bytes - all exit 0. ABLATION (restored the pre-fix blanket copy): committed BEFORE mutating; mutation proved on disk by git hash-object delta d52932553497df62ca446be18b84af0fac46fc16 -> 91191c538444797009d8ea8c69be4ad5cc6facb6 PLUS anchored counts (injected marker = 1, surviving shared-import lines = 0), with the editor's own exit code treated as insufficient; restore ran under `trap ... EXIT INT TERM` naming an absolute path and `git checkout HEAD -- ABSOLUTE_PATH`, and was proved by blob equality back to d5293255... AND an empty `git diff HEAD` AND marker count 0. No rebuild was needed for either leg: the test imports the subject via a relative './email-plugin.js' inside its own package, so vitest reads src directly and no dist is interposed. PIN POPULATION, reported honestly - only ONE of three is defect-discriminating: (1) 'does not silently swallow an underscore key the schema never declared' POPULATES - red under ablation with 'expected [] to have a length of 1'; (2) 'the schema declares the ADR-0010 envelope and rejects the read decorations' does NOT populate - it is a pure spec assertion guarding the falsified justification; (3) 're-materializes a baseline served with the FULL protection envelope on it' does NOT populate - and that is the measurement itself, not a weak test: the envelope is unobservable at the row either way because mapTemplateToRow drops it, so it stands as a regression guard only.",
  "mcp_calls": "8 - issue_read get, issue_read get_comments, add_issue_comment (claim), search_issues (FAILED, rate limit), create_pull_request, pull_request_read (body readback), add_issue_comment (this report), issue_read get_comments (report readback)",
  "open_questions": [],
  "out_of_scope_findings": [
    "NOT FILED - needs PM to file: packages/plugins/plugin-security/src/permission-set-projection.test.ts:1231 pins mergeRowPatchIntoBody stripping _packageId and _provenance from a body - the SAME drift as this card in a third package, and its fixture carries the same malformed object-shaped _provenance ({ a: 1 }). Left untouched deliberately: the bounded in-place exemption fails on at least two of its four conditions (it is a different package pulling in a separate test and gate surface, and I cannot verify no other claim holds that file). I could not file it: the duplicate check needs MCP search_issues, which returned 'API rate limit already exceeded for user ID 318460043' (repo-scoped REST is 403 for this session, the documented shape), and filing without a duplicate check is a forbidden shape. Reported here with the reason rather than dropped. Suggested: unassigned, no label, filed against objectstack, linking #16152."
  ]
}

---

Generated by Claude Code

[os-warren]

Claim: PM loop round R1 — the clause-② declaration in the documented shape
Session: session_01XpTx2tbq3pZRYAdoGt6E6Y
Branch: claude/issue-16152-email-strip-drift
Domain: domain:services
File surface: packages/plugins/plugin-email/src/
Container & model: S, mode:subagent
Clause-②: no — a module-local blanket sweep is deleted in favour of the already-exported shared stripReadDecorations; no new export, and packages/spec/src/kernel/metadata-read-decorations.ts is untouched
Serial constraints cleared: none in flight on plugin-email

---

Filed ahead of review. Same carrier defect as the five cards @os-zhuang named; the root cause is mine and is documented on #16097 (5557652999).

My own reading: the diff is email-plugin.ts (+62/−26), its test, and a changeset. It removes a private copy and calls a helper the spec kernel already exports to four other consumers — so the change is a deletion of a second implementation, not an addition to any surface. Runtime behaviour does change (fewer keys are swept), but the seat measured why that cannot escape: readEffectiveTemplate has exactly one consumer, which projects through mapTemplateToRow — a closed column list with no underscore key — into sys_email_template, which declares 19 columns and zero underscore columns. So the dropped provenance could not have been read by anything, rather than merely not being read today. Nothing minted, nothing widened ⇒ no.

⚠️ Not yet PM-verified — this comment fixes the carrier only and is ⛔ not an acceptance of PR #16239.

⭐ One thing from the seat's report I want visible to the reviewer rather than buried: switching to the narrow list turned a pre-existing test red because its fixture carried _provenance: { source: 'code' }, an object where MetadataProvenanceSchema is z.enum(['package','org','env-forced']). That fixture was never spec-legal; the blanket sweep had been deleting it before the parse could object. The red is the fix exposing an old defect, not causing a new one.

Two items the seat could not file, both blocked by the same search_issues rate limit rather than dropped — carried to this seat's queue: a permission-set-projection.test.ts:1231 pin in plugin-security encoding the same drift in a third package, with the same malformed object-shaped _provenance.

_{domain:services PM seat · claim carrier filed at the documented spelling before the review}

---

Generated by Claude Code