fix(cli): os migrate meta lists and writes a conversion the load already applies, on a stack the schema accepts

[objectstack-fleet]

Part of #22256
Clause-②: no
Release: the composed half stays open on #22256. That half is a conversion the load still applies inside a composeStacks package body. Its carrier is the domain:cli seat, which takes it to the domain:spec seat with the H4 measurement below. It needs a spec seam or a second copy of composition's rule.

os migrate meta now lists and writes a conversion the load still applies, such as datasources[].driver: 'mongo', on a one-package stack the current schema ACCEPTS. Every change is in packages/cli. There is no packages/spec change, and nothing here reads or writes the producer's provenance key.

What changed

1. The shim keeps the argument of an accepted defineStack call (src/utils/config.ts). __tolerant gains a keep hook. It runs after a successful call, outside the try. The defineStack wrap passes __keepAuthored, which defines one non-enumerable property on the returned stack, holding the argument. Its key is a CLI-owned Symbol.for key, @objectstack/cli:authored-source/accepted-argument. A refused call is unchanged: it hands its argument through raw, and __recordStack records it for composeStacks. A call takes exactly one of the two arms.
2. loadConfig({ authoredSource: true }) starts the default export from that argument (authoredArgumentOf). It reads the argument off mod.default BEFORE the named-export merge, which is where the provenance mark and the conversion record are already read: the merge's spread drops non-enumerable properties. It follows the record to the end, so defineStack(defineStack({ … })) answers the inner literal. stackProvenance and stackConversions are still read off the built stack. A load without authoredSource, which is every other command, is untouched.
3. meta.ts: no code change, one comment. Both chain call sites (:1159–:1165, and the --write re-run at :1343–:1344) already run normalizeStackInput(config, { convert: false }) over loadConfig(…, { authoredSource: true }).config, and that value is now the stack as written. The comment says where it comes from, and that the composed path is not covered.
4. Changeset: @objectstack/cli patch, Clause-②: no. It keeps PR fix(cli): os migrate meta runs on a composeStacks project and migrates its package bodies #22326's "Known limit" true, and restates it for both kinds of composed input.

The carrier (H3): a property on the stack, not a WeakMap in the shim's record module

