fix(spec): FlowFunctionEntrySchema 收下 lowered declaration,声明形写手重新扛得住 objectstack build (#4976)

`lowerCallables` 自 #4396 起会把声明形 `functions` 条目降级成
`{ handler: '<ref>', effect: 'writes' }` —— 保留声明、只把可调用体换成字符串
ref。同一次改动没有同步扩 union,于是 CLI 亲手产出的形状被它自己必须通过的
schema 拒收,`objectstack build` 报 `invalid_union: Invalid input`,路径止步于
`functions`,不点名键、不点名条目、不给原因。

补上第四个 union 成员:lowered declaration。它由
`FlowFunctionDeclarationSchema.extend({ handler })` 派生而来,而不是在旁边重抄
一份 —— 两者只差一个字段,所以严格性、surface 名、别名表与
`` `efect` → `effect` `` 处方原样随行,声明形将来加键也自动带过去。别名区未
触碰(不新增 `strictObject` 注册)。

`effect` 在此保持 optional + 默认值:走 `defineStack` 的路径会先把 `'pure'`
默认值落实,但 `{ strict: false }` 会跳过那次 parse,要求必填就会把同一个
`invalid_union` 还给那条路径。

runtime 半边本就正确,未改一行:`normalizeFlowFunctionEntry` 对两种 lowered
形状都返回 `undefined`(都不携带可调用体),而 `mergeRuntimeModule` 在任何
collector 之前就把 sidecar 模块的函数重新挂回 JSON 携带的声明上,所以 `effect`
在构建路径上完整抵达 `collectBundleFunctionEntries`。

两半之间补上跨界 pin:走真实流水线(`defineStack` → `normalizeStackInput` →
`lowerCallables` → parse),而不是手写一份「以为 lowering 会产出什么」的样例
—— 正是这条从未有人跨过的边界,让两侧各自全绿而 build 死在接缝上。

行为面唯一变化:手写 `{ handler: 'someName' }` 由拒收变为接受。该拒收无法与本
成员共存,也本不该存在 —— 裸字符串条目(`functions: { foo: 'foo' }`)自 #4343
起就被接受并附带「注册不到任何东西」的说明,只拒 record 拼法而放行 string 拼法
是同一个契约的两种方言。两者失败方式一致且响亮:execute 时
`no function named '…' is registered`(#1870)。

showcase 换回诚实拼法(`{ handler: sweepProjectHealth, effect: 'writes' }`),
并把「钉死裸形」的守卫倒转为「唯一真正写数据的条目必须声明」—— 那才是值得守的
事实。相邻缺口(数组形 `functions: [{ name, handler }]` 同样无法往返)另立
#6238,不在本 PR 范围。

Author: claude

.changeset/flow-function-lowered-declaration.md

@@ -0,0 +1,70 @@
+---
+"@objectstack/spec": minor
+---
+
+fix(spec): `functions: { fn: { handler, effect: 'writes' } }` survives `objectstack build` (#4976)
+
+`FlowFunctionEntrySchema` gains a fourth union member — the **lowered
+declaration**, a `functions` entry whose `handler` has been replaced by the
+string ref `objectstack build` emits:
+
+```
+functions: {
+  sweepProjectHealth: { handler: 'sweepProjectHealth', effect: 'writes' },
+}
+```
+
+Nothing an author writes changes. This shape is produced by the CLI, not typed
+by a person: `lowerCallables` replaces every inline callable with a serialisable
+ref before the stack is parsed (it must — `z.function()` wraps callables and
+would break the ref mapping), and since #4396 it keeps the declaration beside
+the ref so what a function said about itself survives into the artifact. The
+union was not extended in that change, so the artifact it started emitting was
+rejected by the very schema it had to pass:
+
+```
+  ✗ Validation failed
+
+  functions:
+    ✗ functions
+      invalid_union: Invalid input
+```
+
+Loading from source was unaffected — `objectstack dev`, `objectstack validate`
+and the test suite all passed — so the failure appeared only at build, on the
+one spelling the platform asks writers to use. That is the same asymmetry #4343
+fixed for the bare handler ref, one shape over.
+
+**Why this was worse than a failed build.** `effect: 'writes'` exists so a
+function that writes is not counted as having written nothing (#4396, #4354): a
+`script` step reports no record metrics *because* flow functions are
+contractually pure, and a declared writer instead reports `unmeasuredEffect` so
+the run's broken-sweep query (`selected > 0 AND acted = 0 AND unmeasured = 0`)
+stays off it. The error above names no key, no entry and no reason, so the
+practical repair an author reaches for is deleting the declaration — shipping an
+undeclared writer, which is exactly the state it exists to prevent, recorded
+permanently in `sys_automation_run`.
+
+**One behaviour change worth stating.** `{ handler: 'someName' }` written by
+hand now parses where it used to be rejected as "handler is not callable". The
+rejection could not survive this member and should not have: a bare string entry
+(`functions: { foo: 'foo' }`) has been accepted since #4343 with the caveat that
+it registers nothing, so refusing the record spelling of the same mistake while
+accepting the string spelling was two dialects for one contract. Both fail the
+same way, loudly, at execute: `no function named '…' is registered` (#1870).
+Everything else stays strict — the lowered member is *derived* from the authored
+declaration rather than re-typed beside it, so `{ handler: 'fn', efect: 'writes' }`
+still raises the named surface and the `` `efect` → `effect` `` prescription, an
+unknown `effect` value is still refused, and an empty ref is still not a name.
+
+**Runtime is unchanged and was already correct.** `normalizeFlowFunctionEntry`
+returns `undefined` for a lowered entry in both its shapes, because neither
+carries a callable; `mergeRuntimeModule` re-attaches the sidecar module's
+function to the declaration the JSON carried *before* any collector runs, so
+`effect` reaches `collectBundleFunctionEntries` intact on the built path.
+
+The two halves are now pinned against each other by a round-trip test that
+drives the real pipeline (`defineStack` → `normalizeStackInput` →
+`lowerCallables` → parse) instead of a hand-written sample of what the lowering
+is believed to emit — the crossing neither side previously made, which is why
+both stayed green while the build failed on the join.

examples/app-showcase/objectstack.config.ts

@@ -214,23 +214,21 @@ export default defineStack({
   // `sweepProjectHealth` — the handler `HealthSweepJob` names — lives here too.
   // It is the case the pure contract does not cover: a nightly sweep has no
   // downstream declarative node to persist for it, so it writes over an engine
-  // handle captured at `onEnable`.
+  // handle captured at `onEnable`. That is why it is spelled the DECLARED way
+  // (#4396) — an undeclared writer is counted as having written nothing, which
+  // is indistinguishable from the broken sweep #4354 exists to detect.
   //
-  // ⚠️ Do NOT rewrite this as `{ handler: sweepProjectHealth, effect: 'writes' }`.
-  // That declared form (#4396) is the honest spelling for a writer and is what
-  // this entry wants — but it cannot survive `objectstack build` today: the CLI
-  // lowers it to `{ handler: 'sweepProjectHealth', effect: 'writes' }` and
-  // `FlowFunctionEntrySchema` accepts a bare callable, a declaration whose
-  // `handler` is a CALLABLE, or a bare string ref — never a declaration whose
-  // handler has been lowered to a string. `pnpm build` fails with
-  // `functions: invalid_union`. Filed as #4976; switch back once it lands.
-  // Nothing is lost at runtime meanwhile: `effect` has exactly one consumer,
-  // the `script` node's `unmeasuredEffect` metric, and the JOB path drops it
-  // (`collectBundleFunctions` keeps only the handler).
+  // This entry authored the bare form until #4976, not because the bare form was
+  // right but because the declared one could not survive `objectstack build`:
+  // the CLI lowers it to `{ handler: 'sweepProjectHealth', effect: 'writes' }`
+  // and `FlowFunctionEntrySchema` had no member for a declaration whose handler
+  // is a ref, so `pnpm build` failed with `functions: invalid_union`. #4976
+  // added that member; the honest spelling is back, and this app is the
+  // end-to-end proof that it builds.
   functions: {
     summarizeCompletedTask: ({ input }: { input: Record<string, unknown> }) =>
       `Completed: ${String(input.title ?? 'task')} (priority ${String(input.priority ?? 'normal')}).`,
-    sweepProjectHealth,
+    sweepProjectHealth: { handler: sweepProjectHealth, effect: 'writes' as const },
   },
   jobs: allJobs,
   emailTemplates: allEmails,

examples/app-showcase/test/inert-wirings.test.ts

@@ -96,24 +96,22 @@ describe('declarative jobs resolve their handler (#4774 ①)', () => {
     });
   }
 
-  it('every functions entry is authored in a form `objectstack build` can carry', () => {
-    // `objectstack build` LOWERS each inline callable to a serialisable string
-    // ref before the stack is parsed, and `FlowFunctionEntrySchema` accepts a
-    // bare callable, a declaration whose `handler` is a CALLABLE, or a bare
-    // string ref — but NOT a declaration whose handler has been lowered to a
-    // string, which is exactly what the CLI emits for the declared form
-    // (`{ handler: fn, effect: 'writes' }`, #4396). So authoring the declared
-    // form here builds green from source and fails `pnpm build` with
-    // `functions: invalid_union`. Filed as #4976.
+  it('the sweep DECLARES that it writes — an undeclared writer reads as a broken sweep', () => {
+    // The inverse of the guard that stood here until #4976. That one pinned
+    // every entry to the BARE form, because the declared spelling could not
+    // survive `objectstack build`: the CLI lowers it to
+    // `{ handler: 'sweepProjectHealth', effect: 'writes' }` and
+    // `FlowFunctionEntrySchema` had no member for a declaration whose handler
+    // is a ref, so the reference app was pinned to the dishonest spelling to
+    // keep `pnpm build` green.
     //
-    // Pinning the bare form keeps that failure out of the reference app until
-    // the schema accepts the lowered declaration. Delete this guard — don't
-    // work around it — when #4976 lands.
-    const declared = functionNames().filter((name) => typeof functionEntry(name) !== 'function');
-    expect(
-      declared,
-      `declared-form functions entry/entries cannot survive \`objectstack build\` (#4976): ${declared.join(', ')}`,
-    ).toEqual([]);
+    // #4976 added that member, so the pin inverts rather than disappears — the
+    // thing worth guarding was never "bare", it was that the one entry which
+    // genuinely writes says so. `sweepProjectHealth` is a nightly job with no
+    // downstream declarative node to count its writes, so undeclared it reports
+    // `selected: N, acted: 0` — indistinguishable from the broken sweep #4354
+    // exists to detect, permanently, in `sys_automation_run`.
+    expect(functionEntry('sweepProjectHealth')).toMatchObject({ effect: 'writes' });
   });
 });
 

packages/cli/src/utils/lower-callables.test.ts

@@ -1,6 +1,8 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, it, expect } from 'vitest';
+import { defineStack, normalizeStackInput, ObjectStackDefinitionSchema } from '@objectstack/spec';
+import { FlowFunctionEntrySchema } from '@objectstack/spec/automation';
 import { lowerCallables } from './lower-callables.js';
 
 // ── #3855: `target` is the only handler slot ────────────────────────────────
@@ -124,3 +126,95 @@ describe('lowerCallables — declared `functions` entries (#4396)', () => {
     expect(entry).toEqual({ name: 'syncBilling', handler: 'syncBilling', effect: 'writes' });
   });
 });
+
+// ── #4976: the lowering and the schema must round-trip ──────────────────────
+//
+// Every test above stops at the shape `lowerCallables` EMITS, and every spec
+// test parses only shapes an author WRITES. Nothing crossed the boundary — so
+// when #4396 taught this step to keep a declared entry's declaration, and the
+// union in `flow-function.zod.ts` was not extended in the same change, both
+// halves stayed green and `objectstack build` failed on the join with
+// `invalid_union: Invalid input` and no path past `functions`.
+//
+// These tests are that boundary, driven through the real build pipeline
+// (`defineStack` → `normalizeStackInput` → `lowerCallables` → parse) rather
+// than a hand-written sample of what the lowering is believed to emit: a
+// hand-written sample is a third copy of the truth and drifts exactly the way
+// the two halves already did.
+//
+// SCOPE: the map form. The ARRAY form (`functions: [{ name, handler }]`) does
+// not round-trip either — in both its bare and declared spellings, since #4343
+// and #4976 each only ever touched the map — and its member lives in
+// `stack.zod.ts` rather than in `FlowFunctionEntrySchema`. Filed as #6238;
+// extend the parametrisation below when it lands.
+describe('lowerCallables → the spec parses what it emits (#4976)', () => {
+  const base = {
+    manifest: { id: 'com.example.demo', name: 'demo', version: '1.0.0', type: 'app' as const },
+  };
+
+  /** Exactly what `objectstack compile` does, in the order it does it. */
+  const buildPipeline = (functions: Record<string, unknown>) => {
+    const stack = defineStack({ ...base, functions } as never);
+    const normalized = normalizeStackInput(stack as Record<string, unknown>);
+    return lowerCallables(normalized);
+  };
+
+  const cases: Array<[label: string, functions: Record<string, unknown>]> = [
+    ['a bare handler', { scoreLead: () => ({ score: 1 }) }],
+    ['a declared writer', { syncBilling: { handler: () => ({ ok: true }), effect: 'writes' } }],
+    ['a declaration that states the pure default', { scoreLead: { handler: () => ({ score: 1 }), effect: 'pure' } }],
+    ['a declaration that states nothing', { scoreLead: { handler: () => ({ score: 1 }) } }],
+    ['both spellings side by side', {
+      scoreLead: () => ({ score: 1 }),
+      syncBilling: { handler: () => ({ ok: true }), effect: 'writes' },
+    }],
+  ];
+
+  for (const [label, functions] of cases) {
+    it(`parses every entry it emits for ${label}`, () => {
+      const emitted = (buildPipeline(functions).lowered as {
+        functions: Record<string, unknown>;
+      }).functions;
+
+      for (const [name, entry] of Object.entries(emitted)) {
+        const result = FlowFunctionEntrySchema.safeParse(entry);
+        expect(
+          result.success,
+          `emitted entry '${name}' (${JSON.stringify(entry)}) is not a shape FlowFunctionEntrySchema accepts: `
+          + JSON.stringify(result.success ? [] : result.error.issues),
+        ).toBe(true);
+      }
+    });
+
+    it(`parses the whole lowered stack for ${label}`, () => {
+      // The assertion the build itself makes (`compile.ts` step 3). Parsing the
+      // entries one by one can pass while the stack does not — `functions` is a
+      // union of a record and an array, so a rejected entry surfaces only as
+      // `invalid_union` on the parent, which is precisely the unreadable error
+      // the issue is about.
+      const { lowered } = buildPipeline(functions);
+      const result = ObjectStackDefinitionSchema.safeParse(lowered);
+      expect(
+        result.success,
+        `lowered stack rejected: ${JSON.stringify(result.success ? [] : result.error.issues)}`,
+      ).toBe(true);
+    });
+  }
+
+  it('carries the declaration into the artifact, not just past the parse', () => {
+    // Surviving the parse is worthless if `effect` is dropped on the way — that
+    // would re-create #4396's silent un-declaring with a green build. The
+    // artifact must still SAY 'writes', because that string is what
+    // `mergeRuntimeModule` re-attaches the module's callable to at boot.
+    const { lowered } = buildPipeline({
+      syncBilling: { handler: () => ({ ok: true }), effect: 'writes' },
+    });
+    const parsed = ObjectStackDefinitionSchema.parse(lowered) as {
+      functions: Record<string, { handler: string; effect: string }>;
+    };
+    expect(parsed.functions.syncBilling).toEqual({ handler: 'syncBilling', effect: 'writes' });
+    // And it is JSON — the artifact is `objectstack.json`, not a module.
+    expect(JSON.parse(JSON.stringify(lowered)).functions.syncBilling)
+      .toEqual({ handler: 'syncBilling', effect: 'writes' });
+  });
+});

packages/spec/src/automation/flow-function.test.ts

@@ -66,8 +66,28 @@ describe('FlowFunctionEntrySchema', () => {
     expect(FlowFunctionEntrySchema.safeParse({ handler: () => 1, effect: 'writes' }).success).toBe(true);
   });
 
-  it('rejects a declaration whose handler is not callable', () => {
-    expect(FlowFunctionEntrySchema.safeParse({ handler: 'scoreLead' }).success).toBe(false);
+  it('rejects a declaration whose handler is neither a callable nor a ref', () => {
+    // Narrowed in #4976, and the narrowing is the point rather than a
+    // concession. This assertion used to read `{ handler: 'scoreLead' }` —
+    // "handler is not callable" — but a string handler is exactly what
+    // `objectstack build` emits for a declared entry, so the union now accepts
+    // it (see the lowered-declaration cases below). What survives is the
+    // verdict on a handler that is neither: no callable, no name.
+    expect(FlowFunctionEntrySchema.safeParse({ handler: 42 }).success).toBe(false);
+    expect(FlowFunctionEntrySchema.safeParse({ handler: '' }).success).toBe(false);
+    expect(FlowFunctionEntrySchema.safeParse({ effect: 'writes' }).success).toBe(false);
+  });
+
+  it('accepts a hand-authored `{ handler: <name> }` for the same reason it accepts a bare name', () => {
+    // The inversion #4976 causes, stated plainly rather than left as a
+    // surprise. Hand-authoring the lowered form registers nothing — but that
+    // was ALREADY true of the bare string member (`functions: { foo: 'foo' }`),
+    // which has been accepted since #4343 with exactly that caveat. Rejecting
+    // the record spelling while accepting the string spelling of one mistake
+    // was two dialects for one contract; the loud failure is the same either
+    // way, at execute: "no function named '…' is registered" (#1870).
+    expect(FlowFunctionEntrySchema.safeParse({ handler: 'scoreLead' }).success).toBe(true);
+    expect(FlowFunctionEntrySchema.safeParse('scoreLead').success).toBe(true);
   });
 
   // #4343 — what `objectstack build` produces. The CLI lowers every inline
@@ -82,10 +102,48 @@ describe('FlowFunctionEntrySchema', () => {
     expect(FlowFunctionEntrySchema.safeParse('').success).toBe(false);
   });
 
-  it('drops a lowered ref when normalizing — it names a function without carrying one', () => {
+  // #4976 — the other half of what `objectstack build` emits. #4396 taught
+  // `lowerCallables` to keep a declared entry's declaration beside its lowered
+  // ref; this union was not extended in the same change, so the artifact
+  // `{ syncBilling: { handler: 'syncBilling', effect: 'writes' } }` failed the
+  // build with `invalid_union: Invalid input` — no path past `functions`, no
+  // key named. An author who cannot read that error deletes the declaration and
+  // ships an undeclared writer, which is the exact state `effect` exists to
+  // prevent (#4354).
+  it('accepts a lowered DECLARATION, the other form a built artifact carries', () => {
+    expect(FlowFunctionEntrySchema.safeParse({ handler: 'syncBilling', effect: 'writes' }).success).toBe(true);
+    expect(FlowFunctionEntrySchema.safeParse({ handler: 'syncBilling', effect: 'pure' }).success).toBe(true);
+  });
+
+  it('applies the pure default to a lowered declaration that states no effect', () => {
+    // `defineStack`'s parse normally materialises `effect` before the lowering
+    // ever runs, but `{ strict: false }` skips that parse — so the member must
+    // accept the shape without it, or that path keeps the failure this fixes.
+    const parsed = FlowFunctionEntrySchema.parse({ handler: 'syncBilling' });
+    expect(parsed).toEqual({ handler: 'syncBilling', effect: 'pure' });
+  });
+
+  it('keeps the declaration strict once lowered — a typo in a built artifact still names itself', () => {
+    // Derived from `FlowFunctionDeclarationSchema` rather than re-typed, so the
+    // surface name, the alias table and the prescription travel with it.
+    const result = FlowFunctionEntrySchema.safeParse({ handler: 'syncBilling', efect: 'writes' });
+    expect(result.success).toBe(false);
+    const messages = JSON.stringify(result.error!.issues);
+    expect(messages).toContain('`functions` entry');
+    expect(messages).toContain('`efect` → `effect`');
+    // And a value the runtime has no meaning for is still refused.
+    expect(FlowFunctionEntrySchema.safeParse({ handler: 'syncBilling', effect: 'write' }).success).toBe(false);
+  });
+
+  it('drops BOTH lowered shapes when normalizing — each names a function without carrying one', () => {
     // The callable for that name comes from the sidecar ESM module the build
-    // emits; binding the string would register a name pointing at nothing.
+    // emits; binding the ref would register a name pointing at nothing. This is
+    // not where `effect` is lost on the built path — `mergeRuntimeModule` has
+    // already re-attached the callable to the declaration by the time a boot
+    // normalizes anything (pinned in `packages/runtime`'s
+    // `artifact-function-declarations.test.ts`).
     expect(normalizeFlowFunctionEntry('scoreLead')).toBeUndefined();
+    expect(normalizeFlowFunctionEntry({ handler: 'syncBilling', effect: 'writes' })).toBeUndefined();
   });
 });