SimpleStates

WHAT THIS IS

Small, self-hosted services that return JSON facts before your application makes a decision.

Decision Evidence for Software Systems

SimpleStates does not enforce access, run workflows, or own outcomes. It emits deterministic read-time signals your application can inspect, act on, and explain later.

Four questions. Four primitives.

PlanSignal: what plan or commercial state is declared?
DenySignal: is there an explicit denial?
ExpirySignal: is this still valid right now?
StateMirror: what evidence explains the decision later?

Tiny real-world flow

A billing system says the account is on the Pro plan.
ExpirySignal says the entitlement has not expired.
DenySignal says there is no explicit block.
The application reads those facts and decides whether to grant access.
StateMirror can record the evidence needed to explain that decision later.

BLUEPRINT

════════════════════════════════════════════════════════════
  APPLICATION
  (Enforcement Plane · High-Voltage Circuit)
════════════════════════════════════════════════════════════

  Application-owned Responsibility:
  - Identity resolution
  - Business logic & rules
  - Authorization / gating
  - Economic actions (grants, trades, charges)
  - Human overrides & judgment

                     ▲
                     │  HTTP GET  (Read-Time Signals)
                     │  /state/{signal}?subject=entity_id
                     │  < Deterministic JSON >
                     │
────────────────────────────────────────────────────────────
  SIMPLESTATES
  (Signal Plane · Low-Voltage Circuit)
────────────────────────────────────────────────────────────

  EVIDENCE OUT  ·  STATE IN  ·  DECISIONS MADE (Application-owned)

  EVIDENCE SINK  (Downstream · Write-Time)

  [1] StateMirror
      → Immutable decision snapshot ledger
      → Records what the system *knew* at decision time
      → Stores inputs + decision + timestamps
      → Verifiable via hash-chain

      Example:
      {
        inputs: {
          plan: "gold",
          denied: false,
          expired: false
        },
        decision: "approved",
        decided_at: "2025-12-30T18:42:00.000Z"
      }

                     ▲
                     │  (Application evaluates signals,
                     │   then makes a decision)
                     │
                     ▼

  STATE SOURCES  (Upstream · Read-Time)

  [2] PlanSignal
      → Plan & entitlement state
      → What this entity is allowed to have
      Example: { plan: "gold", tier: "vip", origin: "issuer_api" }

  [3] DenySignal
      → Explicit denial state
      → What this entity must not do
      Example: { denied: true, reason: "abuse", severity: "hard" }

  [4] ExpirySignal
      → Temporal validity state
      → What is still valid in time
      Example: { expired: false, expires_at: "2026-01-15T12:00:00.000Z" }

────────────────────────────────────────────────────────────
  GUARANTEES                    |  EXPLICIT NON-CAPABILITIES
────────────────────────────────|───────────────────────────
  - Emits factual state only     |  - NO enforcement
  - Deterministic responses      |  - NO auth decisions
  - Idempotent write ingress     |  - NO background jobs
  - Self-hosted PostgreSQL       |  - NO outbound webhooks
  - Verifiable integrity         |  - NO dashboards / SaaS UI

                     ▲
                     │  HTTP POST  (Write-Time Ingress)
                     │  /write/{signal}
                     │  < Stored facts only >
                     │
════════════════════════════════════════════════════════════
  EXTERNAL EVENT SOURCES
  (The Inputs)
════════════════════════════════════════════════════════════

  - Billing / Issuers / Platforms   → PlanSignal
  - Admin & Anti-Abuse Actions      → DenySignal
  - Timers / Windows / Issuance     → ExpirySignal
  - Application Decisions           → StateMirror