StateMirror — Spec Sheet

[ DOWNLOAD DATASHEET ]

Inputs

• Evidence reference (evidence_ref) and evidence category (evidence_type)
• Captured timestamp (captured_at) provided by the submitting system
• Computed evidence payload (opaque JSON)
• Optional provenance metadata (source_system, source_version, correlation_id)
• Optional Idempotency-Key request header to make retries safe

Outputs

• Snapshot identifier (snapshot_id)
• Monotonic sequence number (instance-local ordering)
• Receipt timestamp (received_at)
• Integrity hashes (payload_hash, chain_hash)
• Snapshot retrieval by snapshot_id or exact evidence_ref

Verification export

• Commercial tiers may include a verification export path intended for offline review and dispute workflows.
• 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 to payload_hash, and validate chain continuity using chain_hash sequencing.
• This is integrity tooling only. It is not a compliance claim and not legal non-repudiation.

Guarantees

• Stores the submitted payload immutably (no update/delete paths)
• Returns the stored payload faithfully (integrity hashes verify fidelity)
• Detectable tampering via integrity hashes / hash chain
• Does not mutate state on read
• Does not execute side effects

Non-guarantees

• That your payload was correct, complete, or useful
• That you captured at the correct moment
• That timestamps reflect real-world time (clock skew is expected)
• That a missing snapshot implies anything about an outcome
• Security, compliance, or legal non-repudiation

Invariants

• Snapshots are immutable once written
• Payload meaning is application-owned
• Retrieval is reference-driven (not predicate-driven)
• No query into payload contents
• No dashboards required

Failure modes

• Ingest failure → snapshot does not exist (client must retry or accept missing record)
• Duplicate writes without idempotency
• Database corruption/tampering → integrity verification fails
• Large payloads → rejected or operationally expensive
• Hot evidence_ref cardinality → retrieval becomes slow (reference scheme smell)

Performance characteristics

• Write path: single PostgreSQL insert (plus idempotency record if enabled)
• Read path: point lookup by primary key or indexed evidence_ref
• Concurrency: limited by PostgreSQL pool and write serialization (ordering)
• Scaling model: run multiple instances per domain if needed (no multi-tenant dependencies)

Out of scope

• State computation
• Outcome decisions
• Authorization / enforcement
• Analytics, search, and dashboards
• Event sourcing / reconstruction
• Retention automation (operator-managed)
• Webhooks / notifications

Implementation details

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