finding(spec): the expression dialect table lists notification subjects/bodies as `template` slots, but NotifyConfigSchema.title is z.string() and refuses the tmpl envelope

[objectstack-fleet]

Found by the repo:objectos seat (#9831) while staging objectos#316, the docs code-sample gate, on 2026-10-07. Measured on the published @objectstack/spec 17.7.0 and read at origin/main. Class b: the contract text and the schema disagree.

What disagrees

• packages/spec/src/shared/expression.zod.ts:27. The dialect table names the template dialect's slots as "notification subjects/bodies, titleFormat, prompt templates". A template-typed slot accepts either a bare string or the { dialect: 'template', source } envelope (TemplateExpressionInputSchema, :36, and the guidance at :292-295).
• packages/spec/src/automation/io-node-config.zod.ts:192. NotifyConfigSchema.title is z.string().optional(), so only a bare string parses.
• Effect. A notify node written with the tmpl helper is refused, by defineFlow and by NotifyConfigSchema alike: title: expected string, received object. Example: title: tmpl`[{{record.priority}}] {{record.subject}}`. The bare-string spelling of the same text parses.

Why it matters

Docs and authors who follow the dialect table write the envelope form for notifications and get a schema error. objectos's reference/cel.mdx now follows the parse, using bare strings for notify titles, after objectos#316 / PR #321.

Possible directions (the owner decides)

• Type NotifyConfigSchema.title, and any body or subject field, as TemplateExpressionInputSchema, so both spellings parse. Or:
• Correct the dialect table row so it no longer promises the envelope for notification subjects and bodies.

Either way, a test pinning the decision closes it.

---

Generated by Claude Code

[objectstack-fleet]

Path: ② the capabilities an end user meets in the app — automation notifications | 缺项 | P3

Triage: first grade, bug · priority:p3 · domain:spec · area:workflow · pm:queue (finding and needs-triage removed). The field follows the dialect table: a notify title accepts the template input

Triage seat (objectstack-wide, seat post #6015) · session_01AavokzJ5DndAwitDXvKy4U · 2026-10-07T04:58Z. ⛔ Not a claim, ⛔ not a dispatch.

Triage: lands in packages/spec/src/automation/io-node-config.zod.ts (NotifyConfigSchema.title, :192), with the executor half in packages/services/service-automation/src/builtin/notify-node.ts (cross-lane domain:services) ⇒ domain:spec; rationale: the declaration is the outlier against the spec's own dialect table.

• Verified on main at this write:
  • the dialect table names notification subjects and bodies as template slots;
  • NotifyConfigSchema.title is z.string().optional();
  • the executor already treats title as a template: notify-node.ts:259 runs it through interpolate(cfg.title …).
• Direction: the first of the card's two. Type title, and any notify body or subject field the executor interpolates, as TemplateExpressionInputSchema, so the bare string and the tmpl envelope both parse, as every other template slot does.
  • The executor reads the envelope's source. A bare string is unchanged.
  • The changeset is a widening (Clause-②: yes, minor).
  • Pins: the envelope and the bare string both parse and both render the same text; a non-string, non-envelope value is still refused.
• Not the second direction: narrowing the table's promise would leave the one notify slot unlike every other template slot, while the runtime already interpolates it.
• Why p3: an author gets a loud schema error and a working spelling exists, so there is no silent harm.

[objectstack-fleet]

Claim: PM loop round 8 (this card, as triage graded and directed it in 6031254558: the first of the card's two directions) · 2026-10-07T05:43Z
Session: session_01GV6oYwgc1kWiUCb1YaprQ7
Account: os-warren (the seat's linked user as GET /user answers it; the card's assignee from this act)
Branch: claude/issue-22054-notify-title-template-input
Worktree: objectstack-issue-22054
Domain: domain:spec
Seat: domain:spec#2 (seat post #18549)
File surface (at origin/main d5a14dd5; stop on breach and explain in the report):

• packages/spec/src/automation/io-node-config.zod.ts: NotifyConfigSchema.title, and any notify body or subject field the executor interpolates (message), typed as TemplateExpressionInputSchema, so that both the bare string and the tmpl envelope parse. Their .describe() text is made true. Its spec test io-node-config.test.ts.
• Declared cross-lane files (domain:services), only if the executor needs it: packages/services/service-automation/src/builtin/notify-node.ts (it must read the envelope's source; a bare string is unchanged) and its tests under packages/services/service-automation/src/. The declaration goes on the domain:services seat post [PM seat] domain:services · seat 2 — 🟢 os-warren #21118.
• Whatever packages/spec generators move for this (json-schema.manifest/**, spec-changes.json, content/docs/references/automation/**, and any liveness/** row a gate requires), plus .changeset/22054-*.md.
• ⛔ Not the second direction: the dialect table's promise stays. ⛔ A non-string, non-envelope value is still refused.
  Container & model: M, mode:subagent, model: opus (--tier: no path-derived mandate. The clause-② review is owed at CONTRACT_REVIEW_TIER by an isolated subagent, not this build.)
  Clause-②: yes (narrowing: the envelope is newly accepted, a blank or whitespace bare string is newly refused and NotifyConfigParsed.title/message become the envelope union, so the diff carries a BREAKING accept-set narrowing; contract review 6033083158 graded it, @objectstack/spec minor under the launch-window convention)
  Responsibility: @objectstack/spec (NotifyConfigSchema.title is z.string() against the spec's own dialect table) | a working path exists: the bare-string spelling parses and the executor already interpolates it (notify-node.ts:259) | any author writing a notify node with the tmpl envelope hits a loud schema error; objectos's docs met it on objectos#316 and switched to bare strings
  Thread-read: 6031254558
  Serial constraints cleared:
• None of the 6 open PRs touches io-node-config.zod.ts or notify-node.ts (scan at this stamp), and no live Claim: names them.
• Seat 1's PR feat(spec)!: the build doors refuse a builtin node config value its executor contract refuses, with its location #21974 (service-automation: a built-in node's config value its own contract refuses still registers, then fails every run — the built-in half of #21848's class #21898, pm:blocked, held for 18.0) touches packages/services/service-automation/src/builtin/notify-node.test.ts. That is ordinary concurrency on a shared test file: whichever lands later merges main.
• This seat's in-flight PR feat(spec): export the anonymous-form-intake candidates from @objectstack/spec/ui; metadata-core re-exports the same bindings #22056 (spec(ui): export the candidates half of the anonymous-form-intake rule from @objectstack/spec/ui, so the console reads "published" from the server's one rule (objectui#11545, ruling 5967405932's fallback) #22047, spec/ui and metadata-core) and finding(lint): the object save door gives no build verdict on validation conditions, field-rule slots (requiredWhen etc.), option visibleWhen or action predicates; os build refuses them, a metadata save stores them (#22019's sibling) #22032 (packages/lint) are disjoint from this surface.

---

Generated by Claude Code

[objectstack-fleet]

os-dev-report

{
  "issue": 22054,
  "status": "done",
  "branch": "claude/issue-22054-notify-title-template-input",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/22063",
  "session": "session_01GV6oYwgc1kWiUCb1YaprQ7. This run is a subagent, so this is the PM's harness-stamped id, the same one the commits' Claude-Session trailer carries.",
  "premise_still_valid": true,
  "summary": "NotifyConfigSchema.title and .message are now TemplateExpressionInputSchema.optional(), the input every other template slot uses, so the bare string and the tmpl envelope both parse. The parse normalizes both spellings to one value, {dialect:'template', source}. The notify executor reads cfg.title?.source and cfg.message?.source and interpolates them as before. Both spellings deliver the same payload.title and payload.body, and a bare string renders exactly what it rendered before. One rule is added, for this slot only: a template envelope on either key must carry a non-blank source. The shared envelope arm admits an ast-only envelope or a whitespace source. The executor renders source only, so without the rule such a title would fail every run and such a message would go out empty. Every published sentence about the two keys is now true. The 'sent verbatim' wording is gone from the .describe() texts, the docblock, the conflict refusal and the descriptor, and each now names the renderer's single-brace {token} placeholder. Premise: the core holds, because the schema disagreed with the dialect table. One detail is false on main at d5a14dd5: defineFlow and FlowSchema.safeParse ACCEPT the envelope (the builtin config arm is presence-only), and registerFlow registers it. The refusal came only at execute time, from parseNodeConfig: 'config.title: Invalid input: expected string, received object'. CI on head 01ef8368e5 at report time: 14 checks completed with 0 failures, 18 in_progress.",
  "tests": "All runs were on the branch. packages/spec is byte-identical from ed7166a5e2 to the final commit 01ef8368e5; the only later change is one line in notify-template-slots.test.ts. Package runs: spec build (JS and DTS) exit 0. spec check:generated exit 0, all 15 artifacts up to date; the only regenerated artifact is content/docs/references/automation/io-node-config.mdx. spec test exit 0 (620 files, 18497 passed, 1 todo, run at ed7166a5e2). spec typecheck exit 0, check:test-typecheck ledger held. service-automation test exit 0 (174 files, 2116 passed, at 01ef8368e5). service-automation typecheck exit 0. lint test exit 0 (120 files, 5638 passed, at 01ef8368e5). dispatch-gates --commands with no paths derived 111 families at 01ef8368e5. All were run, and --ran reconciled them: 110 run, 1 NOT MEASURED, 0 unrun. NOT MEASURED: check:dual-build-cjs-loads exited 3 (PREREQUISITE NOT MET, it needs every package's dist), so it is declared to CI. check:skill-examples first exited 3 (no client dist), then exited 0 after building @objectstack/client and @objectstack/client-react (262 examples). ESLint, narrowed and run at 01ef8368e5: population read from eslint.config.mjs (files **/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}); --format json counted 4 files, 0 errors, 0 warnings; invariance: no parserOptions.project or projectService anywhere in the config, so no type-aware linting can move an untouched file's verdict. The repo-wide lint is left to CI. Ablations, each with an on-disk anchor count and a blob restore verified equal to HEAD with git diff HEAD empty: (A) executor read reverted to interpolate(cfg.title ?? '') with the new spec: 3 of 4 executor pins red, and the delivered title was {\"dialect\":\"template\",\"source\":\"[won] Deal Acme\"}, for the bare string too. (B) title reverted to z.string(): 10 spec pins red, including collateral, because the new source rule reads .source off a plain string. (base) the new spec pins run against the base schema file restored from d5a14dd5 under a trap: 7 red (6 new pins and the updated 'accepts every declared key'), 27 green. (C) only the new source rule disabled: exactly 1 pin red. Reverse type check: cfg.title?.trim() in the executor turns tsc red with TS2339 on the envelope union, which proves service-automation reads the rebuilt .d.ts.",
  "mcp_calls": "0. No MCP GitHub tool was called.",
  "api_writes": "3, each sent as one POST /repos/objectstack-ai/objectstack/dispatches from this container and executed by the fleet-write relay as objectstack-fleet[bot]: (1) pr_create, POST /repos/objectstack-ai/objectstack/pulls: #22063, draft, body read back byte-identical (10860 bytes); (2) assign, POST /repos/objectstack-ai/objectstack/issues/22063/assignees: os-warren, read back matched; (3) comment, POST /repos/objectstack-ai/objectstack/issues/22054/comments: this report. git push is not a REST write. No label was written, skip-changeset included.",
  "open_questions": [],
  "out_of_scope_findings": [
    "class: c · reach: named producer, and exception: release-text. The card's own example from the objectos#316 docs sample, tmpl`[{{record.priority}}] {{record.subject}}`, now parses on a notify title and renders '[{P1}] {Server down}'. The notify renderer is the flow's interpolate(), which reads single-brace {token}: the inner {var} resolves and the outer braces stay. That was already true for bare strings. Evidence: four shared texts outside this card's surface steer authors to {{var}} on every template slot, notify now included. (1) TYPED_EXPRESSION_SOURCE_REQUIRED.template and (2) TYPED_EXPRESSION_DIALECT_ONLY.template (packages/spec/src/shared/expression.zod.ts) both say: write '{{record.name}}'. These texts are now the refusals a blank or wrong-typed notify title or message receives. (3) The tmpl docblock: 'Variable scope is the same as CEL ({{record.x}} ...)'. (4) The TemplateExpressionInputSchema docblock: 'write {{var}} unless the slot's renderer is known to normalize'. The notify .describe() texts in this PR now state the {token} spelling. Family: template-slot placeholder spelling per renderer (titleFormat normalizes both spellings, notify reads single-brace only, messaging and email read double-brace only). Dedupe words: template slot placeholder spelling; TYPED_EXPRESSION_SOURCE_REQUIRED {{record.name}} prescription; tmpl double brace notify; notify title stray braces",
    "carrier: the objectui flow inspector owner · noted, not filed. objectui packages/app-shell/src/views/metadata-admin/inspectors/FlowNodeConfigField.tsx renders text and textarea controls with String(value). A code-authored notify title or message that is now a legal template envelope would therefore display as [object Object] in Studio. This is a read-only inference and was not reproduced in a browser. The same static notify form (flow-node-config.ts) still offers the pre-17 'url' key, which the flow-node-notify-config-aliases conversion rewrites at load until it retires at 18. Unmeasured: whether the server-descriptor form supersedes the static form online.",
    "carrier: none · noted, not filed (a family-level read-only inference). TemplateExpressionInputSchema and CronExpressionInputSchema admit an ast-only envelope, and the one engine each slot reaches reads only source. Examples: formula templateEngine refuses 'template Expression.source required', and metadata-protocol's titleFormat read is obj.titleFormat.source || obj.titleFormat. This PR closes the gap for notify only, with its own rule. It belongs in the PR's Acceptance notes. The PR body is write-once, so the seat may append this line there."
  ],
  "gates": {
    "derived_families": "111 at 01ef8368e5: exit 0 x110, exit 3 x1 (check:dual-build-cjs-loads, NOT MEASURED). check:skill-examples exited 3, then 0 after a client build. The --ran reconciliation exited 0.",
    "package_runs": {
      "pnpm --filter @objectstack/spec build": 0,
      "pnpm --filter @objectstack/spec check:generated": 0,
      "pnpm --filter @objectstack/spec check:api-surface (inside check:generated, and also as a derived family)": 0,
      "pnpm --filter @objectstack/spec test": 0,
      "pnpm --filter @objectstack/spec typecheck": 0,
      "pnpm --filter @objectstack/service-automation test": 0,
      "pnpm --filter @objectstack/service-automation typecheck": 0,
      "pnpm --filter @objectstack/lint test": 0,
      "node scripts/pm/dispatch-gates.mjs --ran ran.list": 0
    },
    "ci": "in_progress at report time: 14 completed with 0 failures, 18 in progress, on head 01ef8368e5."
  },
  "deviations": [
    "Added one notify-only refinement inside the existing superRefine: a title or message envelope must carry a non-blank source. Partition 3 suggested keeping the rules exactly. The existing three rules are unchanged; the new one only refuses shapes that never parsed before (envelopes), so the change is still a pure widening against the base.",
    "Changed the NOTIFY_KEY_GUIDANCE subject and body sentences from 'with DIFFERENT text' to 'with a DIFFERENT value'. The reason is H3: a bare subject and an envelope title with the same text are different values, and the conversion keeps both. The conversion itself does not move.",
    "packages/spec/src/shared/expression.zod.ts is NOT edited, because it is outside the declared surface, even though its {{var}} prescriptions now apply to notify too. Reported as finding 1.",
    "Blank bare strings ('' and whitespace) are now refused at title and message by the shared non-blank rule. Before, a blank title parsed and then failed every run, and a blank message sent an empty body. Measured zero such values in the monorepo; the objectui inspector deletes a cleared key (setAtPath). The Clause-② arm stays widening, as ruled. This is flagged for the clause-② contract review.",
    "origin/main was not merged: it gained 2 commits (spec/ui and metadata-protocol) with zero file overlap with this diff.",
    "Commit trailers and the PR footer follow AGENTS.md: the model-free Claude-Session and Co-authored-by pair, and the session-URL footer. The harness's attribution reminder asked for a model-named Co-Authored-By and a different footer; AGENTS.md takes precedence."
  ],
  "files_changed": [
    ".changeset/22054-notify-title-template-input.md (@objectstack/spec minor, @objectstack/service-automation patch)",
    "content/docs/references/automation/io-node-config.mdx (generated, gen:docs)",
    "packages/services/service-automation/src/builtin/notify-node.ts (declared cross-lane file)",
    "packages/services/service-automation/src/builtin/notify-template-slots.test.ts (new; kept apart from notify-node.test.ts because PR #21974 edits that file)",
    "packages/spec/src/automation/io-node-config.test.ts",
    "packages/spec/src/automation/io-node-config.zod.ts"
  ],
  "h1_reading": {
    "before": "Measured with record {priority:'P1', subject:'Server down'}. interpolate(envelope) walks the object key by key and returns {\"dialect\":\"template\",\"source\":\"[P1] Server down\"}; stringifyForTemplate then serializes it as JSON. Through the whole node on base, the envelope never got that far: registerFlow accepted it, and every run was refused at parseNodeConfig (config.title: expected string, received object).",
    "after_without_executor_edit": "Measured as ablation A. With the new spec the parse hands the executor an envelope for BOTH spellings, so every notify title, bare strings included, would deliver {\"dialect\":\"template\",\"source\":\"[won] Deal Acme\"}. The executor edit is therefore required.",
    "after": "The executor reads source. A bare string and an envelope both deliver '[won] Deal Acme' and 'Congrats on Acme'. The bare-string render is unchanged.",
    "h2": "No shared unwrap helper exists. engine.ts:12006 inlines typeof === 'string' ? expression : expression.source; lint has local sourceOf and expressionText; metadata-protocol inlines titleFormat.source || titleFormat. None is needed here: the parsed slot is always the envelope, so the executor reads .source off a typed value and no third helper was written."
  },
  "pin_table": [
    {
      "value": "bare '[{stage}] Deal {dealName}' at title or message",
      "parse": "ok, normalized to {dialect:'template', source}",
      "render": "[won] Deal Acme"
    },
    {
      "value": "tmpl`...` or {dialect:'template', source} with the same text",
      "parse": "ok, the same value",
      "render": "[won] Deal Acme (same text)"
    },
    {
      "value": "42, true, ['a'], {source}, {dialect:'cel', source}",
      "parse": "refused, one issue at the key: code invalid_union, message equal to TYPED_EXPRESSION_DIALECT_ONLY.template",
      "render": "the node is refused at the contract parse ('does not satisfy the notify contract', config.title) and nothing is emitted"
    },
    {
      "value": "'' or '   '",
      "parse": "refused: code invalid_union, message equal to TYPED_EXPRESSION_SOURCE_REQUIRED.template",
      "render": "n/a"
    },
    {
      "value": "{dialect:'template', ast:{...}} or {dialect:'template', source:'   '}",
      "parse": "refused: code custom at the key, message naming `source`",
      "render": "n/a"
    },
    {
      "value": "an envelope title together with template",
      "parse": "refused: code custom at ['template'] (mutual exclusion unchanged)",
      "render": "n/a"
    }
  ],
  "describe_changes": [
    {
      "where": "NotifyConfigSchema.title .describe()",
      "before": "Notification title, sent to every recipient verbatim (not localizable — use `template` for per-locale content). Either this or `template` is required; the two are mutually exclusive.",
      "after": "Notification title — a template: a bare string, or a `{ dialect: 'template', source }` envelope (the `tmpl` helper) carrying the same text. It is interpolated per run with the flow's single-brace `{token}` placeholders (`{record.name}`); a `{{var}}` is not a placeholder here — its inner `{var}` resolves and the outer braces stay in the text. One text for every recipient (not localizable — use `template` for per-locale content). Either this or `template` is required; the two are mutually exclusive."
    },
    {
      "where": "NotifyConfigSchema.message .describe()",
      "before": "Notification body, sent verbatim like `title` (not localizable). Only valid with inline `title`, never with `template`.",
      "after": "Notification body — the same template input as `title` (a bare string or a `{ dialect: 'template', source }` envelope), interpolated per run with single-brace `{token}` placeholders; not localizable. Only valid with inline `title`, never with `template`."
    },
    {
      "where": "NotifyConfigSchema docblock, localization bullet",
      "before": "Inline `title`/`message` are the NON-localizable path — raw strings sent to every recipient verbatim.",
      "after": "Inline `title`/`message` are the NON-localizable path — one text for every recipient, interpolated per run (below), never translated."
    },
    {
      "where": "NotifyConfigSchema docblock, new bullet",
      "before": "(none)",
      "after": "title and message are TEMPLATE slots typed with TemplateExpressionInputSchema: a bare string or a { dialect: 'template', source } envelope. The parse normalizes the bare string to the envelope, the executor interpolates source, and both spellings render the same notification. The renderer is interpolate(), so placeholders are single-brace {token}; a {{var}} keeps its outer braces. An envelope must carry a non-blank source."
    },
    {
      "where": "module docblock (published in the generated reference page)",
      "before": "`notify` parses the RAW stored config — its slots are string-typed, so `{token}` templates pass",
      "after": "`notify` parses the RAW stored config — its slots are string-typed or template-typed, so `{token}` templates pass"
    },
    {
      "where": "title and message field JSDoc",
      "before": "Inline notification title — the NON-localizable content path. / Notification body (inline path only).",
      "after": "... the NON-localizable content path, and a template slot (see the docblock above). / Notification body (inline path only) — the same template input as `title`."
    },
    {
      "where": "template-conflict refusal (superRefine)",
      "before": "or inline `title` + `message` (sent verbatim, not localizable)",
      "after": "or inline `title` + `message` (one text for every recipient, not localizable)"
    },
    {
      "where": "NOTIFY_KEY_GUIDANCE.subject / .body",
      "before": "If `title` is also present with DIFFERENT text ... / If `message` is also present with DIFFERENT text ...",
      "after": "If `title` is also present with a DIFFERENT value ... / If `message` is also present with a DIFFERENT value ..."
    },
    {
      "where": "new refusal (notifyTemplateSourceRequired, not exported)",
      "before": "(none)",
      "after": "`KEY` is a template envelope with no non-blank `source`. The notify executor renders `source` — interpolating its `{token}` placeholders per run — and has nothing to render from `ast` alone or from a blank `source`, so (title) every run that reached this node would fail with no title to send / (message) the notification would go out with an empty body. Put the text in `source` (`{ dialect: 'template', source: 'Deal {record.name} won' }`), or write it as a bare string."
    },
    {
      "where": "notify descriptor configSchema.title.description (notify-node.ts)",
      "before": "Notification title, sent verbatim (not localizable — use template for per-locale content). Either this or template is required; mutually exclusive with template.",
      "after": "Notification title, interpolated per run with {token} placeholders (e.g. {record.name}; a {{var}} keeps its outer braces). Not localizable — use template for per-locale content. Either this or template is required; mutually exclusive with template."
    },
    {
      "where": "notify descriptor configSchema.message.description (notify-node.ts)",
      "before": "Notification body, sent verbatim (not localizable). Only valid with inline title, never with template.",
      "after": "Notification body, interpolated per run with {token} placeholders like title. Not localizable. Only valid with inline title, never with template."
    }
  ],
  "hypotheses": {
    "H1": "Confirmed and measured. interpolate stringified the envelope, so the executor edit was needed. Readings are in h1_reading.",
    "H2": "No shared unwrap helper exists, and none was needed: the parsed slot is always an envelope.",
    "H3": "The comparison still holds and the conversion does not move. Measured: a bare subject with an envelope title of the same text keeps both keys, and the strict gate refuses subject (unrecognized_keys) with its guidance. A subject alone, bare or envelope, renames onto title and parses. The population is empty by construction, because an envelope title never parsed before this change. deepEqualAuthored stays the one shared equality.",
    "H4": "Confirmed: 'sent verbatim' was already false, because the executor interpolates. Every sentence is corrected; the list is in describe_changes.",
    "H5": "Nothing new sees these keys. They are not on FLOW_NODE_EXPRESSION_PATHS, so the lint validateExpression walk and the registration expression pass skip them. validate-flow-template-paths recurses into objects and reads an envelope's source as it read the bare string. authorable-surface, liveness, the strictness ledger and api-surface record keys or exports, and none moved; all are green."
  },
  "cleanup": "Removed node_modules from the worktree and removed the worktree itself (git worktree remove, no --force); the branch is on origin at 01ef8368e5. No server, background job or monitor was left running: the one background gate battery exited and was waited on in the foreground."
}

---

Generated by Claude Code