pactium 0.2.0

package/README.md

@@ -0,0 +1,92 @@
+<p align="center">
+  <strong>Pactium — the verifiable protocol substrate for LicoLite.</strong>
+</p>
+
+Pactium is a proof-first npm package that provides LicoLite's durable protocol substrate: verifiable operation facts, workspace projections, checkpoint recovery history, Merkle state, proof envelopes, and proof bundles.
+
+Pactium implements the current verifiable protocol model documented in [Architecture](./docs/architecture/ARCHITECTURE.md), [Protocols](./docs/protocols/PROTOCOLS.md), and [Protocol Profile](./docs/protocols/PROFILE.md). The package root exposes only the latest proof-first API.
+
+## Direction
+
+- **Operation Ledger** is the global ordering authority and uses a transparency log for inclusion and consistency proofs.
+- **Operation lifecycle** is append-only through Operation Intent and Operation Outcome facts.
+- **Workspace Projection** is first priority for the LicoLite Aspect and is enabled by default.
+- **Verifiable Index Engine** is a shared Canonical Prolly Tree based proof engine for state, checkpoint, workspace projection, lifecycle, idempotency, and causality indexes.
+- **Proof Envelopes** bind Ledger, Workspace Projection, Checkpoint, State, and LicoLite evidence into one receipt shape.
+- **Proof Bundles** export portable CAR-like proof material for offline verification.
+- **LicoLite Aspect** is a first-class package surface under `pactium/licolite`.
+
+## Boundaries
+
+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, and durable host evidence storage.
+
+## Status
+
+The proof-first implementation is active. Pactium accepts the latest verifiable schema only; earlier experimental data formats are rejected.
+
+## Usage
+
+```js
+import { createPactium } from "pactium";
+
+const pactium = createPactium({ dataDir: "./.pactium" });
+
+const envelope = await pactium.recordOperation({
+  operationId: "workspace.file.write",
+  workspaceId: "workspace-a",
+  idempotencyKey: "intent-a",
+  outcomeIdempotencyKey: "outcome-a",
+  input: { path: "docs/a.md" },
+  stateMutations: [
+    { key: "docs/a.md", value: { text: "hello" } }
+  ]
+});
+
+console.log(await pactium.verifyEnvelope(envelope));
+```
+
+```js
+import { createLicoLiteAspect, createLicoLiteSigner } from "pactium/licolite";
+
+const signingSecret = process.env.LICOLITE_SIGNING_SECRET;
+if (!signingSecret) throw new Error("LICOLITE_SIGNING_SECRET is required.");
+
+const licolite = createLicoLiteAspect({
+  evidencePolicy: "production",
+  signer: createLicoLiteSigner({
+    signerId: "host-managed-signer",
+    secret: signingSecret
+  })
+});
+
+const envelope = await licolite.recordWorkspaceOperation({
+  operationId: "workspace.effect",
+  workspaceId: "workspace-a",
+  policyEvidence: { decision: "allow" },
+  workspaceEffectEvidence: { durableRef: "host:asset:a" }
+});
+
+console.log(await licolite.verifyEnvelope(envelope));
+```
+
+## Verification
+
+```bash
+npm run verify:release
+```
+
+The default release gate runs deterministic proof vectors, regression snapshots, seeded property tests, scaled public API pressure profiles, coverage thresholds, hygiene checks, release-readiness checks, and package dry run. CI runs the same release gate on every supported Node.js LTS major.
+
+## Documentation
+
+- [Terms](./docs/TERM.md)
+- [Protocol Overview](./docs/protocols/PROTOCOLS.md)
+- [Protocol Profile](./docs/protocols/PROFILE.md)
+- [Architecture](./docs/architecture/ARCHITECTURE.md)
+- [LicoLite Aspect](./docs/LICOLITE-ASPECT.md)
+
+## License
+
+This project is licensed under the [GNU General Public License v3.0 or later](LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,90 @@
+# Pactium
+
+Pactium 是 LicoLite 的 proof-first protocol substrate，用于证明系统状态是可记录、可回溯、可管理的。
+
+## 当前状态
+
+- package root 只导出 proof-first API。
+- `pactium/licolite` 是 first-class LicoLite Aspect。
+- 数据目录采用 latest schema only；不会执行历史数据迁移。
+- Operation Intent / Operation Outcome 是 append-only 生命周期事实。
+- Workspace Projection 默认服务 LicoLite，并与 Ledger commit 同步更新。
+- Proof Envelope 与 Proof Bundle 是主要 receipt/export 形状。
+
+## 安装
+
+```bash
+npm install pactium
+```
+
+## Root API
+
+```js
+import { createPactium } from "pactium";
+
+const pactium = createPactium({ dataDir: "./.pactium" });
+
+const envelope = await pactium.recordOperation({
+  operationId: "workspace.file.write",
+  workspaceId: "workspace-a",
+  idempotencyKey: "intent-a",
+  outcomeIdempotencyKey: "outcome-a",
+  input: { path: "docs/a.md" },
+  stateMutations: [
+    { key: "docs/a.md", value: { text: "hello" } }
+  ]
+});
+
+console.log(envelope.envelopeId);
+console.log(await pactium.verifyEnvelope(envelope));
+```
+
+## LicoLite Aspect
+
+```js
+import { createLicoLiteAspect, createLicoLiteSigner } from "pactium/licolite";
+
+const signingSecret = process.env.LICOLITE_SIGNING_SECRET;
+if (!signingSecret) throw new Error("LICOLITE_SIGNING_SECRET is required.");
+
+const licolite = createLicoLiteAspect({
+  evidencePolicy: "production",
+  signer: createLicoLiteSigner({
+    signerId: "host-managed-signer",
+    secret: signingSecret
+  })
+});
+
+const envelope = await licolite.recordWorkspaceOperation({
+  operationId: "workspace.effect",
+  workspaceId: "workspace-a",
+  policyEvidence: { decision: "allow" },
+  workspaceEffectEvidence: { durableRef: "host:asset:a" }
+});
+
+console.log(await licolite.verifyEnvelope(envelope));
+```
+
+## 验证
+
+```bash
+npm run verify:release
+```
+
+完整压力 profile 可通过以下命令显式开启：
+
+```bash
+PACTIUM_FULL_PRESSURE=1 npm run verify:protocol:gates
+```
+
+## 文档
+
+- [Terms](./docs/TERM.md)
+- [Protocol Profile](./docs/protocols/PROFILE.md)
+- [Protocol Overview](./docs/protocols/PROTOCOLS.md)
+- [Architecture](./docs/architecture/ARCHITECTURE.md)
+- [LicoLite Aspect](./docs/LICOLITE-ASPECT.md)
+
+## 许可证
+
+本项目基于 [GNU General Public License v3.0 or later](LICENSE) 发布。

package/SECURITY.md

@@ -0,0 +1,7 @@
+# Security
+
+Pactium records operation metadata and redacts common sensitive fields before writing ledger inputs.
+
+Host systems remain responsible for authentication, authorization, network exposure, tenant isolation, and secret storage. Pactium should be embedded behind the host system's security boundary.
+
+Please report security issues privately through the repository owner rather than opening a public issue with exploit details.

package/bin/pactium.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import { createPactium, resolveDataDir } from "../src/index.js";
+import { startPactiumHttpServer } from "../src/http.js";
+import { createLicoLiteAspect } from "../src/aspects/licolite/index.js";
+
+function argValue(args, name, fallback = "") {
+  const index = args.indexOf(name);
+  return index >= 0 && index + 1 < args.length ? args[index + 1] : fallback;
+}
+
+function hasArg(args, name) {
+  return args.includes(name);
+}
+
+function printJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+async function bodyFromArgs(args) {
+  const inline = argValue(args, "--body", "");
+  if (inline) return JSON.parse(inline);
+  const file = argValue(args, "--body-file", "");
+  if (file) return JSON.parse(await fs.readFile(file, "utf8"));
+  if (!process.stdin.isTTY) {
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+    const text = Buffer.concat(chunks).toString("utf8").trim();
+    if (text) return JSON.parse(text);
+  }
+  return {};
+}
+
+function usage() {
+  return `Pactium
+
+Usage:
+  pactium doctor [--data-dir DIR]
+  pactium serve [--data-dir DIR] [--host HOST] [--port PORT]
+  pactium intent begin --body JSON
+  pactium outcome append --body JSON
+  pactium operation record --body JSON
+  pactium envelope verify --body JSON
+  pactium bundle verify --body JSON
+  pactium licolite record --body JSON
+  pactium licolite verify --body JSON
+`;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || hasArg(args, "--help") || hasArg(args, "-h")) {
+    process.stdout.write(usage());
+    return;
+  }
+  const dataDir = resolveDataDir(argValue(args, "--data-dir", ""));
+  const pactium = createPactium({ dataDir });
+  const licolite = createLicoLiteAspect({
+    pactium,
+    evidencePolicy: argValue(args, "--evidence-policy", "opportunistic")
+  });
+  const [domain, action] = args.filter((arg, index, all) => {
+    if (index > 0 && all[index - 1].startsWith("--")) return false;
+    return !arg.startsWith("--");
+  });
+
+  if (domain === "doctor") {
+    printJson(await pactium.doctor());
+    return;
+  }
+  if (domain === "serve") {
+    const host = argValue(args, "--host", "127.0.0.1");
+    const port = Number(argValue(args, "--port", process.env.PACTIUM_HTTP_PORT || "7288"));
+    const started = await startPactiumHttpServer({ dataDir, host, port });
+    printJson({
+      protocol: started.protocol,
+      url: started.url,
+      dataDir
+    });
+    return;
+  }
+  if (domain === "intent" && action === "begin") {
+    printJson(await pactium.beginOperationIntent(await bodyFromArgs(args)));
+    return;
+  }
+  if (domain === "outcome" && action === "append") {
+    printJson(await pactium.appendOperationOutcome(await bodyFromArgs(args)));
+    return;
+  }
+  if (domain === "operation" && action === "record") {
+    printJson(await pactium.recordOperation(await bodyFromArgs(args)));
+    return;
+  }
+  if (domain === "envelope" && action === "verify") {
+    printJson(await pactium.verifyEnvelope(await bodyFromArgs(args)));
+    return;
+  }
+  if (domain === "bundle" && action === "verify") {
+    const { verifyProofBundle } = await import("../src/index.js");
+    printJson(await verifyProofBundle(await bodyFromArgs(args)));
+    return;
+  }
+  if (domain === "licolite" && action === "record") {
+    printJson(await licolite.recordWorkspaceOperation(await bodyFromArgs(args)));
+    return;
+  }
+  if (domain === "licolite" && action === "verify") {
+    printJson(await licolite.verifyEnvelope(await bodyFromArgs(args)));
+    return;
+  }
+  process.exitCode = 1;
+  process.stderr.write(usage());
+}
+
+main().catch((error) => {
+  process.exitCode = 1;
+  printJson({
+    code: "pactium_cli_error",
+    error: error instanceof Error ? error.message : String(error)
+  });
+});

