Subscription Entitlement Decision Audit

User attempts premium API access
↓
Application queries:
- PlanSignal
- DenySignal
- ExpirySignal
↓
Application computes eligibility
↓
Application snapshots evidence in StateMirror
↓
Application executes outcome
↓
Support later retrieves exact decision 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 decision = eligible ? "granted" : "rejected";

  // 3. Capture decision evidence.
  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",
      inputs: {
        plan,
        deny,
        expiry,
      },
      computed: {
        eligible,
        decision,
        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 decision evidence.

GET /v1/snapshots/{snapshot_id}

→ returns the submitted state_payload:
{
  subject,
  correlation_id,
  requested_resource,
  inputs: {
    plan,
    deny,
    expiry
  },
  computed: {
    eligible,
    decision,
    policy_version
  }
}

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

// 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 grants or rejects access.
The application owns the outcome.