StateMirror specification

• Evidence reference (evidence_ref) supplied by your application
• Evidence category (evidence_type)
• Captured timestamp (captured_at) supplied by the submitting system
• Computed evidence payload as opaque JSON
• Optional provenance metadata such as source_system, source_version, or correlation_id
• Required Idempotency-Key header for snapshot creation and retries

• Snapshot identifier (snapshot_id)
• Instance-local sequence number
• Receipt timestamp (received_at)
• Integrity hashes such as payload_hash and chain_hash
• Retrieve snapshots by snapshot_id, exact evidence_ref, or bounded evidence_type + captured_at window

Core v1.0.0 retrieval supports:

• GET /v1/snapshots/:snapshot_id — retrieve one snapshot by its identifier.
• GET /v1/snapshots?evidence_ref=... — exact reference match, maximum 100 records. A reference with more than 100 records is rejected; use a more specific reference.
• GET /v1/snapshots?evidence_type=...&captured_after=...&captured_before=...&limit=... — both time bounds required, maximum 24-hour window, default and maximum limit 100. Results are ordered by captured time, newest first.

Retrieval does not query inside state_payload or interpret payload meaning.

• StateMirror Core v1.0.0 includes native Evidence Lanes for common companion evidence shapes: PlanEvidence, DenialEvidence, and ExpiryEvidence.
• Evidence Lanes are optional canonical evidence shapes, not required formats.
• Applications may submit opaque JSON payloads outside those lanes when their evidence model requires it.
• StateMirror preserves submitted evidence. Payload meaning and decision interpretation remain application-owned.

• StateMirror Core v1.0.0 is the stable decision evidence core: preservation, retrieval, integrity semantics, reusable verification logic, snapshot-by-id verification, CLI verify/inspect/export, pretty inspection output, JSON export tooling, and clearer integrity failure diagnostics.

• Verification can check a preserved snapshot by id and can support offline review through exported evidence.
• Export contents are evidence-level receipts, not decisions: snapshot_id, received_at, evidence_ref, evidence_type, payload_hash, chain_hash, and instance-local sequence.
• Verification is procedural: re-hash the stored payload using the published hashing rules, compare it to payload_hash, and validate chain continuity using chain_hash sequencing.
• Verification means payload/hash/chain integrity verification. It does not prove the application made the correct decision.

Immutability describes the service interface, not absolute protection from database administrators. An operator with sufficient database privileges can alter records and recompute hashes. Stored hashes alone cannot establish an independent history or detect every chain-suffix deletion.

The payload hash covers state_payload, not every envelope field. Include important business context inside the payload when it must be hash-covered. Database access, backups and independent records of expected ledger progress remain operator responsibilities. See Security & Operations.

statemirror verify
statemirror inspect
statemirror export

• Preserves the submitted payload after successful ingest without an update or delete operation in the service interface
• Returns the stored payload faithfully by reference
• Provides integrity verification using stored hashes and hash chaining within the documented trust model
• Does not mutate state on read
• Does not execute application outcomes

• That your payload was correct, complete, useful, or timely
• That your application captured evidence at the correct moment
• That your application made the correct decision
• That timestamps reflect real-world time without clock skew
• That a missing snapshot implies anything about an outcome
• Security, compliance, admissibility, or legal non-repudiation

• StateMirror does not evaluate business predicates or query inside payload meaning
• Payload meaning and interpretation remain application-owned
• No dashboard or hosted control plane is required

• Ingest failure - snapshot does not exist
• New idempotency keys for retried evidence can create duplicate snapshots
• Incomplete payload - faithful but insufficient evidence
• Payload or chain changes inconsistent with stored hashes cause verification failures; privileged rewrites with recomputed hashes may evade these checks
• Large payloads - rejected or operationally expensive
• Hot evidence_ref patterns - retrieval or indexing pressure

• Write path: PostgreSQL insert plus integrity/hash-chain work
• Read path: point lookup by primary key or indexed evidence_ref
• Concurrency: limited by PostgreSQL pool and write serialization needs
• Scaling model: run separate instances per domain when isolation is preferred

Applications own state computation, decisions, authorization, policy evaluation and workflow execution. Analytics, alerting and notifications remain in your application or existing tools. StateMirror does not replace event sourcing or observability.

Operators set retention policy and coordinate backups. See backup and retention responsibilities for Core’s cleanup behavior.

• Language: TypeScript (Node.js)
• Interface: HTTP ingest + HTTP retrieval
• Database: PostgreSQL
• Deployment: self-hosted service + self-hosted database