`functions: [{ name, handler }]` (the array form) cannot survive `objectstack build` either — #4343/#4976 both fixed only the map form

[qq9340100]

Blocked-by: #4976

Found while implementing #4976 (the map form's lowered declaration). The array spelling of functions has the same round-trip hole, and it has it in both of its shapes — bare and declared — so it has never been buildable at all.

The two halves disagree

stack.zod.ts declares two accepted shapes for functions and its own TSDoc calls both first-class:

 *   - Map form (preferred): `{ my_handler: (ctx) =` `> {...} }`
 *   - Array form: `[{ name: 'my_handler', handler: (ctx) =` `> {...} }]`

lowerCallables lowers the array form and has a dedicated test pinning what it emits (packages/cli/src/utils/lower-callables.test.ts, "keeps effect on the array form too"):

{ name: 'syncBilling', handler: 'syncBilling', effect: 'writes' }

But the array member of the union in packages/spec/src/stack.zod.ts (~441) requires a callable handler, with no lowered alternative:

functions: z.union([
  z.record(z.string(), FlowFunctionEntrySchema),
  z.array(z.object({
    name: z.string(),
    handler: z.function(),        // ← no string ref member
    packageId: z.string().optional(),
    effect: FlowFunctionEffectSchema.optional(),
  })),
]).optional()

Measured on origin/main @ 773f80a

Driving the real build pipeline (defineStack → normalizeStackInput → lowerCallables → ObjectStackDefinitionSchema.safeParse):

map bare lowered        -> OK
map declared lowered    -> FAIL invalid_union@functions   (#4976, being fixed)
array bare lowered      -> FAIL invalid_union@functions   (this issue)
array declared lowered  -> FAIL invalid_union@functions   (this issue)

Note the middle two lines: #4343 closed the map/bare case and #4976 closes map/declared, and neither touched the array member — so once #4976 lands, the array form is the only remaining spelling of functions that objectstack build refuses, with the same unreadable invalid_union: Invalid input and no path past functions.

Why it stayed invisible

Nothing in the repo authors the array form: grep -rn "functions: \[" examples/ content/docs/ skills/ finds no app and no doc example, only unit tests that stop at the emitted shape or start from a hand-built bundle. lower-callables.test.ts asserts what the lowering produces; the spec tests parse only authored shapes; no test crosses the boundary. That is the same gap #4976 names for the map form, one surface over.

Suggested direction

Symmetric with #4976: let the array member's handler be a callable or a lowered ref (z.union([z.function(), z.string().min(1)])), and extend the cross-boundary round-trip pin #4976 adds (packages/cli/src/utils/lower-callables.test.ts) to cover the array form so the two halves cannot drift apart a third time.

Worth deciding as part of it: whether the array form earns the fix or the retirement. It is a declared authoring surface with no measured consumer — no example app, no doc, no skill uses it — so "retire the array form, keep the map" is a legitimate reading of the startup-focus principle. Either answer closes the round-trip hole; shipping neither leaves a documented shape that fails at build time.

Filed unassigned per Prime Directive #10, out of #4976's scope (that issue's landing point is FlowFunctionEntrySchema; this member lives in stack.zod.ts).

---

Generated by Claude Code

[claude]

Triage: pm:blocked + Blocked-by: objectstack-ai/objectstack#4976 + domain:spec + target:v17.

Domain anchoring

The union member that refuses the lowered shape is packages/spec/src/stack.zod.ts:440-448 (re-read on origin/main 72847c5; the functions: z.union([...]) block is where the body says it is). packages/spec and its generated artifacts ⇒ domain:spec, and per the "shared contract surfaces have one owner" rule this belongs to the spec seat regardless of who needs it — the round-trip pin the fix extends lives in packages/cli, but the authored contract does not move.

Why pm:blocked rather than pm:queue

#4976 is pm:queue + domain:spec + target:v17 and assigned (in flight). Three concrete collisions, not just adjacency:

1. Same union, one member apart — both edits land inside functions: in stack.zod.ts.
2. This issue's stated acceptance is to extend the cross-boundary round-trip pin functions: { fn: { handler, effect: 'writes' } } cannot survive objectstack build — lowering emits a shape FlowFunctionEntrySchema rejects #4976 adds to packages/cli/src/utils/lower-callables.test.ts. That pin does not exist yet; the extension has nothing to attach to until functions: { fn: { handler, effect: 'writes' } } cannot survive objectstack build — lowering emits a shape FlowFunctionEntrySchema rejects #4976 merges.
3. The measurement table in the body is itself written relative to functions: { fn: { handler, effect: 'writes' } } cannot survive objectstack build — lowering emits a shape FlowFunctionEntrySchema rejects #4976 landing ("once functions: { fn: { handler, effect: 'writes' } } cannot survive objectstack build — lowering emits a shape FlowFunctionEntrySchema rejects #4976 lands, the array form is the only remaining spelling").

Blocked-by: added to the body; the unlock sweep returns it when #4976 closes.

The fix/retire question is real, but it does not make this needs-user-decision today

The body raises it honestly: the array form has no measured consumer (no example app, no doc, no skill), so "retire it, keep the map form" is a legitimate reading of the startup-focus principle. Two reasons it is queued rather than sent to the decision inbox:

• Either answer closes the same hole, and the default route is already established: script 的 config 契约要接入 #4277 的执行期 parse,先得有判别式(actionType)形态 #4343 fixed map/bare, functions: { fn: { handler, effect: 'writes' } } cannot survive objectstack build — lowering emits a shape FlowFunctionEntrySchema rejects #4976 fixes map/declared, and the symmetric edit here is the third instance of one pattern. Shipping neither is the only outcome the body rules out, and that is not a decision, it is the status quo.
• Retirement is not a rider on this issue. Removing a declared authoring surface is an ADR-0087 conversion with a liveness-ledger route and generated baselines — the spec-property-retirement playbook, its own programme. If the seat that takes this concludes retirement is right, the correct return is needs_decision with that recommendation, ⛔ not a quiet deletion inside a bug fix.

PM mechanism assumption (verify, falsifying it is welcome): that the symmetric widening (handler: z.union([z.function(), z.string().min(1)])) is sufficient and does not need the same treatment #4976 gives FlowFunctionEntrySchema. The two members are structurally different — the array member is a plain z.object, the map member goes through a named schema — so re-measure the four-cell table in the body after #4976 lands rather than assuming the array rows are the only ones left red.

Release board

target:v17 under criterion ② — stack.zod.ts's own TSDoc calls the array form first-class ("Array form: [{ name: 'my_handler', handler: (ctx) => {…} }]") while objectstack build rejects it with an unreadable invalid_union: Invalid input. A declared authoring shape that cannot survive the build is a schema that lies, and its map-form sibling #4976 is already on the board. Note the board's own exits apply: if the ruling is retirement, this comes off the board rather than being fixed.

Dedup (three repos, open issues and PRs)

⚠️ The GitHub search API is not reachable from this seat (/search/issues answers "sessions are bound to their configured repositories", returning a structurally empty result rather than an error). Dedup was done by paginating all 442 open issues and PRs across the three repos and matching locally on lowerCallables / lower-callables, functions: [, FlowFunctionEntrySchema.

Exactly one match — #4976, handled above as the dependency. It is not a duplicate: its landing point is FlowFunctionEntrySchema, this one's is the array member of the stack.zod.ts union, and the body's measured table shows the two map rows and the two array rows failing independently.

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code