objectstack-upgrade

プロトコルのメジャーバージョンをまたいで ObjectStack メタデータプロジェクトをアップグレードする

事前確認 → 機械的な変換チェーン → 意味上の残課題 → 受け入れレポート

⛔ 境界 — 最初のコマンドを実行する前にお読みください

変換チェーンがすでに適用する書き換えを、手作業で行ってはいけません。 キーの名前が変更された場合、変換テーブルにその変更が記録されています。チェーンを実行すれば、各書き換えがどの段階で行われたかが明示され、結果がスキーマに適合することも確認できます。手作業で編集してもどちらも得られず、チェーンに項目が追加された瞬間、気付かないうちに差異が生じます。

古いメタデータを読み込ませるために、寛容な読み取り処理を追加してはいけません。 ?? によるエイリアス、「両方の表記を受け入れる」分岐、プロジェクト独自のコード内での型変換は、いずれも追加してはいけません。キーが廃止されたのは、それを強制するものがなかったか、表記が一つだけ残るためです。利用側で古い表記を再び受け入れると、廃止によって解消した不具合が顧客のリポジトリ内に再発し、どのゲートでも検出できなくなります。

残課題の項目を、所有者の意図を推測して解決してはいけません。 残課題があるのは、それがビジネス上の判断だからです。自分で判断する場合と確認を求める場合のルールは、レイヤー 2 に記載されています。このスキルで最も重要な段落です。

受け入れ成果物なしに「アップグレード済み」と報告してはいけません。 validate が成功し、レポートが揃っていることが機械的な判定基準です。どちらかが欠けていれば、差分の状態にかかわらず、ステータスは進行中です。

可能であれば、コミットごとに conversionId を一つにしてください。 この ID がコミットの件名であり、コミットの根拠になります。

---

クイックスタート

# 0 · preflight — what major is this project on, what major is installed?
grep -rn "protocol" objectstack.config.ts package.json | head
node -p "require('@objectstack/spec/package.json').version"

# 1 · mechanical — replay the chain (writes only --out; --write also rewrites the sites it can prove)
os validate > .upgrade/validate-before.txt 2>&1 || true   # the control, kept
os migrate meta --from 16 --step
os migrate meta --from 16 --json > .upgrade/migrate.json
os migrate meta --from 16 --out .upgrade/migrated.stack.json

# 2 · semantic residue — harvest the prescriptions, then work each item
node -e "console.log(require('fs').readFileSync(require.resolve('@objectstack/spec/package.json').replace('package.json','spec-changes.json'),'utf8'))" > .upgrade/spec-changes.json

# 3 · acceptance — all four, not three
os validate                      # green (compare against validate-before.txt)
tsc --noEmit                     # tombstones type the retired keys as `never`
os migrate meta --from 17 --json # `applied` must be [] (see §3.3)
# → write .upgrade/REPORT.md (template in §3.4)

---

0 · 事前確認

FROM メジャーバージョンを確認する — 推測してはいけません

--from はインストールされているプロトコルのメジャーバージョンではなく、メタデータが作成されたプロトコルのメジャーバージョンです。信頼度の高い順に、次の 3 つの情報源を確認します。

1. スタック設定の manifest.engines.protocol — 起動時のハンドシェイクで確認される、宣言上の値です。これはバージョンではなく範囲です。すべてのスキャフォールドとサンプルではキャレット形式（engines: { protocol: '^17' }）が使われ、正確な値 '16.0.0' も範囲が一つだけの指定にすぎません。対象とするメジャーバージョン、つまり下限を使います。'^17' → --from 17、'>=15 <18' → --from 15 です。上限を使ってはいけません。
2. プロジェクトが過去にインストールした最新の @objectstack/spec メジャーバージョン — マニフェストがない場合や古い場合は、ロックファイルの履歴を確認します（git log -p pnpm-lock.yaml | grep -m5 '@objectstack/spec'）。
3. 確認する。 2 年前に最後に更新されたプロジェクトのマニフェストに 16 と記載されていても、それは主張であり、実測値ではありません。（1）と（2）が食い違う場合は解決してください。⛔ 低い方を既定値にしてはいけません。既定値の切り替え（3.3）によって、すでにそのメジャーバージョンを超えたソースに制約が適用されてしまいます。

