Stateset iCommerce

StateSet iCommerce Engine

コマースのSQLiteです。 注文、在庫、チェックアウト、決済、返品、サブスクリプション、倉庫業務、財務を備えた完全なコマースランタイムです。1つのデータベースファイルを使って、プロセス内で実行されます。ホスト型のコントロールプレーンも、サービスアカウントも、レート制限もありません。

自律実行に向けて、AI エージェントが支出を行う前に必要なもの、つまり委任されたアイデンティティ、デフォルト拒否の権限、厳密な予算、冪等なコマンド、暗号学的に検証可能なレシートを追加します。

---

まずはこちら

動作するストアフロントを作成します。

npm create stateset-app@latest my-store

次に実行します。

cd my-store
cp .env.example .env.local
npm run seed          # 10 products, stock, a demo catalog in ./store.db
npm run dev           # http://localhost:3000

これは、実際のコマースエンジンを背後で動かす Next.js ストアフロントです。ジェネレーターとシード処理は、 Storefront Golden Path CI ジョブでエンドツーエンドにテストされています。

AI エージェントにコマースのサンドボックスを提供する

Claude Desktop、Cursor、Windsurf、または任意の MCP クライアントの場合：

{
  "mcpServers": {
    "stateset-commerce": {
      "command": "npx",
      "args": ["-y", "-p", "@stateset/cli", "stateset-mcp", "--db", "./store.db", "--profile", "core"]
    }
  }
}

書き込みはデフォルトでプレビューのみです。 デフォルトの core プロファイルでは、スモークテスト済みのコア階層（196 個のツール）のみが公開されます。finance、operations、agents、all を指定すると利用範囲が広がり、--domains a2a,x402 を指定すると個別のドメインが追加されます。各ツールの階層（core、extended、experimental）は cli/docs/TOOLS.md に記載されています。エージェントに適用権限を与える場合は、ツール引数ではなく、必ずオペレーターが管理するファイルを通じて設定してください。

{
  "args": [
    "-y", "-p", "@stateset/cli", "stateset-mcp", "--db", "./store.db", "--apply",
    "--kernel-policy", "./kernel-policy.json",
    "--kernel-principal", "./kernel-principal.json",
    "--kernel-store-id", "store:production"
  ]
}

ホスト型デプロイでは、stateset-mcp-http を使って同じツールを MCP Streamable HTTP（プロトコルリビジョン 2026-07-28）経由で提供できます。設計上ステートレスで、セッション ID は不要です。リクエストごとに新しいサーバーが起動するため、レプリカ間でスケールできます。

npx -y -p @stateset/cli stateset-mcp-http --db ./store.db --port 8090

公開するには --host 0.0.0.0 を追加します。トランスポート境界で書き込みを無効にするには --read-only を、2026-07-28 より前のクライアントを拒否するには --strict-protocol を追加します。

---

インストール

チャネル	コマンド
crates.io	cargo add stateset-sdk --features full
npm	npm install @stateset/[email protected]
PyPI	pip install stateset-embedded==1.40.0
CLI + MCP サーバー	npm install -g @stateset/[email protected]

Ruby と WASM のバインディングには公開済みのパッケージがありますが、最新の状態には保たれていません。 RubyGems の stateset_embedded は 0.1.9、npm の @stateset/embedded-wasm は 0.7.22 で、どちらも 1.40.0 より大幅に遅れています。PHP、Java、Kotlin、Swift、.NET、Go には公開済みパッケージがありません。これらはソースからビルドし、各バインディングの API とインストール例については docs/src/api/ を参照してください。

使い方

import { Commerce } from '@stateset/embedded';

const commerce = new Commerce('./store.db');
const customer = await commerce.customers.create({
  email: '[email protected]',
  firstName: 'Ada',
  lastName: 'Lovelace',
});

use stateset_sdk::prelude::*;

let commerce = Commerce::new("store.db")?;
let customer = commerce.customers().create(CreateCustomer {
    email: "[email protected]".into(),
    first_name: "Ada".into(),
    last_name: "Lovelace".into(),
    ..Default::default()
})?;

金額は最初から最後まで厳密な小数値として扱われます。すべての変更を監査できます。

Rust クイックスタート → · CLI クイックスタート → · はじめに（全言語） →

