[objectstack-fleet]

Requested by Yibo Wang · project thread

Fixes #26803

维护者速读

• 改了什么:IEmailService 契约里 sendTemplate 和 renderTemplate 的错误清单补上 TEMPLATE_INVALID,只改注释,不改类型或 schema。
• 为什么改:插件已经会对含非法占位符的已存模板抛 TEMPLATE_INVALID,但契约没写,渠道或应用作者读契约时不知道这是一个永久失败。
• 风险与回滚:纯文档改动,无运行时影响;回滚即还原这一个提交。
• 先看:packages/spec/src/contracts/email-service.ts(两段新增的 Errors 条目)。
• 两分钟验证:git grep -c TEMPLATE_INVALID -- packages/spec/src/contracts/email-service.ts,预期 4(每个清单两处)。
• 需要你做的:无,席位落地。

Clause-②: no
Metadata-protocol: none
Skills-docs: no skill lists these codes; content/docs/kernel/runtime-services/email-service.mdx (Typed Error Codes) updated in this PR; content/docs/automation/email-templates.mdx already names it.

What changes

• packages/spec/src/contracts/email-service.ts: the sendTemplate and renderTemplate Errors lists name TEMPLATE_INVALID, worded from what @objectstack/plugin-email does: a stored template with a hole the authoring rules refuse (rule email-template-hole-grammar: a second formatter, or a currency argument that is not a literal ISO 4217 code) is refused at render with TEMPLATE_INVALID: email template NAME (locale=LOCALE): HOLE_AND_RULE, and is permanent until the template is re-published.
• content/docs/kernel/runtime-services/email-service.mdx: Typed Error Codes lists TEMPLATE_INVALID.
• .changeset/26803-email-service-template-invalid.md: patch on @objectstack/spec.

Why

The runtime throws this code from both methods since #26799, and service-messaging grades it permanent, but the contract a channel or app author reads did not list it.

Measured

