mps-preflight

Maha Strategies

Maha Strategies プラットフォームは、公開サイトと公開用画面、認証情報が必要な商用 API、そしてその背後にある非公開の運用コントロールプレーンを、1 つの Next.js アプリケーションで提供します。Vercel にデプロイされており、www.mahastrategies.com で利用できます。

このファイルの大部分は、特定のサブシステムの運用手順です。ドキュメント全体ではなく、必要なセクションをお読みください。

スタック

項目	サービス
アプリケーションとホスティング	Vercel 上の Next.js（App Router）、React、TypeScript
データベース	Supabase Postgres。公開アクセス用ポリシーのない RLS
キャッシュ、レート制限、残高	Upstash Redis。デプロイ環境ごとに名前空間を分離
GPU コンピューティング	Modal — workers/maha_workers.py
決済	Stripe — 製品ラインごとに個別のエンドポイントと署名シークレット
メール	Resend
テレメトリー	Sentry。ペイロードの機密情報を除去

ローカルでの実行

Node 22 以降が必要です。

npm install
npm run dev

アプリは http://localhost:3000 で動作します。 .env.example を .env.local にコピーし、作業する画面で必要な値を設定してください。変数が設定されていない場合、ほとんどの機能はクラッシュするのではなく、無効な状態になります。

データベースをローカルで利用するには、Supabase を起動（supabase start）し、supabase/migrations と、決定論的なテスト用データを提供する supabase/seed.sql を適用してください。

チェック

npm run typecheck && npm run lint && npm test

npm test は test/ 内の全テストを実行します。同じコマンドが、プルリクエストごとに CI でも実行されます。これに加え、本番ビルド、本番依存関係の監査、以下のマイグレーション整合性チェックも行われます。

このコードベースでの作業

再構築できない状態の破損を防ぐため、次の 3 つのルールは前提ではなく、必ず遵守するものとして定められています。

1. マイグレーションは追記専用です。 コミット済みのマイグレーションを編集、改名、削除しないでください。本番環境ですでに実行されている可能性があります。新しい前進マイグレーションを追加してください。ファイル名は <14-digit UTC timestamp>_<snake_case>.sql とし、main にある既存のすべてのファイルより後になるようにしてください。次のコマンドで確認します。

   node --experimental-strip-types scripts/check-migrations.ts
   

2. 台帳は追記専用です。 訂正は新しい行として追加し、返金は取消エントリとして記録します。記録済みの商取引の結果を編集または削除してはいけません。オペレーターによる介入は、テーブルへ直接書き込むのではなく、MPS 運用コントロールプレーンの監査済みかつ冪等なアクションを通じて行ってください。

3. シークレットはサーバー側に保持します。 ブラウザーに渡せるのは NEXT_PUBLIC_* 変数のみです。認証情報のシークレットは発行時に一度だけ開示し、ハッシュとしてのみ保存します。

フレームワークに関する注意：このリポジトリでは、古いドキュメントとは API が異なる場合のある Next.js のバージョンを使用しています。AGENTS.md を参照してください。

運用

ランブック	内容
docs/agent-discovery-metering.md	エージェントがプラットフォームを見つけているかを測定し、数値を正しく読み取る方法
docs/backup-restore.md	データベースの復元をリハーサルし、RTO と RPO を測定する方法
docs/database-migrations.md	本番環境へのスキーマ変更の適用、ドリフトの検出、エビデンス
docs/observability.md	Sentry の設定、署名付きアラートの検証、準備状況チェック
docs/release-recovery.md	リリースの健全性、復旧訓練、ロールバック、リハーサル、必須の GitHub 環境
docs/preview-e2e.md	すべてのプレビュー環境へのデプロイにおける統合ゲートと、マージをブロックする方法
docs/slo-capacity.md	サービス目標、エラーバジェット、上限付きキャパシティハーネス
docs/x402-conformance-corpus.md	ベンダー中立の x402 v2 フィクスチャとオフラインのリファレンスランナー
docs/x402-declaration-digest-proposal.md	カタログが証明するディスカバリー宣言ダイジェストの草案とテストベクター
docs/x402-doctor.md	ライブリソース、クローラー、Bazaar のドリフト、上限付き決済の診断
docs/x402-observatory.md	プロトコル準拠に関する公開観測、掲載ポリシー、定期運用
docs/x402-buyer-policy.md	ベンダー中立の署名前予算、承認、リプレイ制御、決済検証
SECURITY.md	脆弱性の報告と、プラットフォームの継続的なセキュリティ前提

