Edge Library credit metering

Advisor-only Edge Library rows can optionally cost credits when an organization promotes or consumes a surviving edge. Metering lives in alphaswarm.billing.edge_credits — ideation routes never invent balances or call Stripe.

Modes

Mode	Env	Behavior
off (default)	ALPHASWARM_EDGE_LIBRARY_METERING_MODE=off	Audit-only; wallet never mutated
permissive	…=permissive	Debit when funded; allow + shortfall audit if not
strict	…=strict	Debit required; HTTP 402 on shortfall

Costs:

• ALPHASWARM_EDGE_LIBRARY_PROMOTE_CREDITS (default 1)
• ALPHASWARM_EDGE_LIBRARY_CONSUME_CREDITS (default 1)
• ALPHASWARM_EDGE_LIBRARY_TRIAL_CREDITS — seeded on first wallet create (default 0)

Persistence

• credit_wallets — one row per organization_id
• credit_ledger_entries — append-only; unique idempotency_key

Migration: 0127_edge_library_credits.

API

As of this writing, alphaswarm/api/routes/ideation.py does not wire these functions to any HTTP route — grep across the monolith finds no @router decorator for /agents/ideation/edges, /agents/ideation/edges/{id}/consume, /agents/ideation/credits/balance, or /agents/ideation/credits/grant (they do still appear in the committed data/openapi.json, which looks stale relative to the current route source). The billing primitives themselves exist and are exercised directly by tests/billing/test_edge_credits.py:

Function	Module	Notes
charge_edge_action(...)	alphaswarm.billing.edge_credits	Debits promote / consume per the enforcement mode
get_balance(...)	alphaswarm.billing.edge_credits	Balance + configured costs
grant_credits(...)	alphaswarm.billing.edge_credits	Admin grant

charge_edge_action(..., idempotency_key=...) takes the idempotency key as a caller-supplied argument rather than generating it — the edge_promote:{org}:{workspace}:{session}:{fingerprint} / edge_consume:{org}:{user}:{edge_id} formats below are the intended convention for whichever caller ends up wiring these routes, not something verifiable in the billing module itself today:

• promote: edge_promote:{org}:{workspace}:{session}:{fingerprint}
• consume: edge_consume:{org}:{user}:{edge_id}

Guardrails

• Still advisor-only — metering does not place orders or touch the money plane.
• Once a POST /agents/ideation/credits/grant route is wired, it is a billing mutation and must attach Depends(require_step_up(...)) per AGENTS rule 52 — scripts/ci/allowlists/step_up_mfa.txt / scripts/ci/check_step_up_mfa.py already allowlist this path in anticipation of that route landing.
• Stripe / invoice settlement remains out of scope; operators grant credits via the admin route (or a future webhook that calls grant_credits), once that route exists.