AVCS

AVCS — エージェント型バージョン管理システム

人間と AI エージェントが同時に作業するための、AI ネイティブなバージョン管理システムです。

エージェントはバージョン管理にコンテキストを費やすべきではありません。 それが設計目標のすべてであり、主張ではなく実測しています。同じ作業にエージェントが費やすコストは次のとおりです。

エージェントが費やすコスト	git ／全機能	AVCS
先に他の人の PR がマージされた後に変更を取り込む（30 KB のモジュール）	18,922 トークン	279 トークン — 99% 削減
このリカバリーを完了するまでの往復回数	7	4
ツールスキーマ。セッションごとに発生	約8.8kトークン（39個のツール）	約3.5kトークン（13個、--profile core）
同じ行での衝突でモデルに渡されるもの	コンフリクトマーカー付きのファイル全体	競合する2つの操作を示す1つのオブジェクト

git のリカバリーコストは ファイルのサイズに比例します。コンフリクトはファイル内のバイト列なので、1行を変更するだけでもエージェントはモジュール全体を読み込み、モジュール全体を書き戻します。AVCS のコストは変更のサイズに比例します。コンフリクトは競合する2つの操作を示すオブジェクトなので、ファイルが大きくなってもコストは変わりません。また、書き換えるブランチも、強制プッシュするものもないため、往復回数が異なります。そしてこれは 1回 のサイクルにすぎず、自分より先にマージされる PR ごとに繰り返されます。測定したファイルサイズでは、削減率は37～99%です。

これは後付けの圧縮テクニックではありません。スナップショットではなく操作グラフを保存することで自然に実現します。リベースが不要なので、読み直すものもありません。リベースの数値を得た手法、注意事項、ハーネスはこちらをご覧ください。 avcs-demo → エージェントのトークンコスト。 スキーマの数値は、公開されている MCP の機能そのものを示しています。JSON が35 KB対14 KBで、通常の1トークンあたり約4バイトで換算しています。

Git はコードがいつ変更されたかを記録します。 AVCS は、コードが現在の状態に至るまでに、誰が、どのような意図で、どのような証拠に基づき、どのようなコンフリクトの判断を経て変更したかを記録します。

AVCS は、人間と多数の AI エージェントが同じコードベースを同時に編集する環境のために構築された、新しい、意図的に Git との互換性を持たないバージョン管理システムです。コミット／ブランチ／マージ／コンフリクトマーカーのモデルを廃し、代わりに意図、セッション、操作、証拠、判断を第一級のオブジェクトとして保存します。コードツリーは信頼できる唯一の情報源ではありません。操作グラフを決定論的に還元して計算される投影です。

state = reduce(base, operationDAG, decisions, policy, materializer)

同じオブジェクト、同じポリシー、同じマテリアライザーを使えば、どのレプリカでも同じツリーが生成されます。マージはテキストの選択ではなく、純粋で決定論的な還元です。

ステータス： 研究用プロトタイプです。実装は実際に動作し、テストでカバーされていますが、各フェーズの完成度は実用可能な MVP の水準です（言語に依存しないテキストの3ウェイマージ、ed25519 署名）。構造を考慮したマージ、意味的な破壊の検出、複数署名による信頼性、堅牢化された分散同期は、ロードマップで管理しています。 まずはここから： インストール · 最初の5分 · サーバーを使って作業する · MCP 経由でエージェントを接続する · エージェントのクイックスタートガイド

まずは動作を確認する： izagood/avcs-demo — この設計が答える問いを実行できるデモです。2つのエージェントが同じファイルを同時に編集すると、どうなるでしょうか？ ./demo.sh を1回実行するだけで、拒否されずに取り込まれる古いヘッドからの適用、リベースなしの同一ファイルの自動マージ、そして同じ行での衝突がコンフリクトマーカーではなく署名付きの決定になる様子を確認できます。

git の上にレイヤーを重ねるのではだめなのですか？

あらゆる「AI + git」ツールは、最終的にエージェントのコンテキストを履歴のそばに保存します。コミットのトレーラー、PR コメント、サイドカー JSON などです。AVCS が存在するのは、これらのオブジェクトがマージ処理そのものに使われる不可欠な要素でなければならず、git に後付けしてもそれは実現できないからです。

