fix(cli): os generate flow scaffolds a flow os validate accepts, and a test that keeps it that way

.changeset/generate-flow-scaffold-validates.md

@@ -0,0 +1,48 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): `os generate flow` scaffolds a flow `os validate` accepts (#14087)
+
+The `flow` scaffold could not survive its own toolchain. Measured on 17.2.0,
+`os g flow my_flow` followed by `os validate` produced four refusals in one
+parse:
+
+```
+flows[0].nodes[0].label expected string, received undefined
+flows[0].nodes[0] unrecognized key(s): `name`, `next`
+flows[0].edges expected array, received undefined
+flows[0] unrecognized key(s): `trigger`
+```
+
+`FlowSchema` is `.strict()` and has never declared a top-level `trigger` on
+protocol 17. A record-change flow binds on the START node's `config` —
+`{ objectName, triggerType, condition }` — which is where
+`AutomationEngine.resolveTriggerBinding` reads it from. The scaffold also wrote
+an `events: ['after_insert', 'after_update']` vocabulary that exists nowhere on
+the current surface, and named a single node it then pointed at a node it never
+emitted.
+
+So the first flow anybody scaffolded was a file their own `os validate`
+rejected — against a `.strict()` error enumerating what is allowed rather than
+saying where the trigger had moved to.
+
+The template now emits the shape the schema accepts and the engine binds:
+`type: 'record_change'`, a labelled START node carrying
+`config: { objectName, triggerType: 'record-after-write' }`, a labelled END
+node, and the `edges` array joining them. `status` stays `'draft'` — the arming
+decision is the author's, and `os validate` says so.
+
+`generate-scaffold-validates.test.ts` puts every generator's output through the
+two steps `os validate` runs on an authored stack (schema parse, then the
+author-time rule registry), loaded through the same `bundle-require` path
+`loadConfig` uses, so the generator and the schema cannot drift apart again
+silently. Both layers are needed: a flow node's `config` is an open slot
+(ADR-0018), so the schema cannot judge the trigger vocabulary at all — the
+`record-*` grammar is held by `validate-flow-trigger-readiness` one layer
+later.
+
+No other generator's output changed. Four of them (`object`, `view`, `action`,
+`app`) are refused for unrelated reasons of their own; the new test records
+them in a shrink-only ledger that fails when one is repaired and its entry is
+left behind.

packages/cli/src/commands/generate.ts