複数のメジャーバージョン分の遅れは、この仕組みが想定するケースです。os migrate meta --from 16 は、メジャーバージョンごとに一つずつアップグレードする必要なく、サポート対象の下限（現在は 16）までのすべてのステップを順番に再実行します。

変更前に、レビューできる状態を整える

git checkout -b upgrade/protocol-17
mkdir -p .upgrade

.upgrade/ ディレクトリは、成果物の作業場所です。機械的な出力（migrate.json、migrated.stack.json、spec-changes.json、retired-names.txt）と、人が作成する出力（REPORT.md）を格納します。レビューのためにリポジトリに残し、マージ時に削除するのが一般的な運用です。所有者と相談して決めてください。

移動後のカタログからスキルを再インストールする

17.x プロジェクトのスキルは skills add から追加されており、skills-lock.json のエントリーは sourceType: github となっています。そのため、同期ではスキップされ（終了コード 0）、エージェントは 17.x のスキルテキストを読み続けます。スキルを削除し（存在しない名前はスキップされます。プロジェクトのスキルがそれだけの場合は --all を指定します）、インストール済みの spec と同じバージョンの @objectstack/skills を追加して、コピーします。

npx skills remove objectstack-ai objectstack-api objectstack-automation \
  objectstack-data objectstack-formula objectstack-i18n objectstack-platform \
  objectstack-pm-dispatch objectstack-query objectstack-ui objectstack-upgrade -y
npm install --save-dev "@objectstack/skills@$(node -p "require('@objectstack/spec/package.json').version")"
npx [email protected] experimental_sync --agent claude-code --copy -y

---

1 · 機械的なレイヤー — 変換チェーンを実行する

os migrate meta の実際の動作

os migrate meta --from 16                       # replay 16 → current
os migrate meta --from 16 --step                # per-hop checkpoint (bisect a failure)
os migrate meta --from 16 --to 17               # stop at a specific major
os migrate meta --from 16 --json                # machine-readable result
os migrate meta --from 16 --out migrated.json   # write the canonicalized stack
os migrate meta --from 16 --write               # rewrite the proven sites in place
os migrate meta --from 16 apps/crm/objectstack.config.ts   # pick the stack explicitly

スタック設定を読み込み、読み込み時の変換パスを適用せずに正規化し、各メジャーバージョンの変換をチェーンの各段階として再生してから、現在のスキーマに対して結果を解析し、出力が有効であることを検証します。出力される内容は次のとおりです。

• Applied N mechanical change(s) — 書き換えた箇所ごとに、path: from → to (conversionId) の形式で1行ずつ表示します。これはすでに変更元が明示された差分です。
• N manual change(s) require your judgment — 通過したメジャーバージョンに関するチェーンの意味的な項目です。それぞれに why と verify の行があります。これはレイヤー2への入力であり、無視してよい警告ではありません。
• Migrated stack is schema-valid — または、まだ有効ではないという警告が表示されます。これは残存項目が解析を妨げていることを意味します。
• 保留中のデータ移行 — チェーンがデプロイメントごとのデータゲートを持つメジャーバージョンに移行する場合に表示されます。詳細は以下を参照してください。

⚠ すべての運用担当者が驚く、ひとつの事実

デフォルトでは、os migrate meta はソースファイルを書き換えません。 機械的な編集内容を一覧表示し、--out の JSON スナップショットのみを書き込みます。--write を指定すると、1つのプロジェクトファイル内の1つのリテラルに追跡できる編集だけをその場で書き換え、書き込まなかった編集は理由とともにすべて一覧表示します。意味的な変更は決して書き込みません。また、書き込み済みファイルに対してチェーンを再実行した結果が一致しない場合は、すべてのファイルを復元して終了コード1で終了します。

保存済みの行：再水和では同じ変換が再生されます

デプロイメントの sys_metadata 行も対象です。読み込み時に自動的に処理されます。メタデータローダーと ObjectQL プラグインは、保存済みの各行に対して applyConversionsToStoredItem を通し、読み込みパスから削除された項目も含めて、1つの項目に変換チェーンを再生します。そのため、プロトコル16で書き込まれた行は、誰も編集しなくてもプロトコル17の形式で再水和されます。