• エビデンスがマージを制御する必要があります。 git は、テストに合格していない振る舞いの変更でも問題なくマージします。AVCS では、その変更は信頼できるエビデンスが揃うまで、リデューサーによって L3 — ブロックと判定されます。また、操作の作成者自身による保証はエビデンスとして認められません。
• 決定はマージ後も残る必要があります。 git merge はバイト列を出力してコンフリクトを解決しますが、選択とその理由は消えてしまいます。AVCS の decision は署名付きオブジェクトです。後から参照でき、以前の決定は今後の自動解決にも影響します。
• 同時編集がコンフリクトマーカーに行き着いてはなりません。 2つのエージェントが1つのファイルを編集した場合、ツリーに <<<<<<< が残り、人間が断片を整理するのではなく、決定的なポリシーの縮約（以下の L0～L4）が行われます。
• 意図は作業とともに引き継がれる必要があります。 トレーラーは作用しないテキストです。intent（目標 + 制約 + 許可された範囲）は、セッションの開始時に参照される対象であり、リースと競合チェックの適用範囲を定め、avcs.context.build が次のエージェントに渡すものです。

git はスナップショットを保存し、テキストの選択にマージを委ねます。AVCS は操作グラフを保存し、意図、エビデンス、決定に基づく計算としてマージを行います。そのため、AVCS は意図的に git と互換性がありません。これらのオブジェクトはメタデータではなく、エンジンそのものだからです。（ブリッジとしての git 連携は用意されています：docs/14、docs/20。）

基本原則

#	原則	Git との違い
1	操作が履歴を構成するのであり、コミットではありません	コミットは多数の操作に対する単なるチェックポイントです
2	識別子はエンティティ IDであり、ファイルパスではありません	名前変更と編集を自動マージできます
3	マージは決定的な縮約であり、テキストの選択ではありません	コンフリクトマーカーはありません
4	コンフリクトは第一級の decision オブジェクトであり、壊れたファイルではありません	理由は履歴に残ります
5	AI の出力はエビデンスを添付した提案済みの操作であり、信頼済みのコードではありません	テストのない振る舞いの変更は accepted にできません
6	コードで最終書き込み優先が既定になることはありません	優先順位はポリシーによって決まります

仕組み

意味のあるものはすべて、コンテンツアドレス方式の追記専用オブジェクトです。コードは操作 DAG 上の投影であり、コミットとして保存されることはありません。

オブジェクト	役割
intent	変更を行う理由（目標＋制約＋許可された範囲）
session	intent に基づくエージェント／人間の作業エピソード
operation	1 つの意味的な変更単位 — 実際の履歴
evidence	機械的に検証可能な証明（テスト／型チェック／lint／スキャン）で、操作に紐付けられるもの
decision	競合や設計上の選択に対する解決策の記録
checkpoint	検証済みの状態ベクトル（操作＋ポリシー＋マテリアライザー） — コミットに代わるもの
view	操作グラフに対する宣言的なクエリ — ブランチに代わるもの
release	署名と来歴情報を持つチェックポイント — タグに代わるもの
policy	リデューサーにパラメーターとして渡す決定論的なマージルール

…これらに加え、生のコンテンツ用の blob と、複数マシンおよびセキュリティの各フェーズで使用されるガバナンスオブジェクト（lease、membership、protection、promotion、redaction、override、approval、line、integration）があります。

競合解決レベル

AVCS はコードに対して、最終書き込み優先方式にフォールバックすることはありません。競合する操作は評価され、根拠とともに記録されたうえで解決されます。

• L0 / L1 — 異なるエンティティ、または同じファイル内の重複しない行領域 → 自動マージ
• L2 — 同じ行領域に重複する同時編集 → ポリシーによる自動判定（人間の判断を優先し、信頼度で重み付け）。自動判定そのものも autoDecisions に記録されます
• L3 — 信頼できる証拠がない動作変更 → ブロック
• L4 — 公開 API の破壊的変更 → 人間による判断が必要。対象範囲のオーナーに振り分けられます