REST API を提供する

stateset-http は、Rust アプリケーションから起動する埋め込み可能なレイヤーです。デフォルトでは 127.0.0.1:3000 にバインドし、OpenAPI 3.1 仕様を /api/v1/openapi.json で提供します。インタラクティブなリファレンスは /api/v1/docs で確認できます。認証はデフォルトで有効です。サーバーはトークンを生成し、serve() の前に bearer_auth_token() で取得できます。ログに表示されるのは、マスキングされたプレビューのみです。ループバック以外へのバインドには、運用担当者が管理する明示的なベアラートークン、認可、およびレート制限（または明示的に信頼されたゲートウェイ）が必要です。Rust クイックスタートのステップ 4 を参照してください。

---

iCommerce を選ぶ理由

ほとんどのコマース API が答えるのは、「モデルが呼び出せるエンドポイントはどれか？」です。StateSet が答えるのは、より難しい問いです。「このアクターは、リソースを安全に確定し、障害から復旧し、何が起きたかを証明するにはどうすればよいか？」

• チャット履歴ではなく、状態。 注文、在庫、残高、承認、ワークフローは、プロセスが再起動しても維持され、ガード付きステートマシンを通じて変化します。
• モデルの確信度ではなく、権限。 エージェントがインテントを提案し、運用担当者が管理するデフォルト拒否のポリシーが、その実行を許可するかどうかを決定します。
• ツール呼び出しへの楽観的な期待ではなく、トランザクション。 ドメイン状態、予算、イベント、冪等性レコードは、まとめてアトミックにコミットされるか、ロールバックされます。
• 検証できない説明ではなく、レシート。 重大な操作では、アクター、プリンシパル、インテント、ポリシーの判断、観測された結果、監査アンカー、決済証拠を記録した封印済みの記録が返されます。
• 奥深い仕組みを支える、シンプルな公開用語彙。 エージェントは quote、buy、sell、pay、fulfill、return_order、refund、subscribe を使って推論する一方、エンジンは完全なドメイン API と生成済み MCP カタログを維持します。
• デフォルトで埋め込み可能。 SQLite はインフラストラクチャ不要の選択肢です。複数のワーカーで共有バックエンドが必要な場合は PostgreSQL を利用できます。

カーネルが実行するコマース

カーネルは、モデルがアクションを提案することと、ソフトウェアがその実行を許可されることの境界です。

objective → typed intent → authenticated agent → delegated authority
          → policy + budget → atomic domain command → economic receipt

プリミティブ	保証されること
EconomicAgent	アクター、委任するプリンシパル、ロール、テナント／ストアのスコープ、認証情報、機能、公開鍵が明示されます。
EconomicAuthority	自動実行、承認必須、拒否の各範囲を厳密に指定し、デフォルト拒否のカーネルポリシーにコンパイルします。
EconomicIntent	8 つの安定したコマース動詞が、モデルのフレームワークに依存せず、厳密なコミットメントと冪等性を扱います。
永続的な予算	SQLite と PostgreSQL は、経済的な変更とアトミックに、スコープ付きの資金予算から差し引きます。プレビューや再実行で二重に消費されることはありません。
EconomicReceipt	アクター、インテント、判断、結果、監査アンカー、決済証拠が、信頼された当事者が連署できる単一の正規ダイジェストを共有します。

アイデンティティとポリシーは、信頼されたランタイム入力です。モデルが作成したツール呼び出しから受け入れることはありません。金額の上限には小数文字列を使用し、法定通貨以外の資産には個別の資産識別子を使用します。在庫コマンドでは、認可された数量と、実行側が観測した数量を紐付けます。

詳細：カーネル実行 · 信頼の基盤（セキュリティモデルと、明示されたギャップの一覧） · カーネルロードマップ

エージェントフレームワーク

エージェントのランタイムがアプリケーションプロセス内で動作し、stdio MCP ではなく JSON スキーマのツールを使用する場合は、組み込みツールキットを使用してください。

エントリーポイント	用途
@stateset/embedded/openai	OpenAI のツール呼び出し／Agents SDK
@stateset/embedded/vercel-ai	Vercel AI SDK
@stateset/embedded/langchain	LangChain／LangGraph JS
@stateset/embedded/generic	任意のランタイム（プレーンな { name, description, schema, execute } ディスクリプター）
stateset_embedded.openai / .langchain / .crewai / .autogen	Python の同等機能