再水和は読み込み時の投影です。ディスク上の行は古い形式のままであり、sys_metadata を手動で編集することはありません。変更を永続化するには、デフォルトで読み取り専用の保存済みデータ向けパスを実行します。

os migrate meta --stored                     # preview, writes nothing
os migrate meta --stored --type view --type object   # narrow the pass
os migrate meta --stored --apply --yes       # rewrite the rows

⛔ --yes は必須です。 指定しない場合、--apply は確認を求めます。また、TTY ではない環境（すべてのエージェントセッションが該当します）では確認を求められないため、代わりに confirmation_required で終了コード1を返して拒否します。

--stored では --from は指定しません。保存済みの行にはそれ自体の履歴があるため、このパスではチェーン全体を再生します。

データ移行はメタデータ移行ではありません

チェーンがデプロイメントごとのデータゲートを持つメジャーバージョンに移行すると、実行結果の最後に、各ゲートの名前、未実行のままにした場合の影響、および書き込みを行う唯一のモードが --apply であることが表示されます。内容を独自に再導出せず、その出力を確認してください。出力からは、それらが実行済みかどうかはわかりません。各デプロイメント固有のデータベースに対して実行されるものであり、メタデータのアップグレードでは実行状況を確認できません。

⛔ 実行結果に表示されたすべてのゲートを、名前とともに pending としてレポートに記載してください。 誰にも知らされていないゲートは、誰にも対応されません。

---

2 · 意味的な残存項目 — あなたが対応する部分

変換によってキーの名前を変更したり、不要になったキーを削除したり、値を宣言済みのブロックに移動したりできます。しかし、判断を下すことはできません。変換で処理できないものは、すべてここに残ります。

2.1 指示の参照元をすべて集める — すべてパッケージに含まれています

指示は、オンラインでアクセスする必要があるドキュメントサイトにはありません。インストール済みパッケージに含まれています。公開されている @objectstack/spec のファイル一覧に照らして実測した結果は次のとおりです。

参照元	利用プロジェクト内の場所	含まれる内容
チェーンの結果	os migrate meta --from N --json → .specChanges	越えるメジャーバージョンに該当する変換と意味上の項目。まずここを確認してください — インストール済みの仕様から算出されるため、古くなることはありません。
D4 の投影	node_modules/@objectstack/spec/spec-changes.json	すべてのメジャーバージョンに対応する同じデータをオフラインで確認できます：perMajor[].converted と perMajor[].migrated。
廃止項目の修正指示	node_modules/@objectstack/spec/json-schema/** および src/**/*.zod.ts	廃止された各キーの [REMOVED] … 修正指示テキスト。検索できます。
FROM → TO テーブル	node_modules/@objectstack/spec/CHANGELOG.md	「代わりに何を書くか」のテーブルを含む、廃止項目ごとの説明。これがパッケージに変更履歴が含まれている理由です。
エラーそのもの	パース時または tsc の出力	エラーに遭遇した時点で表示される、同じ修正指示文字列です。

# every tombstone prescription the installed spec carries, deduped (`| wc -l` sizes it)
grep -rho '\[REMOVED\][^"]*' node_modules/@objectstack/spec/json-schema/ | sort -u

# protocol version, support floor, and this crossing's conversion / semantic counts
node -e "
  const p = require.resolve('@objectstack/spec/package.json');
  const j = require(p.replace('package.json','spec-changes.json'));
  const to = parseInt(j.protocolVersion, 10);
  const e = j.perMajor.find(x => x.to === to);
  console.log(j.protocolVersion, 'floor', j.supportFloor, '| →', to + ':',
              e.converted.length, 'converted,', e.migrated.length, 'semantic');
"

# the FROM → TO table for one retired key
grep -n -B4 -A20 'transform' node_modules/@objectstack/spec/CHANGELOG.md | less

⛔ 覚えている件数や固定のテーブルをレポートに持ち込まないでください。 ここに示すすべての数値は、このインストール環境から読み取ったものです。アップグレード開始時に測定し、レポートでもう一度測定してください。

利用プロジェクトからはアクセスできないため、誰にも案内しないでください：変換およびマイグレーションのレジストリ（src/conversions/registry.ts、src/migrations/registry.ts）と、プラットフォームリポジトリで生成されるアップグレードガイドは、公開パッケージに含まれていません — 含まれているのは src/**/*.zod.ts だけです。利用者向けの投影は spec-changes.json と、チェーン自身の --json 出力です。