外部市場のディスカバリーマトリックス

非公開の Market Scout は、読み取り専用のディスカバリープロセスです。出所を追跡できるウェブ検索のエビデンスを /admin/market-mapping に取り込みます。そこでは、すべての提案が決定論的なスコアリングと人によるレビューの対象となります。公開、支出、デプロイ、人への連絡はできません。

MARKET_SCOUT_SOURCES=exa を設定し、EXA_API_KEY を指定すると、デフォルトのマトリックスは UTC 日ごとに、MPS の請求検証、リサーチブリーフ、ドキュメントデータの抽出、レシート運用に関する 5 つのクエリをローテーションします。各クエリで取得する Exa の結果は最大 8 件です。

デフォルトを置き換えるには、サーバー専用の次の JSON 環境変数を設定します。

MARKET_SCOUT_QUERY_MATRIX={"lanes":[{"id":"claims","label":"Claim verification","queries":["claim verification API pricing","citation audit tool quote"]},{"id":"documents","label":"Document extraction","queries":["PDF table extraction API pricing"]}]}

マトリックスでは最大 8 個の名前付きレーンを設定でき、各レーンには最大 12 個のクエリを指定できます。Scout が毎日の実行で選択するのは、すべてのレーンをまたいだ 5 つのクエリのみです。以前の MARKET_SCOUT_QUERIES JSON 文字列配列設定も、後方互換性のため、単一のカスタムレーンとして引き続きサポートされます。

エージェント問い合わせゲートウェイ

POST /api/agent-inquiries は、/agent-offers.json で公開されているオファー向けの、認証が必要な非拘束の受付エンドポイントです。/agent-inquiry-schema.json に照らして検証し、問い合わせとその最初のイベントを非公開の Supabase 台帳に保存した後、Resend を通じて審査担当者への通知を試みます。支払いを受け付けたり、コミッションを発生させたり、作業を自動的に開始したりすることはありません。

問い合わせゲートウェイでは、データベースに登録された名前付きクライアント認証情報を使用します。認証情報の発行と失効は非公開の審査担当者向け操作です。共有の公開問い合わせトークンはありません。

有効にする前に、以下のデプロイ環境変数を設定してください。

AGENT_REVIEW_TOKEN=<unique reviewer bearer token>
RESEND_API_KEY=<existing Resend key>

任意で設定できる配信先の上書き値は AGENT_INQUIRY_FROM と AGENT_INQUIRY_TO です。審査担当者トークンはサーバー側に保持してください。クライアント認証情報は非公開レジストリで作成され、発行時に一度だけ表示されます。

承認済みクライアントは、/agent-inquiry-schema.json のスキーマに従って JSON を送信します。

curl --request POST https://www.mahastrategies.com/api/agent-inquiries \
  --header "Authorization: Bearer $CLIENT_CREDENTIAL" \
  --header "Content-Type: application/json" \
  --data '{
    "clientRequestId": "client-generated-unique-id",
    "offerId": "rapid-intelligence-brief",
    "requester": { "name": "Requesting principal", "email": "[email protected]" },
    "decision": "The decision this brief will inform.",
    "question": "One clearly defined market, technology, or policy question.",
    "requesterAuthorized": true,
    "agent": { "name": "Approved client agent", "version": "1.0" }
  }'

202 の成功レスポンスは、リクエストが人による審査のために記録されたことだけを意味します。返される notificationStatus には、任意のメール通知が配信されたかどうかが示されます。どちらの結果も、受諾、購入確認、またはサービスレベルの確約を意味するものではありません。