@@ -113,6 +113,29 @@ export default ${toCamelCase(name)}Action;
  flow: {
  description: 'Automation flow',
  defaultDir: 'src/flows',
+ /**
+ * A record-change flow in the shape `FlowSchema` accepts (#14087).
+ *
+ * What this template used to write refused to load: a top-level `trigger:
+ * { type, object, events }` block, nodes carrying `name`/`next`, and no
+ * `edges`. `FlowSchema` is `.strict()` and declares none of that, so the
+ * FIRST flow anybody scaffolded was a file their own `os validate`
+ * rejected — with an error enumerating what is allowed rather than saying
+ * where the trigger had moved to.
+ *
+ * The binding lives on the START node's `config`, which is where
+ * `AutomationEngine.resolveTriggerBinding` reads it from: `objectName`,
+ * one `record-*` `triggerType` token, and an optional bare-CEL
+ * `condition`. `triggerType` is NOT judged by the schema — a node `config`
+ * is an open slot (ADR-0018) — so the token's grammar is held by
+ * `validate-flow-trigger-readiness`, an author-time rule `os validate`
+ * gates on. `generate-scaffold-validates.test.ts` puts this output through
+ * both layers, which is the drift this template is not allowed to repeat.
+ *
+ * `status` stays `'draft'`: the scaffold fixes the SHAPE and leaves the
+ * arming decision to the author (`os validate` says so — draft flows do
+ * fire, so declare `'active'` to arm deliberately).
+ */
  generate: (name: string) => `import * as Automation from '@objectstack/spec/automation';
 
 /**
@@ -121,20 +144,32 @@ export default ${toCamelCase(name)}Action;
 const ${toCamelCase(name)}Flow: Automation.Flow = {
  name: '${toSnakeCase(name)}_flow',
  label: '${toTitleCase(name)} Flow',
- type: 'autolaunched',
+ type: 'record_change',
  status: 'draft',
- trigger: {
- type: 'record_change',
- object: '${toSnakeCase(name)}',
- events: ['after_insert', 'after_update'],
- },
  nodes: [
  {
  id: 'start',
  type: 'start',
- name: 'Start',
- next: 'end',
+ label: 'Start',
+ // A record-change flow binds its trigger HERE, on the START node's
+ // config — there is no top-level \`trigger\` key.
+ // objectName the object whose writes fire this flow
+ // triggerType one record-{before,after}-{create,update,delete,write}
+ // token ('write' is create OR update, in one flow)
+ // condition optional bare-CEL gate, e.g. 'record.amount >= 500'
+ config: {
+ objectName: '${toSnakeCase(name)}',
+ triggerType: 'record-after-write',
+ },
  },
+ {
+ id: 'end',
+ type: 'end',
+ label: 'End',
+ },
+ ],
+ edges: [
+ { id: 'e1', source: 'start', target: 'end', type: 'default' },
  ],
 };
 
@@ -257,15 +292,27 @@ export default ${toCamelCase(name)}Skill;
 };
 
 /**
- * Every metadata type `os generate` can scaffold, with the directory it
- * scaffolds into — derived from `GENERATORS` rather than restated.
+ * Every metadata type `os generate` can scaffold — the directory it scaffolds
+ * into, and the source it writes — derived from `GENERATORS` rather than
+ * restated.
  *
- * Exported for `generate-file-name-registry-parity.test.ts`, and derived on
- * purpose: the pin's job is to hold for the NEXT generator somebody adds, and
- * a hand-kept list would leave that one unmeasured while still reading green.
+ * Exported for `generate-file-name-registry-parity.test.ts` (which reads
+ * `type` / `defaultDir`) and `generate-scaffold-validates.test.ts` (which
+ * reads `generate` to materialize each scaffold and put it through the schema
+ * `os validate` parses it with). Derived on purpose: each pin's job is to hold
+ * for the NEXT generator somebody adds, and a hand-kept list would leave that
+ * one unmeasured while still reading green.
  */
-export const GENERATOR_SCAFFOLD_TARGETS: readonly { type: string; defaultDir: string }[] =
- Object.entries(GENERATORS).map(([type, gen]) => ({ type, defaultDir: gen.defaultDir }));
+export const GENERATOR_SCAFFOLD_TARGETS: readonly {
+ type: string;
+ defaultDir: string;
+ generate: (name: string) => string;
+}[] =
+ Object.entries(GENERATORS).map(([type, gen]) => ({
+ type,
+ defaultDir: gen.defaultDir,
+ generate: gen.generate,
+ }));
 
 // ─── Retired Generators ─────────────────────────────────────────────
 

.changeset/generate-flow-scaffold-validates.md

@@ -0,0 +1,48 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): `os generate flow` scaffolds a flow `os validate` accepts (#14087)
+
+The `flow` scaffold could not survive its own toolchain. Measured on 17.2.0,
+`os g flow my_flow` followed by `os validate` produced four refusals in one
+parse:
+
+```
+flows[0].nodes[0].label expected string, received undefined
+flows[0].nodes[0] unrecognized key(s): `name`, `next`
+flows[0].edges expected array, received undefined
+flows[0] unrecognized key(s): `trigger`
+```
+
+`FlowSchema` is `.strict()` and has never declared a top-level `trigger` on
+protocol 17. A record-change flow binds on the START node's `config` —
+`{ objectName, triggerType, condition }` — which is where
+`AutomationEngine.resolveTriggerBinding` reads it from. The scaffold also wrote
+an `events: ['after_insert', 'after_update']` vocabulary that exists nowhere on
+the current surface, and named a single node it then pointed at a node it never
+emitted.
+
+So the first flow anybody scaffolded was a file their own `os validate`
+rejected — against a `.strict()` error enumerating what is allowed rather than
+saying where the trigger had moved to.
+
+The template now emits the shape the schema accepts and the engine binds:
+`type: 'record_change'`, a labelled START node carrying
+`config: { objectName, triggerType: 'record-after-write' }`, a labelled END
+node, and the `edges` array joining them. `status` stays `'draft'` — the arming
+decision is the author's, and `os validate` says so.
+
+`generate-scaffold-validates.test.ts` puts every generator's output through the
+two steps `os validate` runs on an authored stack (schema parse, then the
+author-time rule registry), loaded through the same `bundle-require` path
+`loadConfig` uses, so the generator and the schema cannot drift apart again
+silently. Both layers are needed: a flow node's `config` is an open slot
+(ADR-0018), so the schema cannot judge the trigger vocabulary at all — the
+`record-*` grammar is held by `validate-flow-trigger-readiness` one layer
+later.
+
+No other generator's output changed. Four of them (`object`, `view`, `action`,
+`app`) are refused for unrelated reasons of their own; the new test records
+them in a shrink-only ledger that fails when one is repaired and its entry is
+left behind.

packages/cli/src/commands/generate.ts

@@ -113,6 +113,29 @@ export default ${toCamelCase(name)}Action;
  flow: {
  description: 'Automation flow',
  defaultDir: 'src/flows',
+ /**
+ * A record-change flow in the shape `FlowSchema` accepts (#14087).
+ *
+ * What this template used to write refused to load: a top-level `trigger:
+ * { type, object, events }` block, nodes carrying `name`/`next`, and no
+ * `edges`. `FlowSchema` is `.strict()` and declares none of that, so the
+ * FIRST flow anybody scaffolded was a file their own `os validate`
+ * rejected — with an error enumerating what is allowed rather than saying
+ * where the trigger had moved to.
+ *
+ * The binding lives on the START node's `config`, which is where
+ * `AutomationEngine.resolveTriggerBinding` reads it from: `objectName`,
+ * one `record-*` `triggerType` token, and an optional bare-CEL
+ * `condition`. `triggerType` is NOT judged by the schema — a node `config`
+ * is an open slot (ADR-0018) — so the token's grammar is held by
+ * `validate-flow-trigger-readiness`, an author-time rule `os validate`
+ * gates on. `generate-scaffold-validates.test.ts` puts this output through
+ * both layers, which is the drift this template is not allowed to repeat.
+ *
+ * `status` stays `'draft'`: the scaffold fixes the SHAPE and leaves the
+ * arming decision to the author (`os validate` says so — draft flows do
+ * fire, so declare `'active'` to arm deliberately).
+ */
  generate: (name: string) => `import * as Automation from '@objectstack/spec/automation';
 
 /**
@@ -121,20 +144,32 @@ export default ${toCamelCase(name)}Action;
 const ${toCamelCase(name)}Flow: Automation.Flow = {
  name: '${toSnakeCase(name)}_flow',
  label: '${toTitleCase(name)} Flow',
- type: 'autolaunched',
+ type: 'record_change',
  status: 'draft',
- trigger: {
- type: 'record_change',
- object: '${toSnakeCase(name)}',
- events: ['after_insert', 'after_update'],
- },
  nodes: [
  {
  id: 'start',
  type: 'start',
- name: 'Start',
- next: 'end',
+ label: 'Start',
+ // A record-change flow binds its trigger HERE, on the START node's
+ // config — there is no top-level \`trigger\` key.
+ // objectName the object whose writes fire this flow
+ // triggerType one record-{before,after}-{create,update,delete,write}
+ // token ('write' is create OR update, in one flow)
+ // condition optional bare-CEL gate, e.g. 'record.amount >= 500'
+ config: {
+ objectName: '${toSnakeCase(name)}',
+ triggerType: 'record-after-write',
+ },
  },
+ {
+ id: 'end',
+ type: 'end',
+ label: 'End',
+ },
+ ],
+ edges: [
+ { id: 'e1', source: 'start', target: 'end', type: 'default' },
  ],
 };
 
@@ -257,15 +292,27 @@ export default ${toCamelCase(name)}Skill;
 };
 
 /**
- * Every metadata type `os generate` can scaffold, with the directory it
- * scaffolds into — derived from `GENERATORS` rather than restated.
+ * Every metadata type `os generate` can scaffold — the directory it scaffolds
+ * into, and the source it writes — derived from `GENERATORS` rather than
+ * restated.
  *
- * Exported for `generate-file-name-registry-parity.test.ts`, and derived on
- * purpose: the pin's job is to hold for the NEXT generator somebody adds, and
- * a hand-kept list would leave that one unmeasured while still reading green.
+ * Exported for `generate-file-name-registry-parity.test.ts` (which reads
+ * `type` / `defaultDir`) and `generate-scaffold-validates.test.ts` (which
+ * reads `generate` to materialize each scaffold and put it through the schema
+ * `os validate` parses it with). Derived on purpose: each pin's job is to hold
+ * for the NEXT generator somebody adds, and a hand-kept list would leave that
+ * one unmeasured while still reading green.
  */
-export const GENERATOR_SCAFFOLD_TARGETS: readonly { type: string; defaultDir: string }[] =
- Object.entries(GENERATORS).map(([type, gen]) => ({ type, defaultDir: gen.defaultDir }));
+export const GENERATOR_SCAFFOLD_TARGETS: readonly {
+ type: string;
+ defaultDir: string;
+ generate: (name: string) => string;
+}[] =
+ Object.entries(GENERATORS).map(([type, gen]) => ({
+ type,
+ defaultDir: gen.defaultDir,
+ generate: gen.generate,
+ }));
 
 // ─── Retired Generators ─────────────────────────────────────────────
 

.changeset/generate-flow-scaffold-validates.md

@@ -0,0 +1,48 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): `os generate flow` scaffolds a flow `os validate` accepts (#14087)
+
+The `flow` scaffold could not survive its own toolchain. Measured on 17.2.0,
+`os g flow my_flow` followed by `os validate` produced four refusals in one
+parse:
+
+```
+flows[0].nodes[0].label expected string, received undefined
+flows[0].nodes[0] unrecognized key(s): `name`, `next`
+flows[0].edges expected array, received undefined
+flows[0] unrecognized key(s): `trigger`
+```
+
+`FlowSchema` is `.strict()` and has never declared a top-level `trigger` on
+protocol 17. A record-change flow binds on the START node's `config` —
+`{ objectName, triggerType, condition }` — which is where
+`AutomationEngine.resolveTriggerBinding` reads it from. The scaffold also wrote
+an `events: ['after_insert', 'after_update']` vocabulary that exists nowhere on
+the current surface, and named a single node it then pointed at a node it never
+emitted.
+
+So the first flow anybody scaffolded was a file their own `os validate`
+rejected — against a `.strict()` error enumerating what is allowed rather than
+saying where the trigger had moved to.
+
+The template now emits the shape the schema accepts and the engine binds:
+`type: 'record_change'`, a labelled START node carrying
+`config: { objectName, triggerType: 'record-after-write' }`, a labelled END
+node, and the `edges` array joining them. `status` stays `'draft'` — the arming
+decision is the author's, and `os validate` says so.
+
+`generate-scaffold-validates.test.ts` puts every generator's output through the
+two steps `os validate` runs on an authored stack (schema parse, then the
+author-time rule registry), loaded through the same `bundle-require` path
+`loadConfig` uses, so the generator and the schema cannot drift apart again
+silently. Both layers are needed: a flow node's `config` is an open slot
+(ADR-0018), so the schema cannot judge the trigger vocabulary at all — the
+`record-*` grammar is held by `validate-flow-trigger-readiness` one layer
+later.
+
+No other generator's output changed. Four of them (`object`, `view`, `action`,
+`app`) are refused for unrelated reasons of their own; the new test records
+them in a shrink-only ledger that fails when one is repaired and its entry is
+left behind.