証拠の信頼性は重要です。操作の作成者自身が、その操作の正当性を証明することはできません。証拠のゲート判定とテスト合格ボーナスの対象となるのは、作成者ではなく、信頼できるアクター（CI ボット／人間）が生成した証拠のみです。

現在の機能

リデューサーとポリシーエンジンが基盤であり、上位フェーズではその上に分散コラボレーション、セキュリティ、可観測性を構築します。

基盤（フェーズ 1〜6）

• ストレージコア — 追記専用のコンテンツアドレス方式オブジェクトストア（.avcs/objects）
• 決定論的リデューサー＋ポリシーエンジン — 上記の L0〜L4 の競合評価を、優先順位の階層、上限付きの信頼性調整、監査可能な自動判定とともに提供
• 言語に依存しないテキストマージ（フェーズ 2） — 決定論的な N-way の行単位 3-way マージ（src/merge/merge3.ts）により、1 つのファイル内の重複しない領域への編集は、言語にかかわらず自動マージされます。編集が重複する場合は、ポリシーによって解決される競合領域になります。コアでは言語解析を行いません
• 暗号学的信頼性（フェーズ 3） — ed25519 署名付きの証拠／判断。偽造された署名は信頼性ゲートで拒否されます。実際の検証ランナー、WorkLease、RepairContext
• 判断の記憶（フェーズ 4） — 過去の人間の判断を呼び出せる機能（recallDecisions）と、今後の自動解決にバイアスを与える、抽出された「学習済みポリシー」
• ポリシーの深化（フェーズ 5） — コードオーナーへの振り分けと、上限付きの信頼性学習
• リリースと来歴（フェーズ 6） — 検証済みチェックポイント＋CycloneDX SBOM＋署名付きアーティファクト

コラボレーション、スケーラビリティ、セキュリティ（フェーズ 7〜12）

• フェーズ 7 — 複数マシン: メンバーシップ／ロール（署名付きキーによるフェデレーション）、pull（オブジェクトのゴシップ。2 つのレプリカが同じ treeHash に収束）、保護機能と finalize CAS（fast-forward でない更新は拒否されるため、古いプッシュが新しい履歴を上書きできません）
• フェーズ 8 — 系譜: 長期間にわたって分岐したライン（例：v1.x ∥ v2.x。同じパスでも内容が異なり、競合はゼロ）、portOp（バックポート＝cherry-pick）
• フェーズ 9 — スケール: エンティティインデックス、materializeAt（タイムトラベル）、重複排除機能付きの大容量 blob のチャンクストレージ
• フェーズ 10 — オブザーバビリティ: blame（誰が／なぜ）、logP、決定論的な bisect、diff
• フェーズ 11 — 外部からの貢献: 隔離ティア＋promote＋信頼されていない CI のゲート
• フェーズ 12 — セキュリティ: redact（漏えいしたシークレットのバイト単位の消去。oid は保持）、緊急時の override、前進のみのロールバック
• ローカルでの取り消し（docs/23）— avcs undo [--last | <op-oid>…] [--purge] [--no-git]：ローカルの ops をビューから削除し、--purge を指定すると、それらのみが参照しているバイトも消去します。ops がプッシュ済みの場合は拒否されます。そのケースは管理者承認が必要な redact で処理するためです。git 連携リポジトリで --purge を指定すると、git のコピーも消去されます。ただし、書き換えが安全かつローカルであると証明できる場合に限ります（リモートに存在しない、コミットが先端にある、そのコミットに他の作業が含まれない、ツリーがクリーンである）。それ以外の場合は AVCS 側の処理のみを行い、残っているものと、それぞれに適したコマンドを正確に示します。「認証情報をローテーションしてください。すでに公開されています」と伝える場合もあります
• 作業ツリーは実際に派生したものです — checkout は、投影した内容を記録します （.avcs/projection.json、パス → blob oid）。次の投影時に、対象ビューに含まれなくなったファイルを削除します。AVCS が書き込んでいないファイル（ビルド出力、無視対象ファイル、自分で作成したものなど）には触れません。また、投影後に編集したファイルは保持され、通知で名前が示されます。黙って上書きされることはありません。そのためビューを切り替えると、以前に投影したすべてのビューの和集合ではなく、そのビューが得られます