package/docs/LICOLITE-ASPECT.md

@@ -0,0 +1,57 @@
+# LicoLite Aspect
+
+This document describes the current LicoLite package surface implemented by `pactium/licolite`.
+
+Pactium is LicoLite's proof-first protocol substrate. LicoLite is the primary host, and `pactium/licolite` is a first-class aspect whose requirements may shape Pactium core capability design.
+
+## Non-Negotiables
+
+| Area | Required behavior |
+| --- | --- |
+| Package relationship | Pactium is subordinate to LicoLite and provides the protocol substrate LicoLite needs. |
+| Export shape | Package root exposes latest proof-first API only; `pactium/licolite` exposes the LicoLite Aspect. |
+| Workspace Projection | Enabled by default for LicoLite and first priority. |
+| Ledger authority | Global Operation Ledger remains the ordering authority. |
+| Projection commit | Workspace Projection updates happen synchronously with Ledger-bound protocol commits. |
+| Workspace reverse lookup | Workspace Membership Index proves whether a Ledger fact belongs to a workspace. |
+| Signing | Enabled by default for the LicoLite Aspect; missing signer behavior is LicoLite policy. |
+| Policy evidence | LicoLite Policy Extension is critical and hash-bound. |
+| Workspace effect evidence | LicoLite Workspace Effect Extension is critical and hash-bound. |
+| Verifier | LicoLite Verifier is required and returns structured Verification Failures. |
+| Data directories | New Pactium-format data directories only. |
+| Migration | No historical LicoLite or Pactium data migration in Pactium. |
+| Host boundary | LicoLite owns policy decisions, operation dispatching, side effects, UI, authorization, and durable Host Evidence storage. |
+
+## Required Public Surfaces
+
+| Surface | Requirement |
+| --- | --- |
+| Root API | Proof-first lifecycle, Ledger, index, state, checkpoint, proof, verification, maintenance, and repair APIs only. |
+| `pactium/licolite` | LicoLite workspace operation recording and verification with default Workspace Projection. |
+| Proof response | Synchronous Pactium Proof Envelope with content-addressed Proof Material Refs. |
+| Offline proof | Proof Bundle export and verification without local Pactium storage. |
+| Lifecycle | Operation Intent, Operation Outcome, Open Intent recovery, idempotency replay, and Operation Causality Index. |
+| Workspace projection | Workspace Order Index plus Workspace Membership Index over the shared Verifiable Index Engine. |
+| State | State Commit bound to Operation Outcome only. |
+| Checkpoint | Intent Checkpoint and Outcome Checkpoint; LicoLite side-effect checkpoints default to Outcome. |
+| Repair | Repair Planner produces deterministic plans; hosts execute them. |
+
+## Explicitly Rejected Old Assumptions
+
+- `pactium/licolite` is not an external plugin.
+- LicoLite Workspace Projection is not optional or secondary.
+- Pactium does not keep removed storage-shaped APIs in the package root export.
+- Pactium does not read or migrate historical LicoLite protocol data in place.
+- Pactium does not expose proof hashes as substitutes for membership, non-membership, consistency, or bundle verification.
+- Pactium does not execute LicoLite policy, side effects, operation dispatching, UI behavior, or authorization.
+- Pactium does not make Protocol Hash, Canonical Value encoding, Prolly Tree chunking, or proof formats host configurable.
+
+## Acceptance Evidence
+
+The LicoLite Aspect is acceptable only when the release gate passes and includes evidence for:
+
+- root export and `pactium/licolite` export snapshots;
+- LicoLite workspace operations with signing, critical extensions, Workspace Projection, State Commit, Checkpoint, Proof Envelope, and Proof Bundle;
+- missing signer/evidence behavior controlled by LicoLite policy, with production-style fail-closed tests;
+- structured Verification Failures for bad signature, missing proof material, unsupported critical extension, bad workspace projection proof, and Ledger consistency failure;
+- public API pressure test `api:licolite-record` in the default scaled release gate, with the 5,000-operation profile available through `PACTIUM_FULL_PRESSURE=1 npm run verify:protocol:gates` for explicit full review.

package/docs/README.md

@@ -0,0 +1,13 @@
+# Pactium Public Docs
+
+Pactium is a proof-first protocol substrate for LicoLite.
+
+## Package Documents
+
+- [Architecture](architecture/ARCHITECTURE.md)
+- [Protocols](protocols/PROTOCOLS.md)
+- [Protocol Profile](protocols/PROFILE.md)
+- [LicoLite Aspect](LICOLITE-ASPECT.md)
+- [Terms](TERM.md)
+
+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.