feat: initial Plutia release — verifiable high-performance PLC mirror (mirror + resolver modes)

1 files changed, 109 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2a4f6f1
--- /dev/null
+++ b/README.md
@@ -0,0 +1,109 @@
+# Plutia
+
+Plutia is a verifiable PLC mirror for `plc.directory`, implemented in Go.
+
+It supports:
+
+- `resolver` mode: compact state-only storage.
+- `mirror` mode: full historical operation archive with compressed append-only blocks, Merkle checkpoints, and inclusion proofs.
+
+## Features
+
+- Pebble-backed KV/index store (`data/index`).
+- Mirror-mode append-only operation log (`data/ops/*.zst`) with zstd compression.
+- Deterministic JSON canonicalization (`json.Compact`) with stable operation hashing.
+- Ed25519 signature verification with configurable policy (`full`, `lazy`, `state-only`).
+- Prev-link chain validation for tamper-evident DID histories.
+- Signed checkpoints with DID and block Merkle roots.
+- HTTP API for resolution, proofs, status, and checkpoints.
+- CLI for serving, replay, DID verification, and snapshots.
+- Benchmark command with rolling throughput/CPU/RSS/disk reporting.
+
+## Project Layout
+
+- `cmd/plutia`: CLI entrypoint.
+- `internal/config`: YAML/env configuration.
+- `internal/types`: operation/state/checkpoint models + canonicalization.
+- `internal/storage`: Pebble store + zstd append-only block log.
+- `internal/verify`: signature and chain-link validation.
+- `internal/state`: state materialization and KV updates.
+- `internal/merkle`: Merkle root/proof generation.
+- `internal/checkpoint`: checkpoint creation/signing/persistence.
+- `internal/ingest`: replay/poll ingestion pipeline.
+- `internal/api`: HTTP handlers.
+- `pkg/proof`: proof response structures.
+
+## Configuration
+
+Use `config.yaml` (see included example) and/or environment variables:
+
+- `PLUTIA_MODE`
+- `PLUTIA_DATA_DIR`
+- `PLUTIA_PLC_SOURCE`
+- `PLUTIA_VERIFY`
+- `PLUTIA_ZSTD_LEVEL`
+- `PLUTIA_BLOCK_SIZE_MB`
+- `PLUTIA_CHECKPOINT_INTERVAL`
+- `PLUTIA_COMMIT_BATCH_SIZE`
+- `PLUTIA_VERIFY_WORKERS`
+- `PLUTIA_LISTEN_ADDR`
+- `PLUTIA_MIRROR_PRIVATE_KEY_PATH`
+- `PLUTIA_POLL_INTERVAL`
+
+## Mirror Key
+
+Checkpoints are signed using `mirror_private_key_path`.
+Accepted key formats:
+
+- raw ed25519 seed/private key (`base64url`, `base64`, or `hex`)
+- JSON object: `{"private_key":"..."}`
+
+## CLI
+
+```bash
+plutia serve --config=config.yaml
+plutia replay --config=config.yaml
+plutia verify --config=config.yaml --did=did:plc:xyz
+plutia snapshot --config=config.yaml
+plutia bench --config=config.yaml --max-ops=200000
+```
+
+## HTTP API
+
+- `GET /health`
+- `GET /metrics`
+- `GET /status`
+- `GET /did/{did}`
+- `GET /did/{did}/proof`
+- `GET /checkpoints/latest`
+- `GET /checkpoints/{sequence}`
+
+`/did/{did}` returns `did_document`, `chain_tip_hash`, and latest checkpoint reference when available.
+
+`/did/{did}/proof` returns chain-tip reference, operation sequence references, Merkle inclusion proof, and checkpoint signature metadata.
+
+## Ingestion Behavior
+
+- Replay from genesis via `plutia replay`.
+- Poll-based incremental ingestion in `serve` mode.
+- Resume from `meta:global_seq`.
+- Parallel DID-partitioned verification with ordered commit.
+- Configurable synced commit batching (`commit_batch_size`).
+- Safe flush on shutdown.
+
+## Verification Policies
+
+- `full`: verify all operations on ingest.
+- `lazy`: ingest without immediate signature verification.
+- `state-only`: verify latest operations per DID.
+
+## Build and Test
+
+```bash
+go test ./...
+go build ./cmd/plutia
+```
+
+## License
+
+MIT OR Apache-2.0