エージェントインフラストラクチャ全体を有効にする前に、Supabase SQL Editor で supabase/migrations/20260716_agent_inquiry_ledger.sql、supabase/migrations/20260716_agent_client_credentials.sql、supabase/migrations/20260716_mps_audit_jobs.sql、および supabase/migrations/20260717_serverless_credential_rate_limits.sql を適用してください。これらにより、非公開の問い合わせ台帳、認証情報レジストリ、MPS 監査台帳、データベースで管理されるイベント履歴、RLS と公開アクセス用ポリシーのない、アトミックな共有認証情報レートリミッターが作成されます。既存の NEXT_PUBLIC_SUPABASE_URL と SUPABASE_SERVICE_ROLE_KEY のデプロイ変数が必要です。

認証情報ベースの商用 API のうち一部は、20260727000100_privacy_preserving_commercial_api_metering.sql を通じて commercial_api_usage_daily にも記録します。これは、MPS 監査、MPS クレジットの読み取り、書籍の利用資格チェック、構造化された書籍コンテンツの配信を対象とする日次集計メーターです。IP アドレス、ユーザーエージェント、トークン値やフィンガープリント、リクエストおよびレスポンス本文、リファラー、メールアドレス、訪問者識別子は意図的に除外されます。読み取り専用の集計ボードは /admin/commercial-api-metering で、利用には REVENUE_CONTROL_TOKEN が必要です。

審査担当者向けの操作には、別の非公開エンドポイントを使用します。

GET   /api/agent-inquiries/:inquiryId
PATCH /api/agent-inquiries/:inquiryId

どちらも Authorization: Bearer <AGENT_REVIEW_TOKEN> が必要です。GET は非公開のリクエスト全体とイベント履歴を返します。PATCH は start_review、needs_clarification、decline、approve_for_scoping のいずれかのアクションを受け付けます。最後のアクションは内部的な処理区分であり、作業を受諾するものではありません。

クライアント認証情報レジストリ

審査担当者向けの非公開操作は、以下で利用できます。

GET  /api/agent-credentials
POST /api/agent-credentials
GET  /api/agent-credentials/:credentialId
PATCH /api/agent-credentials/:credentialId

すべて Authorization: Bearer <AGENT_REVIEW_TOKEN> が必要です。POST は認証情報を一度だけ発行し、その平文の値はそのレスポンスでのみ返されます。新しい clientName または既存の clientId のいずれかに加えて、credentialLabel、1 つ以上の allowedOfferIds および／または任意の allowedCapabilities、任意の rateLimitPerHour（デフォルトは 12）、任意の expiresAt（デフォルトは 90 日）を指定します。ケイパビリティのみの認証情報も使用できます。ケイパビリティのデフォルトはなしです。現在利用できるケイパビリティは mps_audit のみです。PATCH は { "action": "revoke", "reason": "optional note" } を受け付けます。GET エンドポイントが認証情報のシークレットを返すことはありません。

発行例：

curl --request POST https://www.mahastrategies.com/api/agent-credentials \
  --header "Authorization: Bearer $AGENT_REVIEW_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "clientName": "Example client agent",
    "credentialLabel": "Production research intake",
    "allowedOfferIds": ["rapid-intelligence-brief"],
    "allowedCapabilities": ["mps_audit"],
    "rateLimitPerHour": 12
  }'

機能権限で制御された MPS 監査 API

POST /api/mps-audits は、ヘッドレス MPS/0.1 エンジンを単一の文章に適用します。明示的な mps_audit 機能権限を持つ名前付きクライアント認証情報が必要です。同じ認証情報のレート制限を使用し、Supabase に冪等性のある監査レコードを保存します。入力文章は処理されますが、意図的に保持されません。レコードには入力ハッシュ、出力された主張の抜粋、モデル識別子、ステータス、イベント履歴が保持されます。これは計算を行う API であり、認証や人による検証の代わりとなるものではありません。

リクエストスキーマは /mps-audit-schema.json で公開されています。一意の clientRequestId を使用してください。同じ値を異なるテキストで再利用すると、409 が返されます。完了レスポンスには監査結果が含まれます。同じリクエスト ID と文章で再実行すると、モデルを再度呼び出すことなく、保存済みの結果が返されます。

