diff --git a/.changeset/migrate-meta-lists-not-rewrites.md b/.changeset/migrate-meta-lists-not-rewrites.md new file mode 100644 index 0000000000..2e0bd68692 --- /dev/null +++ b/.changeset/migrate-meta-lists-not-rewrites.md @@ -0,0 +1,23 @@ +--- +"@objectstack/cli": patch +--- + +Correct a false verb in `os migrate meta`'s own source comments: the `--from` +arm **lists** the mechanical edits an author's source needs; it rewrites no file +(#10831). + +The `pendingDataMigrations` docblock in +`packages/cli/src/commands/migrate/meta.ts` opened with "this command rewrites an +author's source" — 74 lines above the command header that says the opposite +("The command does not silently rewrite TS config source (that AST rewrite is +unsafe and lossy)"). Both `writeFileSync` calls in the file are guarded by +`if (flags.out)`, so the only file the `--from` arm ever writes is the `--out` +JSON snapshot. The in-place codemod is a separate, unbuilt piece of work. + +The contrast the docblock was drawing — metadata migration's subject is the +author's *source*, the two data migrations' subject is a deployment's *rows* — +is correct and is preserved; only the verb on the first half changed. The +`--stored` arm genuinely does rewrite `sys_metadata` rows and its wording is +untouched. + +No runtime behaviour changes: comment-only. diff --git a/content/docs/automation/flows.mdx b/content/docs/automation/flows.mdx index 3ae6dba6de..27cedf8b1d 100644 --- a/content/docs/automation/flows.mdx +++ b/content/docs/automation/flows.mdx @@ -242,8 +242,9 @@ Replace them per branch — they are different mechanisms, not one rename: | `actionType: 'my_fn'` (shorthand) | `function: 'my_fn'` — the conversion moves it for you | | inline `config.script` | move the logic into a registered function and call it via `config.function` | -Stored flows are rewritten by `os migrate meta --from 16`; authoring one of -these keys in TypeScript is now a compile error carrying the same prescription. +Run `os migrate meta --from 16` to list the mechanical edits for existing flow +sources; apply them by hand. Authoring one of these keys in TypeScript is now a +compile error carrying the same prescription. [#4343]: https://github.com/objectstack-ai/objectstack/issues/4343 diff --git a/content/docs/data-modeling/queries.mdx b/content/docs/data-modeling/queries.mdx index 1b7c034d99..d8c92eea56 100644 --- a/content/docs/data-modeling/queries.mdx +++ b/content/docs/data-modeling/queries.mdx @@ -385,8 +385,8 @@ backend, which left "what can this backend actually compute" unpredictable to th Both were retired (#6188, ADR-0049 enforce-or-remove): a query carrying either is now refused at parse with a prescription. There is no replacement in the query vocabulary — read the rows with an ordinary `fields` query and shape them in the caller, or materialise -the roll-up as a stored field. `os migrate meta --from 16` rewrites affected dataset -measures. +the roll-up as a stored field. Run `os migrate meta --from 16` to list the mechanical +edits for the affected dataset measures; apply them by hand. diff --git a/content/docs/deployment/cli.mdx b/content/docs/deployment/cli.mdx index 4211f924ad..b2db97142e 100644 --- a/content/docs/deployment/cli.mdx +++ b/content/docs/deployment/cli.mdx @@ -919,9 +919,9 @@ an old dialect exits `1`. So "my metadata is on protocol N" becomes a check rather than a belief. Note the division of labour with the default mode: `os migrate meta --from N` -rewrites an **author's source** and reads no database; `--stored` rewrites **one -deployment's rows** and reads no config. Same chain, opposite ends of the -contract — which is why the two modes are mutually exclusive. +lists the edits **an author's source** needs and reads no database; `--stored` +rewrites **one deployment's rows** and reads no config. Same chain, opposite +ends of the contract — which is why the two modes are mutually exclusive. **Without shell access, use the route.** This command needs to reach the deployment's database directly, which a hosted operator cannot do. The same pass diff --git a/content/docs/protocol/objectql/query-syntax.mdx b/content/docs/protocol/objectql/query-syntax.mdx index 742e05acbf..fb586b1d77 100644 --- a/content/docs/protocol/objectql/query-syntax.mdx +++ b/content/docs/protocol/objectql/query-syntax.mdx @@ -857,7 +857,8 @@ by no SQL backend, so which backend could compute them was unpredictable to the Both were retired (#6188, ADR-0049 enforce-or-remove) and are now refused at parse with a prescription. There is no replacement in the query vocabulary — read the rows with an ordinary `fields` query and shape them in the caller, or materialise the roll-up as a -stored field. `os migrate meta --from 16` rewrites affected dataset measures. +stored field. Run `os migrate meta --from 16` to list the mechanical edits for the +affected dataset measures; apply them by hand. ### Group By Multiple Fields diff --git a/packages/cli/src/commands/migrate/meta.ts b/packages/cli/src/commands/migrate/meta.ts index 529ab0ff39..aa3dbea298 100644 --- a/packages/cli/src/commands/migrate/meta.ts +++ b/packages/cli/src/commands/migrate/meta.ts @@ -78,12 +78,12 @@ interface PendingDataMigration { * leaves for the operator (ADR-0104's 2026-07-30 addendum, #3438). * * Metadata migration and data migration are different jobs with different - * subjects: this command rewrites an author's source, while these two rewrite - * (or vouch for) a deployment's rows, one deployment at a time. Nothing here - * can run them, and — with no database in reach — nothing here can say whether - * they have run; the booting server reports that. What this can do is make - * sure the upgrade never *ends* without naming them, because a gate nobody is - * told about is served by nobody. + * subjects: this command reports the edits an author's source needs, while + * these two rewrite (or vouch for) a deployment's rows, one deployment at a + * time. Nothing here can run them, and — with no database in reach — nothing + * here can say whether they have run; the booting server reports that. What + * this can do is make sure the upgrade never *ends* without naming them, + * because a gate nobody is told about is served by nobody. * * Listed only when the author's own metadata declares the field classes each * gate is about, so the advice is never noise.