2.2 3 種類の残存項目

R1 · 意図の選択 — 単一の損失のない移行先がないままキーが廃止された場合。 変換によってキーは削除されるため（プロジェクトはパースできます）、重要な場合は該当箇所を示す通知が出力されます。そのキーの用途は、どこかに引き継ぐ必要があります。どこに引き継ぐかは、ビジネス上の判断です。

R2 · 廃止された API を呼び出すカスタムコード。 チェーンの意味上の項目には、これらが記載されています：存在しなくなったサービススロット、削除されたエンジンのメソッド、名前が変更されたコンテキストフィールド。メタデータは問題なくパースできますが、プロジェクト独自の TypeScript でエラーが発生します — あるいはさらに悪いことに、コンパイルが通ったまま undefined を読み取ります。

R3 · 古い形式を教え続ける文章。 README、コメント、ADR、シード用フィクスチャ、そしてプロジェクト独自の AI 規約ファイルです。何も失敗しないため、次にリポジトリを読むエージェントが、そこから廃止された形式を再び作成してしまいます。

→ references/examples-upgrade.md § 2.3 の R1 の例 — 廃止されたフィールドマッピング transform へそのまま移動しました。

2.4 自分で判断するか、所有者に確認するか

次の3つすべてに当てはまる場合は、自分で判断してください。

1. 移行指示で対象が1つだけ指定されています。 墓標または変換の概要で FROM → TO が1つだけ示され、値は変更されません。
2. 根拠がプロジェクト内にあります。 リポジトリ内を grep すれば判断できます。すでにそのツールを担当しているスキル、すでに存在するインポート、述語がすでに参照しているフィールドなどです。
3. 誤った判断をするとゲートで失敗します。 選択を誤ると、挙動がひっそり変わるのではなく、tsc または validate で失敗します。

次のいずれかに当てはまる場合は、所有者に確認してください。

1. 実際に使える対象が2つ以上あり、その選択がビジネス上の判断になる場合 — 上記の transform のケースです。
2. テストが失敗しなくても変更を検知できる場合 — セキュリティ態勢（認証の既定値）、行の可視性（アクセス述語）、再試行回数、保持期間などです。ここで判断を誤ると、問題に気づかないままリリースされ、監査で発覚します。
3. 新しい場所で機能を再宣言する必要があり、選択を誤るとビルドが失敗するのではなく機能が失われる場合。 特定のスキル内に移動する必要があるエージェントツールが、典型的なケースです。
4. プロジェクト内の元のコードが使われていないか、文書化されていない場合 — 判断材料がありません。その旨を伝え、根拠を作り出さないでください。

確認の方法。 項目ごとに1通のメッセージを送り、対象箇所（ファイルとパス）、移行指示の原文、各選択肢で発生するコストを含む選択肢一覧、推奨案とその理由、選択後に何を検証するかを記載してください。「transform をどう扱えばよいですか？」だけの確認は避けてください。差分について最も詳しくない人に、読み解く作業を押し戻すことになります。

返答を待つ間も、アップグレードを停滞させないでください。 項目をレポートで AWAITING DECISION として保留し、機械的な作業を完了させて、そのまま進めてください。未解決の項目が残っていても、プロジェクトのスキーマは有効にできます。ただし、その状態はまだ 完了 ではありません。

2.5 R2 への対応 — プロジェクト独自コード内の廃止 API

チェーンの意味的なエントリーが検索対象の一覧です。それぞれについて、指定された箇所をプロジェクト独自のソース内で grep して検索します。

# from the chain's own output — the surfaces it says it cannot fix for you
os migrate meta --from 16 --json | node -e "
  let s=''; process.stdin.on('data',d=>s+=d).on('end',()=>{
    for (const t of JSON.parse(s).todos) console.log(t.surface);
  })"
# then, for each surface, search the project (not node_modules)
grep -rn "<surface-token>" src/ app/ --include='*.ts' --include='*.tsx'

実際のアップグレードで何度も問題を起こしてきた落とし穴が1つあります。名前を変更すれば解決するとは限りません。 古い読み取り処理自体が誤っていた場合、それを改名すると、コードではなく不具合を移行することになります。replacement を適用する前に、意味的なエントリーの reason を読んでください。