curl --request POST https://www.mahastrategies.com/api/mps-audits \
  --header "Authorization: Bearer $MPS_AUDIT_CREDENTIAL" \
  --header "Content-Type: application/json" \
  --data '{
    "clientRequestId": "example-audit-20260716-01",
    "text": "In 2024, the company reported a 32 percent increase in output."
  }'

公開 MPS 監査の事前チェック

/audit は、無料で利用でき、利用範囲が制限された公開 MPS 事前チェックです。最大 6,000 文字の文章を受け付け、ブラウザーに主張マップを返し、文章を含まない JSON レコードを訪問者がダウンロードできるようにします。認証情報を使用する API や、有料のプライベート事前チェック /mps/preflight とは別のものです。

このバージョンをデプロイする前に、supabase/migrations/20260717_public_mps_audit_usage.sql を適用し、サーバー専用の MPS_PUBLIC_AUDIT_RATE_LIMIT_SECRET を設定してください。このシークレットは、1 日 3 回の利用枠に対し、IP アドレスとユーザーエージェントを組み合わせた訪問者フィンガープリントを HMAC でハッシュ化します。公開利用状況テーブルにもイベントテーブルにも、入力テキストやそのハッシュは保存されません。公開イベントテーブルには、文章を収集せずにコンバージョンを測定できるよう、送信、完了、失敗、レコードのダウンロードのイベントと件数／タイムスタンプのみが記録されます。

前払い MPS 監査アクセス

このリポジトリには、/mps/audit-access で利用できるセルフサービスの Stripe Checkout が含まれています。購入ごとに、mps_audit のみにスコープを限定した休止状態の認証情報が作成されます。Stripe の署名付きウェブフックは、設定済みの mps_audit_invocation パックをアトミックに付与し、その認証情報を有効化します。シークレットは購入時にブラウザーに一度だけ表示されます。

デフォルトでは無効になっています。20260717_mps_audit_credit_ledger.sql、20260717_self_service_mps_audit_access.sql、20260717_stripe_webhook_idempotency.sql の各マイグレーション、専用の Stripe Price、/api/mps-credits/webhook に設定する専用のウェブフックエンドポイント、および以下のすべてのサーバー専用変数が必要です。これらを設定すると、POST /api/mps-credits/checkout でチェックアウトを作成できるようになります。

STRIPE_MPS_AUDIT_CREDIT_PRICE_ID
MPS_AUDIT_CREDIT_PACK_UNITS
MPS_AUDIT_CREDIT_CHECKOUT_ENABLED=true
STRIPE_MPS_CREDITS_WEBHOOK_SECRET

このエンドポイントでは、checkout.session.completed、checkout.session.async_payment_succeeded、refund.created、refund.updated を購読してください。支払いが成功すると購入付与エントリが追加されます。払い戻しが成功すると、付与エントリを変更するのではなく、比例した取り消しエントリが追加されます。ウェブフックのマイグレーションでは、Stripe の各 evt_ ID が一意制約の下で記録され、そのイベントレコードと台帳の変更がアトミックにコミットされます。重複イベントには、残高を再度変更することなく応答します。順不同で届いた払い戻しは、チェックアウトの付与が存在するまで再試行可能なレスポンスを返します。

GET /api/mps-credits は、認証済みクライアントの台帳残高を返します。前払い認証情報の場合、POST /api/mps-audits はクレジットを 1 つアトミックに予約します。残高がない場合は、購入 URL とともに HTTP 402 を返し、実行に失敗した場合は冪等性のある返金エントリを作成します。既存の認証情報はデフォルトで internal_meter に設定され、従来どおりクレジットの適用なしでメーターのみを使用します。

書籍のチェックアウトウェブフックでは、checkout.session.completed、checkout.session.async_payment_succeeded、refund.created、refund.updated、charge.dispute.closed を購読してください。支払いが成功すると、書籍の利用権が一度だけ発行されます。確定した返金オブジェクトは Stripe の返金ごとに一度だけ記録され、累計取り消し額が元の支払額に達した場合にのみ利用権が取り消されます。異議申し立てによってアクセスが取り消されるのは、Stripe が申し立てを敗訴としてクローズした場合に限られます。

