fix(spec): let a schemaless node own an expression-ledger entry (#4439)

`FLOW_NODE_EXPRESSION_PATHS` (#4027) tells `registerFlow` and `objectstack
validate` which config keys hold expressions and in which dialect. Its
ratchet derives what it expects from descriptor `configSchema` markers and
fails both ways — an undeclared marker, and a ledger entry nothing declares.

`decision` / `script` / `subflow` publish no descriptor `configSchema` on
purpose (a partial one would drop the editors their hand-written Studio
forms need — the #4210 incident). Those two rules compose into a hole: an
expression slot on a schemaless node is unreachable by the ratchet, and the
reverse direction then refuses to let it be entered by hand either.

`decision.conditions[].expression` sat in that hole. Its own schema calls it
a bare CEL predicate and its own comment names `{…}` as the #1491 trap, and
no validator walked it — so a braced predicate passed tsc, passed validate,
passed registration. #4414 made that loud at run time; this makes it a build
failure, which is the delay #4027 exists to remove.

The ratchet now reads both declaration channels. Spec hands the schemaless
one over as JSON Schema (`getSchemalessNodeConfigJsonSchemas()`, memoized,
input mode — the shape a descriptor's `configSchema` already is), so both are
walked by the same function: no second notion of "a declared expression
property", and no `zod` dependency added to service-automation. Each channel
is separately asserted non-empty so a broken derivation cannot hide behind
the other's results.

Swept the rest of the class and recorded the result in the ledger header:
`script.template` is a template id, not a body; `script.inputs` /
`script.variables` / `subflow.input` interpolate `{token}` like essentially
every node config string and are covered generically. The decision predicate
is the only genuinely declared expression slot there.

Docs: the flows guide taught the wrong dialect for decision predicates in
three places, plus a warning that inverted after #4414 — and FlowNodeSchema's
own `@example` did the same. Corrected to bare CEL with the history stated,
so an author whose build now fails knows what changed. The dialect table goes
from three dialects to two: predicates never take braces, values always do.

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

Author: claude

.changeset/schemaless-node-expression-ledger.md

@@ -0,0 +1,76 @@
+---
+"@objectstack/spec": minor
+"@objectstack/service-automation": patch
+"@objectstack/lint": patch
+---
+
+fix(spec): a node that publishes no descriptor configSchema can now own an expression-ledger entry (#4439)
+
+`FLOW_NODE_EXPRESSION_PATHS` is the #4027 ledger that tells `registerFlow` and
+`objectstack validate` which config keys hold expressions, and in which dialect.
+Its ratchet (`config-expression-ledger.test.ts`) derives what it expects from
+descriptor `configSchema` `xExpression` markers, and fails in **both**
+directions — an undeclared marker, or a ledger entry nothing declares.
+
+`decision` / `script` / `subflow` publish **no** descriptor `configSchema` on
+purpose: a published partial schema would drop the editors their hand-written
+Studio forms need (the #4210 incident), so their contract lives in
+`schemaless-node-config.zod.ts`. Those two rules compose into a hole — an
+expression slot on a schemaless node is structurally unreachable by the ratchet,
+and because the reverse direction rejects unclaimed entries, it cannot be
+entered by hand either.
+
+`decision.conditions[].expression` sat in that hole. Its own schema says
+*"Bare CEL predicate deciding this branch"* and its own comment names `{…}` as
+the #1491 trap, and no validator walked it — so `{lead_record.status} ==
+'converted'` passed `tsc`, passed `objectstack validate`, passed registration.
+#4414 made that fail loudly at run time; this makes it fail at build time,
+which is the delay #4027 exists to remove.
+
+## The fix
+
+The ratchet now reads **both** declaration channels:
+
+- **descriptor `configSchema`** — unchanged, enumerated from the live registry;
+- **`schemaless-node-config.zod.ts`** — the marker rides
+  `.meta({ xExpression })` through `z.toJSONSchema`, the same channel
+  `loop.collection` has used since objectui#2670.
+
+Spec hands the second channel over as JSON Schema
+(`getSchemalessNodeConfigJsonSchemas()`, memoized, `input` mode — the shape a
+descriptor's `configSchema` already is), so the ratchet walks both with the
+*same* function. No second notion of "a declared expression property", which is
+the duplication a ledger exists to remove, and no `zod` dependency added to
+`service-automation`. Each channel is separately asserted non-empty, so a broken
+derivation on one side cannot hide behind the other's results.
+
+`SCHEMALESS_NODE_CONFIG_SCHEMAS` is also exported for anything else that needs
+to reason about all node config contracts. Additive — objectui's
+`flow-node-config` reconciliation imports each schema by name and is unaffected.
+
+## The sweep
+
+The other schemaless slots were checked and deliberately carry no marker:
+`script.template` is a template **id**, not a body; `script.inputs` /
+`script.variables` / `subflow.input` are values that interpolate `{token}` —
+text-with-holes, the shape essentially every node config string has, already
+covered generically by `validate-flow-template-paths` and the CLI flow linter.
+A `flow-template` ledger entry means something narrower: a *reference that must
+resolve to a value*, like `loop.collection`. So `decision.conditions[]
+.expression` is the only genuinely declared expression slot on the class — now
+recorded in the ledger's header so it is not re-derived.
+
+## Docs corrected
+
+The flows guide taught the **wrong dialect** for decision predicates in three
+places (`'{order_amount} > 10000'`), plus a "braces missing in a decision
+expression" warning that inverted after #4414 — and `FlowNodeSchema`'s own
+`@example` did the same. All corrected to bare CEL, with the history stated so
+an author with a braced predicate knows what changed and why their build now
+fails. The dialect table drops from three dialects to two: predicates never take
+braces, values always do.
+
+Verified: 13 new/updated tests across the ratchet, the engine's registration
+pass and `@objectstack/lint` (including the exact app-crm predicate rejected at
+both `registerFlow` and `objectstack validate`); `pnpm build`, `pnpm typecheck`
+(122 tasks), `pnpm lint` and `check:docs` clean.

content/docs/automation/flows.mdx

@@ -31,10 +31,10 @@ const approvalFlow = {
       type: 'decision',
       label: 'Check Amount',
       config: {
-        // decision expressions use {braces} around variables — see Expressions in flows
+        // decision expressions are bare CEL — no {braces}; see Expressions in flows
         conditions: [
-          { label: 'High Value', expression: '{order_amount} > 10000' },
-          { label: 'Standard', expression: '{order_amount} <= 10000' },
+          { label: 'High Value', expression: 'order_amount > 10000' },
+          { label: 'Standard', expression: 'order_amount <= 10000' },
         ],
       },
     },
@@ -168,9 +168,10 @@ or missing-`required` violation (#4277). A node type that publishes no
   type: 'decision',
   label: 'Check Status',
   config: {
+    // Bare CEL — the labels must match this node's out-edge labels exactly.
     conditions: [
-      { label: 'Approved', expression: "{status} == 'approved'" },
-      { label: 'Rejected', expression: "{status} == 'rejected'" },
+      { label: 'Approved', expression: "status == 'approved'" },
+      { label: 'Rejected', expression: "status == 'rejected'" },
     ],
   },
 }
@@ -972,30 +973,34 @@ failures so one broken flow does not abort startup.
 
 ## Expressions in flows
 
-A flow mixes **three expression dialects**, and using the wrong one is the
-single most common way a flow silently misbehaves. Which dialect applies is
-decided by *where* the expression sits — not by what it looks like:
+A flow mixes **two expression dialects**, and using the wrong one is the single
+most common way a flow silently misbehaves. Which dialect applies is decided by
+*where* the expression sits — not by what it looks like:
 
 | Where | Dialect | Write it like | Bindings |
 |:---|:---|:---|:---|
 | Start-node `condition` | **CEL** (bare, no braces) | `record.amount > 500` | `record.*`, `previous.*`, bare field names, `vars.*` |
 | Edge `condition` | **CEL** (bare, no braces) | `record.status == 'open'` | same as above |
-| Decision-node `conditions[].expression` | **Template compare** (braces required) | `{order_amount} > 10000` | flow variables by name, in `{…}` |
+| Decision-node `conditions[].expression` | **CEL** (bare, no braces) | `order_amount > 10000` | flow variables by name, and `vars.*` |
 | Field values in `create_record` / `update_record` | **Interpolation** (braces required) | `'Follow up on {record.name}'`, `'{TODAY() + 7}'` | `{var}`, `{var.path}`, `{$User.Id}`, `{$User.Email}`, `{NOW()}`, `{TODAY()}`, `{TODAY() + 90}` (whole days) |
 
 <Callout type="warn">
-**The two failure modes to memorize:**
+**The rule: predicates never take braces; values always do.**
 
-1. **Braces missing in a decision expression** — `'order_amount > 10000'` isn't
-   evaluated as a variable at all. It compares the *string* `"order_amount"`
-   against `"10000"`, which is **always true**, so the flow always takes the
-   first branch and never tells you. Write `'{order_amount} > 10000'`.
+1. **Braces in a predicate** — `'{order_amount} > 10000'` in a decision, edge or
+   start condition is rejected at `os build` / `registerFlow` with an error that
+   names the slot and tells you to drop the braces. Write
+   `'order_amount > 10000'`.
 2. **Braces missing in a field value** — `due_date: 'TODAY() + 7'` writes the
    literal text `TODAY() + 7` into the field. Write `'{TODAY() + 7}'`.
 
-The mirror mistake is putting braces *into* a CEL condition
-(`'{record.amount} > 500'`) — CEL conditions fail loudly rather than silently,
-with an error that tells you to drop the braces.
+Decision expressions were the exception until v17: they were evaluated on the
+legacy template path, so `'{order_amount} > 10000'` was the documented spelling
+and a bare `order_amount > 10000` compared the *string* `"order_amount"` against
+`"10000"` — always true, always the first branch, never a word about it. Both
+halves are gone: the slot is evaluated as the bare CEL it was always declared to
+be (#4414), and the brace spelling now fails the build (#4439). If you have a
+braced decision predicate, drop the braces.
 </Callout>
 
 CEL conditions that fail to evaluate raise an error and stop the run — they

packages/lint/src/validate-expressions.test.ts

@@ -578,6 +578,43 @@ describe('validateStackExpressions (ADR-0032 build-time)', () => {
       expect(issues).toHaveLength(0);
     });
 
+    /**
+     * #4439 — `decision.conditions[].expression` reaches the ledger through the
+     * SCHEMALESS channel (`decision` publishes no descriptor `configSchema`, so
+     * the marker rides `.meta({ xExpression })` on the Zod contract). Until then
+     * the ratchet could only see descriptor-declared slots, so this predicate —
+     * documented bare CEL, evaluated as bare CEL since #4414 — was checked by
+     * nobody and a `{…}` spelling passed `objectstack validate`.
+     */
+    const decisionFlow = (expression: string) => ({
+      objects,
+      flows: [{
+        name: 'convert_lead',
+        nodes: [
+          { id: 'start', type: 'start', config: { objectName: 'crm_lead' } },
+          { id: 'check', type: 'decision', config: { conditions: [{ label: 'Yes', expression }] } },
+        ],
+        edges: [],
+      }],
+    });
+
+    it('flags a `{var}` template dialect in a decision branch expression (#4439)', () => {
+      // The exact predicate app-crm shipped (#4414).
+      const issues = validateStackExpressions(decisionFlow("{lead_record.status} == 'converted'"));
+      const found = issues.filter(i => i.where.includes('conditions[0].expression'));
+      expect(found).toHaveLength(1);
+      expect(found[0].severity).toBe('error');
+      expect(found[0].where).toContain("flow 'convert_lead'");
+      expect(found[0].where).toContain("node 'check'");
+      expect(found[0].where).toContain('decision branch expression');
+      expect(found[0].source).toBe("{lead_record.status} == 'converted'");
+    });
+
+    it('passes the corrected bare-CEL decision predicate (#4439)', () => {
+      const issues = validateStackExpressions(decisionFlow("lead_record.status == 'converted'"));
+      expect(issues.filter(i => i.where.includes('conditions'))).toHaveLength(0);
+    });
+
     it('leaves a correct single-brace loop collection alone', () => {
       // `loop.collection` is the single-brace `{var}` flow-interpolation dialect,
       // where braces are CORRECT. It is recorded in the ledger as `flow-template`

packages/services/service-automation/src/builtin/config-expression-ledger.test.ts

@@ -28,6 +28,7 @@
 import { describe, it, expect } from 'vitest';
 import {
   FLOW_NODE_EXPRESSION_PATHS,
+  getSchemalessNodeConfigJsonSchemas,
   resolveFlowNodeExpressions,
   type FlowNodeExpressionRole,
 } from '@objectstack/spec/automation';
@@ -93,29 +94,67 @@ function collectExpressionProps(
 const engine = new AutomationEngine(silentLogger());
 installBuiltinNodes(engine, ctx());
 
-/** Every declared expression slot, derived from the live descriptors. */
-function declaredFromDescriptors(): { nodeType: string; path: string; role: FlowNodeExpressionRole }[] {
-  const found: { nodeType: string; path: string; role: FlowNodeExpressionRole }[] = [];
+type DeclaredSlot = { nodeType: string; path: string; role: FlowNodeExpressionRole };
+
+/** Resolve an `xExpression` marker to its ledger role, failing loudly on an unknown one. */
+function roleOf(nodeType: string, path: string, marker: string): FlowNodeExpressionRole {
+  const role = ROLE_BY_MARKER[marker];
+  expect(
+    role,
+    `${nodeType}.${path} declares an unknown xExpression marker '${marker}' — ` +
+    `add it to ROLE_BY_MARKER and teach the validators which dialect it takes`,
+  ).toBeDefined();
+  return role!;
+}
+
+/** Declared expression slots on builtins that publish a descriptor `configSchema`. */
+function declaredFromDescriptors(): DeclaredSlot[] {
+  const found: DeclaredSlot[] = [];
   for (const descriptor of engine.getActionDescriptors()) {
     const schema = descriptor.configSchema as SchemaNode | undefined;
     for (const { path, marker } of collectExpressionProps(schema)) {
-      const role = ROLE_BY_MARKER[marker];
-      expect(
-        role,
-        `${descriptor.type}.${path} declares an unknown xExpression marker '${marker}' — ` +
-        `add it to ROLE_BY_MARKER and teach the validators which dialect it takes`,
-      ).toBeDefined();
-      found.push({ nodeType: descriptor.type, path, role: role! });
+      found.push({ nodeType: descriptor.type, path, role: roleOf(descriptor.type, path, marker) });
+    }
+  }
+  return found;
+}
+
+/**
+ * Declared expression slots on the builtins that publish NO descriptor
+ * `configSchema` (#4439).
+ *
+ * `script` / `subflow` / `decision` keep their contract in
+ * `schemaless-node-config.zod.ts` on purpose, so deriving only from descriptors
+ * made their expression slots structurally unreachable by this ratchet — and
+ * because the reverse direction fails on a ledger entry nothing declares, they
+ * could not be entered by hand either. `decision.conditions[].expression` sat
+ * in that hole.
+ *
+ * Spec hands these over as JSON Schema — the same shape a descriptor's
+ * `configSchema` is — so the marker walk below is literally the same function.
+ * No second notion of "a declared expression property", which is the
+ * duplication a ledger exists to remove.
+ */
+function declaredFromSchemalessConfigs(): DeclaredSlot[] {
+  const found: DeclaredSlot[] = [];
+  for (const [nodeType, json] of Object.entries(getSchemalessNodeConfigJsonSchemas())) {
+    for (const { path, marker } of collectExpressionProps(json as SchemaNode)) {
+      found.push({ nodeType, path, role: roleOf(nodeType, path, marker) });
     }
   }
   return found;
 }
 
+/** Every declared expression slot, from BOTH declaration channels. */
+function declaredEverywhere(): DeclaredSlot[] {
+  return [...declaredFromDescriptors(), ...declaredFromSchemalessConfigs()];
+}
+
 const key = (e: { nodeType: string; path: string; role: string }) => `${e.nodeType}.${e.path} (${e.role})`;
 
 describe('configSchema ↔ expression-ledger reconciliation (#4027)', () => {
   it('every xExpression property a builtin declares is in the ledger', () => {
-    const declared = declaredFromDescriptors();
+    const declared = declaredEverywhere();
     // Sanity: if this ever empties, the derivation broke and the whole ratchet
     // would pass vacuously — the failure mode a ledger test must not have.
     expect(declared.length, 'no xExpression properties found — derivation is broken').toBeGreaterThan(0);
@@ -129,13 +168,39 @@ describe('configSchema ↔ expression-ledger reconciliation (#4027)', () => {
     ).toEqual([]);
   });
 
+  // Each channel must be non-empty on its own. Merging them into one list would
+  // let a broken derivation on either side hide behind the other's results —
+  // which is exactly how the schemaless channel went unnoticed until #4439.
+  it.each([
+    ['descriptor configSchema', declaredFromDescriptors],
+    ['schemaless-node-config.zod.ts', declaredFromSchemalessConfigs],
+  ] as const)('derives at least one slot from the %s channel', (_channel, derive) => {
+    expect(derive().length).toBeGreaterThan(0);
+  });
+
   it('the ledger carries no path a builtin no longer declares', () => {
-    const declared = new Set(declaredFromDescriptors().map(key));
+    const declared = new Set(declaredEverywhere().map(key));
     // Structural predicate surfaces (`config.condition`, `edge.condition`) are
-    // not descriptor properties and are deliberately absent from the ledger, so
-    // every ledger entry must correspond to a real declared property.
+    // not declared config properties on either channel and are deliberately
+    // absent from the ledger, so every ledger entry must correspond to a real
+    // declared property.
     const stale = FLOW_NODE_EXPRESSION_PATHS.map(key).filter((k) => !declared.has(k));
-    expect(stale, 'stale ledger entries — the descriptor no longer declares these').toEqual([]);
+    expect(stale, 'stale ledger entries — no descriptor or schemaless schema declares these').toEqual([]);
+  });
+
+  it('decision.conditions[].expression is covered — the #4439 hole', () => {
+    const decision = FLOW_NODE_EXPRESSION_PATHS.find(
+      (e) => e.nodeType === 'decision' && e.path === 'conditions[].expression',
+    );
+    expect(
+      decision,
+      'the slot a schemaless node could not own: declared bare CEL, walked by neither validator',
+    ).toBeDefined();
+    expect(decision!.role).toBe('predicate');
+    // And it must reach the ledger through the schemaless channel specifically —
+    // `decision` publishes no descriptor configSchema, by design.
+    expect(declaredFromSchemalessConfigs().map(key)).toContain(key(decision!));
+    expect(declaredFromDescriptors().map(key)).not.toContain(key(decision!));
   });
 
   it('screen.fields[].visibleWhen is covered — the #3528 regression', () => {
@@ -185,7 +250,25 @@ describe('resolveFlowNodeExpressions — path resolution (#4027)', () => {
     expect(resolveFlowNodeExpressions('screen', { fields: 'nope' })).toEqual([]);
   });
 
+  it('resolves each decision branch predicate, with its index (#4439)', () => {
+    const found = resolveFlowNodeExpressions('decision', {
+      conditions: [
+        { label: 'Yes', expression: "lead.status == 'converted'" },
+        { label: 'No', expression: 'true' },
+      ],
+    });
+    expect(found.map((f) => f.path)).toEqual([
+      'conditions[0].expression',
+      'conditions[1].expression',
+    ]);
+    expect(found.every((f) => f.entry.role === 'predicate')).toBe(true);
+  });
+
   it('returns nothing for a node type with no declared slots', () => {
+    // `config.condition` is a STRUCTURAL surface both validators already walk,
+    // deliberately not a ledger entry — and `assignment` declares no slots.
+    expect(resolveFlowNodeExpressions('assignment', { condition: 'a == b' })).toEqual([]);
+    // A decision branching purely on its edges declares no predicate here.
     expect(resolveFlowNodeExpressions('decision', { condition: 'a == b' })).toEqual([]);
   });
 });