packages/cli/src/commands/generate.ts

@@ -113,6 +113,29 @@ export default ${toCamelCase(name)}Action;
  flow: {
  description: 'Automation flow',
  defaultDir: 'src/flows',
+ /**
+ * A record-change flow in the shape `FlowSchema` accepts (#14087).
+ *
+ * What this template used to write refused to load: a top-level `trigger:
+ * { type, object, events }` block, nodes carrying `name`/`next`, and no
+ * `edges`. `FlowSchema` is `.strict()` and declares none of that, so the
+ * FIRST flow anybody scaffolded was a file their own `os validate`
+ * rejected — with an error enumerating what is allowed rather than saying
+ * where the trigger had moved to.
+ *
+ * The binding lives on the START node's `config`, which is where
+ * `AutomationEngine.resolveTriggerBinding` reads it from: `objectName`,
+ * one `record-*` `triggerType` token, and an optional bare-CEL
+ * `condition`. `triggerType` is NOT judged by the schema — a node `config`
+ * is an open slot (ADR-0018) — so the token's grammar is held by
+ * `validate-flow-trigger-readiness`, an author-time rule `os validate`
+ * gates on. `generate-scaffold-validates.test.ts` puts this output through
+ * both layers, which is the drift this template is not allowed to repeat.
+ *
+ * `status` stays `'draft'`: the scaffold fixes the SHAPE and leaves the
+ * arming decision to the author (`os validate` says so — draft flows do
+ * fire, so declare `'active'` to arm deliberately).
+ */
  generate: (name: string) => `import * as Automation from '@objectstack/spec/automation';
 
 /**
@@ -121,20 +144,32 @@ export default ${toCamelCase(name)}Action;
 const ${toCamelCase(name)}Flow: Automation.Flow = {
  name: '${toSnakeCase(name)}_flow',
  label: '${toTitleCase(name)} Flow',
- type: 'autolaunched',
+ type: 'record_change',
  status: 'draft',
- trigger: {
- type: 'record_change',
- object: '${toSnakeCase(name)}',
- events: ['after_insert', 'after_update'],
- },
  nodes: [
  {
  id: 'start',
  type: 'start',
- name: 'Start',
- next: 'end',
+ label: 'Start',
+ // A record-change flow binds its trigger HERE, on the START node's
+ // config — there is no top-level \`trigger\` key.
+ // objectName the object whose writes fire this flow
+ // triggerType one record-{before,after}-{create,update,delete,write}
+ // token ('write' is create OR update, in one flow)
+ // condition optional bare-CEL gate, e.g. 'record.amount >= 500'
+ config: {
+ objectName: '${toSnakeCase(name)}',
+ triggerType: 'record-after-write',
+ },
  },
+ {
+ id: 'end',
+ type: 'end',
+ label: 'End',
+ },
+ ],
+ edges: [
+ { id: 'e1', source: 'start', target: 'end', type: 'default' },
  ],
 };
 
@@ -257,15 +292,27 @@ export default ${toCamelCase(name)}Skill;
 };
 
 /**
- * Every metadata type `os generate` can scaffold, with the directory it
- * scaffolds into — derived from `GENERATORS` rather than restated.
+ * Every metadata type `os generate` can scaffold — the directory it scaffolds
+ * into, and the source it writes — derived from `GENERATORS` rather than
+ * restated.
  *
- * Exported for `generate-file-name-registry-parity.test.ts`, and derived on
- * purpose: the pin's job is to hold for the NEXT generator somebody adds, and
- * a hand-kept list would leave that one unmeasured while still reading green.
+ * Exported for `generate-file-name-registry-parity.test.ts` (which reads
+ * `type` / `defaultDir`) and `generate-scaffold-validates.test.ts` (which
+ * reads `generate` to materialize each scaffold and put it through the schema
+ * `os validate` parses it with). Derived on purpose: each pin's job is to hold
+ * for the NEXT generator somebody adds, and a hand-kept list would leave that
+ * one unmeasured while still reading green.
  */
-export const GENERATOR_SCAFFOLD_TARGETS: readonly { type: string; defaultDir: string }[] =
- Object.entries(GENERATORS).map(([type, gen]) => ({ type, defaultDir: gen.defaultDir }));
+export const GENERATOR_SCAFFOLD_TARGETS: readonly {
+ type: string;
+ defaultDir: string;
+ generate: (name: string) => string;
+}[] =
+ Object.entries(GENERATORS).map(([type, gen]) => ({
+ type,
+ defaultDir: gen.defaultDir,
+ generate: gen.generate,
+ }));
 
 // ─── Retired Generators ─────────────────────────────────────────────
 

.changeset/generate-flow-scaffold-validates.md

@@ -0,0 +1,48 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): `os generate flow` scaffolds a flow `os validate` accepts (#14087)
+
+The `flow` scaffold could not survive its own toolchain. Measured on 17.2.0,
+`os g flow my_flow` followed by `os validate` produced four refusals in one
+parse:
+
+```
+flows[0].nodes[0].label expected string, received undefined
+flows[0].nodes[0] unrecognized key(s): `name`, `next`
+flows[0].edges expected array, received undefined
+flows[0] unrecognized key(s): `trigger`
+```
+
+`FlowSchema` is `.strict()` and has never declared a top-level `trigger` on
+protocol 17. A record-change flow binds on the START node's `config` —
+`{ objectName, triggerType, condition }` — which is where
+`AutomationEngine.resolveTriggerBinding` reads it from. The scaffold also wrote
+an `events: ['after_insert', 'after_update']` vocabulary that exists nowhere on
+the current surface, and named a single node it then pointed at a node it never
+emitted.
+
+So the first flow anybody scaffolded was a file their own `os validate`
+rejected — against a `.strict()` error enumerating what is allowed rather than
+saying where the trigger had moved to.
+
+The template now emits the shape the schema accepts and the engine binds:
+`type: 'record_change'`, a labelled START node carrying
+`config: { objectName, triggerType: 'record-after-write' }`, a labelled END
+node, and the `edges` array joining them. `status` stays `'draft'` — the arming
+decision is the author's, and `os validate` says so.
+
+`generate-scaffold-validates.test.ts` puts every generator's output through the
+two steps `os validate` runs on an authored stack (schema parse, then the
+author-time rule registry), loaded through the same `bundle-require` path
+`loadConfig` uses, so the generator and the schema cannot drift apart again
+silently. Both layers are needed: a flow node's `config` is an open slot
+(ADR-0018), so the schema cannot judge the trigger vocabulary at all — the
+`record-*` grammar is held by `validate-flow-trigger-readiness` one layer
+later.
+
+No other generator's output changed. Four of them (`object`, `view`, `action`,
+`app`) are refused for unrelated reasons of their own; the new test records
+them in a shrink-only ledger that fails when one is repaired and its entry is
+left behind.

packages/cli/src/commands/generate.ts

@@ -113,6 +113,29 @@ export default ${toCamelCase(name)}Action;
  flow: {
  description: 'Automation flow',
  defaultDir: 'src/flows',
+ /**
+ * A record-change flow in the shape `FlowSchema` accepts (#14087).
+ *
+ * What this template used to write refused to load: a top-level `trigger:
+ * { type, object, events }` block, nodes carrying `name`/`next`, and no
+ * `edges`. `FlowSchema` is `.strict()` and declares none of that, so the
+ * FIRST flow anybody scaffolded was a file their own `os validate`
+ * rejected — with an error enumerating what is allowed rather than saying
+ * where the trigger had moved to.
+ *
+ * The binding lives on the START node's `config`, which is where
+ * `AutomationEngine.resolveTriggerBinding` reads it from: `objectName`,
+ * one `record-*` `triggerType` token, and an optional bare-CEL
+ * `condition`. `triggerType` is NOT judged by the schema — a node `config`
+ * is an open slot (ADR-0018) — so the token's grammar is held by
+ * `validate-flow-trigger-readiness`, an author-time rule `os validate`
+ * gates on. `generate-scaffold-validates.test.ts` puts this output through
+ * both layers, which is the drift this template is not allowed to repeat.
+ *
+ * `status` stays `'draft'`: the scaffold fixes the SHAPE and leaves the
+ * arming decision to the author (`os validate` says so — draft flows do
+ * fire, so declare `'active'` to arm deliberately).
+ */
  generate: (name: string) => `import * as Automation from '@objectstack/spec/automation';
 
 /**
@@ -121,20 +144,32 @@ export default ${toCamelCase(name)}Action;
 const ${toCamelCase(name)}Flow: Automation.Flow = {
  name: '${toSnakeCase(name)}_flow',
  label: '${toTitleCase(name)} Flow',
- type: 'autolaunched',
+ type: 'record_change',
  status: 'draft',
- trigger: {
- type: 'record_change',
- object: '${toSnakeCase(name)}',
- events: ['after_insert', 'after_update'],
- },
  nodes: [
  {
  id: 'start',
  type: 'start',
- name: 'Start',
- next: 'end',
+ label: 'Start',
+ // A record-change flow binds its trigger HERE, on the START node's
+ // config — there is no top-level \`trigger\` key.
+ // objectName the object whose writes fire this flow
+ // triggerType one record-{before,after}-{create,update,delete,write}
+ // token ('write' is create OR update, in one flow)
+ // condition optional bare-CEL gate, e.g. 'record.amount >= 500'
+ config: {
+ objectName: '${toSnakeCase(name)}',
+ triggerType: 'record-after-write',
+ },
  },
+ {
+ id: 'end',
+ type: 'end',
+ label: 'End',
+ },
+ ],
+ edges: [
+ { id: 'e1', source: 'start', target: 'end', type: 'default' },
  ],
 };
 
@@ -257,15 +292,27 @@ export default ${toCamelCase(name)}Skill;
 };
 
 /**
- * Every metadata type `os generate` can scaffold, with the directory it
- * scaffolds into — derived from `GENERATORS` rather than restated.
+ * Every metadata type `os generate` can scaffold — the directory it scaffolds
+ * into, and the source it writes — derived from `GENERATORS` rather than
+ * restated.
  *
- * Exported for `generate-file-name-registry-parity.test.ts`, and derived on
- * purpose: the pin's job is to hold for the NEXT generator somebody adds, and
- * a hand-kept list would leave that one unmeasured while still reading green.
+ * Exported for `generate-file-name-registry-parity.test.ts` (which reads
+ * `type` / `defaultDir`) and `generate-scaffold-validates.test.ts` (which
+ * reads `generate` to materialize each scaffold and put it through the schema
+ * `os validate` parses it with). Derived on purpose: each pin's job is to hold
+ * for the NEXT generator somebody adds, and a hand-kept list would leave that
+ * one unmeasured while still reading green.
  */
-export const GENERATOR_SCAFFOLD_TARGETS: readonly { type: string; defaultDir: string }[] =
- Object.entries(GENERATORS).map(([type, gen]) => ({ type, defaultDir: gen.defaultDir }));
+export const GENERATOR_SCAFFOLD_TARGETS: readonly {
+ type: string;
+ defaultDir: string;
+ generate: (name: string) => string;
+}[] =
+ Object.entries(GENERATORS).map(([type, gen]) => ({
+ type,
+ defaultDir: gen.defaultDir,
+ generate: gen.generate,
+ }));
 
 // ─── Retired Generators ─────────────────────────────────────────────
 

.changeset/generate-flow-scaffold-validates.md

@@ -0,0 +1,48 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): `os generate flow` scaffolds a flow `os validate` accepts (#14087)
+
+The `flow` scaffold could not survive its own toolchain. Measured on 17.2.0,
+`os g flow my_flow` followed by `os validate` produced four refusals in one
+parse:
+
+```
+flows[0].nodes[0].label expected string, received undefined
+flows[0].nodes[0] unrecognized key(s): `name`, `next`
+flows[0].edges expected array, received undefined
+flows[0] unrecognized key(s): `trigger`
+```
+
+`FlowSchema` is `.strict()` and has never declared a top-level `trigger` on
+protocol 17. A record-change flow binds on the START node's `config` —
+`{ objectName, triggerType, condition }` — which is where
+`AutomationEngine.resolveTriggerBinding` reads it from. The scaffold also wrote
+an `events: ['after_insert', 'after_update']` vocabulary that exists nowhere on
+the current surface, and named a single node it then pointed at a node it never
+emitted.
+
+So the first flow anybody scaffolded was a file their own `os validate`
+rejected — against a `.strict()` error enumerating what is allowed rather than
+saying where the trigger had moved to.
+
+The template now emits the shape the schema accepts and the engine binds:
+`type: 'record_change'`, a labelled START node carrying
+`config: { objectName, triggerType: 'record-after-write' }`, a labelled END
+node, and the `edges` array joining them. `status` stays `'draft'` — the arming
+decision is the author's, and `os validate` says so.
+
+`generate-scaffold-validates.test.ts` puts every generator's output through the
+two steps `os validate` runs on an authored stack (schema parse, then the
+author-time rule registry), loaded through the same `bundle-require` path
+`loadConfig` uses, so the generator and the schema cannot drift apart again
+silently. Both layers are needed: a flow node's `config` is an open slot
+(ADR-0018), so the schema cannot judge the trigger vocabulary at all — the
+`record-*` grammar is held by `validate-flow-trigger-readiness` one layer
+later.
+
+No other generator's output changed. Four of them (`object`, `view`, `action`,
+`app`) are refused for unrelated reasons of their own; the new test records
+them in a shrink-only ledger that fails when one is repaired and its entry is
+left behind.

