w3ds

W3DS — Web 3 Data Spaces

W3DS では、ユーザーは個人用の eVault でデータを所有し、プラットフォームは交換可能なフロントエンドとして機能します。あるプラットフォームに書き込まれたデータは、Awareness Protocol を介して、登録済みのほかのすべてのプラットフォームに自動的に同期されます。このスキルは、W3DS 上で開発する開発者向けです。プラットフォームの統合、eVault GraphQL API の呼び出し、Web3 Adapter の接続、ローカル開発のデバッグを扱います。

権威ある情報源

https://docs.w3ds.metastate.foundation が権威ある情報源です。 このスキルはその内容を簡潔にまとめた索引であり、情報が古くなる場合があります。このスキルとドキュメントの内容が異なる場合は、ドキュメントを優先してください。その旨を伝え、ドキュメントに従ってください。

確信が持てないとき、または回答が記憶に頼ることになる場合は、必ずドキュメントを取得してください。このスキルに記載されている引用先はすべて有効な URL なので、事前に解決する必要はありません。

必要な情報	取得先
すべてのページの機械可読な索引	https://docs.w3ds.metastate.foundation/llms.txt
ドキュメント全体を収録したファイル	https://docs.w3ds.metastate.foundation/llms-full.txt
このスキルの最新版	https://docs.w3ds.metastate.foundation/skill/SKILL.md
すべてのオントロジーとその schemaId	https://ontology.w3ds.metastate.foundation/schemas
ドメインと、各ドメインに属するスキーマ	https://ontology.w3ds.metastate.foundation/domains