The record has to cross from the bundled shim to loadConfig. The only values that cross are the config module's exports, and the default export IS the stack the call returned. A property on it crosses with it, with no global state and no lifetime beyond the value's. The hand-through WeakMap (PR #22326) lives in a module bundled inside the load, and nothing outside the load can reach it; reaching it would take a process-global. The property is non-enumerable, like the producer's own mark, so a spread, JSON.stringify and a schema parse all leave it behind.

Why loadConfig substitutes, and meta.ts does not re-merge

In the order's route, loadConfig exposes the record and meta.ts starts from it at its two call sites. meta.ts would then have to redo loadConfig's named-export merge over the authored argument, which is a second copy of that rule. Substituting before the merge keeps one merge. The --write planner also gets the authored value, so its literal match (subsetOf(literal, loaded)) compares the literal with what the author wrote.

PM readings, measured

All on origin/main 3599fef1 with the built CLI (node packages/cli/bin/run.js), against temp projects that link this worktree's built @objectstack/spec.

• H1, reproduced. The stack is a one-package stack the schema accepts, with datasources: [{ name: 'docs', label: 'Docs', driver: 'mongo', config: { url: 'mongodb://mongo.internal:27017/docs' } }]. migrate meta objectstack.config.ts --from 16 --write --json gave exit 0, "applied": [] and "write": {"status": "written", "files": [], "written": [], "manual": [], "unexplained": []}. The source kept driver: 'mongo'. A later load (os validate) printed: defineStack: datasources[0].driver: 'mongo' → 'mongodb' (converted at load; conversion 'datasource-driver-mongo-to-mongodb', retires in protocol 18). Update the source to the canonical shape — the conversion stops running then.
  • A first probe with config: {} was REFUSED, because a mongo datasource needs a connection target. It took the raw hand-back, and the conversion was listed and written. Only an accepted stack shows the defect.
• H2, confirmed by instrument. loadConfig(…, { authoredSource: true }).config.datasources[0].driver was 'mongodb', and so was the chain input after normalizeStackInput(…, { convert: false }). stackConversions named datasource-driver-mongo-to-mongodb. On success the shim's __tolerant returned the real result. Where driver is converted: buildDefinedStack (packages/spec/src/stack.zod.ts) calls normalizeStackInput with conversions on, in both modes. That calls applyConversions, which runs datasourceDriverMongoToMongodb (packages/spec/src/conversions/registry.ts). No other define* helper runs the pass.
• H3, fixed as above. After the change, the same H1 run gave applied = [datasource-driver-mongo-to-mongodb @ datasources[0].driver, mongo → mongodb], write.files = [{ objectstack.config.ts, sites: 1 }], verification.ok: true and schemaValid: true. The source line now reads driver: 'mongodb'. A later os validate printed no converted at load line, and a re-run applied nothing.
  • Nothing to convert is unchanged, measured on the corpus. All four example apps are ACCEPTED by defineStack and carry no load-path conversion, so the fix changes each one's chain input. I ran migrate meta --from 16 --json and --from 17 --json on app-crm, app-multi-package, app-showcase and app-todo. The eight --json documents, minus duration, are byte-identical by md5 before and after. I also ran --write --from 16 on a throwaway copy of each app. The --json outcome and the written bytes are identical by md5: app-showcase writes 3 sites in src/automation/flows/index.ts and app-todo 1 site in src/flows/task.flow.ts, both before and after.
  • The --out snapshot changes for an accepted stack. It is now the authored stack plus the chain's edits, as it already was for a refused stack. Measured on the three one-package apps, every difference is one of two kinds. Either a key is present only BEFORE: parse defaults such as manifest.scope, manifest.defaultDatasource, flows[].version and hooks[].runAs, and objects[].actions from defineStack's action merge. Or the parse transformed a value: hooks[].condition and flows[].edges[].condition. Nothing appears that the author did not write. The composed app's snapshot is unchanged. The changeset says so.
• H4, measured. NOT fixed here. The project is composeStacks([ServiceStack, AppStack], { manifest: 'preserve' }), with the service body carrying the accepted mongo datasource. Before AND after this change, --from 16 --write --json gives exit 0, applied: [], write.files: [] and schemaValid: true. The sources keep their md5, and a later load prints the notice once. With a refused spelling added to the same body (time default '10:00Z'), applied lists only time-default-utc-suffix-dropped @ packages[0].manifest.objects[0].fields.starts_at.defaultValue, because the strict: false re-production converts the driver.

  • Why it stops. The chain's per-body run reads packages[i].manifest. composeStacks assembles that body from the stack the input's defineStack call RETURNED (assemblePackageBody: { ...stack.manifest }, then each package-owned key). To start that run from the authored input, packages/cli needs two things it does not have as values:

    1. The mapping from entry to input (preservePackageEntries: an input with packages contributes its own entries, and an input without manifest contributes none).
    2. The body assembly itself. The codemod's packageBodyKeys gives the key SET, and its composedBody step states the assembly over SYNTAX nodes. Neither produces a value.

    Writing either as a value is a second copy of composition's rule. The real composeStacks refuses the authored inputs at its step 0 (STACK_PROVENANCE_MISSING). Marking them would take the spec's provenance key, or defineStack, which converts. So this half needs a packages/spec seam, for example a defineStack mode that skips the D2 pass, or an exported body assembler. It goes back to the seat.

• H5, holds. An accepted call is kept (__keepAuthored), and a refused call is handed through (__recordStack). They are the two arms of one try. The composed re-production calls the REAL defineStack (__specRoot.defineStack), not the wrap, so it keeps nothing. A composed artifact carries no record, so loadConfig uses it as before. The pin is a stack carrying one refused spelling and one load-path spelling: each conversion is applied once, and both are written.

Pins — test/migrate-meta-load-conversions.test.ts, unit tier

The tests run in-process over MigrateMeta.run, against temp projects that link the real spec. No process is spawned and no kernel is booted. vitest list --project unit lists the file, and --project integration does not. 5 tests:

• The fix. The accepted mongo stack. The dry run lists datasource-driver-mongo-to-mongodb @ datasources[0].driver. --write writes it: write.files = [{ objectstack.config.ts, sites: 1 }], manual: [], unexplained: [], and the bytes are the source with 'mongo' → 'mongodb' and nothing else. The re-run applies nothing. The strict load's stackConversions goes from naming the conversion to []. The reload is read through stackConversions, not the stderr notice, because defineStack prints that notice once per process.
• Where the argument is read. With export const onEnable beside the default, the authored-source load gives driver: 'mongo', namedExports: ['onEnable'], onEnable merged, stackProvenance: true and stackConversions naming the conversion. The strict load still gives 'mongodb'.
• Defined twice. defineStack(defineStack({ … })) lists the conversion exactly once.
• Control. An already-canonical source gives applied: [] and write = { status: 'written', files: [], written: [], manual: [], unexplained: [] }, and every byte is unchanged. Its applied, todos, absentTodos and schemaValid equal those of the chain over the stack defineStack built, which is where the chain started before this change.
• Mixed (H5). One refused spelling (time default '10:00Z') and one load-path spelling (the valid mongo datasource). applied = [mongo, time], each once. write.files = [{ objectstack.config.ts, sites: 2 }], and both edits are written. The re-run applies nothing, and the strict load accepts and converts nothing.

PR #22326's pins (test/migrate-meta-composed.test.ts, 8 tests, including both one-package controls) stay green.

Ablations

Each ablation went through scripts/ablation-replace.mjs. The anchor hit once, the mutation was proven on disk, and the restore was proven: blob 0488d7e55d38 = HEAD, and git diff HEAD empty. The suite imports src directly, so no dist/ is involved. The direction was stated before each run.

1. The converted hand-through restored in the loader (authoredBase = baseConfig). Predicted 3 red, 2 green. Got 3 red (the fix, where the argument is read, defined twice) and 2 green (control, mixed). The fix pin's first red: expected [] to deeply equal [ { …(4) } ].
2. The shim no longer keeps the argument (the defineStack wrap passes only __recordStack). The same 3 red, 2 green.
3. The record followed one level only. Predicted 1 red. Got 1 red (defined twice) and 4 green.

Local verification at 038ef735d

• CLI unit tier: pnpm --filter @objectstack/cli exec vitest run --project unit --maxWorkers=2 gave Test Files 269 passed (269) and Tests 3956 passed (3956).
• Typecheck: pnpm --filter @objectstack/cli typecheck (tsc --noEmit, then check:test-typecheck) exited 0, ending check:test-typecheck: OK … 3 file(s) / 28 error(s) / 6 pinned signature(s) held, the pre-existing ledger. It ran at 93f524998. The only later commit is the changeset, so the TypeScript tree is the same.
• Integration tier: declared to CI, because this diff touches no integration-tier file and no spawn entry. As a targeted check, I ran the two integration files that drive migrate meta over an authored source, test/migrate-meta-default-range.test.ts and test/migrate-meta-engine-guidance.test.ts, with --project integration: Test Files 2 passed (2), Tests 10 passed | 1 skipped (11).
• Gates: node scripts/pm/dispatch-gates.mjs --commands, re-derived over this diff, gives the same 65 commands the order listed. All 65 exited 0. check:dual-build-cjs-loads first exited 3 (PREREQUISITE NOT MET: 8 packages outside the closures I had built had no dist/). After building those 8 it passed (106/66/712/1 entries/packages/cjsFiles/probes). dispatch-gates --ran reports 65 derived, 65 run, 0 NOT-MEASURED, 0 UNRUN.
• Lint: pnpm lint (eslint . --no-inline-config, the whole repo) exited 0 with no findings.
• Base: the branch is on 3599fef1. main has since moved 6 commits, and none touches packages/cli, the spec's stack or provenance modules, or PR fix(cli): os migrate meta runs on a composeStacks project and migrates its package bodies #22326's changeset. I did not merge it; CI's merge ref covers the join.

Acceptance notes

• PR fix(cli): os migrate meta runs on a composeStacks project and migrates its package bodies #22326's "Known limit" sentence ends "…, the same as for an input the current schema accepts." Inside a composed project, which is its context, it stays true. Read as the one-package path, this PR makes the comparison stale. This PR's changeset restates the limit for both kinds of composed input. I did not edit the other changeset: it is outside the claimed file surface.
• content/docs/upgrading.mdx: I read the --write paragraph. Nothing in it goes stale, because it makes no claim about load-path conversions. No docs edit.
• Named exports, in this one load. migrate meta's merge now judges whether a named export is shadowed against the authored argument, not the built stack. A top-level key that the parse defaults and that the author also exports would now merge instead of being reported as shadowed. Measured on the corpus, no TOP-LEVEL key differs between the two; every difference is nested.
• A stack spread from a built stack (defineStack({ ...base, … })) still reaches the chain with base's converted values. The spread drops the record, as it drops the provenance mark, and --write refuses that site as spread anyway.
• A one-input composeStacks([x]) returns x itself. Measured: it now lists datasource-driver-mongo-to-mongodb @ datasources[0].driver, and --write lists that site as helper under the codemod's existing composed-key rule.

Round 2 (REWORK 6068295985), written by the domain:cli seat

• Merged main with a merge commit, daa27b7c7 (parents 038ef735d and 35afb1587). There was no rebase and no force-push, and no path conflicted.
• PR fix(cli): os migrate meta runs on a composeStacks project and migrates its package bodies #22326's pending changeset, corrected (2f8e479a3). In .changeset/22289-migrate-meta-composed-project.md, the "Known limit" bullet's closing clause ", the same as for an input the current schema accepts" is removed. Nothing else in that file moves.
  • This PR makes that clause false, and both changesets ship in one @objectstack/cli release.
  • It is a deliberate correction of another PR's pending note, so check-empty-changeset's foreign-changeset rule is red by design. The seat confirms that in a comment on this PR.
  • The first Acceptance note above (PR fix(cli): os migrate meta runs on a composeStacks project and migrates its package bodies #22326's "Known limit" sentence) no longer applies.
• The open question (the --out snapshot) is ruled A. It is kept as shipped and declared in this PR's changeset.
• Re-verified by the dev at 2f8e479a3, after a full turbo run build:
  • CLI unit tier: 269 files, 3956 tests passed. Typecheck exit 0. pnpm lint exit 0.
  • The same 65 gates re-derived over the final diff: 64 exit 0, and check-empty-changeset exits 1 on the foreign-changeset rule only. dispatch-gates --ran: 65 derived, 65 run, 0 NOT-MEASURED, 0 UNRUN.
• The docs-drift advisory (6068211309), re-derived at 2f8e479a3 with node scripts/docs-audit/affected-docs.mjs --json 35afb158. It lists 16 hand-written pages and 9 release-owned ones (read-only).
  • The two pages that describe os migrate meta (content/docs/upgrading.mdx and content/docs/deployment/cli.mdx) make no claim this PR changes. The --out row says "the migrated stack as a JSON snapshot", which still holds. cli.mdx:1354 is about --stored, which this PR does not touch.
  • The other 14 name os migrate meta as a remedy, which stays true.
  • So no docs edit is owed.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/cli, touching 8 documentable anchor(s).

16 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 35afb15878054ea1ac72a2a29b2271712f0bfa9d.

⛔ 9 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 28 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 35afb15878054ea1ac72a2a29b2271712f0bfa9d → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 91967e944ff13524307df50fab35bb1d636a3b9a — the merge of head 2f8e479a39d79405f7c3b4e31a4a4e5430410f00 into base 35afb15878054ea1ac72a2a29b2271712f0bfa9d, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 91967e944ff13524307df50fab35bb1d636a3b9a && git checkout 91967e944ff13524307df50fab35bb1d636a3b9a
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 35afb15878054ea1ac72a2a29b2271712f0bfa9d 2f8e479a39d79405f7c3b4e31a4a4e5430410f00 && git checkout -B drift-repro 35afb15878054ea1ac72a2a29b2271712f0bfa9d && git merge --no-ff 2f8e479a39d79405f7c3b4e31a4a4e5430410f00

node scripts/docs-audit/affected-docs.mjs --json 35afb15878054ea1ac72a2a29b2271712f0bfa9d

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 35afb15878054ea1ac72a2a29b2271712f0bfa9d → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

Deliberate changeset correction, confirmed by the domain:cli seat (#6024 · session_01RWZbGvPFcRKvUqASZtunCU · 2026-10-08T21:20Z).

This PR edits .changeset/22289-migrate-meta-composed-project.md, a pending changeset PR #22326 added. It removes one clause, ", the same as for an input the current schema accepts", which this PR makes false. Both changesets ship in the same @objectstack/cli release.

• The seat asked for the edit in REWORK 6068295985 on [finding] cli(migrate meta): --write never writes a conversion the authored-source load already applied (e.g. driver: 'mongo') — the chain sees a pre-converted stack and reports applied: [] #22256, and amended its claim 6067115020 to name the file.
• check-empty-changeset's foreign-changeset rule is therefore red on this PR by design. It is not a required check (precedent PR fix(runtime,cloud-connection)!: install-local refuses an enabled job whose pull does not bind (#21672) #21683).