2.6 R3 への対応 — プロジェクト全体の文言チェック

形が固まった後、最後に実行し、リポジトリ全体を対象にしてください。

# every retired key name the installed spec knows, as a search list
grep -rho '\[REMOVED\] `[^`]*`' node_modules/@objectstack/spec/json-schema/ \
  | sed 's/.*`\(.*\)`.*/\1/' | sort -u > .upgrade/retired-names.txt

その後、プロジェクトの *.md、コメント、シード用フィクスチャ、AI 規約ファイルをチェックしてください。中でも規約ファイルが最も重要です。次のエージェントは何かを書く前にこのファイルを読み込むため、ここに廃止された形式が残っていると、アップグレード完了後の次の機能開発で、コードベースに再び持ち込まれます。

---

3 · 受け入れ条件 — 「アップグレード済み」の意味

成果物は4つです。そのうち3つは機械的にチェックされ、残りの1つは人が読みます。

3.1 型チェック済み

tsc --noEmit

廃止されたキーは、単にスキーマに存在しないだけではありません。入力型が never の墓標として宣言されています。そのキーに何かを割り当てると、実行前に、記述した箇所でコンパイルエラーになります。したがって tsc の成功は、型付きソースに廃止されたキーが残っていないことを示す肯定的な証拠です。

3.2 パース時に検証

同じ墓標によってパース時にも拒否され、一般的な「認識されないキー」ではなく、移行指示を伴うエラーが返されます。この経路では、JSON ファイル、データベースの行、実行時に構築されるデータなど、tsc では検出できないメタデータを捕捉します。有効化のために特別な作業をする必要はありません。ただし、スキーマが入力を黙って削除する場合と受け入れる場合を見分けられないため、このプロジェクトで実際に機能していることを必ず確認してください。逆方向のチェックを参照してください。

3.3 検証

os validate            # green is the criterion
os validate --strict   # warnings become errors — agree with the owner whether this is the bar

os validate は、プロトコルスキーマ（tombstone が拒否する部分）と、作成時のルールセットの2段階で実行されます。それぞれを分けて読み取ってください。共有モデルがない、またはオプションがない選択肢フィールドに関するルールの指摘は、移行の残りではなく、既存のプロジェクト品質の問題です。どちらに該当するかを確認するには、開始前にアップグレード前のソースに対して os validate を1回だけ実行し、その出力を比較用として保存します。

⚠ validate が成功しても、チェーンに残作業がないとは限りません

一部の変換は移行チェーン専用です。ローダーは意図的にこれらを適用せず、古い形式に対して tombstone も拒否しません。名前変更ではなくデフォルト値の切り替えであるためです。自動適用すると、意図的に制約を省略しているソースにも制約が設定されてしまいます。16 → 17 の移行には、required が単独で暗黙に指定していた物理的な storage.notNull を書き込む field-required-notnull-explicit があります。

この形式のみを含むプロジェクトは、チェーンにまだ作業が残っていても、validate は成功します。つまり、validate の成功は必要条件ではありますが十分条件ではありません。この不足を補う基準となるのは、次の再実行です。

os migrate meta --from <target-major> --json   # `applied` が [] であること

見出しではなく applied を確認してください。--to のデフォルトは、このビルドにステップがある最も高いメジャーバージョンです。そのため、リリース系列の大半ではインストール済みのメジャーバージョンより1つ先になり、todos には次のメジャーバージョンの意味上の残りが含まれます。実在するものではありますが、このアップグレードの対象ではありません。

→ references/examples-upgrade.md § 3.4 The report — the human half. にそのまま移動しました。

3.5 ゲートが実際に機能することを確認する

証拠として報告する前に、パースゲートを1回作動させます。チェーンが変換するはずの値を1つ取り上げ、移行後に元に戻してからパースします。

# a stack that still carries a retired key, fed straight to the schema
os validate .upgrade/residue-probe.config.mjs

プローブはプレーンなデータリテラルとして記述してください。⛔ define* の呼び出しは使用しないでください。os validate は、作成済みソースモードを使わずに設定を読み込みます。また、すべての define* ヘルパーは Schema.parse() であるため、実際の設定と同じ形式で記述されたプローブは読み込み中に例外を発生させ、検証しようとしているゲートまで到達しません。

