feat(spec): CloneFlowResponseSchema declares an optional data.noticeCode beside notice - #29779

📓 Docs Drift Check

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

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

• content/docs/concepts/metadata-lifecycle.mdx (via /api/v1/automation/:name/clone (route, bridged from symbol CloneFlowResponseSchema — its route source's handler names it))

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

• content/docs/releases/v17/17-6.mdx (via /api/v1/automation/:name/clone (route, bridged from symbol CloneFlowResponseSchema — its route source's handler names it))
• content/docs/releases/v17/17-7.mdx (via /api/v1/automation/:name/clone (route, bridged from symbol CloneFlowResponseSchema — its route source's handler names it))

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.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 019790643f1f1b0e503b71d2b007ac36b29ccc2d && git checkout 019790643f1f1b0e503b71d2b007ac36b29ccc2d
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 7ba8b11f52215f945ef1fd417d38b1fb00d8c20e be18e3d1b06da2c7fbdadcb3c1382dd046c449ba && git checkout -B drift-repro 7ba8b11f52215f945ef1fd417d38b1fb00d8c20e && git merge --no-ff be18e3d1b06da2c7fbdadcb3c1382dd046c449ba

node scripts/docs-audit/affected-docs.mjs --json 7ba8b11f52215f945ef1fd417d38b1fb00d8c20e

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

domain:server#1 · os-warren · session_01JQwxbXsK9j25sd7eVwW96G

Contract-review-claim: session_01JQwxbXsK9j25sd7eVwW96G · head be18e3d · 2026-11-03T04:20Z

domain:server#1 · os-warren · session_01JQwxbXsK9j25sd7eVwW96G

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: be18e3d1b06da2c7fbdadcb3c1382dd046c449ba
Local-runs: none
Scope: packages/spec/src/api/automation-api.zod.ts + packages/spec/src/api/contract.zod.ts (the declaredCode precedent the key name cites), packages/spec/src/automation/flow.zod.ts (FlowSchema, the data.flow member the pins' fixture must satisfy), packages/client/src/index.ts (automation.clone, first consumer of CloneFlowResponse['data']), packages/runtime/src/domains/automation.ts and packages/runtime/src/flow-clone.ts (the serving side and FLOW_CLONE_NOTICE), packages/runtime/src/route-ledger.ts (the clone row naming the schema), packages/runtime/src/domains/automation-flow-clone-custom-package.test.ts (parses the served answer through the schema), packages/spec/authorable-surface/api.json (the shard the level axis reads), scripts/check-changeset-no-major.mjs and scripts/pm/clause2-line.mjs (the gate that enforces the level rule), AGENTS.md §3 of the Human Minimum (the level rule). Read, not reviewed. Remainder of the diff (the changeset, the regenerated mdx, the test file) is the lane seat's ACCEPT at TIER_DEFAULT.

① Derived judgments

• Accept set of CloneFlowResponseSchema.data widens by one optional member noticeCode: z.string().optional(). Every answer that parsed on main ({ flow, packageId, notice }) still parses; an answer carrying a string noticeCode now parses where main's z.object would have stripped it silently (the object is not .strict(), so on main the key was accepted-and-dropped, never refused). Widening, no narrowing. Right.
• notice stays z.string() required, its describe byte-identical to main. Right.
• Public type surface: CloneFlowResponse (z.input) and CloneFlowResponseParsed (z.infer) each gain noticeCode?: string. No export added or removed: api-surface/api.json, declaration-map/api.json, export-origins/api.json, json-schema.manifest/api.json unchanged on the head, and check:api-surface / check:export-origins / check:declaration-map are not owed a regeneration. Right.
• authorable-surface/api.json lists api/CloneFlowResponse:data and its three siblings on both main and the head, nothing below data; a nested key of a REST answer is not an authorable key, so the shard does not move and Metadata-protocol: none is a true reading of the tree. Right.
• packages/client automation.clone() returns CloneFlowResponse['data'] imported as a type from @objectstack/spec/api; the return type gains the optional key with no source change in the client, and nothing in the client reads data.notice or data.noticeCode, so it type-checks against the widened shape by construction. No client changeset owed: the client publishes nothing it did not publish before. Right.
• packages/runtime clone handler answers deps.success({ flow, packageId, notice: FLOW_CLONE_NOTICE }) with no noticeCode; the key is optional, so the served answer still parses, and automation-flow-clone-custom-package.test.ts (CloneFlowResponseSchema.safeParse(answer.body).success === true, answer.data.notice === FLOW_CLONE_NOTICE) stays green by construction. Serving the code is runtime: the flow and permission-set "New similar" clone notices carry a code, so the Console can translate them (zh-CN shows English today) #29727's half. Right.
• route-ledger.ts clone row's note still spells data as { flow, packageId, notice }. Stale by one optional key, prose only, and the PR body names it for runtime: the flow and permission-set "New similar" clone notices carry a code, so the Console can translate them (zh-CN shows English today) #29727 to update when the server sends the code. Not a finding on this PR's hits; noted for runtime: the flow and permission-set "New similar" clone notices carry a code, so the Console can translate them (zh-CN shows English today) #29727.
• Generated: only content/docs/references/api/automation-api.mdx moves (the data summary row and a new noticeCode nested-shape row). check:generated is answered by CI; see ② for the check-run state.

② Semver level

Changeset .changeset/29758-clone-flow-notice-code.md: '@objectstack/spec': patch, body carries Clause-②: yes (widening) and Metadata-protocol: none; PR body carries the same two lines. Patch is the level the repo's rules require; the triage audit's "spec minor" is superseded by ruling A and is not a finding against the PR.

• AGENTS.md Human Minimum §3: "The level follows the kind alone: a kind takes at least minor on a package the diff moves, none takes patch; a non-protocol change, widening or breaking, ships patch and keeps its BREAKING banner and ADR-0087 disposition." A key added to a served REST answer changes nothing a metadata author can write, so the kind is none and the level is patch.
• scripts/check-changeset-no-major.mjs, "The LEVEL axis ([finding] No gate answers whether a changeset's LEVEL fits the surface — Check Changeset is green on patch and on minor for the same diff #16055)", ruling A (maintainer, 2026-10-21, on changeset levels: minor only when the metadata protocol changes (added / narrowed / semantic), patch otherwise; release notes grouped by what the reader must do (maintainer ruling A, 2026-10-21) #25105): "none grades every introduced entry patch"; "A non-protocol widening (REST) or narrowing (a driver, a posture) ships patch"; "none beside a minor is the half of the ruling with teeth ... refused whatever the package, moved or not". The judgeLevel branch if (declared.protocol === 'none') { if (moved.length) none-baseline-moved; if (minors.length) none-minor; none-clean } refuses a minor under none outright. The self-test pins the exact pairing this PR uses: armVerdict('Clause-②: yes (widening)\nMetadata-protocol: none\n') === 'none-clean' ("a yes (widening) with none beside it (a REST widening) ships patch").
• So the dev's deviation is the rule, not a workaround: a minor here would have been refused by Check Changeset, and correctly so. The gate is right; the triage line "a spec minor" restated the pre-ruling-A coupling of Clause-②: yes to minor.
• Consistency of the lines: Clause-②: yes (widening) names the accept-set widening ① confirms; Metadata-protocol: none names the unchanged authorable surface ① confirms; patch is what none grades. The two contradiction checks in the gate (added under no, narrowed without the (narrowing) arm) are not engaged. Consistent.
• Check-runs on the head at the time of this record: Check Changeset success (the level axis on this body and changeset is none-clean), Governed Surface Queue Guard success, PR-body guards success, Check PR Size success, Spec property liveness success, Lint · PM dispatch-gates success, Lint · scoped · tooling self-tests success, Check Documentation Links success, Dogfood Regression Gate success; 7 skipped by design (opt-in and conditional jobs). Still in progress on two reads: Build Core, Build UI Deps, Build Docs, Test Core 1/8 through 8/8, Live E2E UI, Type Check · workspace / source gates / consumer gates / debt ledger, Lint · ESLint / docs & code guards / repo & tooling gates / CI, release & engine gates / scoped · query-options erasure / scoped · slot lookup & corpus. No failure on any completed run. The landing rule (landing-operations.md: all PR checks green, not the required subset) is still owed by those runs; this record does not stand in for them.

③ Boundary flags

• Dev flag (deviation): "Changeset is @objectstack/spec patch, not the minor the order named." Answered in ②: patch is required by AGENTS.md §3 and ruling A; no action.
• Dev flag (deviation): "No @objectstack/client entry." Answered in ①: the client's source does not move and its return type follows the spec type by import; no changeset owed.
• Dev flag (deviation): "The schema TSDoc also gained one sentence naming noticeCode." Read: the TSDoc sentence matches the describe (stable code, console shows its own translation, falls back to notice for an unknown or absent code). No action.
• open_questions: []. None to answer.
• Author: PR user.login is objectstack-fleet[bot], so no human login to name.
• Triage 6594892213 named "a spec minor" and "regenerated artifacts" as binding. The level point is resolved against the repo's written rule in ②; the regeneration point is met (the one artefact the member moves is regenerated, and the ledgers that did not move are shown in ① not to be owed). Escalation not needed: a seat does not out-rule AGENTS.md, and triage's line is the older coupling, not a maintainer ruling.
• Name veto window: noticeCode stays the seat's call. Precedent read in ④.

④ Design judgment

packages/spec/src/api/automation-api.zod.ts against card #29758's Wanted list, ADR-0126 §9 (no clone lineage, the notice is the stated fact), declaredCode in contract.zod.ts, and the first consumers (packages/client automation.clone, the runtime clone handler, #29706's Console mapping):

• Optional, string, located beside notice. noticeCode: z.string().optional() sits in data after notice; notice: z.string() is required and its describe is unchanged. An answer with no noticeCode parses; notice absent is refused with exactly one issue at data.notice; a non-string noticeCode is refused with exactly one issue at data.noticeCode. The pins' fixture flow (name matching /^[a-z_][a-z0-9_]*$/, label, type: 'autolaunched', status: 'obsolete' which is in the FlowSchema status enum, two nodes, one edge) satisfies FlowSchema's required members, so the "exactly one issue" assertions are sound against the live FlowSchema. Holds.
• The describe tells a client what to do. "a client maps a code it knows to its own translated sentence, and falls back to notice verbatim for a code it does not know or when this key is absent (an older server sends none). The values are the server's; notice stays the English fallback." That is the card's Wanted sentence, and it is the whole contract Studio: zh-CN first screens stop mixing English: the clone notice, the new package form, the flow rail group #29706 needs: map known, fall back otherwise, never drop notice. Holds.
• No values enumerated. The schema is z.string(), not an enum or literal; the describe names no code. The vocabulary stays with the server (runtime: the flow and permission-set "New similar" clone notices carry a code, so the Console can translate them (zh-CN shows English today) #29727). This is the right side of the line: an enum here would make every new notice a spec release and would break the fallback story (an unknown code must parse, not be refused). Holds.
• Regenerated mdx matches the describe. The nested-shape row for noticeCode in content/docs/references/api/automation-api.mdx carries the describe text verbatim, typed string, marked optional; the data summary row reads { flow: object; packageId: string; notice: string; noticeCode?: string }. Holds.
• Key name against precedent. declaredCode (contract.zod.ts) is the nearest: a THING + Code key, z.string().optional(), naming an open, producer-owned code beside a required sibling (code there, notice here). The other two *Code keys in packages/spec/src/api (statusCode, authorizationCode in documentation.zod.ts) are HTTP-shaped and not a closer fit. noticeCode reads as "the code of the notice beside it", which is what it is. Holds; the name stays under the veto window as the card says.
• Attempt to break it. (a) An empty string '' parses as a noticeCode; the describe's "a code it does not know" covers it, so a client falls back to notice; declaredCode has the same latitude, and tightening to .min(1) here would diverge from that precedent for no consumer gain. Not a finding. (b) A server sending noticeCode without notice is refused, which is correct: the English fallback is the contract. (c) main's schema silently stripped an unknown noticeCode; a server that ships the code before this spec lands would have had it dropped at a parsing client, which is why the contract-first order (automation-api: CloneFlowResponseSchema declares an optional noticeCode beside notice, so the Console can translate the flow "New similar" notice #29758 then runtime: the flow and permission-set "New similar" clone notices carry a code, so the Console can translate them (zh-CN shows English today) #29727) is right. (d) Transport: CloneFlowResponse is z.input, so a consumer typing an answer in hand may omit the key; CloneFlowResponseParsed is z.infer, where the key is string | undefined. Both are what an optional key should type to. No must-fix, no should-fix.

Implemented-by: claude/project-thread-30noxg
Reviewed-by: session_01JQwxbXsK9j25sd7eVwW96G

VERDICT: PASS

domain:server#1 · os-warren · session_01JQwxbXsK9j25sd7eVwW96G

席位核对

ACCEPT · domain:server#1 · head be18e3d1b06da2c7fbdadcb3c1382dd046c449ba · 2026-11-03T04:44Z · contract review PASS 6595431256 at CONTRACT_REVIEW_TIER (schema face: packages/spec/src/api/automation-api.zod.ts, fable subagent, independent of the dev); remainder (test file, regenerated mdx, changeset) read by the seat at TIER_DEFAULT

1. Shape: draft, base main, Fixes #29758. 4 files, +79/-2: CloneFlowResponseSchema.data gains noticeCode: z.string().optional() beside the unchanged required notice, with 4 pins in automation-api.zod.test.ts, the regenerated automation-api.mdx, and one changeset (@objectstack/spec patch, Clause-②: yes (widening), Metadata-protocol: none). The card was taken on the cross-lane channel 「接手无主阻塞项」 (triage 6594892213). Not governed, under 3000 lines.
2. Premise measured: the clone answer carries only the English notice, so the Console cannot translate it (Studio: zh-CN first screens stop mixing English: the clone notice, the new package form, the flow rail group #29706 row 1). The ablation reds the accept and refusal pins (report 6595350768).
3. Gates on this head: check-runs pinned to be18e3d1: 65 total, 57 success, 8 skipped, 0 failed. Dev local: dispatch-gates --ran 102 derived, 101 exit 0, 1 NOT MEASURED (check:dual-build-cjs-loads, which CI runs); spec 892/892 files, typecheck 0, pnpm lint 0.
4. Accepted deviations: the changeset is patch, not the minor named in the triage audit. The review traced AGENTS.md Human Minimum §3 ("a non-protocol change, widening or breaking, ships patch") and scripts/check-changeset-no-major.mjs, which refuses minor beside Metadata-protocol: none. authorable-surface/api.json does not move, so none is a true reading of the tree. Key name noticeCode is the seat's call under the veto window, following the declaredCode precedent.
5. Out of scope: serving the code from the runtime and the permission-set door is runtime: the flow and permission-set "New similar" clone notices carry a code, so the Console can translate them (zh-CN shows English today) #29727 (seat 3). The review noted that the packages/runtime/src/route-ledger.ts clone row still spells data as { flow, packageId, notice }; that is passed to runtime: the flow and permission-set "New similar" clone notices carry a code, so the Console can translate them (zh-CN shows English today) #29727, with no new card.
6. Landing: not governed and under 3000 lines ⇒ the seat lands it (pr_ready + automerge_enable). At MERGED: landing record on automation-api: CloneFlowResponseSchema declares an optional noticeCode beside notice, so the Console can translate the flow "New similar" notice #29758 (closed by Fixes), pm:dispatched + pm:blocking removed; seat 3 told that runtime: the flow and permission-set "New similar" clone notices carry a code, so the Console can translate them (zh-CN shows English today) #29727 is unblocked.