os migrate meta --from <N> cannot load the retired-key sources it exists to fix — validates through the post-retirement schema before converting

Extracted from the Tier-2A run record #9417 (QA wave #9296), where it is the round's single clause failure — cli.migrate-meta-codemod (P1, rev 1), clauses 1 & 2. Subject sha e4e5c6e3c608b1b807c83a0d5b734f213eb1a1dd.

The defect

os migrate meta --from <N> loads the stack config through the current, post-retirement schema before any conversion runs. A source carrying a retired key therefore fails validation and the command exits 1 having rewritten nothing.

That input — a source with retired keys — is the only input the command exists to handle.

Why it matters more than a P1 usually does

The refusal it prints is the very instruction that sends people there. Run \os migrate meta --from ` to rewrite existing sources automaticallyappears **144 times across 39 files** underpackages/spec/src(verified independently of the run:git grep -c "os migrate meta --from" origin/main -- packages/spec/src`). Every one of those retirement messages promises an automatic fix that the tool cannot perform on the input it was told to fix.

So the user-visible loop is: author hits a retired key → spec tells them to run the codemod → codemod refuses because of the retired key → spec tells them to run the codemod.

Evidence and controls (from #9417, reproduced twice)

The retired key is the source's only validation issue — nothing else in the file is invalid.
Same refusal at --from 17 and --from 3, so the ADR-0087 floor check is not the gate either; the failure is upstream of version dispatch.
--out is not implicated.
The command behaves normally on a clean tree, so it is not broken generally — only on the input class it targets.

Not yet probed

The --stored arm (replaying over sys_metadata rows) is a different code path and was not exercised. Worth a probe before the fix is scoped: if it shares the pre-validation step it has the same defect; if it does not, the fix may only need to bring the file arm in line with it.

Fix direction (not prescribed)

The conversion must run before the source is validated against the current schema, or the load must be tolerant of keys the target version retired. Whatever lands should be pinned by a test whose fixture is exactly the failing case — a source carrying a retired key, migrated end-to-end — since a test on a clean source passes today and proves nothing.

Left unlabelled for domain:*: routing is the triage seat's call (the fix lands in packages/cli, possibly with packages/spec retirement-message coordination). Priority likewise — filed P1 by its checklist item, but the 144 messages prescribing it are an argument for re-levelling that belongs to triage, not to the runner or the wave PM.

Triage: lands in packages/cli (migrate-meta codemod load path) ⇒ domain:cli, type Bug, pm:queue, target:v17. Board rationale (binary test, classes ① and ④): the 144 shipped retirement messages across packages/spec/src direct every author who hits a retired key to a command that refuses that exact input — the v17 upgrade path dead-loops on day one, and it is a release-notes apology if shipped. Dispatch note: first probe the --stored arm (per the card's "Not yet probed") — it decides whether the fix is one arm or two; the pin fixture must be a retired-key source migrated end-to-end. If the fix needs packages/spec retirement-message coordination, that half transfers to the spec seat — the CLI half must not edit spec.

Triage seat routine — session session_pm_triage_20260818T0104Z.

Generated by Claude Code

Claim: PM loop round 14
Session: session_012WKSnqAaoqtW3QX7SSf1Vk
Branch: claude/issue-9418-migrate-meta-retired-key-load
Worktree: objectstack-issue-9418
Domain: domain:cli
File surface: packages/cli/src/commands/migrate/meta.ts, packages/cli/src/utils/ (load/validate helpers it calls), packages/cli/test/migrate-meta.e2e.test.ts (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus
Serial constraints cleared: packages/cli — no in-flight claim on this package (#8928 landed 51cd953fb; #9451 is the other packages/cli queue card and is deliberately held back this round for same-package serialization). No sibling card pins the codemod's load behaviour.

Tier derivation (node scripts/pm/dispatch-gates.mjs --tier packages/cli/src/commands/migrate/meta.ts, run now, not recalled): "no path-derived mandate … the tier stays the PM's per-card judgment call."

Clause ②: no — and this is the reasoning, so it can be falsified. The one question is does the set of accepted requests change? For a contract surface the answer here would be yes-shaped: the codemod would start accepting retired-key sources it refuses today. It is nevertheless the declared = enforced restoration half of the mechanical boundary test, not a widening: 144 shipped retirement messages across 39 files in packages/spec/src already declare that this command handles exactly that input (re-counted on origin/main this round — 39 files / 144 occurrences, matching the card exactly). The triage seat flagged Clause-② explicitly on #9416 and #9446 and did not flag it here; that asymmetry is evidence, not silence. If the implementation finds that the fix widens what os migrate meta accepts beyond what those messages promise, stop and report — that is a tier error to correct, not a scope call to make.

Stale-premise check on origin/main (8a56ad5a1): packages/cli/src/commands/migrate/meta.ts last moved in 445ae4deb (an unrelated locale fix), so nothing has repaired the load path since the card was filed. The card's own evidence re-measured and confirmed.

Generated by Claude Code

fix(cli): os migrate meta can open the retired-key sources it exists …

{
  "issue": 9418,
  "status": "done",
  "branch": "claude/issue-9418-migrate-meta-retired-key-load",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/9530",
  "premise_still_valid": true,
  "summary": "Reproduced on origin/main first: a defineStack config carrying agent.knowledge exits 1 at load, printing the very prescription that sends authors there. ONE ZONE-2 ASSUMPTION FALSIFIED: there is no CLI-side pre-validation step to reorder - loadConfig() validates nothing and meta.ts validates nothing before the chain. The gate lives INSIDE the loaded config module, because retiredKey() is a z.never() tombstone that the schema rejects rather than strips, and every define* helper is a Schema.parse() that a real objectstack.config.ts runs itself (os init scaffolds defineStack; the example apps import defineView/defineAgent from spec SUBPATHS). That is why only the card's second direction was available: loadConfig() gains an opt-in authoredSource mode, set by os migrate meta alone, that shims every @objectstack/spec entrypoint (root and subpaths) so define* helpers are try-real-then-authored - the real helper runs first, and only an artifact the current schema refuses is handed on as authored, with the swallowed verdict on stderr. NO WIDENING (clause 2 holds): a source that loads today loads identically, validation is moved after the conversion rather than skipped (schemaValid is still taken on the migrated stack), and os build/validate/serve keep the strict load - pinned in both directions.",
  "tests": "All at final head 1644f27c8, after the last commit. (1) PIN FAILS ON UNPATCHED MAIN - reverse-verified from the COMMITTED state with both source files restored to origin/main and the test kept: 'test/migrate-meta.e2e.test.ts (14 tests | 1 failed | 12 skipped) x loads it, converts it, and reports the migrated stack schema-valid / Error: Command failed: ... migrate meta --from 16 --json --out ...'. Predicted direction held on BOTH halves: the migration pin turned red, the os validate control stayed green (1 failed | 1 passed | 12 skipped). Restoring the fix left the tree byte-identical to the commit (git status empty). (2) pnpm --filter @objectstack/cli test: 'Test Files 132 passed (132) / Tests 1418 passed (1418)'. (3) vitest run test/migrate-meta.e2e.test.ts: 14/14 passed. (4) pnpm --filter @objectstack/cli typecheck: exit 0, script name echoed (not a zero-match filter). (5) Gate union RE-DERIVED from the actual changed paths via scripts/pm/dispatch-gates.mjs, not recalled - check:nul-bytes, check:cross-package-test-inputs, check:query-options-erasure, check:engine-double-contract, check:where-matcher, check:type-check-coverage, scripts/docs-audit/check-affected-docs.mjs: all exit 0. Two ratchets report 'baseline key set verified against 6ce8feb: no files added'. (6) check:type-check-debt on the BUILT closure (turbo run build, 'Tasks: 70 successful, 70 total' first): '33 ledger entr(ies) re-measured in 223.9s, 1926 raw tsc error(s) total, none above its recorded number'. (7) eslint --no-inline-config clean on the three changed files - that is eslint, NOT the whole Lint & Repo Gates family; the derived members of it are listed above. No ablation was run: this is a load-path fix with no dist-resolved dogfood assertion. --STORED ARM VERDICT: NOT affected, probed empirically rather than read - runStored() never calls loadConfig(); it boots createStandaloneStack from the compiled artifact dist/objectstack.json and replays the chain over sys_metadata rows. Run in the very project dir whose config carries the retired key: 'Examined 0 stored metadata row(s) ... / No stored metadata to examine (1157ms)' EXIT=0. It never opened that file, so the fix is ONE ARM, not two.",
  "open_questions": [],
  "out_of_scope_findings": [
    "filed as #9529: the same 144 retirement messages promise the tool 'rewrites your source files' and it does not - --out writes a JSON snapshot and objectstack.config.ts is never touched (no --write/--fix flag; os lint --fix is itself a dry run). Pre-existing, downstream of this card, filed unassigned with a Blocked-by: #9418 line and no labels; both resolutions touch a maintainer-ruled sentence, so it is not an implementer's call.",
    "NOT filed - hypothesis measured and FALSIFIED: defineStack's load-time ADR-0087 D2 pass does not pre-apply conversions the chain would otherwise attribute, so meta.ts's convert:false attribution invariant is not defeated for real configs. Same key through defineStack vs a bare literal both reported 'applied: action-execute-to-target'. No defect, so no issue."
  ]
}

Generated by Claude Code

ACCEPT (substance) — PR #9530. Round 14, session session_012WKSnqAaoqtW3QX7SSf1Vk. ⛔ Not enqueued yet: Build Core is green and nothing is red, but five of the six required checks are still running.

The card's diagnosis was wrong, and the dev proved it rather than working around it

Both the card and my dispatch brief described "a single pre-validation step on the file arm, upstream of version dispatch" — and my Zone 2 explicitly invited falsification if the load path validated somewhere else. There is no such step. loadConfig() validates nothing and meta.ts validates nothing before the chain. The gate lives inside the loaded config module: retiredKey() is a z.never() tombstone that the schema rejects rather than strips, and every define* helper is a Schema.parse() that a real objectstack.config.ts runs itself — os init scaffolds defineStack, and the example apps author through spec subpaths (/ui, /data, /ai). So the refusal fires during bundleRequire evaluation, before the command's first statement.

⭐ That is why the card's two offered directions were not symmetric, which neither the card nor I noticed: "run the conversion before validating" has nothing in CLI code to reorder. Only the second direction was ever available. The correction also retro-explains every control the card recorded — same refusal at --from 17 and --from 3, --out not implicated, normal on a clean tree — all consistent with a failure that precedes the command entirely.

What I verified myself rather than taking on report

My brief made this card's whole tier ruling conditional on one thing: "if the fix widens what os migrate meta accepts beyond what those messages promise, STOP and report." The dev did not stop; it argued containment. I checked the argument, both halves:

The tolerance is genuinely opt-in. authoredSource is set at exactly one call site — meta.ts:308, os migrate meta alone. Control: 15 files under packages/cli/src call loadConfig, so the other 14 keep the strict default and os build / validate / serve still hear the tombstone. The claim is not asserted, it is structural.
Validation is moved, not skipped. The migrated stack is still ObjectStackDefinitionSchema.safeParsed at :321 and reported as schemaValid at :341. The final verdict still comes from the schema; a source broken for reasons the chain cannot fix is still reported broken, just after the codemod has done its part.
The shim really tries the real helper first — return __real.${name}(...authored), falling back to authored[0] only on throw, with the swallowed verdict on console.warn. So a source that loads today loads identically, defaults and transforms included; only an artifact the current schema already refuses takes the new path.

Clause ② ruling therefore stands: declared = enforced restoration, not a widening. Recorded because it was ruled in advance and could have gone the other way.

⚠️ Correction to my own claim comment on this card

I wrote that "144 shipped retirement messages across 39 files" declare this behaviour. "Shipped" was wrong. 33 of those 144, across 11 files, are *.test.ts fixtures. The shipped figure is 111 mentions across 28 files (of which 85 across 25 files carry the canonical promise sentence). My argument does not depend on the difference — 111 shipped mentions still send every v17 author into the dead loop — but the number was load-bearing enough that it propagated into #9529 as a promise count, where it is wrong in a way that mis-prices one of that card's two resolutions. Corrected in full there. ⇒ A count is a reading too: state its population, or it will be reused against a different one.

Zone 1 items, all three discharged

--stored probed empirically, not read — runStored() never calls loadConfig(); it boots createStandaloneStack from the compiled dist/objectstack.json. Run in the very project dir whose config carries the retired key, it never opened that file (EXIT=0, "No stored metadata to examine"). One arm, not two.
The pin fails on unpatched main — reverse-verified from the committed state with both source files restored: the migration case turns red, and the os validate control stays green, the predicted asymmetry on both halves. Restoring left the tree byte-identical.
⭐ And the shipped suite could not have caught this, which is the finding underneath the fixture requirement: migrate-meta.e2e.test.ts already had a v17 conversion suite that passed on a build where the command could not open a single real project — because its fixture was a bare export default { ... } literal, and a bare literal is validated by nobody at load. Exactly the "passes on unpatched main and proves nothing" shape the card warned about. The new fixture is shaped like a real project (defineStack root + helpers imported from a spec subpath), and a tolerance scoped to defineStack alone fails it.
⛔ packages/spec untouched, as required. Changed files: changeset, meta.ts, utils/config.ts, the e2e test.

Follow-ups

os migrate meta never rewrites the authored sources that 144 shipped retirement messages promise it will #9529 filed correctly — pre-existing, out of scope, Blocked-by: #9418, unassigned, no labels. ⚠️ It raises a live target:v17 board question (this card's fix clears the hard failure but does not make the shipped sentence true); ⛔ that is the triage seat's to answer, flagged there and escalated in the round report.
One hypothesis measured and falsified rather than filed: defineStack's load-time ADR-0087 D2 pass does not pre-apply conversions the chain would otherwise attribute (same key through defineStack vs a bare literal both reported applied: action-execute-to-target). No defect ⇒ no issue. Correct call — a filed non-defect costs a triage slot.
Docs Drift Check listed 13 advisory pages and 2 release-owned ones. ⛔ The release pages were correctly not touched; this PR edits no docs at all.

Generated by Claude Code

LANDED — PR #9530 merged to origin/main @ 994e917f5 (07:52:46Z). Card auto-closed completed. Round 14, session session_012WKSnqAaoqtW3QX7SSf1Vk.

Confirmed by the required two readings plus a probe for a symbol the PR introduced:

Queue/timeline — pull_request.closed, outcome merged. ⛔ Not the auto_merge field.
origin/main — merge commit 994e917f5.
Probe — authoredSource: 0 → 7 (meta.ts ×2, utils/config.ts ×5). Baseline taken before enqueueing, so the non-zero means landing rather than a pre-existing hit. Control: files containing loadConfig in packages/cli/src = 15, unchanged — which is itself a second reading worth having: the tolerance added no new call sites, so it did not spread while landing.

The containment was re-verified ON MAIN, not carried over from the branch

This matters here because main absorbed another merge (91c6c2880) between my pre-merge check and this one. Both properties the Clause-② ruling rests on still hold on the merged result:

authoredSource: true is set at exactly one call site — meta.ts:308. The other 14 loadConfig callers keep the strict load, so os build / validate / serve still deliver the tombstone as the upgrade channel.
The migrated stack is still ObjectStackDefinitionSchema.safeParsed at meta.ts:321. Validation moved after the conversion; it was not removed.

⇒ A pre-merge verification of a soundness property is not a post-merge verification of it. The queue merges onto a moving base, and the property could have been weakened by someone else's landing in between. Cheap to re-run, so re-run it.

⚠️ Board handoff — `target:v17` is NOT automatically discharged by this closure

This card carries target:v17 and is now closed, so the board reads clear. It should not be assumed clear without triage looking at #9529.

What landed fixes the hard failure: the codemod now opens the retired-key sources it exists to handle. What it does not do is make the shipped prescription true — os migrate meta still never rewrites objectstack.config.ts or the per-artifact modules; --out writes a JSON snapshot, in a shape the sources are not authored in, and there is no --write / --fix flag (probed on origin/main, zero hits, against a control listing the ten flags the command does declare).

So an author following the prescription still hand-edits every file. That is declared ≠ enforced on a public surface — board class ② — on the same v17 upgrade path this card was boarded for. ⛔ This seat does not produce target:* (one producer per board, the triage seat), so I am neither moving the label nor grading #9529 — flagging it so the closure is not silently read as the board item being discharged.

Also corrected on #9529: the "144 messages across 39 files" figure — mine originally, and it counts test fixtures and non-promise mentions. Shipped is 111 mentions / 28 files, of which 85 / 25 carry the canonical sentence. The difference mis-prices one of that card's two resolutions.

What the dev got right that the card did not

The card's stated diagnosis — "a pre-validation step, upstream of version dispatch" — does not exist. The tombstone is a z.never() inside the loaded config module, because every define* helper is a Schema.parse() the author's own config runs. So of the two fix directions the card offered, only one was ever available, and the card's own controls (same refusal at --from 17 and --from 3, --out not implicated, normal on a clean tree) all retro-explain as a failure that precedes the command entirely.

The --stored arm was probed empirically rather than read and is unaffected — runStored() boots from the compiled dist/objectstack.json and never opens the config. One arm, not two, as triage asked.

And the pin now fails on unpatched main — reverse-verified, migration case red, os validate control green. ⭐ The shipped suite could not have caught this: its fixture was a bare export default { ... } literal, and a bare literal is validated by nobody at load, so a v17 conversion suite passed green on a build where the command could not open a single real project.

Generated by Claude Code

fix(cli): os migrate meta can open the retired-key sources it exists …

test(cli): the retired-key e2e fixture uses a retired member with no …

Navigation Menu

Repository navigation

`os migrate meta --from <N>` cannot load the retired-key sources it exists to fix — validates through the post-retirement schema before converting #9418

The defect

Why it matters more than a P1 usually does

Evidence and controls (from #9417, reproduced twice)

Not yet probed

Fix direction (not prescribed)

The card's diagnosis was wrong, and the dev proved it rather than working around it

What I verified myself rather than taking on report

⚠️ Correction to my own claim comment on this card

Zone 1 items, all three discharged

Follow-ups

The containment was re-verified ON MAIN, not carried over from the branch

⚠️ Board handoff — `target:v17` is NOT automatically discharged by this closure

What the dev got right that the card did not

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

os migrate meta --from <N> cannot load the retired-key sources it exists to fix — validates through the post-retirement schema before converting #9418

Description

The defect

Why it matters more than a P1 usually does

Evidence and controls (from #9417, reproduced twice)

Not yet probed

Fix direction (not prescribed)

Activity

os-zhuang commented on Aug 18, 2026

os-zhuang commented on Aug 18, 2026

claude commented on Aug 18, 2026

os-zhuang commented on Aug 18, 2026

The card's diagnosis was wrong, and the dev proved it rather than working around it

What I verified myself rather than taking on report

⚠️ Correction to my own claim comment on this card

Zone 1 items, all three discharged

Follow-ups

os-zhuang commented on Aug 18, 2026

The containment was re-verified ON MAIN, not carried over from the branch

⚠️ Board handoff — target:v17 is NOT automatically discharged by this closure

What the dev got right that the card did not

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

`os migrate meta --from <N>` cannot load the retired-key sources it exists to fix — validates through the post-retirement schema before converting #9418

⚠️ Board handoff — `target:v17` is NOT automatically discharged by this closure