ブランチはビューに、コミットはチェックポイントに、タグはリリースになります。エージェントは第一級のMCP サーバー（39 個のツール、または --profile core で 13 個）を通じて AVCS を操作し、人間はCLIを使います。Phase 14 以降、サーバーは統合キュー（avcs submit、POST /integrate）を実行します。古い投稿に対して「head が移動しました。先に pull してください」と返すことはありません。サーバーが投稿者に代わってフロンティアの和集合を再集約し、結果は必ず判定（advanced | conflict 修復パケット | needs_evidence — 検証を 1 回実行すればよく、やり直しは不要 | queued）になります。Phase 15 以降、レプリカはリアルタイムで収束します（GET /events のロングポーリング、avcs sync --watch、競合の早期警告）。Phase 16 で MCP の機能が完成しました。avcs.sync.land は 1 回の呼び出しで作業を反映し、avcs.context.build は決定論的な切り詰めを伴う、上限付きの作業コンテキストを組み立てます。また、購読可能なリソースは head が移動したときにクライアントへ通知します。詳しくは docs/17 と docs/18 を参照してください。動作は 827 件のテストで構成される契約テストスイート（test/*.test.ts、すべて成功）によって固定されており、tsc も問題なく完了します。

インストール

Node ≥ 22.6 が必要です。AVCS は型ストリッピングによって TypeScript を直接実行するため、ビルド工程も実行時の依存関係もありません。

AVCS は npm で @izagood/avcs として公開されています。グローバルにインストールすると、PATH から avcs コマンドを実行できます。

npm install -g @izagood/avcs

インストールせず、レジストリから直接実行することもできます。

npx @izagood/avcs version

最初の 5 分（サーバーも git も不要）

AVCS はローカルファーストです。ディスク上のリポジトリだけで、履歴、blame、取り消し、リリースを含む完全な VCS として機能し、サーバーも git も必要ありません。既存のプロジェクトディレクトリで次を実行します。

avcs init .                        # create the repo (inside a git repo is fine — .avcs is git-ignored)
avcs import . -m "initial import"  # bring the existing tree in as operations

# …edit files as usual, then record the change:
avcs commit -m "add mul()"         # authors operations for your working-tree changes

avcs status                        # operation / conflict summary
avcs log                           # operation history
avcs blame file:src/math.js        # who owns this file and why (entity key = file:<path>)
avcs conflicts                     # decisions a human still owes
avcs decide <conflict-id> --choose <op-oid> --reason "…"   # …and pay one: a signed decision


avcs undo --last                   # take the last operation back out of the view…
avcs checkout                      # …and re-project the working tree from it

注目すべき点は 2 つあります。commit は git のコミットとは異なり、実際の履歴となる意味的な操作を記録します。また、作業ツリーは信頼できる唯一の情報源ではなく、checkout で再マテリアライズする投影です。すべてのコマンドは avcs help で確認できます。

署名アイデンティティ

avcs のアイデンティティは、特定のチェックアウトではなく、あなたとこのマシンに属します。~/.ssh や ~/.gnupg と同じスコープです。一度プロビジョニングすれば、このマシン上のすべてのリポジトリで署名に使用できます：

avcs key provision human:you    # writes ~/.avcs/private/human:you.json (0600, dir 0700)
avcs key ls                     # who this machine can sign as, and which keystore each came from
avcs key import <key-file>      # put an existing identity on a NEW machine

キーストアは $AVCS_CONFIG_HOME、それが設定されていない場合は $XDG_CONFIG_HOME/avcs、それも設定されていない場合は ~/.avcs です。リポジトリは、別のアクター（CI チェックアウト、2 つ目のアイデンティティなど）として署名するために、独自のキーを <store>/private/ に保持できます。このオーバーライドが最初に読み込まれます。12 — ローカルでの運用を参照してください。

id があなたのアイデンティティです。信頼、キー、ガバナンスキーはこれに紐づきます。帰属情報と連絡先を設定するには、git と同じ方法で表示名とメールアドレスを設定します。これらはあなたが作成するすべての操作に含まれるため、blame や履歴であなたを表示し、連絡を取れるようになりますが、何かを制限することはありません：

avcs config user.name  "Ada Lovelace"
avcs config user.email "[email protected]"
avcs config actor      "human:ada"      # the id commits author as (else your sole key / AVCS_ACTOR)
avcs config                              # show what is set

これらの設定は .avcs/config.json に保存されます。AVCS_AUTHOR_NAME / AVCS_AUTHOR_EMAIL / AVCS_ACTOR を設定すると、呼び出しごとに上書きできます。

サーバーを使って作業する

サーバーがなくても、リポジトリは便利に使えます。サーバーが用意できたら、avcs serve、avcs-server、または準拠した任意の実装を使って、一連のやり取りをいくつかのコマンドで行えます：

avcs clone https://your.server/acme/web .      # fetch the graph AND project a working tree
avcs clone https://your.server/acme/web . --at <checkpoint>   # …at one exact checkpoint
avcs sync                                      # pull + push against the remote it recorded
avcs sync --watch                              # live convergence: long-poll + contention early warning
avcs land -m "add mul()"                       # push + checkpoint + integrate, in one step

使うコマンドは land です。古くなったヘッドは「head moved — pull first」と差し戻されるのではなく、サーバーの統合キューで取り込まれます。そのため、結果は landed か、人間が判断するためのコンフリクトパケットのどちらかになり、やり直しは不要です。avcs remote add <name> <url> でサーバーを追加登録し、avcs sync <name> で使用するサーバーを選択します。

署名キーを渡さずに CI から読み込む場合。 デフォルトの認証情報は、正規化されたリクエストに対する AVCS-Sig 署名です。この署名にはメソッドと本文が含まれるため、取得された読み取り用認証情報を使って書き込みを再実行することはできません。これが適切なデフォルトですが、一時的な読み取り専用ユーザーには適していません。そのため、読み取りではベアラートークンも使用できます：

AVCS_HUB_TOKEN=… avcs clone https://your.server/acme/web .

トークンは設計上、読み取り専用です。書き込みパスにはトークンを渡すパラメーターがないため、変数が漏れてもクローンはできますが、プッシュ、確定、ポリシーの書き換えはできません。保持している署名キーは常にトークンより優先されるため、署名を使う読み取りユーザーが気づかないうちにトークン認証へ降格されることはありません。トークンの形式、有効期間、スコープはサーバーによって決まります。docs/26を参照してください。

エージェントを接続する（MCP）

エージェントは MCP サーバーを介して AVCS を操作します。avcs をインストールしたら、Claude Code CLI に登録します：

avcs mcp install            # runs `claude mcp add avcs -- avcs mcp` for you (scope: user)
claude mcp list             # confirm "avcs" is Connected

avcs mcp 自体が、エージェントによって起動される stdio サーバーです（対象リポジトリは $AVCS_REPO、未設定の場合は cwd）。手動で登録する場合、または他の MCP クライアントを使う場合は、avcs mcp を指定します：

claude mcp add avcs -- avcs mcp

MCP SDK は optionalDependency として同梱されるため、通常のインストールに含まれており、追加の手順は不要です。

すべてのツールはデフォルトで簡潔に応答します。呼び出し時に verbose フラグを指定すると、整形表示を有効にできます。エージェントが読まない空白も、処理コストがかかることに変わりはないためです。

エージェントが実行するループ — 5 つの操作で、land は 1 回の呼び出しで完了します：

avcs.guide                                  # the loop, the rules, error recovery
avcs.context.build   { intentOid }          # provenance, prior decisions, live risks
avcs.operation.propose { path, content }    # never write final files directly
avcs.validate.run + avcs.evidence.attach    # a behaviour change needs passing evidence
avcs.sync.land       { by }                 # push + checkpoint + integrate → landed | conflict

要となるのは sync.land です。古くなったヘッドは自動的に取り込まれるため、結果は landed か、人間が判断するためのコンフリクトパケットのいずれかです。「pull してやり直し」は不要です。--profile core を追加すると、39 個すべてではなく、これら 13 個のツールだけを公開できます。エージェントに渡されるスキーマは、セッションごとに 35 KB から 14 KB に縮小されます：

claude mcp add avcs -- avcs mcp --profile core

後でアップグレードするには、npm install -g @izagood/avcs@latest を再実行します。削除するには、npm uninstall -g @izagood/avcs を実行します（リポジトリのデータはそのまま残ります）。

ソースからインストールする

最新の main を追跡したい場合や、AVCS 自体を開発したい場合は、同梱の install.sh を使ってください。リポジトリをクローンし、チェックアウト先を参照する avcs ランチャーを設定するため、更新は git pull だけで済み、再インストールは不要です。

curl -fsSL https://raw.githubusercontent.com/izagood/avcs/main/install.sh | bash

このワンライナーは、リポジトリを ~/.local/share/avcs にクローンし（--dir／AVCS_HOME で変更できます）、avcs ランチャーを ~/.local/bin にインストールします。再実行すると、チェックアウトがその場で更新されます。すでにクローンがある場合は、その中からインストーラーを実行してください。

git clone https://github.com/izagood/avcs.git && cd avcs
./install.sh

ランチャーは ~/.local/bin に配置されます（--bin-dir <dir> または AVCS_BIN_DIR で変更できます）。まだ ~/.local/bin が PATH に含まれていない場合、追加する行がインストーラーによって表示されます。

ソースからインストールするその他の方法：

./install.sh --bin-dir /usr/local/bin   # system-wide (may need sudo)
./install.sh --name avcs-dev            # install under a different command name
./install.sh --dir ~/src/avcs --ref v1  # one-liner mode: clone dir + ref to install
./uninstall.sh                          # remove the launcher (data is left intact)

実行時に node が PATH に含まれていない場合は、AVCS_NODE=/path/to/node を指定してランチャーにパスを知らせてください。

ライブラリとして使用する（@izagood/avcs）

ホスティングサーバー（avcshub など）は、AVCS コアをバージョン管理されたパッケージとして利用できます。開発とテストでは型ストリッピングを使って生の .ts を実行しますが、npm publish では tsconfig.build.json を使って tsc でコンパイルした dist/（JS と型宣言）が公開されるため、利用側でビルドツールを用意せずにインポートできます。

npm install @izagood/avcs

import { startHub, type HubHandle } from "@izagood/avcs/hub";   // the hub server
import { ObjectStore, CorruptObjectError } from "@izagood/avcs/store";
import { verifyMessage, generateKeypair } from "@izagood/avcs/identity";
import { Repo } from "@izagood/avcs";                            // root: primary public API

const hub = await startHub({ repoDir: "./data", port: 8080, gated: true });

エントリーポイント：.（ルートのバレル）・./hub・./hub/client・./store・./identity・./types。

リリース：PR で package.json の version を更新し、main にマージします。.github/workflows/release.yml が新しいバージョンを検出し、npm publish（プロビナンス付き）を実行して、コミットに vX.Y.Z のタグを付け、GitHub Release を作成します。公開処理はレジストリの確認で制御されるため、バージョンを変更しない package.json の編集では何も行われません。また、すべての PR でリリースのドライラン（CI での npm run build + npm pack --dry-run）が実行され、マージ前にパッケージングのリグレッションを検出します。@izagood スコープへの公開権限を持つ NPM_TOKEN リポジトリシークレットが必要です。

独自のサーバーを構築する

AVCS はサービスではなく、プロトコルです。準拠サーバーに必要なエンドポイントは 3 つです。

GET  /have            the oids you hold        → ["operation_ab12…", …]
GET  /objects/:oid    one object as JSON       → { … }  (404 if absent)
POST /objects         take one object          → { "oid": "operation_ab12…" }

それ以外はすべて任意です。クライアントは GET /version から機能フラグを読み取り、フラグがない場合、またはエンドポイントが 404／405／501 を返した場合は、独自のフォールバックを使用します。最初の 2 つだけを提供する読み取り専用ミラーも正当なサーバーです。統合キュー、バッチ処理、ロングポーリングを備えていないサーバーも同様です。

これは意図的な設計です。avcs は、自分では制御できないデプロイ環境に接続するパブリッククライアントだからです。

契約となるドキュメントは 2 つです。

• 26 — サーバープロトコル — 各エンドポイントのリクエスト／レスポンス形式、ステータスコード、機能ネゴシエーション、SSH スタイルのリクエスト署名、そしてサーバーの作成者が実際によく犯すミスをまとめた表です。
• 24 — 正規化された相互運用 — oid の計算方法です。JavaScript 以外で実装する場合は、まずこれを読んでください。オブジェクトの ID は正規化された JSON の sha256 であり、正規化処理のうち 3 つの部分は、わずかな違いが生じやすい箇所です。ここから逸脱してもエラーにはなりません。互いに収束しない、どちらも正しい 2 つの実装ができあがります。

何よりも先に、spec/canonical-vectors.json（受理例 10 件、拒否例 4 件。それぞれ期待される正規化バイト列と oid を含みます）を使って、正規化処理を検証してください。

次に、適合性テストスイートをサーバーに向けて実行します。

AVCS_CONFORMANCE_URL=https://your.hub/acme/web npm run conformance

適用されるレベルが報告されます。core（3 つのエンドポイントと、ソースの treeHash を再現するクローン）に続き、機能フラグに応じて sync、governance、queue が実行されます。告知していないレベルは失敗ではなくスキップされます。部分的なサーバーも正当なものです。

core が検証するのは、オブジェクトの複製とクローン可能性であり、サーバー側でのプロジェクションではありません。treeHash の比較は、プッシュしたクライアントとクローンしたクライアントという 2 つのクライアント間で行われます。そのため、サーバーが受け取ったデータを忠実に返すことは確認できますが、サーバー自身がそれらのオブジェクトからツリーを導出できることは確認しません。オブジェクトを正しく保存して提供する一方で、何もマテリアライズしないサーバーでも core に合格できます。これは意図したとおりです。プロジェクションはクライアント側の責務であり、それも行うサーバーは、このレベルで求められる以上のことをしています。

まずは次の 3 つの実装を参考にしてください。

• examples/server.py — 標準ライブラリのみを使った、完全準拠の core レベルサーバーです。JavaScript も avcs ライブラリも不要です。依存するのはドキュメント 24 とゴールデンベクターだけです。これがポイントです。python3 examples/server.py --selftest を実行してベクターで正規化処理を検証し、その後、適合性テストスイートをサーバーに向けて実行してください。

• avcs-server — このライブラリを基盤に構築された、スタンドアロンでセルフホスト可能なマルチリポジトリサーバーです。core で適合性を検証済みです。実行、コードの確認、またはフォークをして、ご自身のデプロイの出発点としてご利用ください。

• このリポジトリの startHub — リファレンス実装です。単一リポジトリ対応でマルチテナントではありませんが、プロトコル全体を提供します。仕様を実行可能な形にしたものとして読むか、avcs serve で実行してください。

チェックアウトから実行する

AVCS 自体を開発していますか？すべてのコマンドは、チェックアウトから直接 node で実行できます。

# Walk all four merge scenarios end to end
node --experimental-strip-types src/demo.ts

# Run the behavior-contract test suite
node --experimental-strip-types --test test/*.test.ts      # or: npm test

# Human-facing CLI (or just `avcs <command>` once installed)
node --experimental-strip-types src/cli.ts init .
node --experimental-strip-types src/cli.ts status
node --experimental-strip-types src/cli.ts conflicts
node --experimental-strip-types src/cli.ts log

# Agent-facing MCP server (`avcs mcp` once installed; ships the SDK as an optionalDependency)
npm install
AVCS_REPO=$(pwd) npm run mcp      # = node --experimental-strip-types src/mcp/server.ts

型チェック（tsc --noEmit）には npm install が必要ですが、ランタイム自体に依存関係はありません。

コードマップ

パス	役割
src/objects/types.ts	オブジェクトモデルの定義（唯一の信頼できる情報源）
src/store/objectStore.ts	追記専用のコンテンツアドレス方式のストア
src/core/canonical.ts	正規シリアライズとコンテンツアドレス指定（oid）
src/core/identity.ts	ed25519 による署名／検証と Keyring（フェーズ 3）
src/reducer/reducer.ts	操作グラフからコードツリーへのリダクションと競合の段階付け
src/reducer/policy.ts	ポリシーエンジン（優先順位の段階、信頼性の補正）
src/reducer/incremental.ts	差分再リダクション（変更のないグループを再利用）
src/merge/merge3.ts	言語に依存しない N-way の行単位 3-way テキストマージ（フェーズ 2）
src/policy/owners.ts, reliability.ts	コードオーナーへの割り当て · 信頼性の学習（フェーズ 5）
src/validation/runner.ts, repair.ts	検証ランナー · RepairContext（フェーズ 3）
src/concurrency/lease.ts	WorkLease（フェーズ 3）
src/release/sbom.ts	SBOM の生成（フェーズ 6）
src/hub/hubServer.ts, hubClient.ts	複数マシン同期サーバー（フェーズ 7。API 名では従来の「hub」という用語を維持）
src/api/repo.ts	高レベルのファサード（CLI、デモ、MCP で共有）
src/api/keystore.ts	マシンレベルのプライベートキーストア（~/.avcs/private）
src/mcp/server.ts	エージェント向け MCP インターフェース（39 個のツール。--profile core では 13 個を公開）
src/cli.ts	人間向けの検査／リリース CLI
src/demo.ts	エンドツーエンドのシナリオ

設計ドキュメント

• 00 — 概要と原則
• 01 — アーキテクチャ
• 02 — オブジェクトモデル
• 03 — リダクションと競合レベル
• 04 — ポリシーエンジン
• 05 — ビュー · チェックポイント · リリース
• 06 — MCP／スキルインターフェース
• 07 — ロードマップ
• 08 — ガバナンスとコンセンサス（avcshub）
• 09 — Git／GitHub のユースケース対応と設計の進化
• 10 — 本番環境向け設計計画
• 11 — 差分リダクション
• 12 — ローカル環境での本番運用
• 13 — Hub の本番運用
• 14 — Git ブリッジ（実環境との互換性）
• 15 — 言語に依存しないコア
• 16 — ワークスペースのスコープ
• 17 — 同期の収束：統合キューとライブ同期（設計）
• 18 — 第一級の接続としての MCP
• 19 — エンティティの識別性：名前変更と編集の可換性
• 20 — ワークスペース優先の Git ブリッジ
• 21 — shared-paths：ワークスペース間で共有されるビルド環境
• 22 — 領域ポリシーの調停（設計）
• 23 — ローカルでの取り消し：共有前の緊急回避手段
• 24 — 正規形式の相互運用：言語に依存しない正規化のサブセット
• 25 — エージェントのクイックスタート：Claude Code（MCP）から AVCS を操作する
• 26 — サーバープロトコル：準拠サーバーが提供すべき機能

コントリビューション

これは開発初期段階の研究用プロトタイプであり、設計は現在も変化しています。Issue の作成や議論を歓迎します。変更を提案する場合は、現在のモデルの根拠を理解するための出発点として、上記の設計ドキュメントをご覧ください。プルリクエストを作成する前に、npm test と npm run typecheck を実行してください。

イシューの報告

AVCS を使用中に変更してほしい点に気づいたら、自由形式のフィードバックを送るのではなく、イシューを作成してください。構造化された報告のほうが、対応しやすくなります。.github/ISSUE_TEMPLATE に 2 つのテンプレートがあります。

• 🔧 変更リクエスト — 既存の動作、CLI/MCP インターフェース、デフォルト設定、またはドキュメントの変更を提案します。
• 🐞 バグ報告 — 動作がおかしい、クラッシュする、または非決定的な結果が生じる場合に使用します。

🌐 どの言語でも歓迎します。 英語、한국어、日本語など、最も使いやすい言語でイシューを作成してください。メンテナーが必要に応じて翻訳します。言語を理由に報告をためらわないでください。

main へのすべてのプッシュとプルリクエストで CI（.github/workflows/ci.yml）が実行されます。Node 22.x と 24.x で、npm ci → npm run typecheck → npm test の順に実行されます。プルリクエストは CI が成功した場合にのみマージされます。

ライセンス

Apache License 2.0 の下でライセンスされています。Copyright © 2026 jaebin lee。帰属表示については NOTICE をご覧ください。