MetaState-Prototype-Project/prototype のチェックアウト内で作業していますか？ docs/docs/** はサイトの内容を反映しています。便利な参照先ですが、別の権威ある情報源ではありません。

必ず守ること

何かを設計する前に、Data Ownership Rules を読んでください。要点は次のとおりです。

1. eVault が信頼できる唯一の情報源です。プラットフォームが保存するものはすべて、eVault の投影です。 ドキュメントでプラットフォームは「キャッシュおよびアグリゲーター」と呼ばれています。これは、別の場所にある正本データのローカルコピーを高速化のために保持してよいという意味であり、データを所有してよいという意味ではありません。
2. 永続化されるエンティティには、3 つの要素が必要です。 オントロジー（解決済みの schemaId。独自に作成してはいけません）、解決可能な所有者（すべての行についてデータ主体に解決される ownerEnamePath。プラットフォームを指してはいけません）、そしてその所有者の eVault への名前付き書き込みパスです。
3. プラットフォームは GitW3 リポジトリに存在します。 1 つ上のレイヤーでも同じ考え方が当てはまります。リポジトリは W3DS が公開するプラットフォームメタデータの信頼できる唯一の情報源であり、コードと同じ場所にある .w3ds/platform.json に保持されます。通常の Git ホスティングにはコードは保存されますが、プラットフォームの eName、公開済みプロファイル、バージョンごとの ID、PPA 証明書、デプロイ記録は保存されません。reference/gitw3.md を参照してください。
4. 思い出すのではなく、解決してください。 オントロジー ID、エンドポイント、GraphQL フィールド名、ACL 動詞、eName は、記憶に頼らず照会してください。このスキルには意図的にオントロジー UUID を記載していません。

ローカルデータベースを使うこと自体は違反ではありません。一部のユーザーデータが存在する場所がローカルデータベースだけである場合は、違反です。

事前確認 — W3DS コードを書く前に

以下の4つすべてに答えてください。答えられない場合、それが問題です。回避策となるコードを書くのではなく、その旨を報告してください。

1. どのオントロジーですか？ GET https://ontology.w3ds.metastate.foundation/schemas を実行して、title で照合し、GET /schemas/:id でフィールド名を確認してください。まず GET /domains/:id/schemas で対象分野を絞り込んでください。一致するものがない場合は、新しいオントロジーの提案を参照してください。schemaId を決してでっち上げないでください。エラーが表面化しないまま、書き込みは成功し、パケットは配信されますが、対応するマッピングがないため受信側のプラットフォームすべてで破棄されます。
2. どのユーザーの eVault が所有しますか？ ownerEnamePath を示し、問題のないケースだけでなく、すべての行で解決されることを確認してください。所有者は、データが誰についてのものかを示す人物またはグループです。解決結果がない場合、handleChange は何も返さず、エンティティは同期されません。
3. 真実ですか、それとも投影ですか？ 再構築可能性のテストを適用してください。このデータベースを削除し、関連する eVault を再生して再構築した場合、何が失われるでしょうか？ 「重要なものは何もない」なら、正しい設計は投影です。ユーザーが失うと困るものがあるなら、そのデータはあなたのデータベース以外に保存先がありません。
4. 何が eVault に書き込みますか？ 呼び出し箇所を示してください。ローカル書き込みの後の handleChange、またはステートレスアプリでの eVault への直接書き込みです。「同期は後で行います」という意味なら、現時点ではプラットフォームがデータを所有しています。

停止ルール

次の場合は作業を止め、問題をユーザー自身の言葉で説明し、eVault 優先の代替案を提示して、コードを書く前に確認を求めてください。

• 設計上、ローカルデータベースがユーザーデータの信頼できる情報源になっている。 マッピングのないテーブル、オントロジーに対応するものがないフィールド、eVault への経路がないままローカルに書き込まれるエンティティ、eVault に接続できるのに eVault 由来の状態よりローカルの行を優先する読み取り。
• 永続化されるエンティティ型にオントロジーがなく、Ontology サービスからも解決できない。

2つ目は行き止まりではなく、進むべき道があります。オントロジーは誰でも提案できる通常の JSON ファイルです。draft-07 スキーマを作成し（新しいランダムな UUIDv4 schemaId、GET /domains から取得した domain、各プロパティの description、additionalProperties: false）、services/ontology/schemas/ に対する PR を作成すると申し出てください。また、その変更がマージされるまでは、その型は存在しないことを明確に伝えてください。手順の全容はreference/w3ds-native.mdを参照してください。

停止するのはこの2つの場合だけです。それ以外のすべて（所有者パスが見つからない、見慣れないディレクティブ、サービスが停止しているなど）は、作業を止める理由ではなく、通常どおり解決して報告する問題です。

確認できない場合

フェッチツールがない、オフライン、またはフェッチに失敗した場合は、作業を進めてください。ただし、未確認の識別子を確認済みとして提示してはいけません。

• 未確認の項目はすべて、確認できる正確な URL とともに回答に記載してください。
• 呼び出し箇所に、次のように明記してください。// TODO(w3ds): unverified — confirm against https://ontology.w3ds.metastate.foundation/schemas
• もっともらしい UUID、エンドポイント、フィールド名で空白を埋めてはいけません。誤った識別子は、明らかなプレースホルダーよりも危険です。エラーが表面化しないからです。

完了の定義

W3DS タスクの完了を報告する前に、各項目を確認してください。

• すべての eVault GraphQL 呼び出しと HTTP 呼び出しで X-ENAME: @<ename> を送信している。
• すべての eVault URL は呼び出し時に Registry から取得しており、ハードコードされていない。
• すべての schemaId は、このセッションで Ontology サービスから解決しており、記憶に頼っていない。
• すべての新しいエンティティタイプにオントロジー、解決可能な ownerEnamePath、および所有者の eVault への書き込み経路がある。
• マッピングされたテーブルへの書き込み後は毎回 handleChange を呼び出している。これには、マイグレーション、シード、管理用パス、バックグラウンドジョブからの書き込みも含まれる。
• Webhook コントローラーは eventId で重複を排除し、グローバルな id で upsert し、プラットフォームが消費しないオントロジーに対しては 200 を返す。
• 作り上げた情報がない。検証していない UUID、エンドポイントパス、GraphQL フィールド、マッピングディレクティブ、ACL 動詞は使用していない。検証できない場合は、それぞれをレスポンスで明示し、コード内にも記録している。
• 新たに永続化する対象には再構築可能性テストを適用し、その結果を回答に記載している。
• プラットフォームのリポジトリを変更した場合、管理対象の .w3ds/platform.json フィールドを手動編集しておらず、履歴を書き換えておらず、鍵素材をコミットしていない。

エコシステムの概要

「デジタル・セルフ」は、eName + eID 証明書 + eVaultの三位一体です。ユーザーはeID Walletで鍵を保持します。ProvisionerがユーザーのeVaultを作成します。RegistryはW3IDをeVaultのURLに解決し、プラットフォームディレクトリをホストします。Ontologyサービスは、各プラットフォームがローカルスキーマを対応付けるJSON Schemaを公開します。各プラットフォームのWeb3 Adapterは、ローカルDBと所有者のeVaultを橋渡しします。データが変更されると、eVaultはAwareness Protocolを実行し、登録されている他のすべてのプラットフォームに通知します。

コンポーネント	概要	参照先
eVault	W3IDごとのGraphQLデータストア。Neo4jを基盤とし、書き込み時にWebhookを送信します	reference/evault.md
W3ID / eName	UUIDベースの永続的な識別子。eNameはRegistryに登録されたW3IDです	reference/identity.md
Binding Document	ユーザーとeNameを結び付ける、署名済みMetaEnvelope（id_document、photograph、social_connection、self）	reference/identity.md
Registry	W3IDの解決、プロビジョニング用の/entropy、JWKS、プラットフォーム一覧、鍵バインディング証明書（一時的）	reference/registry.md
Ontology	/schemas、/schemas/:id、/domainsで提供されるJSON Schema draft-07レジストリ	reference/registry.md
Provisioner	新しいeVaultを作成します。POST /provisionを提供します	reference/wallet.md
eID Wallet	モバイルアプリ（Tauri/SvelteKit）。Secure Enclave / HSMでECDSA P-256鍵を保持します	reference/wallet.md
wallet-sdk	TypeScript SDK：provision、authenticate、syncPublicKeyToEvault。CryptoAdapterを介して暗号方式に依存しません	reference/wallet.md
Web3 Adapter	各プラットフォームでローカルDBとeVaultを橋渡しします。外向きはhandleChange、内向きはfromGlobalです	reference/platform.md
Awareness Protocol	書き込み後、eVaultから他のすべてのプラットフォームのPOST /api/webhookへ通知します	reference/protocols.md
w3ds://auth	セッション署名による認証フロー	reference/protocols.md
w3ds://sign	任意のペイロード（文書、投票、参照）のセッション署名	reference/protocols.md
w3ds://file	ファイルのblob用URIスキーム。形式はw3ds://file?id=@<ename>/<meta-envelope-id>です	reference/protocols.md
AaaS	Awareness-as-a-Service — eVaultによる直接的なWebhook一斉送信を置き換える、本番環境向けのサービス	reference/protocols.md
GitW3	W3DS対応のGitフォージ。.w3ds/platform.json、プラットフォーム／バージョン／デプロイメントのeName、PPAを備えます	reference/gitw3.md
Company delegation	取締役が役職を付与し、個人は会社を代理して署名します。検証者は取締役会までの委任チェーンを追跡します	reference/company-delegation.md

本番環境のURL

サービス	URL
ドキュメント（正式版）	https://docs.w3ds.metastate.foundation
Provisioner	https://provisioner.w3ds.metastate.foundation
Registry	https://registry.w3ds.metastate.foundation
Ontology	https://ontology.w3ds.metastate.foundation
GitW3（W3DS対応のGitフォージ）	https://git.w3ds.metastate.foundation

出典：リンク.

ルーティングルール

コードや設定を書く前に、以下の参照ファイルを読み込んでください。

ユーザーの質問に含まれる内容	読み込むファイル
「これはデータベースに保存すべきか」、「テーブル／エンティティ／モデル／フィールドを追加」、「X をどうモデル化すればよいか」、キャッシュ、ローカルコピー、データの所有権、「これは W3DS ネイティブか」、設計またはアーキテクチャのレビュー	reference/w3ds-native.md
GitW3、.w3ds/platform.json、プラットフォームの eName、バージョンの eName、デプロイメントの eName、PPA 証明書、既存アプリの移植、プラットフォーム用の git remote／タグ／リリース、w3ds-deployment-key.json、「これはどこにホストすればよいか」	reference/gitw3.md
webhook コントローラー、mapping.json、handleChange、fromGlobal、toGlobal、Web3 Adapter、ownerEnamePath、__date、__calc、__file、「プラットフォームはどう構築すればよいか」	reference/platform.md
GraphQL、createMetaEnvelope、updateMetaEnvelope、removeMetaEnvelope、bulkCreateMetaEnvelopes、uploadFile、metaEnvelope(id)、metaEnvelopes、ACL、X-ENAME、/whois、/logs、MetaEnvelope、Envelope、Neo4j モデル	reference/evault.md
W3ID、eName、@<UUID> 形式、X-ENAME ヘッダー、Binding Document、id_document、photograph、social_connection、self、鍵のローテーション、友人ベースの復旧	reference/identity.md
Registry、/resolve、/entropy、/list、JWKS、鍵バインディング証明書、オントロジー ID の検索、新しいオントロジーの提案、/schemas、/domains	reference/registry.md
w3ds://auth、w3ds://sign、Awareness Protocol パケット、署名の検証、ECDSA P-256、multibase、base58btc、base64 署名形式、verifySignature、AaaS、w3ds://file URI、ファイルの間接参照	reference/protocols.md
eID Wallet、wallet-sdk、provision、authenticate、syncPublicKeyToEvault、CryptoAdapter、ハードウェア鍵とソフトウェア鍵の違い、PATCH /public-key、デバイス間での鍵の委任	reference/wallet.md
会社、取締役、取締役会、役割、委任、再委任、「代理で署名する」、「会社のために署名する」、verifyDelegatedSignature、buildDelegatedSignRequest、buildGrantSignRequest、w3ds-sign/v1、w3ds-grant/v1、スコープ、appLimits、株式保有	reference/company-delegation.md
pnpm dev:core、Dev Sandbox、ポート（4321 / 3001 / 4000 / 8080）、REGISTRY_ENTROPY_KEY_JWK、pnpm generate-entropy-jwk、「webhook が発火しない」、「署名の検証に失敗する」、「エンティティが重複する」	reference/dev-setup.md

質問が複数のトピックにまたがる場合（プラットフォーム構築でよくあります）は、順番にではなく、最も関連性の高い参照ファイルを2、3個まとめて読み込んでください。構築タスクでは、ほとんどの場合 w3ds-native.md と platform.md の両方が必要です。

推測しないでください

以下の値は、推測してもほぼ確実に間違っています。

• オントロジーの schemaId — https://ontology.w3ds.metastate.foundation/schemas から解決してください。このスキルには、意図的に含まれていません。w3ds-file-v1 は例外で、これはプロトコルの文字列リテラルであり、レジストリの検索値でも UUID でもありません。
• GraphQL のフィールド名／ミューテーション名 — createMetaEnvelope が慣用的な名前です。storeMetaEnvelope はレガシーなエイリアスで、Web3 Adapter の EVaultClient 内部で現在も使用されています。完全なシグネチャは reference/evault.md を参照してください。
• マッピングディレクティブの構文 — __date(...)、__calc(...)、__file(...)、tableName(path),globalAlias、および配列の users(participants[].id),participantIds — reference/platform.md にある例をそのまま使用してください。
• 署名のエンコード方式 — ソフトウェアキーは base64 の生の 64 バイト（r || s）を出力し、ハードウェアキーは multibase base58btc（z...）を出力します。reference/protocols.md を参照してください。
• エンドポイントのパスとヘッダー — eVault のすべてのリクエストには X-ENAME: @<ename> が必要です。/provision は Provisioner 上にあり、eVault-core 上にはありません（ただし、ローカル開発ではどちらも同じ eVault-core プロセス内でポート 3001 を使用して実行されます）。
• プラットフォームマニフェストの値 — platformName、割り当て済みの ename、リリースで管理される version、および PPA 証明フィールドは GitW3 によって管理されます。手動で編集、捏造したり、プラットフォーム間でコピーしたりしないでください。reference/gitw3.md を参照してください。

不確かな場合は、https://docs.w3ds.metastate.foundation から該当するページを取得してください。取得できない場合は、確認できない場合に従ってください。

用語に関する重要なポイント

• MetaEnvelope と Envelope：MetaEnvelope は最上位のエンティティ（1 件の投稿、1 人のユーザー）です。Envelope はそのエンティティの単一のフィールドで、LINKS_TO を介してリンクされた独立した Neo4j ノードとして保存されます。
• W3ID と eName：すべての eName は W3ID です。レジストリに登録されている W3ID のみが eName（解決可能）です。グローバルの場合、どちらも @<UUID> 形式を使用します。
• オントロジーとスキーマ：ここでの「オントロジー」は、オントロジーサービスが公開し、その schemaId（W3ID）で参照される特定の JSON Schema を意味します。セマンティックウェブにおける言葉の意味ではありません。
• プラットフォームとポストプラットフォーム：プラットフォームは Web3 Adapter と /api/webhook エンドポイントを介して W3DS に参加します。ポストプラットフォームは「データレス」モードで動作し、データを所有せず、ユーザーの eVault がデータを所有します。
• w3ds-file-v1 と File オントロジー：w3ds-file-v1 は、blob の参照解決のために uploadFile が作成する低レベルのストレージエンベロープです。File オントロジーは、ファイルマネージャーや eSigner 形式のアプリ向けの高レベルのプラットフォームレコードです。相互に置き換えることはできません。フィールド名とレイヤーが異なります。詳細は reference/protocols.md を参照してください。
• Awareness Protocol と AaaS：Awareness Protocol は、パケットと受信側の契約です。AaaS はその永続的な配信システムで、eVault のトランザクショナルアウトボックス、不変のイベント、サブスクリプション、少なくとも 1 回の再試行、およびデッドレターで構成されます。
• storeMetaEnvelope／updateMetaEnvelopeById：レガシーな GraphQL ミューテーション名で、Web3 Adapter の EVaultClient 内部で現在も使用されています。外部連携では createMetaEnvelope／updateMetaEnvelope／removeMetaEnvelope を使用してください。

作業時の指針

• ユーザーの eVault URL は、/graphql または /whois にアクセスする前に、必ず Registry を介して解決してください。eVault URL をハードコードせず、解決結果をキャッシュして再検証し、HEAD /whois が失敗した場合はキャッシュから削除してください。
• eVault への GraphQL 呼び出しと HTTP 呼び出しには、必ず X-ENAME が必要です。このヘッダーの欠落は、400 エラーの最も一般的な原因です。
• ACL モデルは 2 つ共存しています。_acl ブロックは、動詞ごとの許可（READ/CREATE/UPDATE/DELETE のビットマスク）、拒否、およびオントロジー条件を指定し、存在する場合はこれが優先されます。従来の acl 文字列配列は、["*"] を除き一括で適用され、_acl のないレコードには引き続き適用されます。この違いを無視して、ACL が一括適用だと説明しないでください。詳しくは reference/evault.md を参照してください。
• Webhook の配信は少なくとも 1 回行われます。Webhook コントローラーは、グローバルな MetaEnvelope の id ではなく、eventId に基づいて冪等にしてください。異なる更新が意図的に同じ id を共有することがあります。
• 配信順序が保証されるのは、サブスクリプションと MetaEnvelope ごとであり、全体ではありません。eVault は AaaS の取り込みが確認されるまで再試行します。AaaS はデッドレター化するまで 24 時間、サブスクライバーへの再試行を続けます。
• すでに確認できるものを複製しないでください。Awareness Protocol を通じてレコードを受け取る場合は、それを可視化するために 2 つ目のエンベロープを書き込むのではなく、サブスクライブしてください。
• 公開を予定しているプラットフォームを構築していますか？それは GitW3 リポジトリに置くべきだと、早い段階で伝えてください。単なるリポジトリのインポートは、ガイド付きのポート手順とは異なります。また、後から ID を追加するよりも、最初から設定するほうが適切です。
• w3ds-deployment-key.json、プラットフォームトークン、移行証明、または個人用アクセストークンを絶対にコミットしないでください。鍵の情報をどこかに貼り付けるよう求められた場合は、作業を中断して理由を説明してください。
• ユーザーがローカルで実行している場合は、トラブルシューティングの前に reference/dev-setup.md を確認してください。同期の不具合の多くは、サービスが起動していないか、環境変数が不足していることが原因です。