MPS 運用コントロールプレーン

プリペイドクレジットと Stripe ウェブフックのマイグレーション適用後に、supabase/migrations/20260718_mps_operational_control_plane.sql を適用し、専用のサーバー専用 MPS_OPERATIONS_TOKEN を設定してください。AGENT_REVIEW_TOKEN は再利用しないでください。コントロールプレーンには公開 UI がなく、保存されたシークレットハッシュや平文の認証情報を返すことはありません。

介入を行う前に、完全一致検索のエンドポイントを使用してください。リクエストボディを使うことで、領収書メールアドレスや顧客識別子が URL／アクセスログに残るのを防ぎます。指定できる値は、領収書メールアドレス、クライアント ID、認証情報 ID、14 文字の認証情報プレフィックス、チェックアウト ID、Stripe Checkout Session ID、PaymentIntent ID、Refund ID、Event ID です。

curl --request POST https://www.mahastrategies.com/api/admin/mps-operations/lookup \
  --header "Authorization: Bearer $MPS_OPERATIONS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"query":"[email protected]"}'

変更には /api/admin/mps-operations/actions を使用します。各リクエストには、オペレーターが指定する一意の冪等性キー、理由、外部チケットまたは Stripe 参照情報が必要です。データベースは、変更と不変のオペレーター操作レコードを 1 つのトランザクションでコミットします。

既存の台帳行は編集も削除もせず、クレジット訂正を追加してください。

{
  "action": "credit_adjustment",
  "clientId": "client_...",
  "quantity": 1,
  "idempotencyKey": "support-ticket-1042-credit-restore",
  "reason": "Restore one credit after a confirmed engine failure.",
  "referenceId": "ticket-1042"
}

有効な認証情報または支払い待ちの認証情報をただちに失効させます。

{
  "action": "credential_revocation",
  "credentialId": "cred_...",
  "idempotencyKey": "abuse-case-1043-revoke",
  "reason": "Credential reported as compromised.",
  "referenceId": "ticket-1043"
}

クライアント単位の残高を保持したまま、紛失した有効なプリペイド MPS 認証情報を置き換えます。

{
  "action": "credential_replacement",
  "credentialId": "cred_...",
  "idempotencyKey": "support-ticket-1044-replace",
  "reason": "Customer lost the only plaintext copy.",
  "referenceId": "ticket-1044"
}

置き換えでは、古い認証情報をアトミックに失効させ、新しい認証情報の平文を一度だけ返します。冪等性を保った再試行では、元の置き換えを確認できますが、平文を再度開示することはできません。新しい認証情報は、承認済みのシークレット共有チャネルを通じて渡してください。チケット、ログ、ソース管理、チャットには絶対に記載しないでください。Supabase Studio は調査に使用できますが、残高の訂正、失効、置き換えはすべて、テーブルを直接編集せず、監査対象のこれらの操作を通じて行う必要があります。

オファーから現金化までの収益コントロールプレーン

supabase/migrations/20260720001900_revenue_control_plane.sql と supabase/migrations/20260720002000_revenue_event_reconciliation.sql を適用し、別個のサーバー専用 REVENUE_CONTROL_TOKEN を設定してください。レビュー担当者用または MPS 運用用のトークンは再利用しないでください。非公開エンドポイントは次のとおりです。

POST /api/admin/revenue-control-plane

ここでは、個人を特定できる情報を含まないソース参照、オファーの振り分け、不変の商取引結果イベントのみを記録します。アウトリーチの送信、顧客への請求、契約への署名、ウォレットの操作、エンゲージメントの受諾はできません。既存のセルフサービス型オファーは現在の購入ページに振り分けられます。Rapid Intelligence Brief と Verified Research Brief のシグナルには、引き続き人間によるスコープと価格の確認が必要です。

安定したソース参照を使用して、受信シグナルを振り分けます。

