feat(automation,migrate): os migrate meta --stored covers flow rows (#4454) (#4492)

* feat(automation,metadata-protocol): one flow canonicalization policy, reusable off the load seam (#4454)

`os migrate meta --stored` (#4327) covers every metadata type except `flow`,
because flow-node conversions carry ADR-0078's open-namespace conflict guard
and that needs the automation engine's live executor registry. This is the
half both possible hosts need.

`AutomationEngine.canonicalizeStoredFlow` is now the single policy, and
`registerFlow` calls it — so the load seam and any stored-row migration can
never disagree about what "canonical" means. It returns two shapes from one
pass:

  - `parsed` for EXECUTION — FlowSchema.parse + the #4347 region pass, schema
    defaults materialized. What registerFlow runs.
  - `storable` for PERSISTENCE — conversions plus the `{dialect, source}`
    envelopes the schema derives for edge conditions, and deliberately nothing
    else.

Excluding schema defaults is the load-bearing decision, and it was measured
rather than assumed. Driving a pre-17 flow through all three steps shows parse
+ normalize REMOVE nothing (FlowSchema is strict since #4001, so an unknown key
throws instead of being dropped — the graftNormalizedOperators precedent does
not transfer) and ADD only defaults: `version`, `runAs`, per-edge `type` /
`isDefault`. Persisting a default the author never wrote would pin every
migrated row to today's value while untouched rows follow tomorrow's — two
populations with different behaviour, which is the drift this pass exists to
remove. A migration must not become a source of it.

`migrateStoredMetadata` gains an optional `canonicalizeFlow` hook. Without it,
flow rows keep reporting `skipped` with the reason. With it: conversions are
applied and reported per row, a refused rename (the guard firing over a live
third-party node type) fails the row loudly naming the token, and a flow that
cannot canonicalize at all is reported rather than persisted as a guess.

One subtlety the tests pin: the condition envelope is a schema transform, not a
conversion, so it emits NO notice while still changing the body. Reading notices
alone — correct for every other type — would call such a row canonical and
leave it re-deriving on every boot. Both passes are copy-on-write, so identity
(`storable === body`) is the exact test for flows.

No host is wired yet: booting the automation plugin in the CLI would arm
triggers and schedulers (registerFlow activates them), so that needs either an
inert plugin mode or the admin route. Tracked in #4454.

Refs #4327, #3903, #4001, #4347, ADR-0078, ADR-0087

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

* feat(automation,migrate): os migrate meta --stored covers flow rows (#4454)

The stored-metadata pass (#4327) skipped `flow` — the one type where the most
stored dialect actually lives, since the graduated conversions
`flow-node-crud-filter-alias`, `-object-alias`, `-notify-config-aliases` and
`-script-config-aliases` are all flow-node entries. Flow-node conversions carry
ADR-0078's open-namespace conflict guard, which must consult the LIVE executor
registry to tell a rename from a clobber, and the metadata layer cannot obtain
one. This wires the engine in without wiring in a server.

`AutomationServicePluginOptions.armRuntime` (default true — every existing host
is unaffected). With `false` the plugin brings up the engine and the COMPLETE
node registry — built-ins plus whatever `automation:ready` contributes, because
a partial registry would make the guard read a live custom node type as unowned
and rewrite over it — then stops before anything is armed:

  - no flow registered (registerFlow calls activateFlowTrigger, so record
    triggers and scheduled jobs would go live);
  - no kernel:ready / metadata:reloaded re-sync (skipping only the boot pull
    would arm them a moment later);
  - no declarative connector materialized (an MCP provider spawns a process);
  - no suspended wait-timer re-armed (it RESUMES paused runs — a migration that
    silently continues someone's approval is indefensible).

`os migrate meta --stored` boots it in that mode and passes
`canonicalizeStoredFlow` as the protocol's `canonicalizeFlow` hook. A migration
process must not become a second server.

`IAutomationService.canonicalizeStoredFlow` is declared on the contract rather
than only on the implementation, because the CLI consumes it through the
`automation` slot — which is exactly what the slot-lookup lint rule asks for
instead of erasing the lookup to `any`.

Verified against a real database, not only unit tests: a legacy flow row
(`config.filters`) seeded into examples/app-todo migrates preview(exit 1) →
apply → re-run(exit 0), the row comes back with `config.filter`, a
`sys_metadata_history` entry sourced `migrate-stored`, and — the load-bearing
part — NO schema defaults written (`version`, `runAs`, per-edge `type` are
absent), so the row is not frozen on today's default values. Boot logs confirm
17 executors registered and then "inert mode … no trigger or schedule armed".

Refs #4327, #3903, #4001, #4347, ADR-0078, ADR-0087

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

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/stored-migration-covers-flows.md

@@ -0,0 +1,67 @@
+---
+"@objectstack/service-automation": minor
+"@objectstack/metadata-protocol": minor
+"@objectstack/cli": patch
+---
+
+feat(automation,migrate): `os migrate meta --stored` now covers flow rows too (#4454)
+
+#4327 gave the stored-metadata conversion chain a finish line for every
+metadata type except `flow` — the one type where the most stored dialect
+actually lives, since the graduated conversions `flow-node-crud-filter-alias`,
+`flow-node-crud-object-alias`, `flow-node-notify-config-aliases` and
+`flow-node-script-config-aliases` are all flow-node entries. Flow-node
+conversions carry ADR-0078's open-namespace conflict guard, which has to consult
+the *live* executor registry to tell a rename from a clobber, and the metadata
+layer has no way to obtain one. Flows were reported `skipped` with that reason.
+They are now converted.
+
+**One canonicalization policy, two shapes.**
+`AutomationEngine.canonicalizeStoredFlow` is the single implementation and
+`registerFlow` calls it, so the load seam and the migration can never disagree
+about what "canonical" means. It returns `parsed` (for execution — the
+`FlowSchema.parse` + #4347 region output, schema defaults materialized) and
+`storable` (for persistence).
+
+**`storable` excludes schema defaults, and that is the load-bearing decision.**
+Measured rather than assumed: driving a pre-17 flow through all three steps
+*removes* nothing — `FlowSchema` is strict since #4001, so an unrecognized key
+throws instead of being silently dropped, which means the
+`graftNormalizedOperators` precedent (it exists because the *view* parse strips
+Studio-only auxiliary keys) does not transfer — and *adds* only defaults:
+`version`, `runAs`, per-edge `type` / `isDefault`. Persisting a default the
+author never wrote would pin every migrated row to today's value while untouched
+rows follow tomorrow's: two populations with different behaviour, which is
+exactly the drift this pass exists to remove. So the write-back is the
+conversion result plus the `{dialect, source}` envelopes the schema derives for
+edge conditions, and nothing else.
+
+One subtlety worth knowing if you extend this: that envelope is a schema
+transform, not a conversion, so it emits **no** notice while still changing the
+body. Reading notices alone — correct for every other metadata type — would call
+such a row canonical and leave it re-deriving on every boot. Both passes are
+copy-on-write, so identity is the exact test for flows.
+
+**New: `AutomationServicePluginOptions.armRuntime`** (default `true`, so every
+server, dev stack and test host is unaffected). Set `false` and the plugin
+brings up the engine and the complete node registry — built-ins plus whatever
+`automation:ready` contributes, because a *partial* registry would make the
+conflict guard read a live custom node type as unowned and rewrite over it — and
+then stops before anything is armed:
+
+| Skipped when `armRuntime: false` | Why it must be |
+|---|---|
+| flow pull + `kernel:ready` / `metadata:reloaded` re-sync | `registerFlow` calls `activateFlowTrigger` — record triggers and scheduled jobs would go live |
+| declarative connector materialization | opens real connections; an MCP provider spawns a child process |
+| suspended-run wait-timer re-arm | would resume someone's paused approval mid-migration |
+
+`os migrate meta --stored` boots the plugin in that mode. A migration process
+must not become a second server.
+
+A refused rename — the guard firing because the old node-type token is a live
+name something else owns in this environment — fails that row loudly, naming the
+token and its owner. Never a silent skip, never a clobber. A flow that cannot
+canonicalize at all (a strict-schema violation, a malformed control-flow region)
+is reported as failed with the parse message rather than persisted as a guess;
+such a row cannot register today either, so the report is telling you about a
+flow that is already broken at runtime.

content/docs/deployment/cli.mdx

@@ -809,9 +809,21 @@ counting as done:
 
 | Not rewritten | Why |
 | :--- | :--- |
-| `flow` rows | Flow-node conversions carry a conflict guard that needs the automation engine's live executor registry; flows canonicalize at their own seam when the engine loads them |
 | Types with no repository write path (`agent`) | Their write path records no history and would force a draft live — a half-write is worse than leaving the row to the read path |
 | Rows that still fail the current schema after conversion | That is a genuine contract violation, not chain-owned history. The write path's rejection is correct; fix the row in Studio |
+| A flow whose rename the conflict guard refused | The old node-type token is a live name something else owns here. Rewriting would clobber that owner, so the row fails loudly naming the token — never a silent skip |
+
+**Flows are covered, and cost one extra plugin.** Flow-node conversions carry an
+open-namespace conflict guard that has to consult the *live* executor registry
+to tell a rename from a clobber, so this run boots the automation engine — in an
+inert mode that installs the node registry and then arms nothing: no flow
+registered, no record trigger or scheduled job bound, no connector
+materialized, no suspended run resumed. A migration process must not become a
+second server. What gets written back for a flow is the conversion result plus
+the `condition` envelopes the schema derives, and deliberately **not** the
+schema's defaults (`version`, `runAs`, per-edge `type`) — persisting a default
+the author never wrote would pin that row to today's value while untouched rows
+follow tomorrow's, which is the drift this command exists to remove.
 
 <Callout type="warn">
 `--apply` is the only writing mode, and it rewrites **metadata** — each affected

docs/adr/0087-metadata-protocol-upgrade-contract.md

@@ -450,10 +450,40 @@ writing mode.
   never rewritten. Canonicalizing a past version's body would break the
   checksum↔body pairing this contract depends on — the migration is a new
   commit, not a rewrite of history.
-- **What the pass does not cover, it names.** Flows (their seam is
-  `AutomationEngine.registerFlow`, which holds the executor registry the
-  conflict guard needs) and types with no repository write path are reported as
-  `skipped` with the reason, never counted as done. Giving flows the same finish
-  line needs a canonicalization entry point on the automation engine — tracked
-  as #4454, and worth doing precisely because the graduated flow-node
-  conversions are where the most stored dialect lives.
+- **What the pass does not cover, it names.** Types with no repository write
+  path are reported as `skipped` with the reason, never counted as done.
+
+## Addendum (2026-08-01b) — flows reach the finish line too (#4454)
+
+The pass above initially skipped `flow` rows, which was the largest hole in it:
+the graduated flow-node conversions are where the most stored dialect lives.
+Closing it needed three decisions.
+
+- **One canonicalization policy, two shapes.**
+  `AutomationEngine.canonicalizeStoredFlow` is now the single implementation and
+  `registerFlow` calls it, so the load seam and the migration cannot disagree
+  about what canonical means. It returns `parsed` (for execution — schema
+  defaults materialized) and `storable` (for persistence).
+- **`storable` excludes schema defaults, and this is load-bearing.** Measured,
+  not assumed: driving a pre-17 flow through parse + the region pass *removes*
+  nothing (`FlowSchema` is strict since #4001 — an unknown key throws rather
+  than being dropped, so the `graftNormalizedOperators` precedent does not
+  transfer) and *adds* only defaults: `version`, `runAs`, per-edge `type` /
+  `isDefault`. Persisting a default the author never wrote would pin every
+  migrated row to today's value while untouched rows follow tomorrow's — two
+  populations with different behaviour, which is the drift this pass exists to
+  remove. So the write-back is conversions plus the schema's `condition`
+  envelopes, and nothing else.
+- **The engine is borrowed, not started.** `AutomationServicePlugin` gains
+  `armRuntime: false`: built-in nodes installed and `automation:ready` fired
+  (the registry must be COMPLETE, or the conflict guard reads a live custom node
+  type as unowned and rewrites over it), then a hard stop before anything is
+  armed — no flow registered, no trigger or schedule bound, no connector
+  materialized, no suspended run resumed. `registerFlow` arms triggers as a side
+  effect, so skipping only the boot pull would not have been enough; the
+  `kernel:ready` and `metadata:reloaded` re-syncs are skipped for the same
+  reason. A migration process must not become a second server.
+
+A refused rename — the guard firing because the old token is a live name owned
+by something else — fails that row loudly with the token and its owner. Never a
+silent skip, never a clobber; that is the whole reason the guard exists.

packages/cli/src/commands/migrate/meta.ts

@@ -30,6 +30,7 @@ import { bootSchemaStack } from '../../utils/schema-migrate.js';
 import { buildDataMigrationPlugins } from '../../utils/data-migration-plugins.js';
 import { OCCUPANCY_HINT, probeMigrationTarget } from '../../utils/migrate-occupancy-gate.js';
 import { describeOccupancy } from '../../utils/sqlite-occupancy.js';
+import type { IAutomationService } from '@objectstack/spec/contracts';
 
 async function confirm(question: string): Promise<boolean> {
   if (!process.stdin.isTTY) return false; // non-interactive → require --yes
@@ -511,12 +512,15 @@ export default class MigrateMeta extends Command {
 
     let stack;
     try {
-      // `PlatformObjectsPlugin` only — this pass needs `sys_metadata` and its
-      // history/audit siblings, which the protocol assembly registers itself.
-      // No storage adapter: unlike the file migration, nothing here reads bytes.
+      // `PlatformObjectsPlugin` for `sys_metadata` and its history/audit
+      // siblings, plus the automation engine in INERT mode so `flow` rows are
+      // covered too (#4454) — flow-node conversions need its executor registry
+      // for the conflict guard, and `armRuntime: false` means taking it arms
+      // nothing. No storage adapter: unlike the file migration, nothing here
+      // reads bytes.
       stack = await bootSchemaStack({
         ...(flags['database-url'] ? { databaseUrl: flags['database-url'] } : {}),
-        extraPlugins: await buildDataMigrationPlugins(),
+        extraPlugins: await buildDataMigrationPlugins({ automation: true }),
       });
     } catch (error: any) {
       if (flags.json) { await emitJson({ error: error.message }, 0, { compact: true }); this.exit(1); return; }
@@ -541,10 +545,23 @@ export default class MigrateMeta extends Command {
       const { formatStoredMigrationReport, storedMigrationClean } =
         await import('@objectstack/metadata-protocol');
 
+      // The automation engine canonicalizes `flow` rows — it holds the executor
+      // registry ADR-0078's conflict guard needs (#4454). It is booted inert, so
+      // this is the only thing it does in this process. Absent (an older stack,
+      // or a boot that skipped it), flow rows keep reporting `skipped` with the
+      // reason rather than being silently counted done.
+      // `SchemaStack.kernel` is untyped, so the slot's contract is stated on the
+      // result rather than as a type argument — narrowing, not erasing.
+      let automation: IAutomationService | undefined;
+      try { automation = stack.kernel.getService('automation') as IAutomationService | undefined; }
+      catch { /* not registered — flows stay reported as skipped */ }
+      const canonicalize = automation?.canonicalizeStoredFlow?.bind(automation);
+
       const report = await protocol.migrateStoredMetadata({
         apply,
         ...(flags.type && flags.type.length > 0 ? { types: flags.type } : {}),
         actor: 'os migrate meta --stored',
+        ...(canonicalize ? { canonicalizeFlow: canonicalize } : {}),
       });
       const clean = storedMigrationClean(report);
       if (!clean) exitCode = 1;

packages/cli/src/utils/data-migration-plugins.ts

@@ -24,11 +24,27 @@ import { resolveStorageCapabilityArg } from '../commands/serve.js';
  *    where the server would.
  */
 export async function buildDataMigrationPlugins(
-  opts: { storage?: boolean } = {},
+  opts: { storage?: boolean; automation?: boolean } = {},
 ): Promise<unknown[]> {
   const plugins: unknown[] = [];
   const { PlatformObjectsPlugin } = await import('@objectstack/platform-objects/plugin');
   plugins.push(new PlatformObjectsPlugin());
+  if (opts.automation === true) {
+    // `os migrate meta --stored` needs the automation ENGINE, never the
+    // automation RUNTIME (#4454). Flow-node conversions carry ADR-0078's
+    // open-namespace conflict guard, which consults the live executor registry
+    // to tell a rename from a clobber — and only this plugin has that registry.
+    //
+    // `armRuntime: false` is what makes taking it safe: the engine and the full
+    // node registry come up (built-ins plus whatever `automation:ready`
+    // contributes, because a PARTIAL registry would make the guard rewrite over
+    // a live custom node type instead of refusing), and then nothing is armed —
+    // no flow registered, no record trigger or scheduled job bound, no
+    // declarative connector materialized, no suspended run resumed. A migration
+    // process must not become a second server.
+    const { AutomationServicePlugin } = await import('@objectstack/service-automation');
+    plugins.push(new AutomationServicePlugin({ armRuntime: false, suspendedRunStore: 'memory' }));
+  }
   if (opts.storage === true) {
     try {
       const { SettingsServicePlugin } = await import('@objectstack/service-settings');

packages/metadata-protocol/src/index.ts

@@ -17,6 +17,7 @@ export type {
 
 export { formatStoredMigrationReport, storedMigrationClean } from './stored-migration.js';
 export type {
+  StoredFlowCanonicalization,
   StoredMigrationNotice,
   StoredMigrationOutcome,
   StoredMigrationReport,