F11_Commerce / Commerce

catalog・cart・inventoryをF3へ正しくhandoffし、決済成功だけでpaidにする器官。

server-authoritative catalogからcartを作り、checkout planを承認してF3 handoffを発生させる。

入力 → 状態 → 出力

線形テキスト代替: Action Registryが検証したpayloadをengineへ渡す。engineはこの器官のdurable state sliceを更新し、resultまたはerrorをAction Coreへ返す。光は実行中、琥珀の境界はarmed状態、外縁はこの器官の作用半径を表す。

入力validated JSON payload
状態engine-owned durable slice
承認必要な外部 / 不可逆操作だけ
出力result / receipt / explicit error
回復payment webhookの署名が確認されるまでpaidにしない。restock/refundは別の承認連鎖で戻す。

10 registered actionsF3_Payment + G4_Pre_Gain_Gate dependenciesstripe_supabase binding reference

保存状態はAction Coreのfilesystem state store内の capabilities sliceとして再起動可能なplain dataで保持される。functionや秘密値をstateへ保存しない。

全Action

以下はAction Registryに実在するF11_Commerceの全actionである。クリックでpayload境界、状態、出力、回復を開ける。

capability.commerce.bindBind commercelocal or validated transition

payload: provider mode
状態: unbound → configured / ready
result: Capability engine の ok result、または明示的な validation / provider error。plan・receipt・stateは持続sliceへ返る。
recovery: error codeと状態を残し、必要に応じて再計画・再承認・retryへ戻る。

capability.commerce.upsert_catalogUpsert catalog productlocal or validated transition

payload: productId amountMinor currency
状態: state transition defined by the capability engine
result: Capability engine の ok result、または明示的な validation / provider error。plan・receipt・stateは持続sliceへ返る。
recovery: error codeと状態を残し、必要に応じて再計画・再承認・retryへ戻る。

capability.commerce.add_to_cartAdd to cartlocal or validated transition

payload: productId
状態: state transition defined by the capability engine
result: Capability engine の ok result、または明示的な validation / provider error。plan・receipt・stateは持続sliceへ返る。
recovery: error codeと状態を残し、必要に応じて再計画・再承認・retryへ戻る。

capability.commerce.plan_checkoutPlan commerce checkoutreversible preparation

payload: cartId
状態: durable plan → approval_required
result: Capability engine の ok result、または明示的な validation / provider error。plan・receipt・stateは持続sliceへ返る。
recovery: error codeと状態を残し、必要に応じて再計画・再承認・retryへ戻る。

capability.commerce.arm_checkoutArm commerce checkoutreversible preparation

payload: checkoutPlanId
状態: approval_required → armed
result: Capability engine の ok result、または明示的な validation / provider error。plan・receipt・stateは持続sliceへ返る。
recovery: error codeと状態を残し、必要に応じて再計画・再承認・retryへ戻る。

capability.commerce.execute_checkoutExecute commerce checkoutapproval boundary / external effect

payload: checkoutPlanId
状態: armed → visible provider/result state
result: Capability engine の ok result、または明示的な validation / provider error。plan・receipt・stateは持続sliceへ返る。
recovery: 実行前にarm状態を要求する。失敗はengineが保持し、同一keyは重複実行を防ぐ。

capability.commerce.apply_payment_eventApply commerce payment eventlocal or validated transition

payload: eventId type orderId signature
状態: state transition defined by the capability engine
result: Capability engine の ok result、または明示的な validation / provider error。plan・receipt・stateは持続sliceへ返る。
recovery: error codeと状態を残し、必要に応じて再計画・再承認・retryへ戻る。

capability.commerce.plan_restockPlan commerce restockreversible preparation

payload: orderId reason
状態: durable plan → approval_required
result: Capability engine の ok result、または明示的な validation / provider error。plan・receipt・stateは持続sliceへ返る。
recovery: error codeと状態を残し、必要に応じて再計画・再承認・retryへ戻る。

capability.commerce.arm_restockArm commerce restockreversible preparation

payload: restockPlanId
状態: approval_required → armed
result: Capability engine の ok result、または明示的な validation / provider error。plan・receipt・stateは持続sliceへ返る。
recovery: error codeと状態を残し、必要に応じて再計画・再承認・retryへ戻る。

