pactium 0.2.0 → 0.2.1

package/docs/FAQ.md

@@ -0,0 +1,189 @@
+# Frequently Asked Questions
+
+## General
+
+### What is Pactium?
+
+Pactium is a proof-first protocol substrate for Node.js. It records operation facts into an append-only transparency log and produces cryptographic proofs that operations were recorded and the ledger history is consistent. It is designed as the protocol substrate for LicoLite.
+
+### What does "proof-first" mean?
+
+Every write operation returns a verifiable proof envelope rather than a simple acknowledgment. The proof is the API response -- it includes ledger inclusion proofs, index proofs, and content-addressed references that can be independently verified.
+
+### Is Pactium a database?
+
+No. Pactium is a protocol substrate that records operation metadata and produces cryptographic proofs. It maintains verifiable indexes and state roots, but it is not a general-purpose data store. Host systems own their application data, business logic, and side effects.
+
+### Is Pactium a blockchain?
+
+No. Pactium is a local protocol substrate, not a distributed consensus system. It uses a transparency log (similar to Certificate Transparency) for append-only operation recording and Merkle proofs for verification, but it does not run a network, perform consensus, or require gas/tokens.
+
+### What is the relationship between Pactium and LicoLite?
+
+Pactium exists to serve LicoLite as its protocol substrate. LicoLite is the primary host, and `pactium/licolite` is a first-class package aspect (not a plugin). LicoLite requirements may shape Pactium core capabilities.
+
+---
+
+## Installation and Setup
+
+### Why does Pactium require Node.js 22+?
+
+Pactium uses modern Node.js APIs (built-in test runner, structured clone, modern crypto) that are stable in Node.js 22 LTS. It also supports Node.js 24 for forward compatibility.
+
+### I get `ERR_REQUIRE_ESM` -- what do I do?
+
+Pactium is a pure ESM package. It cannot be loaded with `require()`. Options:
+
+1. Add `"type": "module"` to your `package.json`
+2. Rename your file to `.mjs`
+3. Use dynamic import: `const { createPactium } = await import("pactium")`
+
+### Does Pactium have any runtime dependencies?
+
+No. Pactium has zero runtime dependencies. It uses only Node.js built-in modules (`node:crypto`, `node:fs`, `node:path`, etc.).
+
+### Where does Pactium store data?
+
+By default, Pactium stores data in the directory you specify via `dataDir` option (e.g., `./.pactium`). You can also use `inMemory: true` for testing. The storage format is content-addressed JSON files managed through the Storage Port abstraction.
+
+---
+
+## Usage
+
+### How do I record an operation?
+
+```js
+import { createPactium } from "pactium";
+
+const pactium = createPactium({ dataDir: "./.pactium" });
+
+const envelope = await pactium.recordOperation({
+  operationId: "my.operation",
+  workspaceId: "my-workspace",
+  idempotencyKey: "unique-intent-key",
+  outcomeIdempotencyKey: "unique-outcome-key",
+  input: { /* your operation input */ },
+  stateMutations: [
+    { key: "state-key", value: { /* your state */ } }
+  ]
+});
+```
+
+### What happens if I record the same operation twice?
+
+If you use the same `idempotencyKey`, Pactium returns an Idempotency Replay -- the existing proof envelope is returned without appending a new ledger fact. The replay is marked so callers can distinguish it from a new commit.
+
+### How do I verify a proof?
+
+```js
+// Local verification (requires Pactium instance)
+const result = await pactium.verifyEnvelope(envelope);
+
+// Portable verification (no local storage needed)
+import { verifyProofBundle } from "pactium";
+const bundle = await pactium.exportProofBundle(envelope);
+const result = await verifyProofBundle(bundle);
+```
+
+### What is a Proof Bundle and when should I use it?
+
+A Proof Bundle is a portable, self-contained export that includes all content-addressed blocks needed for verification. Use it when:
+
+- You need to verify a proof without access to the original Pactium storage
+- You want to share verification material with external parties
+- You want to archive proof material independently from the data directory
+- You need to preserve verification capability across Pactium version upgrades
+
+### What is the difference between Intent and Outcome?
+
+- **Operation Intent** declares what the host intends to do (recorded before the operation)
+- **Operation Outcome** declares the result (recorded after the operation completes or fails)
+
+Both are append-only facts. The Intent is never mutated into the Outcome. Failed and successful outcomes are both recorded as facts.
+
+### Can I use Pactium without LicoLite?
+
+Yes. The core `pactium` export is independent. `pactium/licolite` is a first-class aspect for LicoLite hosts, but you can use the core API directly for any host system that needs verifiable operation recording.
+
+---
+
+## Architecture
+
+### Why is there only one Verifiable Index Engine?
+
+Pactium uses a shared Canonical Prolly Tree-based engine for all indexes (state, workspace, lifecycle, idempotency, causality). Domain adapters convert domain-specific material into canonical keys and values. This eliminates the complexity of maintaining multiple independent tree implementations while keeping proofs consistent.
+
+### Why are hash algorithms and chunking not configurable?
+
+These are protocol constants, not tuning options. If a verifier expects `sha256` and the writer used `sha3`, proofs would be incompatible. Protocol parameters are fixed per protocol version to ensure all parties can verify proofs without negotiation.
+
+### What does the host system own vs. what does Pactium own?
+
+**Pactium owns:** Protocol facts, canonical encoding, hash computation, ledger ordering, index proofs, verification, proof generation, repair planning.
+
+**Host owns:** Policy decisions (allow/deny), operation dispatching, side-effect execution, authorization, durable evidence storage, UI, key management and rotation.
+
+### How does workspace isolation work?
+
+Each operation is associated with a `workspaceId`. Pactium maintains per-workspace projection indexes (order and membership) that are verifiable. You can prove that a ledger event belongs to a specific workspace, or prove that it does not belong, using Merkle proofs from the shared index engine.
+
+---
+
+## Verification
+
+### What does verification actually check?
+
+Envelope verification checks:
+
+1. Ledger inclusion proof validity (leaf is in the ledger at the stated tree size)
+2. Content-addressed proof material integrity (referenced blocks match their CIDs)
+3. Index proof validity (state/workspace proofs are mathematically correct)
+4. Critical extension support (all required extensions are understood)
+5. Signature validity (if signed heads are used)
+
+### What is a "critical extension"?
+
+A critical extension is a Proof Extension that must be understood by the verifier. If a verifier encounters an unknown critical extension, verification fails. This prevents silently ignoring important evidence bindings.
+
+LicoLite uses two critical extensions: Policy Extension and Workspace Effect Extension.
+
+### What happens when verification fails?
+
+Pactium returns structured Verification Failures (not thrown exceptions). Each failure includes:
+
+- `layer` -- which verification layer failed (ledger, index, envelope, extension)
+- `code` -- machine-readable failure code
+- `severity` -- critical, warning, or info
+- `repairable` -- whether the Repair Planner can address it
+
+You can feed failures to the Repair Planner to generate deterministic repair tasks.
+
+---
+
+## Troubleshooting
+
+### "Storage not initialized" error
+
+Call `createPactium()` or `createStoragePort()` with a valid `dataDir`. The data directory is created automatically on first use.
+
+### Verification returns unexpected failures
+
+- Ensure you're verifying against the same Pactium instance (or use Proof Bundles for portable verification)
+- Check that proof material refs are resolvable (content-addressed blocks exist in storage)
+- For LicoLite envelopes, ensure the verifier supports the required critical extensions
+
+### Proof Bundle verification fails but envelope verification passes
+
+This usually means the bundle export is incomplete. Ensure `exportProofBundle()` was called with a valid envelope and that the bundle contains all required content-addressed blocks.
+
+### "Consistency proof failed" between two ledger heads
+
+This means the ledger history diverged -- a later ledger state is not a valid continuation of the earlier one. This is a security-critical finding that indicates the ledger was rewritten or forked.
+
+### Performance concerns with large indexes
+
+The Prolly Tree engine uses structural sharing and Content-Defined Chunking for efficient updates. For large state sets, consider:
+
+- Using the `scan()` and `prefix()` methods for range queries instead of full snapshots
+- Using `diff()` to compute changes between state roots efficiently
+- Checking memory usage with the pressure profile: `PACTIUM_FULL_PRESSURE=1 npm run verify:protocol:gates`