{
  "action": "route_inbound",
  "idempotencyKey": "inbound-brief-1042",
  "reason": "Qualified website inquiry entered the commercial review queue.",
  "referenceId": "contact-1042",
  "signal": {
    "sourceType": "website_contact",
    "sourceReference": "contact-1042",
    "offerId": "rapid-intelligence-brief",
    "hasDefinedDecision": true,
    "hasSpecificQuestion": true,
    "hasOrganization": true
  }
}

後から、別の冪等性キーを使って状態を持つ結果を記録します。paid と refunded には、正の amountCents と 3 文字の通貨コードが必要です。台帳で許可されるのは有効な遷移のみです。振り分け／レビューからチェックアウトへ、チェックアウトから支払い済みへ、支払い済みから配信済みへ、支払い済みまたは配信済みから返金済みへ遷移できます。

検証済みの Stripe 支払いと取消しのウェブフックは、この台帳に自動的に反映されるようになりました。MPS 監査クレジットと書籍の利用権は、既存の製品ウェブフックがアクセスを付与した後にのみ配信済みとして記録されます。MPS Preflight はレポートの完了時に配信を記録します。支払いの正式な情報源は引き続き Stripe であり、収益コントロールプレーンのトークンが Stripe やブラウザーに送信されることはありません。

運用とオブザーバビリティ

このプラットフォームには、プライバシー情報を除去した Sentry のエラー／パフォーマンステレメトリー、Redis と Modal MCP の依存関係スパン、署名付きの低クレジットおよび上流接続性ウェブフック、非公開の設定準備状況エンドポイントが含まれています。環境変数、署名検証、ダッシュボード、リリーステストについては、運用ランブックを参照してください。

本番リリースの健全性は1時間に4回確認され、最後に正常だった Vercel デプロイが正確に保持されます。また、レビュー担当者の承認を必須とするロールバックに対応し、復旧後の準備状況確認と完全なカナリア検証を実施します。リリース復旧ランブックを参照してください。

内部の可用性およびレイテンシー目標は、公開サーフェス、準備状況の依存関係、Upstash キールックアップ、明示的な確認を必要とする制御された上流 MCP プロファイルを対象とした、上限付きの Preview 容量ハーネスによって適用されます。サービス目標と容量受け入れ基準を参照してください。

インバウンド収益ゲートキーパー

supabase/migrations/20260720002100_inbound_revenue_gatekeeper.sqlを適用してください。一般ユーザーおよびエージェントからの送信にはPOST /api/inbound-submissionsを使用します。スキーマは/inbound-submission-schema.jsonに、機械可読なエージェントカードは/.well-known/agent.jsonにあります。このエンドポイントは、データベースを利用した時間単位のレート制限、ハニーポット、厳格なサイズ／スキーマ検証、決定論的な適格性判定を使用します。受け付けたすべての送信を非公開の Revenue Control Plane に振り分けますが、コミットメント、支払い、契約、自動的なアウトリーチは作成しません。

スケジュールされたGET /api/cron/inbound-digestエンドポイントは、未送信の適格な送信を1日1回まとめて送信します。INBOUND_DIGEST_TOと Vercel のCRON_SECRETを設定してください。INBOUND_DIGEST_TOKENは、別途承認された手動トリガーでのみ利用できます。vercel.jsonは、Vercel Cron の呼び出しを13:00 UTCにスケジュールします。ダイジェストには個人の連絡先情報が含まれるため、受信者アドレスは非公開にしてください。

インバウンド運用キュー

supabase/migrations/20260720003200_inbound_operations_queue.sqlを適用し、サーバー専用の別個のINBOUND_OPERATIONS_TOKENを設定してから、/admin/inboundを開いてください。この非公開キューには、インバウンドの適格性判定、連絡先のコンテキスト、紐付けられた収益ステータス、追記専用のレビュー履歴が表示されます。実行できる操作は、レビュー、確認依頼、スコープ承認、チェックアウトへの誘導、辞退、失注処理に限られます。メッセージの送信、契約の受諾、支払いの受領済みとしての記録はできません。