fix(spec): accept a lowered handler ref in functions, so defineStack({ functions }) survives a build (#4343)

`objectstack build` lowers every inline callable to a serialisable string ref
BEFORE the stack is parsed — it must, since `z.function()` wraps callables and
would break the ref mapping — so a built manifest holds `{ myFn: 'myFn' }`.
`FlowFunctionEntrySchema` accepted only a function or a `{ handler, effect }`
declaration, so the parse rejected what the build had just produced: a
documented, first-class authoring mechanism could not survive a build.

Nothing had noticed because no bundled example used `functions`. #4343 turns
that from latent into blocking: `config.function` becomes the only thing a
`script` node runs, so registering one is now mandatory for any app with a
script node — which is what the showcase demo in this branch hit.

`Hook.handler` already declared exactly this pair (a string post-build, an
inline function pre-build), so this puts `functions` on the platform's existing
shape rather than a new one. A string carries no callable and
`normalizeFlowFunctionEntry` still drops it by design — the real functions ride
in the sibling ESM module the build emits and are merged by name — so
hand-authoring one registers nothing and fails loudly at execute rather than
silently.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ct9NXp2JumjKuARtQnrbPf

Author: claude

.changeset/script-branch-keys-retired.md

@@ -60,6 +60,22 @@ a row in `sys_metadata` has no author for a tombstone to teach. So a stored emai
 arrives stripped of the keys nothing read and then **refuses for naming no callable**,
 where it used to log a line and report success. That flip is the behavior change to expect.
 
+**A build gap this surfaced, fixed here.** `FlowFunctionEntrySchema` now also accepts a
+**lowered handler ref** (a non-empty string), the form `objectstack build` produces: the
+CLI lowers every inline callable to a serialisable ref *before* the stack is parsed (it
+must — `z.function()` wraps callables and would break the ref mapping), so a built
+manifest holds `{ myFn: 'myFn' }`, which neither previous member accepted. The result was
+that `defineStack({ functions })` — a documented, first-class mechanism — could not
+survive a build at all. Nothing had noticed because no bundled example used it; #4343
+turns that from latent into blocking, since `config.function` becomes the only thing a
+`script` node can run. `Hook.handler` already declared exactly this pair (`z.union([
+z.string(), <function> ])`, "string, post-build / inline function, pre-build"), so this
+brings `functions` onto the platform's established shape rather than inventing one. A
+string carries no callable and `normalizeFlowFunctionEntry` still drops it by design — the
+real functions ride in the sibling ESM module the build emits, merged by name — so
+hand-authoring one registers nothing and fails loudly at execute ("no function named '…'
+is registered"), never silently.
+
 Also in this change: the retired constants `SCRIPT_BUILTIN_ACTION_TYPES`,
 `SCRIPT_INVOKE_FUNCTION_ACTION_TYPE` and the `ScriptBuiltinActionType` type are removed
 (they described the dispatch set that no longer exists); `os validate` names a retired key

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

@@ -69,6 +69,24 @@ describe('FlowFunctionEntrySchema', () => {
   it('rejects a declaration whose handler is not callable', () => {
     expect(FlowFunctionEntrySchema.safeParse({ handler: 'scoreLead' }).success).toBe(false);
   });
+
+  // #4343 — what `objectstack build` produces. The CLI lowers every inline
+  // callable to a serialisable ref BEFORE the stack is parsed, so a built
+  // manifest holds `{ scoreLead: 'scoreLead' }`. Rejecting that made
+  // `defineStack({ functions })` — a documented, first-class mechanism —
+  // unbuildable, which #4343 turned from latent into blocking by making
+  // `config.function` the only thing a `script` node can run.
+  it('accepts a lowered handler ref, the form a built artifact carries', () => {
+    expect(FlowFunctionEntrySchema.safeParse('scoreLead').success).toBe(true);
+    // Empty is not a name.
+    expect(FlowFunctionEntrySchema.safeParse('').success).toBe(false);
+  });
+
+  it('drops a lowered ref when normalizing — it 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.
+    expect(normalizeFlowFunctionEntry('scoreLead')).toBeUndefined();
+  });
 });
 
 describe('defineStack({ functions }) — the authoring surface (#4396)', () => {

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

@@ -112,13 +112,33 @@ export type FlowFunctionDeclaration = z.infer<typeof FlowFunctionDeclarationSche
 export type FlowFunctionDeclarationInput = z.input<typeof FlowFunctionDeclarationSchema>;
 
 /**
- * One entry of the `functions` map as authors may write it: the handler alone
- * (pure), or a {@link FlowFunctionDeclarationSchema} that states its effect.
+ * One entry of the `functions` map: the handler alone (pure), a
+ * {@link FlowFunctionDeclarationSchema} that states its effect, or the
+ * **lowered handler ref** a built artifact carries.
+ *
+ * The first two are what an author writes. The third is what `objectstack
+ * build` produces and was, until #4343, the reason `defineStack({ functions })`
+ * could not survive a build at all: the CLI lowers every inline callable to a
+ * serialisable string ref BEFORE the stack is parsed (it must — `z.function()`
+ * wraps callables and would break the ref mapping), so the manifest reaching
+ * this schema holds `{ myFn: 'myFn' }`, which neither of the other two members
+ * accepts. The build failed on a mechanism its own docs call first-class.
+ *
+ * A string entry carries no callable, and that is correct rather than lossy:
+ * the real functions ride in the sibling ESM module esbuild emits, and
+ * {@link collectBundleFunctionEntries} merges both sources by name. The string
+ * is the artifact's record that the NAME exists — which is why
+ * {@link normalizeFlowFunctionEntry} deliberately drops it (see there).
+ *
+ * Authoring a string by hand therefore registers nothing. It fails loudly, not
+ * silently: a `script` node naming it refuses at execute with "no function
+ * named '…' is registered" (#1870).
  */
 export const FlowFunctionEntrySchema = lazySchema(() => z.union([
   z.function(),
   FlowFunctionDeclarationSchema,
-]).describe('A named handler function, or a declaration record stating its effect'));
+  z.string().min(1).describe('A lowered handler ref (built artifacts) — the callable rides in the sibling ESM module'),
+]).describe('A named handler function, a declaration record stating its effect, or a lowered handler ref'));
 
 export type FlowFunctionEntry = z.infer<typeof FlowFunctionEntrySchema>;
 
@@ -153,6 +173,12 @@ export function isFlowFunctionEffect(value: unknown): value is FlowFunctionEffec
  * Deliberately hand-written rather than a `FlowFunctionEntrySchema.parse()`:
  * the entry holds a live function, and the collectors that call this run on the
  * boot path where re-parsing every handler buys nothing.
+ *
+ * A lowered string ref (the third member of that schema) returns `undefined`
+ * here BY DESIGN — it names a function without carrying one. The callable for
+ * that name comes from the built sidecar module, which the same collector
+ * merges in; treating the string as an entry would register a name bound to
+ * nothing.
  */
 export function normalizeFlowFunctionEntry(entry: unknown): NormalizedFlowFunction | undefined {
   if (typeof entry === 'function') {