package/docs/MIGRATION.md

@@ -0,0 +1,110 @@
+# Migration Guide
+
+This guide covers version compatibility, protocol stability, and upgrade guidance for Pactium.
+
+## Version Policy
+
+Pactium follows [Semantic Versioning](https://semver.org/):
+
+- **Major** (1.0, 2.0) -- breaking changes to public API or protocol format
+- **Minor** (0.2, 0.3) -- new features, backward-compatible API additions
+- **Patch** (0.2.1) -- bug fixes with no API or protocol changes
+
+During the `0.x` series, minor versions may include breaking changes. The protocol profile is locked per minor version.
+
+## Protocol Stability
+
+| Component | Stability | Change policy |
+| --- | --- | --- |
+| Protocol Hash (`sha256`) | Locked per protocol version | Requires new `PACTIUM_PROTOCOL` value |
+| Canonical Value encoding | Locked per protocol version | Requires new protocol version |
+| Proof vector outputs | Locked per protocol version | Changing expected vectors requires explicit protocol revision |
+| Ledger leaf/node hash format | Locked per protocol version | Part of protocol constants |
+| Content-Defined Chunking params | Locked per protocol version | Protocol constants, not configuration |
+| Public API shape | Stable within minor | Additions in minor, removals in next minor/major |
+| TypeScript declarations | Stable within minor | New types in minor, type changes in next minor/major |
+
+## Data Directory Compatibility
+
+### Current: v0.2.x
+
+Pactium v0.2.x creates and manages its own data directory format. Key constraints:
+
+- **New directories only** -- Pactium does not read or migrate data from earlier experimental formats
+- **Latest schema only** -- there is no support for loading older schema versions
+- **Forward-compatible within patch** -- patch releases do not change data format
+
+### Upgrading between minor versions
+
+When upgrading from one minor version to the next (e.g., future 0.2.x to 0.3.x):
+
+1. Check the [CHANGELOG](../CHANGELOG.md) for breaking changes
+2. Create a fresh data directory for the new version if the protocol version changes
+3. Use Proof Bundles to preserve portable verification material from the old version
+
+Pactium intentionally does not include automatic migration. Data directories are protocol-versioned, and mixing protocol versions in one directory is not supported.
+
+## Node.js Compatibility
+
+| Pactium version | Node.js requirement |
+| --- | --- |
+| 0.2.x | `^22.0.0 \|\| ^24.0.0` |
+
+Pactium is pure ESM. It cannot be loaded via `require()`. If your project uses CommonJS, use dynamic `import()`:
+
+```js
+// CommonJS interop
+const { createPactium } = await import("pactium");
+```
+
+## ESM-Only Package
+
+Pactium ships as a pure ES module. There is no CommonJS build and no dual-package export.
+
+**If you see `ERR_REQUIRE_ESM`:**
+
+- Ensure your `package.json` has `"type": "module"`
+- Or rename your files to `.mjs`
+- Or use dynamic `import()` from CommonJS
+
+**If you see `ERR_MODULE_NOT_FOUND`:**
+
+- Ensure you're importing from the correct path (`pactium` or `pactium/licolite`)
+- Deep imports into `src/` are not part of the public API and may change without notice
+
+## API Stability Tiers
+
+| Tier | Surface | Guarantee |
+| --- | --- | --- |
+| **Public** | Exports from `pactium` and `pactium/licolite` | Semver-governed; no removals in patch |
+| **Protocol Constants** | `PACTIUM_PROTOCOL`, `PACTIUM_PROTOCOL_PROFILE`, `HASH_DOMAINS` | Locked per protocol version |
+| **Type Declarations** | `.d.ts` exports | Stable within minor version |
+| **CLI** | `pactium` commands | Stable within minor; new subcommands in minor |
+| **Internal** | Files under `src/` not exported from entry points | No stability guarantee |
+
+## Proof Portability
+
+Proof Bundles exported from any Pactium version remain independently verifiable as long as:
+
+1. The protocol version is known to the verifier
+2. The bundle contains all required content-addressed blocks
+3. Critical extensions in the bundle are supported by the verifier
+
+Proof Bundles are the recommended way to preserve verification material across Pactium version upgrades.
+
+## Breaking Change Announcements
+
+Breaking changes will be:
+
+1. Documented in the [CHANGELOG](../CHANGELOG.md) under a `### Breaking Changes` section
+2. Announced at least one minor version in advance when possible (deprecation notices)
+3. Accompanied by migration instructions in this document
+
+## From Pre-Release to Stable (Future)
+
+When Pactium reaches 1.0:
+
+- The protocol format will be considered stable
+- Data directory format will receive backward-compatible migration support
+- The public API will follow strict semver without the `0.x` flexibility
+- This section will be updated with specific 0.x-to-1.0 migration steps

package/docs/README.md

@@ -1,13 +1,51 @@
-# Pactium Public Docs
+# Pactium Documentation
 
-Pactium is a proof-first protocol substrate for LicoLite.
+Welcome to the Pactium documentation. This index covers all maintained documentation for the proof-first protocol substrate.
 
-## Package Documents
+## Getting Started
 
-- [Architecture](architecture/ARCHITECTURE.md)
-- [Protocols](protocols/PROTOCOLS.md)
-- [Protocol Profile](protocols/PROFILE.md)
-- [LicoLite Aspect](LICOLITE-ASPECT.md)
-- [Terms](TERM.md)
+| Resource | Description |
+| --- | --- |
+| [README](../README.md) | Project overview, installation, and quick start |
+| [API Reference](./API.md) | Complete public API documentation |
+| [Examples Guide](../examples/README.md) | Annotated usage examples with learning path |
+| [FAQ](./FAQ.md) | Frequently asked questions and troubleshooting |
 
-The current `src/` tree implements the proof-first package surface. Repository maintenance, release, tooling, ADR, and optimization records are intentionally not part of the published npm package.
+## Core References
+
+| Document | Description |
+| --- | --- |
+| [Architecture](./architecture/ARCHITECTURE.md) | System architecture, module structure, and data flow |
+| [Protocol Specification](./protocols/PROTOCOLS.md) | Protocol behavior, data structures, and verification rules |
+| [Protocol Profile](./protocols/PROFILE.md) | Versioned protocol parameter matrix (algorithms, constants, formats) |
+| [LicoLite Aspect](./LICOLITE-ASPECT.md) | First-class LicoLite integration surface and requirements |
+| [Terms](./TERM.md) | Protocol glossary with preferred and avoided vocabulary |
+
+## Maintenance and Operations
+
+| Document | Description |
+| --- | --- |
+| [Migration Guide](./MIGRATION.md) | Version compatibility, upgrade guidance, and breaking changes |
+| [Quality Gates](https://github.com/Unka-Malloc/Pactium/blob/stable/docs/QUALITY-GATES.md) | Release verification requirements and automated gate coverage |
+| [Release Rules](https://github.com/Unka-Malloc/Pactium/blob/stable/docs/RELEASE.md) | Release process and publication criteria |
+
+## Decisions
+
+| Document | Description |
+| --- | --- |
+| [ADR Index](https://github.com/Unka-Malloc/Pactium/tree/stable/docs/adr) | 55 Architecture Decision Records covering protocol design choices |
+
+## Documentation Principles
+
+- **Current behavior only** -- maintained docs describe what is implemented today, not planned features
+- **Design claims require evidence** -- every design claim has a corresponding ADR and working implementation
+- **Protocol vocabulary** -- all docs use the vocabulary defined in [Terms](./TERM.md)
+- **Closure enforced** -- the release gate rejects documentation that describes unimplemented surfaces
+
+## What Is Not Published
+
+The npm package includes a curated subset of documentation:
+
+**Published in npm tarball:** `README.md`, `README.zh-CN.md`, `CHANGELOG.md`, `SECURITY.md`, `docs/README.md`, `docs/API.md`, `docs/FAQ.md`, `docs/MIGRATION.md`, `docs/logo.svg`, `docs/architecture/`, `docs/protocols/`, `docs/LICOLITE-ASPECT.md`, `docs/TERM.md`, `examples/`
+
+**Not published:** ADRs, optimization analysis, quality gates, release rules, agent instructions, release tooling, tests, build outputs, and binary/cache artifacts (these are available on GitHub only when appropriate)

package/docs/architecture/ARCHITECTURE.md

@@ -2,6 +2,8 @@
 
 Pactium is a proof-first protocol substrate for LicoLite. LicoLite is the primary host, and `pactium/licolite` is a first-class package aspect rather than an external plugin.
 
+## System Overview
+
 ```text
 LicoLite host
   -> pactium/licolite
@@ -18,18 +20,206 @@ LicoLite host
             -> Maintenance Task Engine and Repair Planner
 ```
 
-## Authority
+## Module Dependency Graph
+
+```text
+                    ┌─────────────────────┐
+                    │   pactium/licolite   │  LicoLite Aspect
+                    │  (aspect.js, etc.)   │
+                    └──────────┬───────────┘
+                               │
+                    ┌──────────▼───────────┐
+                    │    pactium (core)     │  Public API facade
+                    │    src/index.js       │
+                    └──────────┬───────────┘
+                               │
+              ┌────────────────┼────────────────┐
+              │                │                │
+    ┌─────────▼──────┐  ┌─────▼──────┐  ┌─────▼──────────┐
+    │  Pactium Core  │  │   Proof    │  │  Maintenance   │
+    │  pactium-core  │  │ envelope   │  │  task-engine   │
+    │                │  │ bundle     │  │  repair plan   │
+    └───────┬────────┘  └─────┬──────┘  └────────────────┘
+            │                 │
+    ┌───────┼─────────────────┼──────────────────┐
+    │       │                 │                  │
+    │  ┌────▼────┐  ┌────────▼───────┐  ┌──────▼──────┐
+    │  │ Ledger  │  │ Index Engine   │  │ Verification│
+    │  │ transp. │  │ snapshot-      │  │ failure.js  │
+    │  │ log     │  │ merkle-index   │  └─────────────┘
+    │  └────┬────┘  └────────┬───────┘
+    │       │                │
+    │  ┌────▼────────────────▼───────┐
+    │  │     Protocol Layer          │
+    │  │  canonical/value.js         │
+    │  │  protocol/constants.js      │
+    │  │  protocol/hashing.js        │
+    │  └─────────────┬───────────────┘
+    │                │
+    │  ┌─────────────▼───────────────┐
+    │  │     Storage Port            │
+    │  │  local-json-storage-port.js │
+    │  └─────────────────────────────┘
+    └────────────────────────────────────────────┘
+```
+
+## Authority Model
 
 The Operation Ledger is the global ordering authority. Workspace Projection, Merkle State, Checkpoint Tree, lifecycle, idempotency, and causality indexes are verifiable structures, but they do not replace Ledger Authority.
 
 The shared Verifiable Index Engine is the canonical ordered-key proof engine. State, checkpoint, workspace projection, lifecycle, idempotency, and causality indexes use domain adapters over that shared engine rather than separate tree implementations.
 
+## Data Flow: Recording an Operation
+
+```text
+  Host calls recordOperation(input)
+       │
+       ▼
+  ┌─────────────────────────────┐
+  │ 1. Idempotency Check        │ Check Intent/Outcome Idempotency Indexes
+  │    (replay if existing)     │ Return existing proof if found
+  └──────────────┬──────────────┘
+                 │ (new operation)
+                 ▼
+  ┌─────────────────────────────┐
+  │ 2. Canonical Encode         │ Normalize input to PactiumCanonicalValue
+  │    + Protocol Hash          │ Compute content-addressed identifiers
+  └──────────────┬──────────────┘
+                 │
+                 ▼
+  ┌─────────────────────────────┐
+  │ 3. Ledger Append            │ Append Intent + Outcome as leaf entries
+  │    (Transparency Log)       │ Compute new Ledger Head
+  └──────────────┬──────────────┘
+                 │
+                 ▼
+  ┌─────────────────────────────┐
+  │ 4. Index Updates            │ Update lifecycle, idempotency, workspace,
+  │    (Verifiable Index Engine)│ state, checkpoint, and causality indexes
+  └──────────────┬──────────────┘
+                 │
+                 ▼
+  ┌─────────────────────────────┐
+  │ 5. Proof Assembly           │ Gather inclusion proof, index proofs,
+  │    (Proof Envelope)         │ state root, extensions → Proof Envelope
+  └──────────────┬──────────────┘
+                 │
+                 ▼
+  ┌─────────────────────────────┐
+  │ 6. Return Proof Envelope    │ Content-addressed Proof Material Refs
+  │    to caller                │ included for later verification
+  └─────────────────────────────┘
+```
+
+## Data Flow: Verifying a Proof Envelope
+
+```text
+  Caller provides Proof Envelope
+       │
+       ▼
+  ┌─────────────────────────────┐
+  │ 1. Resolve Proof Material   │ Load content-addressed blocks via refs
+  └──────────────┬──────────────┘
+                 │
+                 ▼
+  ┌─────────────────────────────┐
+  │ 2. Ledger Inclusion Check   │ Verify leaf hash against Ledger Head
+  │                             │ using RFC 6962 inclusion proof
+  └──────────────┬──────────────┘
+                 │
+                 ▼
+  ┌─────────────────────────────┐
+  │ 3. Index Proof Check        │ Verify membership/non-membership proofs
+  │                             │ against index roots
+  └──────────────┬──────────────┘
+                 │
+                 ▼
+  ┌─────────────────────────────┐
+  │ 4. Extension Check          │ Verify critical extensions are supported
+  │                             │ Verify extension hash bindings
+  └──────────────┬──────────────┘
+                 │
+                 ▼
+  ┌─────────────────────────────┐
+  │ 5. Result                   │ { ok, failures[], checked[] }
+  │                             │ Failures are structured, not thrown
+  └─────────────────────────────┘
+```
+
 ## LicoLite Boundary
 
 Pactium owns protocol facts, proof algorithms, canonical encoding, storage ports, verification, repair planning, and LicoLite protocol-substrate adapters.
 
 LicoLite owns runtime policy decisions, operation dispatching, side effects, UI ownership, authorization, and durable Host Evidence storage. Pactium binds LicoLite policy and workspace-effect evidence as critical proof extensions and verifies those bindings.
 
+```text
+  ┌──────────────────────────────────────────────────────┐
+  │                    LicoLite Host                      │
+  │                                                      │
+  │  Policy     Operations    Side Effects    Evidence   │
+  │  Decisions  Dispatching   Execution       Storage    │
+  │                                                      │
+  └────────────────────────┬─────────────────────────────┘
+                           │
+              ─ ─ ─ ─ ─ ─ ─│─ ─ ─ ─ ─ ─ ─  Host Boundary
+                           │
+  ┌────────────────────────▼─────────────────────────────┐
+  │                  pactium/licolite                     │
+  │                                                      │
+  │  Signing    Critical Extensions    Workspace Proj.   │
+  │  Authority  (policy + effects)     (default: on)     │
+  │                                                      │
+  └────────────────────────┬─────────────────────────────┘
+                           │
+  ┌────────────────────────▼─────────────────────────────┐
+  │                   Pactium Core                       │
+  │                                                      │
+  │  Ledger   Index Engine   Proofs   Repair   Storage   │
+  │                                                      │
+  └──────────────────────────────────────────────────────┘
+```
+
+## Storage Architecture
+
+```text
+  Data Directory (.pactium/)
+  ├── blocks/           Content-addressed block store (CID → canonical bytes)
+  ├── protocol/         Protocol objects (scoped key-value)
+  │   ├── ledger/       Ledger entries, heads
+  │   ├── indexes/      Index roots and node references
+  │   ├── checkpoints/  Checkpoint tree state
+  │   └── projections/  Workspace projection state
+  └── metadata/         Directory metadata and protocol version
+```
+
+The Storage Port abstraction separates Pactium's protocol logic from persistence mechanics. The current implementation uses a local JSON backend. Storage backends may change how bytes are stored but cannot change canonical encoding, hash computation, or proof semantics.
+
+## Shared Engine: Index Domain Adapters
+
+All verifiable indexes share one Canonical Prolly Tree engine:
+
+```text
+  ┌─────────────────────────────────────────────────────────┐
+  │              Verifiable Index Engine                     │
+  │         (Canonical Prolly Tree + CAS nodes)             │
+  └─────────────────────────┬───────────────────────────────┘
+                            │
+       ┌────────────┬───────┼───────┬────────────┬──────────┐
+       │            │       │       │            │          │
+  ┌────▼───┐  ┌────▼──┐  ┌─▼──┐  ┌─▼──────┐  ┌─▼────┐  ┌─▼───────┐
+  │ State  │  │Worksp.│  │Life│  │Idempot.│  │Check │  │Causality│
+  │ Index  │  │Proj.  │  │cycle│ │Index   │  │point │  │Index    │
+  │Adapter │  │Adapter│  │Adp.│  │Adapter │  │Adptr │  │Adapter  │
+  └────────┘  └───────┘  └────┘  └────────┘  └──────┘  └─────────┘
+```
+
+Each domain adapter normalizes its domain-specific keys and values into canonical `Index Key` and `Index Value Ref` forms before they enter the shared engine. This means:
+
+- One set of membership/non-membership proof algorithms
+- One set of structural-sharing and diff algorithms
+- One CDC (Content-Defined Chunking) implementation
+- Consistent proof format across all domain indexes
+
 ## Current Implementation Status
 
 The current `src/` implementation is the proof-first package surface. The package root exports proof-first APIs, and `pactium/licolite` exports the first-class LicoLite Aspect.
@@ -57,6 +247,8 @@ The maintained design is implemented by these package surfaces:
 | LicoLite Aspect | `src/aspects/licolite/`: `createLicoLiteAspect`, `createLicoLiteSigner`, evidence helpers, verifier |
 | CLI and HTTP facades | `bin/pactium.mjs`, `src/http.js` |
 
+## Non-Surfaces
+
 Maintained docs must not describe SQLite storage, separate per-workspace lane queues, repair fact execution, or pressure baseline regression enforcement as implemented unless those surfaces are added and verified.
 
 If a maintained document introduces a design area that cannot be mapped to an implementation anchor, the design must be implemented and documented before release.

package/docs/logo.svg

@@ -0,0 +1,45 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="-150 -150 300 300" role="img" aria-label="Pactium Logo">
+  <title>Pactium</title>
+  <defs>
+    <linearGradient id="gold" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#c9a96e"/>
+      <stop offset="50%" stop-color="#f0d28c"/>
+      <stop offset="100%" stop-color="#a8893a"/>
+    </linearGradient>
+    <linearGradient id="silver" x1="0" y1="1" x2="1" y2="0">
+      <stop offset="0%" stop-color="#7a8ea8"/>
+      <stop offset="100%" stop-color="#b0c0d4"/>
+    </linearGradient>
+  </defs>
+
+  <circle r="140" fill="none" stroke="url(#gold)" stroke-width="0.5" opacity="0.3"/>
+
+  <g fill="none" opacity="0.2" stroke="#c9a96e" stroke-width="0.8">
+    <line x1="0" y1="-134" x2="0" y2="-140" transform="rotate(0)"/>
+    <line x1="0" y1="-134" x2="0" y2="-140" transform="rotate(22.5)"/>
+    <line x1="0" y1="-134" x2="0" y2="-140" transform="rotate(45)"/>
+    <line x1="0" y1="-134" x2="0" y2="-140" transform="rotate(67.5)"/>
+    <line x1="0" y1="-134" x2="0" y2="-140" transform="rotate(90)"/>
+    <line x1="0" y1="-134" x2="0" y2="-140" transform="rotate(112.5)"/>
+    <line x1="0" y1="-134" x2="0" y2="-140" transform="rotate(135)"/>
+    <line x1="0" y1="-134" x2="0" y2="-140" transform="rotate(157.5)"/>
+    <line x1="0" y1="-134" x2="0" y2="-140" transform="rotate(180)"/>
+    <line x1="0" y1="-134" x2="0" y2="-140" transform="rotate(202.5)"/>
+    <line x1="0" y1="-134" x2="0" y2="-140" transform="rotate(225)"/>
+    <line x1="0" y1="-134" x2="0" y2="-140" transform="rotate(247.5)"/>
+    <line x1="0" y1="-134" x2="0" y2="-140" transform="rotate(270)"/>
+    <line x1="0" y1="-134" x2="0" y2="-140" transform="rotate(292.5)"/>
+    <line x1="0" y1="-134" x2="0" y2="-140" transform="rotate(315)"/>
+    <line x1="0" y1="-134" x2="0" y2="-140" transform="rotate(337.5)"/>
+  </g>
+
+  <polygon fill="none"
+    points="115.5,47.8 47.8,115.5 -47.8,115.5 -115.5,47.8 -115.5,-47.8 -47.8,-115.5 47.8,-115.5 115.5,-47.8"
+    stroke="url(#gold)" stroke-width="1.8" opacity="0.65"/>
+
+  <circle r="113" fill="none" stroke="#d4c5a0" stroke-width="1.2" opacity="0.45"/>
+  <circle cx="-16" cy="16" r="89" fill="none" stroke="url(#silver)" stroke-width="1.1" opacity="0.40"/>
+  <circle cx="13" cy="-10" r="63" fill="none" stroke="#a0b0c4" stroke-width="1.0" opacity="0.45"/>
+  <circle r="36" fill="none" stroke="url(#gold)" stroke-width="1.2" opacity="0.55"/>
+  <circle r="3" fill="#c9a96e" opacity="0.5"/>
+</svg>