packages/cli/src/commands/generate.ts

@@ -113,6 +113,29 @@ export default ${toCamelCase(name)}Action;
  flow: {
  description: 'Automation flow',
  defaultDir: 'src/flows',
+ /**
+ * A record-change flow in the shape `FlowSchema` accepts (#14087).
+ *
+ * What this template used to write refused to load: a top-level `trigger:
+ * { type, object, events }` block, nodes carrying `name`/`next`, and no
+ * `edges`. `FlowSchema` is `.strict()` and declares none of that, so the
+ * FIRST flow anybody scaffolded was a file their own `os validate`
+ * rejected — with an error enumerating what is allowed rather than saying
+ * where the trigger had moved to.
+ *
+ * The binding lives on the START node's `config`, which is where
+ * `AutomationEngine.resolveTriggerBinding` reads it from: `objectName`,
+ * one `record-*` `triggerType` token, and an optional bare-CEL
+ * `condition`. `triggerType` is NOT judged by the schema — a node `config`
+ * is an open slot (ADR-0018) — so the token's grammar is held by
+ * `validate-flow-trigger-readiness`, an author-time rule `os validate`
+ * gates on. `generate-scaffold-validates.test.ts` puts this output through
+ * both layers, which is the drift this template is not allowed to repeat.
+ *
+ * `status` stays `'draft'`: the scaffold fixes the SHAPE and leaves the
+ * arming decision to the author (`os validate` says so — draft flows do
+ * fire, so declare `'active'` to arm deliberately).
+ */
  generate: (name: string) => `import * as Automation from '@objectstack/spec/automation';
 
 /**
@@ -121,20 +144,32 @@ export default ${toCamelCase(name)}Action;
 const ${toCamelCase(name)}Flow: Automation.Flow = {
  name: '${toSnakeCase(name)}_flow',
  label: '${toTitleCase(name)} Flow',
- type: 'autolaunched',
+ type: 'record_change',
  status: 'draft',
- trigger: {
- type: 'record_change',
- object: '${toSnakeCase(name)}',
- events: ['after_insert', 'after_update'],
- },
  nodes: [
  {
  id: 'start',
  type: 'start',
- name: 'Start',
- next: 'end',
+ label: 'Start',
+ // A record-change flow binds its trigger HERE, on the START node's
+ // config — there is no top-level \`trigger\` key.
+ // objectName the object whose writes fire this flow
+ // triggerType one record-{before,after}-{create,update,delete,write}
+ // token ('write' is create OR update, in one flow)
+ // condition optional bare-CEL gate, e.g. 'record.amount >= 500'
+ config: {
+ objectName: '${toSnakeCase(name)}',
+ triggerType: 'record-after-write',
+ },
  },
+ {
+ id: 'end',
+ type: 'end',
+ label: 'End',
+ },
+ ],
+ edges: [
+ { id: 'e1', source: 'start', target: 'end', type: 'default' },
  ],
 };
 
@@ -257,15 +292,27 @@ export default ${toCamelCase(name)}Skill;
 };
 
 /**
- * Every metadata type `os generate` can scaffold, with the directory it
- * scaffolds into — derived from `GENERATORS` rather than restated.
+ * Every metadata type `os generate` can scaffold — the directory it scaffolds
+ * into, and the source it writes — derived from `GENERATORS` rather than
+ * restated.
  *
- * Exported for `generate-file-name-registry-parity.test.ts`, and derived on
- * purpose: the pin's job is to hold for the NEXT generator somebody adds, and
- * a hand-kept list would leave that one unmeasured while still reading green.
+ * Exported for `generate-file-name-registry-parity.test.ts` (which reads
+ * `type` / `defaultDir`) and `generate-scaffold-validates.test.ts` (which
+ * reads `generate` to materialize each scaffold and put it through the schema
+ * `os validate` parses it with). Derived on purpose: each pin's job is to hold
+ * for the NEXT generator somebody adds, and a hand-kept list would leave that
+ * one unmeasured while still reading green.
  */
-export const GENERATOR_SCAFFOLD_TARGETS: readonly { type: string; defaultDir: string }[] =
- Object.entries(GENERATORS).map(([type, gen]) => ({ type, defaultDir: gen.defaultDir }));
+export const GENERATOR_SCAFFOLD_TARGETS: readonly {
+ type: string;
+ defaultDir: string;
+ generate: (name: string) => string;
+}[] =
+ Object.entries(GENERATORS).map(([type, gen]) => ({
+ type,
+ defaultDir: gen.defaultDir,
+ generate: gen.generate,
+ }));
 
 // ─── Retired Generators ─────────────────────────────────────────────
 

.changeset/generate-flow-scaffold-validates.md

@@ -0,0 +1,48 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): `os generate flow` scaffolds a flow `os validate` accepts (#14087)
+
+The `flow` scaffold could not survive its own toolchain. Measured on 17.2.0,
+`os g flow my_flow` followed by `os validate` produced four refusals in one
+parse:
+
+```
+flows[0].nodes[0].label expected string, received undefined
+flows[0].nodes[0] unrecognized key(s): `name`, `next`
+flows[0].edges expected array, received undefined
+flows[0] unrecognized key(s): `trigger`
+```
+
+`FlowSchema` is `.strict()` and has never declared a top-level `trigger` on
+protocol 17. A record-change flow binds on the START node's `config` —
+`{ objectName, triggerType, condition }` — which is where
+`AutomationEngine.resolveTriggerBinding` reads it from. The scaffold also wrote
+an `events: ['after_insert', 'after_update']` vocabulary that exists nowhere on
+the current surface, and named a single node it then pointed at a node it never
+emitted.
+
+So the first flow anybody scaffolded was a file their own `os validate`
+rejected — against a `.strict()` error enumerating what is allowed rather than
+saying where the trigger had moved to.
+
+The template now emits the shape the schema accepts and the engine binds:
+`type: 'record_change'`, a labelled START node carrying
+`config: { objectName, triggerType: 'record-after-write' }`, a labelled END
+node, and the `edges` array joining them. `status` stays `'draft'` — the arming
+decision is the author's, and `os validate` says so.
+
+`generate-scaffold-validates.test.ts` puts every generator's output through the
+two steps `os validate` runs on an authored stack (schema parse, then the
+author-time rule registry), loaded through the same `bundle-require` path
+`loadConfig` uses, so the generator and the schema cannot drift apart again
+silently. Both layers are needed: a flow node's `config` is an open slot
+(ADR-0018), so the schema cannot judge the trigger vocabulary at all — the
+`record-*` grammar is held by `validate-flow-trigger-readiness` one layer
+later.
+
+No other generator's output changed. Four of them (`object`, `view`, `action`,
+`app`) are refused for unrelated reasons of their own; the new test records
+them in a shrink-only ledger that fails when one is repaired and its entry is
+left behind.

packages/cli/src/commands/generate.ts

@@ -113,6 +113,29 @@ export default ${toCamelCase(name)}Action;
  flow: {
  description: 'Automation flow',
  defaultDir: 'src/flows',
+ /**
+ * A record-change flow in the shape `FlowSchema` accepts (#14087).
+ *
+ * What this template used to write refused to load: a top-level `trigger:
+ * { type, object, events }` block, nodes carrying `name`/`next`, and no
+ * `edges`. `FlowSchema` is `.strict()` and declares none of that, so the
+ * FIRST flow anybody scaffolded was a file their own `os validate`
+ * rejected — with an error enumerating what is allowed rather than saying
+ * where the trigger had moved to.
+ *
+ * The binding lives on the START node's `config`, which is where
+ * `AutomationEngine.resolveTriggerBinding` reads it from: `objectName`,
+ * one `record-*` `triggerType` token, and an optional bare-CEL
+ * `condition`. `triggerType` is NOT judged by the schema — a node `config`
+ * is an open slot (ADR-0018) — so the token's grammar is held by
+ * `validate-flow-trigger-readiness`, an author-time rule `os validate`
+ * gates on. `generate-scaffold-validates.test.ts` puts this output through
+ * both layers, which is the drift this template is not allowed to repeat.
+ *
+ * `status` stays `'draft'`: the scaffold fixes the SHAPE and leaves the
+ * arming decision to the author (`os validate` says so — draft flows do
+ * fire, so declare `'active'` to arm deliberately).
+ */
  generate: (name: string) => `import * as Automation from '@objectstack/spec/automation';
 
 /**
@@ -121,20 +144,32 @@ export default ${toCamelCase(name)}Action;
 const ${toCamelCase(name)}Flow: Automation.Flow = {
  name: '${toSnakeCase(name)}_flow',
  label: '${toTitleCase(name)} Flow',
- type: 'autolaunched',
+ type: 'record_change',
  status: 'draft',
- trigger: {
- type: 'record_change',
- object: '${toSnakeCase(name)}',
- events: ['after_insert', 'after_update'],
- },
  nodes: [
  {
  id: 'start',
  type: 'start',
- name: 'Start',
- next: 'end',
+ label: 'Start',
+ // A record-change flow binds its trigger HERE, on the START node's
+ // config — there is no top-level \`trigger\` key.
+ // objectName the object whose writes fire this flow
+ // triggerType one record-{before,after}-{create,update,delete,write}
+ // token ('write' is create OR update, in one flow)
+ // condition optional bare-CEL gate, e.g. 'record.amount >= 500'
+ config: {
+ objectName: '${toSnakeCase(name)}',
+ triggerType: 'record-after-write',
+ },
  },
+ {
+ id: 'end',
+ type: 'end',
+ label: 'End',
+ },
+ ],
+ edges: [
+ { id: 'e1', source: 'start', target: 'end', type: 'default' },
  ],
 };
 
@@ -257,15 +292,27 @@ export default ${toCamelCase(name)}Skill;
 };
 
 /**
- * Every metadata type `os generate` can scaffold, with the directory it
- * scaffolds into — derived from `GENERATORS` rather than restated.
+ * Every metadata type `os generate` can scaffold — the directory it scaffolds
+ * into, and the source it writes — derived from `GENERATORS` rather than
+ * restated.
  *
- * Exported for `generate-file-name-registry-parity.test.ts`, and derived on
- * purpose: the pin's job is to hold for the NEXT generator somebody adds, and
- * a hand-kept list would leave that one unmeasured while still reading green.
+ * Exported for `generate-file-name-registry-parity.test.ts` (which reads
+ * `type` / `defaultDir`) and `generate-scaffold-validates.test.ts` (which
+ * reads `generate` to materialize each scaffold and put it through the schema
+ * `os validate` parses it with). Derived on purpose: each pin's job is to hold
+ * for the NEXT generator somebody adds, and a hand-kept list would leave that
+ * one unmeasured while still reading green.
  */
-export const GENERATOR_SCAFFOLD_TARGETS: readonly { type: string; defaultDir: string }[] =
- Object.entries(GENERATORS).map(([type, gen]) => ({ type, defaultDir: gen.defaultDir }));
+export const GENERATOR_SCAFFOLD_TARGETS: readonly {
+ type: string;
+ defaultDir: string;
+ generate: (name: string) => string;
+}[] =
+ Object.entries(GENERATORS).map(([type, gen]) => ({
+ type,
+ defaultDir: gen.defaultDir,
+ generate: gen.generate,
+ }));
 
 // ─── Retired Generators ─────────────────────────────────────────────
 

.changeset/generate-flow-scaffold-validates.md

@@ -0,0 +1,48 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): `os generate flow` scaffolds a flow `os validate` accepts (#14087)
+
+The `flow` scaffold could not survive its own toolchain. Measured on 17.2.0,
+`os g flow my_flow` followed by `os validate` produced four refusals in one
+parse:
+
+```
+flows[0].nodes[0].label expected string, received undefined
+flows[0].nodes[0] unrecognized key(s): `name`, `next`
+flows[0].edges expected array, received undefined
+flows[0] unrecognized key(s): `trigger`
+```
+
+`FlowSchema` is `.strict()` and has never declared a top-level `trigger` on
+protocol 17. A record-change flow binds on the START node's `config` —
+`{ objectName, triggerType, condition }` — which is where
+`AutomationEngine.resolveTriggerBinding` reads it from. The scaffold also wrote
+an `events: ['after_insert', 'after_update']` vocabulary that exists nowhere on
+the current surface, and named a single node it then pointed at a node it never
+emitted.
+
+So the first flow anybody scaffolded was a file their own `os validate`
+rejected — against a `.strict()` error enumerating what is allowed rather than
+saying where the trigger had moved to.
+
+The template now emits the shape the schema accepts and the engine binds:
+`type: 'record_change'`, a labelled START node carrying
+`config: { objectName, triggerType: 'record-after-write' }`, a labelled END
+node, and the `edges` array joining them. `status` stays `'draft'` — the arming
+decision is the author's, and `os validate` says so.
+
+`generate-scaffold-validates.test.ts` puts every generator's output through the
+two steps `os validate` runs on an authored stack (schema parse, then the
+author-time rule registry), loaded through the same `bundle-require` path
+`loadConfig` uses, so the generator and the schema cannot drift apart again
+silently. Both layers are needed: a flow node's `config` is an open slot
+(ADR-0018), so the schema cannot judge the trigger vocabulary at all — the
+`record-*` grammar is held by `validate-flow-trigger-readiness` one layer
+later.
+
+No other generator's output changed. Four of them (`object`, `view`, `action`,
+`app`) are refused for unrelated reasons of their own; the new test records
+them in a shrink-only ledger that fails when one is repaired and its entry is
+left behind.

