1 files changed, 369 insertions, 0 deletions
diff --git a/PLUTIA.md b/PLUTIA.md
new file mode 100644
index 0000000..f0dddaf
--- /dev/null
+++ b/PLUTIA.md
@@ -0,0 +1,369 @@
+# Plutia — Verifiable PLC Mirror
+
+Repository: [https://github.com/Fuwn/plutia](https://github.com/Fuwn/plutia)
+License: MIT OR Apache-2.0
+
+## Project Overview
+
+Plutia is a high-performance, verifiable alternative mirror for plc.directory.
+
+It must support two configurable operating modes:
+
+1. Resolver Mode (lightweight, state-only)
+2. Mirror Mode (full historical archive + verifiable proofs)
+
+Plutia is intended to be a production-grade, decentralization-focused infrastructure component capable of becoming a trusted first-choice mirror to plc.directory.
+
+The implementation must prioritize:
+
+* Deterministic data handling
+* Cryptographic correctness
+* Append-only integrity guarantees
+* Efficient disk usage (single-digit GB footprint for full mirror)
+* Static Go binaries
+* Clean modular architecture
+* Reproducibility
+* Long-term maintainability
+
+The implementation language is Go.
+
+---
+
+## Design Goals
+
+1. Eliminate Postgres/WAL/index overhead seen in existing plc-mirror implementations.
+2. Store historical operations in compressed append-only block files.
+3. Maintain a minimal KV state store for current DID resolution.
+4. Provide verifiable proofs of inclusion and integrity.
+5. Allow configurable verification policy.
+6. Produce signed checkpoints to prevent equivocation.
+7. Be able to operate on modest VPS instances (20–40GB disk).
+8. Be horizontally extensible later (replication / gossip optional future).
+
+---
+
+## Operating Modes
+
+Configurable via YAML OR environment variables:
+
+mode: resolver | mirror
+
+### Resolver Mode
+
+Stores only:
+
+* did -> latest operation reference
+* did -> materialized DID document
+* did -> chain tip hash
+
+Does not retain full historical chain.
+
+Intended footprint: 1–3GB.
+
+### Mirror Mode
+
+Stores:
+
+* Full operation history
+* Compressed append-only operation blocks
+* Minimal index mapping op sequence and DID chains
+* Signed checkpoints
+* State KV store (same as resolver mode)
+
+Intended footprint: ~4–6GB total.
+
+---
+
+## Storage Architecture
+
+### 1) Append-Only Operation Log (Mirror Mode Only)
+
+Directory layout:
+
+data/
+ops/
+000001.zst
+000002.zst
+index/
+state/
+checkpoints/
+
+Each block file:
+
+* Contains multiple operations
+* Each operation is canonicalized JSON bytes
+* Stored as:
+  [varint length][operation bytes]
+* Block compressed with zstd
+* Block hash recorded in index
+
+Block size target: 4–16MB uncompressed before compression.
+
+Compression: zstd level configurable (default level 9).
+
+### 2) KV State Store
+
+Use Pebble (github.com/cockroachdb/pebble).
+
+Keys:
+
+did:{did} -> serialized current state struct
+opseq:{global_seq} -> block_ref (block_id, offset, length)
+chain:{did} -> latest op sequence
+block:{block_id} -> block hash
+meta:global_seq -> uint64
+meta:mode -> resolver | mirror
+
+Value structures must be versioned.
+
+### 3) Canonicalization
+
+Operations must be:
+
+* Deterministically encoded
+* Signature-verifiable
+* Stored exactly as received except whitespace normalization
+
+No reordering of fields that would invalidate signature material.
+
+---
+
+## Verification Policy
+
+Configurable:
+
+verify: full | lazy | state-only
+
+full:
+
+* Verify each operation upon ingestion.
+* Validate signature chain.
+* Validate prev CID linkage.
+
+lazy:
+
+* Store raw ops.
+* Verify on-demand and in background.
+
+state-only:
+
+* Verify only latest operation for each DID.
+
+Verification must use ed25519 via standard Go crypto libraries.
+
+---
+
+## Checkpoint System
+
+Every N operations (configurable, default 100000):
+
+Produce checkpoint:
+
+{
+sequence: uint64,
+timestamp: RFC3339,
+did_merkle_root: hash,
+block_merkle_root: hash,
+previous_checkpoint_hash: hash
+}
+
+Checkpoint is:
+
+* Serialized deterministically
+* Signed with mirror private key
+* Stored under data/checkpoints/
+* Exposed via API
+
+Merkle tree:
+
+* Leaves = hash(did + chain_tip_hash)
+* Tree hash = sha256
+
+Purpose:
+
+* Allow external clients to verify inclusion.
+* Detect equivocation.
+* Enable mirror-to-mirror comparison.
+
+---
+
+## API Surface
+
+HTTP server using net/http.
+
+Endpoints:
+
+GET /health
+GET /metrics
+GET /did/{did}
+GET /did/{did}/proof
+GET /checkpoints/latest
+GET /checkpoints/{sequence}
+GET /status
+
+Resolver response includes:
+
+{
+did_document,
+chain_tip_hash,
+checkpoint_reference
+}
+
+Proof endpoint includes:
+
+* Chain proof or chain tip reference
+* Merkle inclusion proof
+* Checkpoint signature
+
+---
+
+## Ingestion
+
+Source: [https://plc.directory](https://plc.directory)
+
+Plutia must support:
+
+* Poll-based ingestion
+* Replay from genesis
+* Resume from stored sequence
+* Graceful recovery
+
+Concurrency model:
+
+* Single ingestion pipeline
+* Buffered channel for block assembly
+* Background checkpointing
+
+---
+
+## Configuration
+
+config.yaml:
+
+mode: mirror
+data_dir: ./data
+plc_source: [https://plc.directory](https://plc.directory)
+verify: full
+zstd_level: 9
+block_size_mb: 8
+checkpoint_interval: 100000
+listen_addr: :8080
+mirror_private_key_path: ./mirror.key
+
+---
+
+## Project Structure
+
+plutia/
+cmd/plutia/main.go
+internal/config/
+internal/ingest/
+internal/storage/
+internal/state/
+internal/checkpoint/
+internal/merkle/
+internal/api/
+internal/verify/
+internal/types/
+pkg/proof/
+go.mod
+
+Clean separation:
+
+* Storage interface
+* Verification logic
+* API layer
+* Merkle logic
+* Ingestion logic
+
+---
+
+## Performance Requirements
+
+* Memory footprint under 1GB for mirror mode.
+* No relational database.
+* Efficient sequential disk writes.
+* Minimal random IO.
+* Backpressure-aware ingestion.
+* Safe shutdown with flush.
+
+---
+
+## Security Requirements
+
+* No unsafe deserialization.
+* Deterministic hashing.
+* Signature verification strict.
+* Refuse malformed operations.
+* No silent chain truncation.
+* Checkpoint signing key rotation supported.
+
+---
+
+## CLI
+
+plutia serve --config=config.yaml
+plutia verify --did=did:plc:xyz
+plutia snapshot
+plutia replay
+
+---
+
+## Testing Requirements
+
+* Unit tests for:
+
+  * Canonical encoding
+  * Signature verification
+  * Merkle tree correctness
+  * Block encoding/decoding
+* Integration test:
+
+  * Replay small PLC sample dataset
+  * Verify final state correctness
+
+---
+
+## Deliverables
+
+The Codex agent must:
+
+1. Initialize Go module.
+2. Implement storage layer with Pebble.
+3. Implement append-only block writer with zstd.
+4. Implement state KV logic.
+5. Implement verification engine.
+6. Implement Merkle + checkpoint system.
+7. Implement HTTP API.
+8. Provide README explaining usage.
+9. Provide sample config.yaml.
+10. Ensure build via:
+    go build ./cmd/plutia
+
+---
+
+## Non-Goals (for v1)
+
+* Gossip between mirrors
+* Distributed clustering
+* UI
+* Advanced analytics
+* Horizontal sharding
+
+---
+
+## Core Principle
+
+Plutia must be:
+
+* Smaller than Postgres-based mirrors
+* Deterministic
+* Tamper-evident
+* Efficient
+* Trustworthy
+
+It should be credible as a first-choice alternative to plc.directory.
+
+---
+
+End of specification.