実行する前に結果を予測し、実際に得られた結果を記録してください。「成功した」は、表の各行で異なる事実を意味します。

結果	意味	受け入れの証拠
拒否され、エラーに修正テキストが含まれる	tombstone 化されたキーです。「認識されないキー」でも、非推奨ラベルでもありません。処方そのものがエラーです。	拒否の内容を引用します。
受け入れられ、チェーンが書き換える	読み込みパスに有効な受け入れ期間がある変換です。	パースゲートではなく、チェーンの差分です。
受け入れられ、validate が成功したまま	移行チェーン専用の変換（3.3）です。	この種の変換を検出できるのは、対象メジャーバージョンからの再実行だけです。

3.6 保存済みの行：信じるのではなく、アサートする

上記の4つの成果物は、作成済みのソースを対象としています。デプロイメントでは、保存済みデータのパス自体がアサーションです。読み取り専用で実行し、終了コードに応じて処理を分岐します。

os migrate meta --stored --json    # 0 = every row canonical, 1 = work left

これにより、「このデプロイメントはプロトコル N を使用している」ことを、単なる思い込みではなく CI のチェックにできます。実行済みであることを条件にするものはありません。読み取り時の再構築が引き続き保証となります。

---

→ references/examples-upgrade.md § The v17-canonical shapes, compiled. にそのまま移動しました。

---

障害モード

症状	実際の原因	対処法
migrate meta が変更を報告するが、ファイルは変更されない	想定どおりの動作です。デフォルトの実行では一覧を表示するだけです。	--write を渡すか、表示された編集内容を手動で適用します。その後、対象のメジャーバージョンから再実行し、変更が 0 件であることを確認します。
対象のメジャーバージョンから再実行しても変更が適用される	移植が不完全か、チェーンが認識していない形式からソースが実行時にメタデータを構築しています。	--out と比較し、メタデータを動的に構築するコード内で conversionId の使用箇所を grep します。
validate は成功するが、機能が気付かないうちに動作しなくなった	R2 の残存項目です。名前が変更されたキーを読み取るコードが、undefined を読み取るようになっています。	実際にその経路を実行します。解析が成功しても、プロジェクト独自のコードにある ?? チェーンについては何も分かりません。
最初から validate が成功しており、「アップグレードするものはなかった」	マイグレーションチェーンのみの変換です。拒否する tombstone がないため、何も警告されません。	それでもチェーンを再実行します。validate の成功は必要条件ですが、十分条件ではありません。3.3 を参照してください。
validate が、廃止されたキーとは無関係な検出結果を報告する	スキーマではなく、作成時のルール検査です。	アップグレード前の validate の結果と比較します。以前から存在する検出結果は、今回のアップグレードの対象外です。
廃止されたキーをエラーなしで往復できる	そのキーを含むスキーマが厳密ではなく、キーが取り除かれているか、そのキーがまだ有効な読み込み経路上にあります。	どちらなのかを特定します。それぞれ必要な受け入れ証拠が異なります。逆方向の確認 を参照してください。
--apply が拒否された／保存データ専用のフラグが拒否された	--apply、--yes、--force、--type、--database-url は --stored と併用した場合にのみ意味があります。	--stored を追加するか、フラグを削除します。作成元ソースのチェーンが書き込むのは --out と、--write を指定した場合のソースのみです。
MigrationFloorError	--from がチェーンのサポート下限より古いバージョンです。	まず以前の経路でサポート下限までアップグレードします。この下限はリリースポリシー上の境界であり、見落としではありません。

実行結果を読まずにスクリプトで処理していますか？ 上記のすべての --json エラーには、分岐に使える安定した error コード（stored_only_flag、missing_from_major、unsupported_from_major、confirmation_required、database_busy）が含まれています。人間向けには、表の説明が同じ事実を示しています。

スキル間の振り分け

• 修正後のメタデータの作成 — 修正する形式に応じたドメインスキル（data、ui、automation、ai、api、i18n）を読み込みます。書き換える CEL がある場合は、いずれも formula に引き継ぎます。
• アップグレードで明らかになったランタイム、プラグイン、CLI に関する質問 — platform を読み込みます。