Subscription Entitlement Decision Audit

User attempts premium API access
↓
Application queries:
- PlanSignal
- DenySignal
- ExpirySignal
↓
Application computes eligibility
↓
Application submits evidence to StateMirror
↓
Application executes outcome
↓
Support later retrieves submitted evidence snapshot

// Canonical SimpleStates decision-audit pattern.
// SimpleStates emits facts. The application decides and executes.

async function handlePremiumApiRequest(req) {
  const subject = req.user.id;
  const correlationId = req.headers["x-correlation-id"] ?? crypto.randomUUID();

  // 1. Query read-time facts.
  const plan = await planSignal.state({
    subject,
    scope: "account",
  });

  const deny = await denySignal.state({
    subject,
    scope: "premium_api",
  });

  const expiry = await expirySignal.state({
    subject,
    scope: "premium_api_access",
  });

  // 2. Application-owned interpretation.
  const eligible =
    plan.status === "active" &&
    plan.entitlements?.includes("premium_api") &&
    deny.signal !== "denial_present" &&
    expiry.signal !== "expired";

  const applicationResult = eligible ? "granted" : "rejected";

  // 3. Submit evidence about the decision moment.
  // Evidence Lanes are optional canonical shapes, not required formats.
  const snapshot = await stateMirror.capture({
    evidence_ref: `premium-api:${subject}:${correlationId}`,
    evidence_type: "subscription_entitlement_decision",
    captured_at: new Date().toISOString(),
    state_payload: {
      subject,
      correlation_id: correlationId,
      requested_resource: "premium_api",
      evidence_lanes: {
        PlanEvidence: plan,
        DenialEvidence: deny,
        ExpiryEvidence: expiry,
      },
      computed: {
        eligible,
        application_result: applicationResult,
        policy_version: "premium-api-access-2025-12-REV-A",
      },
    },
  });

  // 4. Application executes outcome.
  if (eligible) {
    return grantPremiumApiAccess({
      subject,
      snapshot_id: snapshot.snapshot_id,
    });
  }

  return rejectPremiumApiAccess({
    subject,
    reason: "not_eligible",
    snapshot_id: snapshot.snapshot_id,
  });
}

// Later, support can retrieve the exact evidence the application submitted.

GET /v1/snapshots/{snapshot_id}

→ returns the submitted state_payload:
{
  subject,
  correlation_id,
  requested_resource,
  evidence_lanes: {
    PlanEvidence,
    DenialEvidence,
    ExpiryEvidence
  },
  computed: {
    eligible,
    application_result,
    policy_version
  }
}

// StateMirror answers:
// "What did the application know when it acted?"

// It does not answer:
// "Was the decision correct?"
// "Should the application have granted access?"
// "What should happen next?"

PlanSignal emits entitlement facts.
DenySignal emits denial facts.
ExpirySignal emits temporal validity facts.
StateMirror preserves submitted evidence.

The application computes eligibility.
The application decides whether to grant or reject access.
The application owns the action and outcome.