capability.commerce.execute_restockExecute commerce restockapproval boundary / external effect

payload: restockPlanId
状態: armed → visible provider/result state
result: Capability engine の ok result、または明示的な validation / provider error。plan・receipt・stateは持続sliceへ返る。
recovery: 実行前にarm状態を要求する。失敗はengineが保持し、同一keyは重複実行を防ぐ。

Capability Spec

F11 Commerce — Capability Spec

Catalog, cart, order, and inventory lifecycle above F3 Payment. Server-authoritative price/inventory. Cart idempotency. Checkout plan handed to F3 — no charge in F11. Order paid state driven only by verified payment webhook event. Refund/restock is a separate approval path. Tax/shipping snapshot frozen at checkout plan time.

Order States

State	Meaning
`draft`	Local draft order.
`open`	Open for checkout.
`checkout_pending`	Checkout handed to F3; awaiting payment.
`paid`	Verified payment event applied.
`fulfilled`	Fulfillment complete.
`cancelled`	Cancelled before payment.
`refunded`	Restock/refund path completed.

Dependencies

F3_Payment (required): checkout handoff payload for plan_checkout → execute_checkout
G4 (required for live mode): g4_required if live without human approval

Actions

Action	Flow
`bind`	Stripe+Supabase binding
`upsert_catalog`	Server-authoritative catalog sync
`add_to_cart`	Idempotent cart line add
`plan_checkout` → `arm_checkout` → `execute_checkout`	Approval + F3 handoff (no charge)
`apply_payment_event`	Verified webhook → `paid` only
`plan_restock` → `arm_restock` → `execute_restock`	Separate inventory restore

Environment Names

Name	Role
`SUPABASE_URL`	Supabase project URL
`SUPABASE_SECRET_KEY`	Server-only key
`MIKAAIR_COMMERCE_CATALOG_AUTHORITY`	Server product/price/inventory JSON
`MIKAAIR_COMMERCE_TAX_RATE_BPS`	Tax rate in basis points
`MIKAAIR_COMMERCE_SHIPPING_FLAT_MINOR`	Flat shipping minor units
`MIKAAIR_PAYMENT_MODE`	`test` or `live`

binding / secret boundary

provider設定はbinding templateから参照する。環境変数は名前だけを扱い、値はsource repository・画面・reportに書かない。

環境変数名	扱い
`SUPABASE_URL`	configuration reference — 値は表示・保存しない
`SUPABASE_SECRET_KEY`	secret reference — 値は表示・保存しない
`MIKAAIR_COMMERCE_CATALOG_AUTHORITY`	configuration reference — 値は表示・保存しない
`MIKAAIR_COMMERCE_TAX_RATE_BPS`	configuration reference — 値は表示・保存しない
`MIKAAIR_COMMERCE_SHIPPING_FLAT_MINOR`	configuration reference — 値は表示・保存しない
`MIKAAIR_PAYMENT_MODE`	configuration reference — 値は表示・保存しない

payment webhookの署名が確認されるまでpaidにしない。restock/refundは別の承認連鎖で戻す。

source trace

../MikaAir LIGHTNESS/F_BUS_Capability/F11_Commerce/spec/capability_spec.md 3a00c692fe72
../MikaAir LIGHTNESS/F_BUS_Capability/F11_Commerce/binding/binding_manifest.template.json 6a5a162709f4
../MikaAir LIGHTNESS/F_BUS_Capability/F11_Commerce/agent.md df33734a18b8
../MikaAir LIGHTNESS/F_BUS_Capability/runtime_bridge.mjs 7e7384638a41
../MikaAir LIGHTNESS/F_BUS_Capability/action_surface.mjs e5bae5f48648
../MikaAir LIGHTNESS/A_BUS_Action_Core/A2_State_Store/filesystem_store.mjs b1cc32d3f456
../MikaAir LIGHTNESS/F_BUS_Capability/F11_Commerce/contract/index.mjs 86af17bbd16f
../MikaAir LIGHTNESS/F_BUS_Capability/F11_Commerce/engine.mjs 3bb30c5e5e16