StateMirror - Spec Sheet

[ DOWNLOAD DATASHEET ]

Inputs

• 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
• Optional idempotency key for safer retries

Outputs

• Snapshot identifier (snapshot_id)
• Instance-local sequence number
• Receipt timestamp (received_at)
• Integrity hashes such as payload_hash and chain_hash
• Snapshot retrieval by snapshot_id or exact evidence_ref

Evidence Lanes

• 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.

Core release line

• 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 and export

• 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.
• This is integrity tooling only. It is not a compliance claim, legal non-repudiation claim, guarantee of upstream truth, policy correctness, or decision correctness.

CLI workflow

statemirror verify
statemirror inspect
statemirror export

Stable behavior

• Stores the submitted payload immutably after ingest
• Returns the stored payload faithfully by reference
• Provides tamper-evidence through integrity hashes and hash chaining
• Does not mutate state on read
• Does not execute application outcomes

Non-claims

• 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

Invariants

• Snapshots are immutable once written
• Payload meaning is application-owned
• Retrieval is reference-driven, not predicate-driven
• Payload contents are not interpreted by StateMirror
• State is queried. Decisions are made. Actions remain application-owned
• No dashboard or hosted control plane is required

Failure modes

• Ingest failure - snapshot does not exist
• Duplicate writes without idempotency
• Incomplete payload - faithful but insufficient evidence
• Database corruption or tampering - integrity verification fails
• Large payloads - rejected or operationally expensive
• Hot evidence_ref patterns - retrieval or indexing pressure

Performance characteristics

• 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

Out of scope

• State computation
• Outcome decisions
• Authorization or enforcement
• Policy evaluation
• Workflow execution
• Application behavior ownership
• Analytics, search, dashboards, or alerting
• Event sourcing or reconstruction
• Retention automation
• Webhooks or notifications

Implementation details

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