os migrate plan exits 0 when the host config exists but could not be loaded — the one remaining UNMEASURED shape after #12938

[hotlong]

Split out of #12938, which restored the composition but deliberately did not touch exit semantics (the dispatch bounded it to "only what is composed/visible", and the artifact-less run is byte-pinned to today's output, exit 0 included).

The remaining sliver

After #12938, os migrate plan can still compute a plan over a metadata set that is a fraction of the target's tables, in exactly one way: a host objectstack.config.{ts,js,mjs} exists but cannot be loaded. A missing environment variable is the ordinary cause — ObjectStack Cloud's own control-plane config throws without AUTH_SECRET, and that shape is representative rather than exotic.

Today that path:

• warns loudly on stderr, naming the config, the underlying error and the consequence ("an empty plan here is UNMEASURED, not 'in sync'");
• carries composition.hostConfigLoaded: false in os migrate plan --json;
• and exits 0, printing "Physical schema is in sync with metadata — nothing to migrate" when the reduced set happens to be clean.

Composing the platform floor still happens on that path, so managedTables rises to 9 — above the five-table artifact-less baseline that consumer-side coverage gates are calibrated against (objectstack-ai/cloud#1705's workflow uses managedTables <= 5). A count alone therefore cannot distinguish "the config blew up" from "this deployment is genuinely small"; only hostConfigLoaded can.

#12938's own body raised this class in its non-normative "Suggested direction" section: "a plan computed over a metadata set that is a fraction of the target's tables is UNMEASURED, and today it is indistinguishable from 'in sync'".

The decision, stated so it can be ruled on rather than guessed

Should os migrate plan (and apply) exit non-zero when a host config is present and could not be loaded?

• A — exit non-zero. Matches "prefer failing to falling back" and "absence must be loud". Cost: a command that works today (nobody's migrate ever read the config before os migrate plan / apply compose neither the host config nor PlatformObjectsPlugin — they diff a five-table subset and cannot apply the drift their own message names #12938) starts failing for any project whose config needs environment the operator did not supply to this one-shot run. That is a behaviour regression for a population that has nothing to do with this defect.
• B — keep exit 0, keep the loud warning and the hostConfigLoaded discriminator, and let consumers gate on it. What os migrate plan / apply compose neither the host config nor PlatformObjectsPlugin — they diff a five-table subset and cannot apply the drift their own message names #12938 shipped. Cost: a human skimming a green plan can still miss the warning; the safety depends on someone reading composition.hostConfigLoaded.
• C — a flag (--require-host-config / --strict-coverage) that turns B into A on demand. Cost: one more surface, and the default still reads green.

No recommendation is offered here; #12938's dispatch ruled the axis out of scope rather than deciding it, so this is a fresh call.

Where to look

• packages/cli/src/utils/schema-migration-plugins.ts — the catch that reports the unloadable config, and hostConfigLoaded.
• packages/cli/src/commands/migrate/plan.ts — the composition block in the --json payload.
• objectstack-ai/cloud#1705 / fix(rest): resolve the ENVIRONMENT's analytics service for dataset queries #1707 — the consumer whose coverage gate is blind to this path today.

Generated by Claude Code

[os-elon]

⚖️ RULED — 2026-08-29, maintainer, live director session batch #3 (session session_016SG9S6V15MqeAgkehDcTwk), verbatim: 「同意」 — adopting option A: when a host objectstack.config.{ts,js,mjs} exists but cannot be loaded, os migrate plan AND os migrate apply exit non-zero, with an error naming the config, the underlying failure (e.g. the missing environment variable), and the remedy. A green exit over an UNMEASURED partial metadata set is the false-green a migration tool must never emit — the population this "regresses" was computing defective plans all along.

Scope pinned at ruling: the config-ABSENT path (no host config file at all) keeps today's behaviour — only present-but-unloadable turns red. The loud stderr text and the composition.hostConfigLoaded JSON discriminator stay (consumers like objectstack-ai/cloud#1705 keep their signal). Pins both directions: present+unloadable ⇒ non-zero for both commands; absent ⇒ unchanged; present+loadable ⇒ unchanged.

Ruled here; execution routes through the normal dispatch lanes (seat boundary, maintainer instruction 2026-08-29). Card → pm:queue.

---

Generated by Claude Code

[os-litant]

os-dev-report

{
 "issue": 12953,
 "status": "done",
 "branch": "claude/issue-12953-migrate-plan-unloadable-config",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/13113",
 "premise_still_valid": true,
 "head_sha": "542756251",
 "coordinates_relocated": {
 "packages/cli/src/utils/schema-migration-plugins.ts": "PRESENT, unmoved — the catch that reports the unloadable config is at L312 on origin/main db39dfc1c; hostConfigLoaded declared L226",
 "packages/cli/src/commands/migrate/plan.ts": "PRESENT, unmoved — composition block in the --json payload at L186-199",
 "packages/cli/src/commands/migrate/apply.ts": "PRESENT — not named by the issue's 'Where to look', but the ruling names apply too; its compositionPayload is at L186-195",
 "packages/cli/src/utils/schema-migrate.ts": "third construction site of SchemaMigrationComposition (L341) — found by grep, not named in the issue"
 },
 "summary": "Executed the 2026-08-29 maintainer ruling (verbatim 「同意」, option A) exactly as pinned. SchemaMigrationComposition now carries the load failure structurally (hostConfigError); a shared choke point refuseWhenHostConfigUnloadable() renders the refusal and sets process.exitCode, called from both commands' run() wrapper AFTER the body returns, so the whole report (human plan or --json document) is written before the process exits non-zero. Predicate is hostConfigPath !== null && !hostConfigLoaded — NOT !hostConfigLoaded alone, which is false on the config-absent shape too and would have turned the untouched population red while every direction-1 assertion still passed. The loud stderr warning and composition.hostConfigLoaded are both preserved byte-for-byte per the ruling. Changeset is minor (behaviour change to exit status), not major.",
 "tests": "REPRODUCTION — real commands, not source reading. 3 fixture projects x 4 invocations (migrate plan | plan --json | apply --yes | apply --yes --json), driven through packages/cli/bin/run-dev.js + tsx, captured before AND after, temp path and wall-clock duration masked as per-run noise. (1) config PRESENT+UNLOADABLE (module body throws on a missing env var, the issue's own AUTH_SECRET shape): exit 0/0/0/0 BEFORE -> 1/1/1/1 AFTER; stdout byte-identical both modes; stderr gains exactly one line: '[migrate] X Host config <p>/objectstack.config.ts exists but could not be loaded: Missing required environment variable OS_12953_AUTH_SECRET. This run therefore covered ONLY the objects the data stack registered - a fraction of what this deployment serves - so its result is UNMEASURED, not \"in sync\", and it is reported as a FAILURE rather than as success. Remedy: supply the environment this config needs (the failure named above says which), or fix the config, then re-run.' The --json payload on this path is BYTE-IDENTICAL before/after (composition.hostConfigLoaded:false, composition.hostConfig, managedTables:9) - only the exit status changed. (2) config ABSENT: 0/0/0/0 -> 0/0/0/0, stdout AND stderr byte-identical on all four invocations (managedTables:5, no composition block). (3) config PRESENT+LOADABLE: 0/0/0/0 -> 0/0/0/0, stdout AND stderr byte-identical on all four (managedTables:10, hostConfigLoaded:true). INSTRUMENTATION POSITIVE CONTROL for the 'hostConfigLoaded still present' claim: the same grep probe returns 0 matches on the absent direction, so it genuinely fails when the field is gone. ABLATION (process.exitCode = 1 -> 0 in refuseWhenHostConfigUnloadable): mutation proven on disk BEFORE any reading - anchor 'process.exitCode = 1;' count 1->0, injected marker count 1, blob hash 02c2d131->ba5fd538; restored via `git checkout HEAD --` on an ABSOLUTE path under an EXIT/INT/TERM trap and proven restored by blob-hash equality with the HEAD blob (02c2d131 == 02c2d131) + empty `git diff HEAD` + marker count back to 0 - not by the trap's exit code. Result: exactly 2 of 9 e2e cases RED (the two direction-1 exit-status pins for plan and apply); the other 7 GREEN, including BOTH of direction 2 and BOTH of direction 3 - the asymmetry the ruling's scope demands. NO REBUILD LEG NEEDED AND NONE SKIPPED: packages/cli/dist does not exist in this tree and the suite drives bin/run-dev.js (src through tsx), so src IS the artifact under test. PINS: new packages/cli/test/migrate-unloadable-host-config-exit.e2e.test.ts (9 cases, real child process, all three directions) + unit pins on describeUnloadableHostConfig in packages/cli/src/utils/schema-migration-plugins.test.ts (all three directions + message-less throw). TEST UNION at head 542756251: `pnpm --filter @objectstack/cli exec vitest run --maxWorkers=2` over the changed modules' blast radius (file set enumerated by grep -rln, with a nonsense-pattern positive control) - 9 files, 62 tests, ALL PASSED; os-verify-lock VERDICT command-exit 0. `pnpm --filter @objectstack/cli typecheck` - VERDICT command-exit 0. GATES (derived at head with `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack`, no stale-tree warning after merging origin/main): check:nul-bytes, check:cli-command-ids, check:cli-test-child-env (the three the dispatch named), plus check:cross-package-test-inputs, check:test-source-alias, check:type-check-coverage, check:objectql-double-limit, check:engine-double-contract, check:driver-memory-census, check:query-options-erasure, check:where-matcher, check:changeset-gate-self-tests, check:objectui-changeset, check:pm-half-states, check:published-files, check:page-declaration-shape, check:slot-lookup, check:type-source-resolution, check-adr-0087-registration, check-changeset-no-major, check-empty-changeset, check-ci-filter-parity, check-comment-mask-adoption, check-cross-package-test-inputs, check-keyed-text-bounds, check-plugin-teardown-shape, check-undeclared-dep-imports, check-shard-attestation, docs-audit/check-affected-docs, docs-audit/check-drift-comment, release-rehearsal-clone --self-test - ALL GREEN (exit codes captured before any pipe).",
 "not_measured": [
 "check:type-check-debt - its --re-measure REFUSED to run: the workspace build closure is unbuilt (@objectstack/service-knowledge has no dist), and it says a number taken from here would measure a different world. NOT a red gate. Its structural half, check:type-check-coverage, IS green. Residual risk closed by hand: the new e2e file lands in packages/cli/test/**, which the @objectstack/cli TEST_DEBT ratchet freezes at 146 errors; tsc --listFiles proved that file is absent from the package's typecheck program (tsconfig include: [\"src\"] - a known, ledgered shape), and type-checking it standalone under the package's compiler options gave ZERO errors, with a deliberately broken copy as the positive control that the probe can fail.",
 "check:i18n, check:i18n-coverage, check:dual-build-cjs-loads - all three printed PREREQUISITE NOT MET (they read built output; packages/cli/dist absent). Each states in its own words that nothing was measured. Attempting the CLI build to satisfy check:i18n hit os-verify-lock exit 99 (queue-timeout, 540s, holder was another agent running the full @objectstack/cli test suite) - DECLARED NARROWING, left to CI. Low risk: the change adds no i18n-keyed message and no declared label; the new stderr line is a plain console.error, the same shape as the sibling warning beside it.",
 "scripts/pm/check-half-states.mjs - exit 3, PREREQUISITE NOT MET: no valid GitHub credential in this container; it states 'no reading at all'.",
 "check-test-completeness - a CI harness that takes a turbo test log as an argument; invoked bare it prints usage. A mis-invocation, not a failed measurement.",
 "The 14 remaining packages/cli test files that reach the changed modules (of 23 enumerated by grep -rln) were NOT run locally - DECLARED NARROWING. The lock queue made a fuller run unaffordable in one turn (a sibling agent held it 645s running exactly that suite). CI runs the farm regardless."
 ],
 "open_questions": [
 {
 "question": "The ruling fixes the exit STATUS for `os migrate apply`, but does not say whether apply should also decline to PERFORM the DDL on the unloadable-config path. Today (and in this PR) apply still flushes the deferred schema work and applies drift over the reduced set, then exits non-zero.",
 "options": [
 "A - leave as shipped: apply does exactly what it did before and reports non-zero. Minimal, literally the ruling, nothing regresses relative to today (the same DDL ran before, silently, with exit 0).",
 "B - refuse before mutating: apply exits non-zero without touching the database. Reads more naturally as 'a migration tool refusing an UNMEASURED run', but it is a second behaviour change the ruling did not make, and it stops config-broken deployments from getting their platform floor created."
 ],
 "recommendation": "A, as shipped - it is the literal ruling and strictly an improvement over today. Flagging B because 'exit non-zero after having written DDL' is an odd contract for a mutating command, and that axis genuinely was not ruled on. Not blocking; a maintainer call for a follow-up card if PM wants it."
 }
 ],
 "out_of_scope_findings": []
}

---

Generated by Claude Code