Python フレームワークの追加機能は、次のコマンドで一度にインストールできます。 pip install "stateset-embedded[agents]==1.40.0"。

このツールキットは、支払いに対応したヘルパー（getPayableToolCatalog()、 executePaidTool()、discoverRemotePaymentService()）と、コントラクト／リプレイの ヘルパー（getRuntimeContract()、simulatePlan()、executePlan()、 replayMutation()）も公開します。書き込みを有効にする前に simulateMutation() または executePlan({ dryRun: true }) を呼び出し、 コマースの状態を変更するエージェントにのみ allowApply を設定してください。

実際に動作する例：Embedded Agent Toolkit · AI Agents

エージェント間コマース

エージェント間の直接決済、見積もりと交渉、条件付きリリースのエスクロー、 分割払い、サブスクリプション、ディスカバリーとレピュテーション、署名付き イベントストリーミングを標準機能としてサポートしています。Intelligent Commerce Protocol、 A2A Protocol Overview、および x402を参照してください。

決定論的なマルチエージェント・マーケットプレイスのデモでは、買い手、3 つの加盟店、 決済エージェントが、Ed25519 署名付きの完全順序メッセージボードを共有します。 落札された案件は、独立した 2 つのカーネル境界を越えて処理されます。

(cd bindings/node && npm run build)
node examples/sequencer-marketplace/demo.mjs --self-test --kernel

---

アーキテクチャ

レイヤー構造の Rust カーネルと、言語バインディングおよび Node ベースの オペレーターランタイムという 2 つの外側の製品サーフェスで構成されています。

stateset-primitives | stateset-crypto | stateset-pricing | stateset-observability
stateset-policy | stateset-authz | stateset-a2a | stateset-jobs
stateset-migrations | stateset-macros
        ->
stateset-core | stateset-sync
        ->
stateset-db
        ->
stateset-embedded
        ->
stateset-http | stateset-sdk | bindings/*
        ->
admin | cli

次の順に読み進めてください。stateset-core、stateset-db、stateset-embedded、 次に stateset-sync／stateset-policy／stateset-authz／stateset-pricing、 続いて stateset-http、最後に bindings/node と admin/ または cli/ です。

全体の解説：Architecture · Dependency Direction · Workspace Inventory（自動生成）

---

開発

nvm use                      # .nvmrc / .node-version (20.20.0)
rustup show active-toolchain # pinned by rust-toolchain.toml (1.90.0)

npm run check                # developer gate across the core workspace surfaces
npm run check:release        # release preflight; run before cutting a tag

サーフェスごとの開発サイクル：

cargo test -p stateset-core -p stateset-db -p stateset-embedded
npm --prefix cli test
npm --prefix admin test
npm --prefix bindings/node run check

正式なリモートゲートは、master 上の CI です。CI では、Rust 1.85 でワークスペースの MSRV も検証し、同じ固定バージョンの Node 20.20.0 でバインディングと管理サーフェスを 実行します。

コントリビューション：CONTRIBUTING.md · リリース：RELEASING.md · セキュリティ：SECURITY.md

---

ドキュメント

• 書籍 — 概念、すべてのコマース領域、A2A、 決済、セキュリティ、ポリシー、アダプター、運用、API リファレンスを扱います。 mdbook serve docs でローカルにビルドできます。
• ツールカタログ — MCP／CLI ツールサーフェスの自動生成された 正式な一覧（現在、87 の領域にわたる 923 個のツール）。
• バインディングごとの API リファレンス — Rust、Node、Python、Go、 Java、Kotlin、Swift、.NET、Ruby、PHP、WASM。
• サンプル — 実行可能なエンドツーエンドのプログラム。
• docs.rs の Rust API ドキュメント。
• CHANGELOG.md — リリース履歴。
• llms.txt — エージェント向けの機械可読なインデックスです。AGENTS.md は、 このリポジトリを扱うエージェント向けの簡潔なガイドです。

---

ライセンス

MIT または Apache-2.0 のデュアルライセンスで、 どちらを選択するかは任意です。