packages/cli/src/commands/generate.ts

@@ -113,6 +113,29 @@ export default ${toCamelCase(name)}Action;
  flow: {
  description: 'Automation flow',
  defaultDir: 'src/flows',
+ /**
+ * A record-change flow in the shape `FlowSchema` accepts (#14087).
+ *
+ * What this template used to write refused to load: a top-level `trigger:
+ * { type, object, events }` block, nodes carrying `name`/`next`, and no
+ * `edges`. `FlowSchema` is `.strict()` and declares none of that, so the
+ * FIRST flow anybody scaffolded was a file their own `os validate`
+ * rejected — with an error enumerating what is allowed rather than saying
+ * where the trigger had moved to.
+ *
+ * The binding lives on the START node's `config`, which is where
+ * `AutomationEngine.resolveTriggerBinding` reads it from: `objectName`,
+ * one `record-*` `triggerType` token, and an optional bare-CEL
+ * `condition`. `triggerType` is NOT judged by the schema — a node `config`
+ * is an open slot (ADR-0018) — so the token's grammar is held by
+ * `validate-flow-trigger-readiness`, an author-time rule `os validate`
+ * gates on. `generate-scaffold-validates.test.ts` puts this output through
+ * both layers, which is the drift this template is not allowed to repeat.
+ *
+ * `status` stays `'draft'`: the scaffold fixes the SHAPE and leaves the
+ * arming decision to the author (`os validate` says so — draft flows do
+ * fire, so declare `'active'` to arm deliberately).
+ */
  generate: (name: string) => `import * as Automation from '@objectstack/spec/automation';
 
 /**
@@ -121,20 +144,32 @@ export default ${toCamelCase(name)}Action;
 const ${toCamelCase(name)}Flow: Automation.Flow = {
  name: '${toSnakeCase(name)}_flow',
  label: '${toTitleCase(name)} Flow',
- type: 'autolaunched',
+ type: 'record_change',
  status: 'draft',
- trigger: {
- type: 'record_change',
- object: '${toSnakeCase(name)}',
- events: ['after_insert', 'after_update'],
- },
  nodes: [
  {
  id: 'start',
  type: 'start',
- name: 'Start',
- next: 'end',
+ label: 'Start',
+ // A record-change flow binds its trigger HERE, on the START node's
+ // config — there is no top-level \`trigger\` key.
+ // objectName the object whose writes fire this flow
+ // triggerType one record-{before,after}-{create,update,delete,write}
+ // token ('write' is create OR update, in one flow)
+ // condition optional bare-CEL gate, e.g. 'record.amount >= 500'
+ config: {
+ objectName: '${toSnakeCase(name)}',
+ triggerType: 'record-after-write',
+ },
  },
+ {
+ id: 'end',
+ type: 'end',
+ label: 'End',
+ },
+ ],
+ edges: [
+ { id: 'e1', source: 'start', target: 'end', type: 'default' },
  ],
 };
 
@@ -257,15 +292,27 @@ export default ${toCamelCase(name)}Skill;
 };
 
 /**
- * Every metadata type `os generate` can scaffold, with the directory it
- * scaffolds into — derived from `GENERATORS` rather than restated.
+ * Every metadata type `os generate` can scaffold — the directory it scaffolds
+ * into, and the source it writes — derived from `GENERATORS` rather than
+ * restated.
  *
- * Exported for `generate-file-name-registry-parity.test.ts`, and derived on
- * purpose: the pin's job is to hold for the NEXT generator somebody adds, and
- * a hand-kept list would leave that one unmeasured while still reading green.
+ * Exported for `generate-file-name-registry-parity.test.ts` (which reads
+ * `type` / `defaultDir`) and `generate-scaffold-validates.test.ts` (which
+ * reads `generate` to materialize each scaffold and put it through the schema
+ * `os validate` parses it with). Derived on purpose: each pin's job is to hold
+ * for the NEXT generator somebody adds, and a hand-kept list would leave that
+ * one unmeasured while still reading green.
  */
-export const GENERATOR_SCAFFOLD_TARGETS: readonly { type: string; defaultDir: string }[] =
- Object.entries(GENERATORS).map(([type, gen]) => ({ type, defaultDir: gen.defaultDir }));
+export const GENERATOR_SCAFFOLD_TARGETS: readonly {
+ type: string;
+ defaultDir: string;
+ generate: (name: string) => string;
+}[] =
+ Object.entries(GENERATORS).map(([type, gen]) => ({
+ type,
+ defaultDir: gen.defaultDir,
+ generate: gen.generate,
+ }));
 
 // ─── Retired Generators ─────────────────────────────────────────────
 

.changeset/generate-flow-scaffold-validates.md

@@ -0,0 +1,48 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): `os generate flow` scaffolds a flow `os validate` accepts (#14087)
+
+The `flow` scaffold could not survive its own toolchain. Measured on 17.2.0,
+`os g flow my_flow` followed by `os validate` produced four refusals in one
+parse:
+
+```
+flows[0].nodes[0].label expected string, received undefined
+flows[0].nodes[0] unrecognized key(s): `name`, `next`
+flows[0].edges expected array, received undefined
+flows[0] unrecognized key(s): `trigger`
+```
+
+`FlowSchema` is `.strict()` and has never declared a top-level `trigger` on
+protocol 17. A record-change flow binds on the START node's `config` —
+`{ objectName, triggerType, condition }` — which is where
+`AutomationEngine.resolveTriggerBinding` reads it from. The scaffold also wrote
+an `events: ['after_insert', 'after_update']` vocabulary that exists nowhere on
+the current surface, and named a single node it then pointed at a node it never
+emitted.
+
+So the first flow anybody scaffolded was a file their own `os validate`
+rejected — against a `.strict()` error enumerating what is allowed rather than
+saying where the trigger had moved to.
+
+The template now emits the shape the schema accepts and the engine binds:
+`type: 'record_change'`, a labelled START node carrying
+`config: { objectName, triggerType: 'record-after-write' }`, a labelled END
+node, and the `edges` array joining them. `status` stays `'draft'` — the arming
+decision is the author's, and `os validate` says so.
+
+`generate-scaffold-validates.test.ts` puts every generator's output through the
+two steps `os validate` runs on an authored stack (schema parse, then the
+author-time rule registry), loaded through the same `bundle-require` path
+`loadConfig` uses, so the generator and the schema cannot drift apart again
+silently. Both layers are needed: a flow node's `config` is an open slot
+(ADR-0018), so the schema cannot judge the trigger vocabulary at all — the
+`record-*` grammar is held by `validate-flow-trigger-readiness` one layer
+later.
+
+No other generator's output changed. Four of them (`object`, `view`, `action`,
+`app`) are refused for unrelated reasons of their own; the new test records
+them in a shrink-only ledger that fails when one is repaired and its entry is
+left behind.

packages/cli/src/commands/generate.ts

@@ -113,6 +113,29 @@ export default ${toCamelCase(name)}Action;
  flow: {
  description: 'Automation flow',
  defaultDir: 'src/flows',
+ /**
+ * A record-change flow in the shape `FlowSchema` accepts (#14087).
+ *
+ * What this template used to write refused to load: a top-level `trigger:
+ * { type, object, events }` block, nodes carrying `name`/`next`, and no
+ * `edges`. `FlowSchema` is `.strict()` and declares none of that, so the
+ * FIRST flow anybody scaffolded was a file their own `os validate`
+ * rejected — with an error enumerating what is allowed rather than saying
+ * where the trigger had moved to.
+ *
+ * The binding lives on the START node's `config`, which is where
+ * `AutomationEngine.resolveTriggerBinding` reads it from: `objectName`,
+ * one `record-*` `triggerType` token, and an optional bare-CEL
+ * `condition`. `triggerType` is NOT judged by the schema — a node `config`
+ * is an open slot (ADR-0018) — so the token's grammar is held by
+ * `validate-flow-trigger-readiness`, an author-time rule `os validate`
+ * gates on. `generate-scaffold-validates.test.ts` puts this output through
+ * both layers, which is the drift this template is not allowed to repeat.
+ *
+ * `status` stays `'draft'`: the scaffold fixes the SHAPE and leaves the
+ * arming decision to the author (`os validate` says so — draft flows do
+ * fire, so declare `'active'` to arm deliberately).
+ */
  generate: (name: string) => `import * as Automation from '@objectstack/spec/automation';
 
 /**
@@ -121,20 +144,32 @@ export default ${toCamelCase(name)}Action;
 const ${toCamelCase(name)}Flow: Automation.Flow = {
  name: '${toSnakeCase(name)}_flow',
  label: '${toTitleCase(name)} Flow',
- type: 'autolaunched',
+ type: 'record_change',
  status: 'draft',
- trigger: {
- type: 'record_change',
- object: '${toSnakeCase(name)}',
- events: ['after_insert', 'after_update'],
- },
  nodes: [
  {
  id: 'start',
  type: 'start',
- name: 'Start',
- next: 'end',
+ label: 'Start',
+ // A record-change flow binds its trigger HERE, on the START node's
+ // config — there is no top-level \`trigger\` key.
+ // objectName the object whose writes fire this flow
+ // triggerType one record-{before,after}-{create,update,delete,write}
+ // token ('write' is create OR update, in one flow)
+ // condition optional bare-CEL gate, e.g. 'record.amount >= 500'
+ config: {
+ objectName: '${toSnakeCase(name)}',
+ triggerType: 'record-after-write',
+ },
  },
+ {
+ id: 'end',
+ type: 'end',
+ label: 'End',
+ },
+ ],
+ edges: [
+ { id: 'e1', source: 'start', target: 'end', type: 'default' },
  ],
 };
 
@@ -257,15 +292,27 @@ export default ${toCamelCase(name)}Skill;
 };
 
 /**
- * Every metadata type `os generate` can scaffold, with the directory it
- * scaffolds into — derived from `GENERATORS` rather than restated.
+ * Every metadata type `os generate` can scaffold — the directory it scaffolds
+ * into, and the source it writes — derived from `GENERATORS` rather than
+ * restated.
  *
- * Exported for `generate-file-name-registry-parity.test.ts`, and derived on
- * purpose: the pin's job is to hold for the NEXT generator somebody adds, and
- * a hand-kept list would leave that one unmeasured while still reading green.
+ * Exported for `generate-file-name-registry-parity.test.ts` (which reads
+ * `type` / `defaultDir`) and `generate-scaffold-validates.test.ts` (which
+ * reads `generate` to materialize each scaffold and put it through the schema
+ * `os validate` parses it with). Derived on purpose: each pin's job is to hold
+ * for the NEXT generator somebody adds, and a hand-kept list would leave that
+ * one unmeasured while still reading green.
  */
-export const GENERATOR_SCAFFOLD_TARGETS: readonly { type: string; defaultDir: string }[] =
- Object.entries(GENERATORS).map(([type, gen]) => ({ type, defaultDir: gen.defaultDir }));
+export const GENERATOR_SCAFFOLD_TARGETS: readonly {
+ type: string;
+ defaultDir: string;
+ generate: (name: string) => string;
+}[] =
+ Object.entries(GENERATORS).map(([type, gen]) => ({
+ type,
+ defaultDir: gen.defaultDir,
+ generate: gen.generate,
+ }));
 
 // ─── Retired Generators ─────────────────────────────────────────────