• TEMPLATE_INVALID on origin/main 6090bb7: thrown by template-engine.ts render (TEMPLATE_INVALID: + the grammar's refusal) and re-thrown by EmailService.resolveAndRenderTemplate with the template name and locale in front; both sendTemplate and renderTemplate go through that resolver.
• TEMPLATE_UNSUPPORTED: EmailService never throws it. Only the service-messaging email and inbox channels raise it, when the registered email service lacks sendTemplate / renderTemplate. So it is not added to IEmailService's lists.
• Error-code ledger: does not apply. error-code-ledger.zod.ts registers route error.code values; TEMPLATE_NOT_FOUND, TEMPLATE_INACTIVE and MISSING_VARIABLES are absent from it (0 hits) because they are Error message prefixes, not envelope codes. Mirroring that, TEMPLATE_INVALID is not added, and the ledger and its test are untouched.

Acceptance notes

• content/docs/kernel/runtime-services/email-service.mdx Typed Error Codes now lists TEMPLATE_INVALID beside the three older codes (claim surface amended by the seat, 2026-10-27T20:51Z).

Verification

All on head 6978e58 (spec tests on 0ca6a37; the later commit is .mdx only).

Spec tests and typecheck (under os-verify-lock)

pnpm --filter @objectstack/spec test && pnpm --filter @objectstack/spec typecheck: VERDICT command-exit 0. Test Files 736 passed (736); Tests 22050 passed, 1 todo.

Derived gates

node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack: On 6978e58: 97 derived, 94 exit 0, 3 NOT MEASURED with exit 3 (full-build prerequisite: spec check:skill-examples, check:dual-build-cjs-loads, check:lean-entry-closure); --ran: 94 run, 3 NOT-MEASURED, 0 UNRUN. Earlier, on 0ca6a37: 73 commands. 71 exit 0. check:doc-formula-expressions first exited 3 (formula not built), then exit 0 after building formula and lint. check:dual-build-cjs-loads and check:lean-entry-closure exit 3 (PREREQUISITE NOT MET, need a full build): NOT MEASURED locally, CI runs them. --ran reconciliation: 73 derived, 71 run, 2 NOT-MEASURED, 0 UNRUN.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WGufziYqBAqnKprHc4h25c

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 1 documentable anchor(s).

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

• content/docs/api/client-sdk.mdx (via IEmailService (symbol, a top-level interface))
• content/docs/deployment/self-hosting.mdx (via IEmailService (symbol, a top-level interface))
• content/docs/kernel/contracts/index.mdx (via IEmailService (symbol, a top-level interface))

⛔ 2 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17/17-1.mdx (via IEmailService (symbol, a top-level interface))
• content/docs/releases/v18/18-1.mdx (via IEmailService (symbol, a top-level interface))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 147 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 94e29cd11f5d959a4847369837ce719879497b15 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 7b7b9f509a12674ad3fc6417e1f83efbc92105dd — the merge of head 6978e58122bd4ecc32b7d5aeab155c5a8f3bcbc0 into base 94e29cd11f5d959a4847369837ce719879497b15, 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 7b7b9f509a12674ad3fc6417e1f83efbc92105dd && git checkout 7b7b9f509a12674ad3fc6417e1f83efbc92105dd
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 94e29cd11f5d959a4847369837ce719879497b15 6978e58122bd4ecc32b7d5aeab155c5a8f3bcbc0 && git checkout -B drift-repro 94e29cd11f5d959a4847369837ce719879497b15 && git merge --no-ff 6978e58122bd4ecc32b7d5aeab155c5a8f3bcbc0

node scripts/docs-audit/affected-docs.mjs --json 94e29cd11f5d959a4847369837ce719879497b15

⚠️ 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 94e29cd11f5d959a4847369837ce719879497b15 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 6978e58122bd4ecc32b7d5aeab155c5a8f3bcbc0
Local-runs: none
Scope: packages/spec/src/contracts/email-service.ts, content/docs/kernel/runtime-services/email-service.mdx, .changeset/26803-email-service-template-invalid.md + packages/plugins/plugin-email/src/email-service.ts, packages/plugins/plugin-email/src/template-engine.ts, packages/formula/src/template-engine.ts, packages/formula/src/mail-hole-grammar.ts, packages/lint/src/validate-email-template-hole-grammar.ts, packages/lint/src/authoring-rules.ts, packages/services/service-messaging/src/email-channel.ts, packages/services/service-messaging/src/inbox-channel.ts, packages/spec/src/api/error-code-ledger.zod.ts, content/docs/automation/email-templates.mdx, packages/spec/scripts/build-docs.ts

Read on this head: the PR body (patched by the seat), its 2 commits, its file list, the one PR comment (docs-drift 6453226337), the net diff against main; card #26803 body and all four comments (6448509653, 6452785442, 6453226732, 6453251122); PR #26799 body and file list; the cited code on origin/main at 94e29cd11 via read-only git show / git grep; the head's check-runs (readings below). Written at 2026-10-27T21:41Z.

① Derived judgments

1. Who throws, from where. packages/plugins/plugin-email/src/template-engine.ts:121 — render() throws Error('TEMPLATE_INVALID: ' + refusal.message) for any parsed hole carrying refusal. packages/plugins/plugin-email/src/email-service.ts:1476-1483 — resolveAndRenderTemplate catches exactly that prefix and rethrows as TEMPLATE_INVALID: email template NAME (locale=ROW_LOCALE): + the rest. renderTemplate (:1497-1499) and sendTemplate (:1508-1509) both call that resolver first, before any transport, queue or sys_email row. So "from both methods", the message shape, "nothing is delivered" / "nothing is rendered" all hold. Note the locale in the message is the resolved row's locale, which the contract's (locale=LOCALE) placeholder covers.
2. Throw vs return, consistent with siblings. TEMPLATE_NOT_FOUND (:1389, :1411), TEMPLATE_INACTIVE (:1414) and MISSING_VARIABLES (template-engine.ts:155, re-thrown :1428) are all thrown Errors with the code as message prefix, never a { status: 'failed', error } return — TEMPLATE_INVALID is thrown the same way. The contract's existing three entries name the code without saying throw or return; the new entry says "refused at render, as TEMPLATE_INVALID: …" — same register, no new dialect. The .mdx heading "may return/throw implementation errors" is pre-existing and the new bullet fits it.
3. The rule and its name. packages/lint/src/validate-email-template-hole-grammar.ts:45 EMAIL_TEMPLATE_HOLE_GRAMMAR = 'email-template-hole-grammar'; registered gating, commands: ALL, surfaces: CLI_AND_RUNTIME, runtimeTypes: ['email_template'] (authoring-rules.ts:2472-2481). The grammar is judgeHoleFormatter (packages/formula/src/template-engine.ts): chainsASecondFormatter → rule one-formatter; formatter === 'currency' && arg !== undefined && !/^[A-Z]{3}$/ → rule currency-code-literal. The contract's "a second formatter, or a currency argument that is not a literal ISO 4217 code" is exactly those two branches. (currency with NO argument is admitted and formats USD — the contract says "argument that is not", so it does not overclaim.)
4. "Permanent" and "until re-published". The same grammar gates os validate / os build / os lint and the email_template runtime publish door (registry entry above; PR feat(formula,plugin-email,lint)!: a mail template hole takes one formatter and a literal currency code, refused at authoring and at render #26799 pins it at 422 INVALID_METADATA), so a template cannot be re-published with the hole, and nothing but a new publish changes the stored row. service-messaging grades it permanent on both channels (email-channel.ts:425, inbox-channel.ts:254). content/docs/automation/email-templates.mdx:115-119 already states the same ("judged at its next publish; until then sendTemplate and renderTemplate fail with TEMPLATE_INVALID"). Both sentences hold.
5. TEMPLATE_UNSUPPORTED left out: correct. Repo-wide, the string is produced only by service-messaging email-channel.ts:339 and inbox-channel.ts:174, as the CHANNEL's own status: 'failed' error when the registered email service lacks sendTemplate / renderTemplate. plugin-email never emits it and no IEmailService method can. The card's "if the contract also documents it" condition is false, so nothing to check in.
6. Error-code ledger untouched: correct. packages/spec/src/api/error-code-ledger.zod.ts registers "every service-specific code a route may put in error.code" (its header); git grep of TEMPLATE_NOT_FOUND|TEMPLATE_INACTIVE|MISSING_VARIABLES|TEMPLATE_INVALID over it returns 0 hits. The four codes are thrown-Error message prefixes from a kernel service, never a REST envelope code, so the ledger is the wrong register. The triage line's "add it to the ledger if it is not there" is answered by measurement, and the PR body says so.
7. Other docs and skills. git grep of the four codes over skills/**, .claude/skills/**, content/docs/**, docs/**, examples/** and plugin-email / service-messaging markdown: the only enumerations of the vocabulary are content/docs/kernel/runtime-services/email-service.mdx (updated here) and content/docs/automation/email-templates.mdx (already names TEMPLATE_INVALID at :118). content/docs/references/system/email-template.mdx:51 is AUTO-GEN and names TEMPLATE_NOT_FOUND inside the locale description, not as a list. No plugin-email README exists. The three docs-drift pages (client-sdk.mdx, self-hosting.mdx, kernel/contracts/index.mdx) name IEmailService but list no codes — nothing to update. CHANGELOGs are release-owned. The Skills-docs: line is true as written.
8. Generated artifacts. packages/spec/scripts/build-docs.ts:918-919 — contracts/ holds TypeScript interfaces, not Zod schemas, so this TSDoc feeds no content/docs/references/** page; api-surface records export names, not comments. No regeneration owed; the file list is complete.
9. The .mdx bullet. True sentence by sentence (see 1, 3, 4); "renderTemplate raises it too" is true. The page's Methods block has never listed renderTemplate — a pre-existing gap this PR neither widens nor owes.
10. Verification claim. /compare/0ca6a3723...6978e5812 touches only the .mdx (+1), so the dev's spec test and typecheck on 0ca6a3723 cover the head's packages/spec tree exactly as claimed.

② Semver level

patch on @objectstack/spec is correct: comment-only edit inside an interface's TSDoc, no type, export, schema or authorable-key change. Clause-②: no and Metadata-protocol: none are both true and both appear line-initial in the PR body and the changeset body; none takes patch (Post-Task Checklist §3). Not breaking, so no ADR-0087 marker is owed. The changeset text matches the code (rule name, message shape, permanence, "documentation only").

③ Boundary flags

• Dev: 3 derived gates NOT MEASURED locally (check:skill-examples, check:dual-build-cjs-loads, check:lean-entry-closure, full-build prerequisite). Judged against the head's check-runs — readings below.
• Claim amendment (6453251122): file surface widened to the .mdx Typed Error Codes list. The dev reported the gap as an out-of-scope finding (6453226732) and stopped at the surface; the seat amended the claim; the second commit adds exactly that one line. Surface honoured, no breach.
• Branch claude/project-thread-vmoww1, not claude/issue-26803-*. Declared in the claim as the platform-assigned thread branch; Implemented-by below uses it as measured. PR-body guards are green.
• Triage asked for the ledger — answered: does not apply (judgment 6).
• Docs Drift Check (advisory) — 3 pages name the symbol, none lists codes; nothing owed (judgment 7).
• Governed surfaces: none in the file list; Governed Surface Queue Guard success.
• Check-runs on 6978e5812: read at 2026-10-27T21:11:49Z (35 runs, 18 in_progress), 2026-10-27T21:13:53Z (43 runs, 18 in_progress), then every two minutes to 2026-10-27T21:41:00Z: 51 runs, 42 success, 9 skipped (opt-in harnesses, UI matrix shards, Temporal Conformance, duplicate Auto Label / PR Size runs from the body edit), 0 failure, 0 in_progress. All eight required contexts success: Lint & Repo Gates, TypeScript Type Check, Test Core, Build Core, Governed Surface Queue Guard, Lint UI (skipped by path filter, which is its green on a diff without ui/), Type Check UI, Build & E2E UI. The three gates the dev could not measure locally ride Lint & Repo Gates / TypeScript Type Check / Build Core, all success; Check Changeset success twice. Head sha unchanged across every reading.

Implemented-by: claude/project-thread-vmoww1
Reviewed-by: session_01WGufzgbJhFoXYsLSe5WSPP

VERDICT: PASS

[objectstack-fleet]

维护者速读 (席位终稿)

• 改了什么：IEmailService 契约里 sendTemplate 和 renderTemplate 的错误清单补上 TEMPLATE_INVALID，运行时服务文档的 Typed Error Codes 也补上同一行。只改注释和文档，不改类型、schema 或运行时。
• 为什么改：邮件插件自 feat(formula,plugin-email,lint)!: a mail template hole takes one formatter and a literal currency code, refused at authoring and at render #26799 起会对含非法占位符的已存模板抛 TEMPLATE_INVALID，渠道把它当永久失败，但契约没写，渠道或应用作者读契约时不知道这是一个最终失败。
• 风险与回滚：纯文档改动，无运行时影响。回滚 = revert 本 PR。
• 先看：packages/spec/src/contracts/email-service.ts（两段新增的 Errors 条目）、content/docs/kernel/runtime-services/email-service.mdx（Typed Error Codes 一行）。
• 两分钟验证：git grep -n TEMPLATE_INVALID -- packages/spec/src/contracts/email-service.ts content/docs/kernel/runtime-services/email-service.mdx，预期两个 Errors 清单和文档清单各有一条。
• 需要你做的：无，席位落地。

席位意见：接受。契约复核 PASS（6454314274），每一句新增文字都对照了 main 上的代码。

席位核对 · ACCEPT · domain:spec seat 3 · os-support-ai · session session_01WGufzgbJhFoXYsLSe5WSPP · 2026-10-27T21:43Z

Head: 6978e58122bd4ecc32b7d5aeab155c5a8f3bcbc0 · card #26803 · claim 6452785442 (surface amended to add the docs page)

1. 形态: a draft PR to main with Fixes #26803 as its only closing keyword. 3 paths, +23 / −0: the two Errors lists in email-service.ts, one line in email-service.mdx and one changeset. All inside the amended claim surface. check-governed-merges --pr 26911: NOT governed, 23 lines ≤ 3000, so the ordinary queue landing applies.
2. 前提实测: the premise holds: Blocked-by: #26673 cleared when PR feat(formula,plugin-email,lint)!: a mail template hole takes one formatter and a literal currency code, refused at authoring and at render #26799 merged. The review read the code on origin/main 94e29cd11: plugin-email's template engine throws TEMPLATE_INVALID, EmailService rethrows it with the template name and locale, and both sendTemplate and renderTemplate reach it through the same resolver before any send. It is thrown like the three sibling codes, and service-messaging grades it permanent (record ① 1).
3. 门禁 check-runs (on this head): 51 runs, 42 success, 9 skipped, none red or pending; mergeable state clean. The contract-tier review is PASS on this same head (record 6454314274), and the head has not moved since. The dev's three NOT-MEASURED gates (full-build prerequisite) run inside required CI jobs that are green.
4. 接受的偏差: (a) The docs line was added after the dev's first head, by a seat amendment of the claim surface; the review checked that the second commit touches exactly that list. (b) The error-code ledger is untouched: it registers route envelope codes, and none of the four template codes is there (they are Error message prefixes). (c) TEMPLATE_UNSUPPORTED is not listed, because EmailService never throws it; only the service-messaging channels do.
5. 范围外去向: none. No other doc or skill lists this vocabulary; content/docs/automation/email-templates.mdx already names TEMPLATE_INVALID. Skills-docs: is true as written.
6. 落地条款: every added sentence was checked against the code by the review, and Clause-②: no / Metadata-protocol: none / patch on @objectstack/spec stand. Ready and auto-merge go through the relay in this act, and the seat follows the PR to MERGED.

---

Generated by Claude Code