Citation-Credit Model

Flow

1. API receives citation intent and writes to vaultcrux.citation_staging.
2. Worker processes staging records asynchronously.
3. Worker writes:
   • agent_contributions
   • contribution_citations
   • agent_credit_ledger
4. Worker emits replay-safe outbox events:
   • contribution.created
   • citation.added
   • credit.posted
   • credit.reversed

v1.2 economy semantics

• query_vault returns credit_cost and cost_reason.
• Free tier shared/commons retrieval applies configurable multiplier (default 3x).
• Free tier available balance is capped (default 500) with overflow moved into escrow:
  • overflow reason: credit_earned_overflow
  • release reason: credit_overflow_released
• Conversion burn reason: subscription_conversion (billing_provider='paddle').
• Platform tip debit reason: platform_tip with sink credit reason platform_tip_sink.
• Cross-tenant marketplace transfer reasons:
  • buyer debit: bundle_purchase_debit
  • seller credit: bundle_sale_credit

Additional outbox types:

• platform.tip
• credit.conversion
• credit.policy.updated
• bundle.purchase.cross_tenant
• shield.decision
• shield.trust.changed
• shield.approval.requested
• shield.approval.resolved
• shield.taint.blocked
• shield.sandbox.violation
• shield.kill_switch.toggled

Idempotency

• citation_staging is deduped by (tenant_id, idempotency_key)
• contribution_citations is deduped by (tenant_id, contribution_id, idempotency_key)
• agent_credit_ledger is deduped by (tenant_id, agent_id, idempotency_key)
• event_outbox uses deterministic UUID event IDs