pactium 0.2.0 → 0.2.1

package/examples/README.md

@@ -0,0 +1,106 @@
+# Pactium Examples
+
+This directory contains runnable examples demonstrating Pactium's core capabilities. Each example is a standalone `.mjs` file that can be executed directly with Node.js.
+
+## Running Examples
+
+```bash
+# From the project root
+node examples/record-operation.mjs
+node examples/verify-envelope.mjs
+node examples/export-proof-bundle.mjs
+node examples/workspace-projection.mjs
+node examples/licolite-signed-operation.mjs
+```
+
+Examples create a `.pactium` data directory in the working directory. Remove it between runs for a fresh state: `rm -rf .pactium`.
+
+## Learning Path
+
+If you're new to Pactium, follow these examples in order:
+
+### 1. Record an Operation
+
+**File:** [`record-operation.mjs`](./record-operation.mjs)
+
+The simplest end-to-end example. Creates a LicoLite Aspect instance and records a workspace operation with policy evidence and workspace effect evidence, then verifies the resulting envelope.
+
+**Concepts introduced:**
+- `createPactium()` instance creation
+- `createLicoLiteAspect()` aspect setup
+- `recordWorkspaceOperation()` high-level API
+- `verifyEnvelope()` verification
+- Proof Envelope structure
+
+### 2. Two-Phase Operation Lifecycle
+
+**File:** [`verify-envelope.mjs`](./verify-envelope.mjs)
+
+Demonstrates the low-level two-phase operation lifecycle: first record an Operation Intent, then append an Operation Outcome. This is the pattern for operations where you need to track the "in-progress" state.
+
+**Concepts introduced:**
+- `beginOperationIntent()` -- declare intent before execution
+- `appendOperationOutcome()` -- declare result after execution
+- Two-envelope lifecycle (intent + outcome)
+- Envelope verification with `checked` details
+
+### 3. Export and Verify a Proof Bundle
+
+**File:** [`export-proof-bundle.mjs`](./export-proof-bundle.mjs)
+
+Shows how to export a recorded operation as a portable Proof Bundle and verify it independently -- without access to the original Pactium storage.
+
+**Concepts introduced:**
+- `exportProofBundle()` -- create portable proof material
+- `verifyProofBundle()` -- standalone verification function
+- Bundle structure (type, hash, content-addressed blocks)
+- Portable/offline verification
+
+### 4. Workspace Projection and Membership Proofs
+
+**File:** [`workspace-projection.mjs`](./workspace-projection.mjs)
+
+Records operations across multiple workspaces, queries workspace projections, and demonstrates verifiable workspace membership and non-membership proofs.
+
+**Concepts introduced:**
+- Multi-workspace operation recording
+- `getWorkspaceProjection()` -- query workspace state
+- `proveWorkspaceMembership()` -- prove event belongs to workspace
+- Non-membership proofs -- prove event does NOT belong to workspace
+- Workspace isolation guarantees
+
+### 5. LicoLite Signed Operations
+
+**File:** [`licolite-signed-operation.mjs`](./licolite-signed-operation.mjs)
+
+Full LicoLite integration example with Ed25519 signing, critical policy/effect extensions, production evidence policy, and LicoLite-level verification including bundle export.
+
+**Concepts introduced:**
+- `createLicoLiteSigner()` -- Ed25519 signing authority
+- `evidencePolicy: "production"` -- fail-closed on missing evidence
+- Critical extensions (policy + workspace effect)
+- LicoLite-level verification (core + signing + extensions)
+- Bundle export through the aspect
+
+## Key Patterns
+
+### Idempotent Recording
+
+All examples use `idempotencyKey` and `outcomeIdempotencyKey`. If you re-run an example without clearing the data directory, the second call returns an idempotency replay (existing proof) rather than creating duplicate ledger entries.
+
+### Proof-First API
+
+Every write operation returns a Proof Envelope. The envelope is the proof -- it contains or references all material needed to verify that the operation was recorded and the ledger is consistent.
+
+### Error Handling
+
+Verification results are returned as structured objects (`{ ok, failures, checked }`), not thrown exceptions. Verification failures include layer, code, severity, and repairability information.
+
+## Next Steps
+
+After working through these examples, consult:
+
+- [API Reference](../docs/API.md) for complete API documentation
+- [Protocol Specification](../docs/protocols/PROTOCOLS.md) for protocol behavior details
+- [Architecture](../docs/architecture/ARCHITECTURE.md) for system design and data flow
+- [FAQ](../docs/FAQ.md) for common questions

package/examples/export-proof-bundle.mjs

@@ -0,0 +1,40 @@
+/**
+ * Example: Export and Verify a Proof Bundle
+ *
+ * Demonstrates exporting a portable proof bundle from a recorded operation
+ * and verifying it without access to local Pactium storage.
+ */
+import { createPactium, verifyProofBundle } from "../src/index.js";
+
+const pactium = createPactium({ dataDir: "./.pactium" });
+
+// Record an operation
+const envelope = await pactium.recordOperation({
+  operationId: "workspace.config.update",
+  workspaceId: "settings-workspace",
+  idempotencyKey: "update-theme-intent",
+  outcomeIdempotencyKey: "update-theme-outcome",
+  input: { setting: "theme", value: "dark" },
+  stateMutations: [
+    { key: "settings/theme", value: { mode: "dark", updatedBy: "user-1" } }
+  ]
+});
+
+console.log("Operation recorded:", envelope.envelopeId);
+
+// Export as a portable proof bundle
+const bundle = await pactium.exportProofBundle(envelope);
+
+console.log("Bundle exported:");
+console.log("  Type:", bundle.bundleType);
+console.log("  Hash:", bundle.bundleHash);
+console.log("  Blocks:", bundle.index?.length ?? 0, "content-addressed blocks");
+
+// Verify the bundle independently (no local storage needed)
+const result = await verifyProofBundle(bundle);
+
+console.log(JSON.stringify({
+  verified: result.ok,
+  bundleHash: result.bundleHash,
+  failures: result.failures
+}, null, 2));

package/examples/licolite-signed-operation.mjs

@@ -0,0 +1,62 @@
+/**
+ * Example: LicoLite Signed Workspace Operation
+ *
+ * Demonstrates using the LicoLite Aspect with signing enabled,
+ * critical policy/effect extensions, and LicoLite-level verification.
+ */
+import { createLicoLiteAspect, createLicoLiteSigner } from "../src/aspects/licolite/index.js";
+
+// Create a LicoLite Aspect with signing and production evidence policy
+const licolite = createLicoLiteAspect({
+  dataDir: "./.pactium",
+  evidencePolicy: "production",
+  signer: createLicoLiteSigner({
+    signerId: "example-signer",
+    secret: "example-secret-for-demonstration-only"
+  })
+});
+
+// Record a workspace operation with full evidence
+const envelope = await licolite.recordWorkspaceOperation({
+  operationId: "workspace.asset.upload",
+  workspaceId: "media-workspace",
+  idempotencyKey: "upload-image-intent",
+  outcomeIdempotencyKey: "upload-image-outcome",
+  input: {
+    filename: "photo.jpg",
+    size: 1024000,
+    mimeType: "image/jpeg"
+  },
+  // LicoLite policy evidence (critical extension)
+  policyEvidence: {
+    decision: "allow",
+    rule: "upload-size-limit",
+    evaluatedAt: new Date().toISOString()
+  },
+  // LicoLite workspace effect evidence (critical extension)
+  workspaceEffectEvidence: {
+    durableRef: "host:storage:media-workspace/photo.jpg",
+    effectType: "file-upload",
+    byteLength: 1024000
+  },
+  stateMutations: [
+    { key: "assets/photo.jpg", value: { ref: "host:storage:media-workspace/photo.jpg", size: 1024000 } }
+  ]
+});
+
+console.log("Signed envelope ID:", envelope.envelopeId);
+console.log("Critical extensions:", envelope.criticalExtensions);
+
+// LicoLite-level verification (checks core + signing + extensions)
+const result = await licolite.verifyEnvelope(envelope);
+
+console.log(JSON.stringify({
+  verified: result.ok,
+  failures: result.failures
+}, null, 2));
+
+// Export as portable bundle for external verification
+const bundle = await licolite.exportProofBundle(envelope);
+const bundleResult = await licolite.verifyBundle(bundle);
+
+console.log("\nBundle verification:", bundleResult.ok ? "PASS" : "FAIL");

package/examples/verify-envelope.mjs

@@ -0,0 +1,41 @@
+/**
+ * Example: Verify a Proof Envelope
+ *
+ * Demonstrates the two-phase operation lifecycle (intent then outcome)
+ * and verifying the resulting proof envelope.
+ */
+import { createPactium } from "../src/index.js";
+
+const pactium = createPactium({ dataDir: "./.pactium" });
+
+// Phase 1: Begin an Operation Intent
+const intentEnvelope = await pactium.beginOperationIntent({
+  operationId: "workspace.document.create",
+  workspaceId: "docs-workspace",
+  idempotencyKey: "create-readme-intent",
+  input: { path: "README.md", format: "markdown" }
+});
+
+console.log("Intent recorded:", intentEnvelope.factId);
+
+// Phase 2: Append the Operation Outcome
+const outcomeEnvelope = await pactium.appendOperationOutcome({
+  intentId: intentEnvelope.factId,
+  workspaceId: "docs-workspace",
+  idempotencyKey: "create-readme-outcome",
+  outcome: "success",
+  stateMutations: [
+    { key: "README.md", value: { content: "# Project\n", format: "markdown" } }
+  ]
+});
+
+console.log("Outcome recorded:", outcomeEnvelope.factId);
+
+// Verify the outcome envelope
+const result = await pactium.verifyEnvelope(outcomeEnvelope);
+
+console.log(JSON.stringify({
+  verified: result.ok,
+  checked: result.checked,
+  failures: result.failures
+}, null, 2));

package/examples/workspace-projection.mjs

@@ -0,0 +1,55 @@
+/**
+ * Example: Workspace Projection and Membership Proof
+ *
+ * Demonstrates recording multiple operations across workspaces,
+ * querying workspace projections, and proving workspace membership.
+ */
+import { createPactium } from "../src/index.js";
+
+const pactium = createPactium({ dataDir: "./.pactium" });
+
+// Record operations in different workspaces
+const envelopeA = await pactium.recordOperation({
+  operationId: "workspace.file.write",
+  workspaceId: "project-alpha",
+  idempotencyKey: "alpha-write-1",
+  outcomeIdempotencyKey: "alpha-outcome-1",
+  input: { path: "src/main.js" },
+  stateMutations: [
+    { key: "src/main.js", value: { content: "console.log('alpha')" } }
+  ]
+});
+
+const envelopeB = await pactium.recordOperation({
+  operationId: "workspace.file.write",
+  workspaceId: "project-beta",
+  idempotencyKey: "beta-write-1",
+  outcomeIdempotencyKey: "beta-outcome-1",
+  input: { path: "src/index.js" },
+  stateMutations: [
+    { key: "src/index.js", value: { content: "console.log('beta')" } }
+  ]
+});
+
+// Query workspace projection for project-alpha
+const projection = await pactium.getWorkspaceProjection("project-alpha");
+console.log("Workspace 'project-alpha' projection:");
+console.log(JSON.stringify(projection, null, 2));
+
+// Prove that envelopeA's fact belongs to project-alpha
+const membershipProof = await pactium.proveWorkspaceMembership({
+  workspaceId: "project-alpha",
+  ledgerEventId: envelopeA.factRef.ledgerEventId
+});
+
+console.log("\nMembership proof for envelopeA in project-alpha:");
+console.log("  Member:", membershipProof.member);
+
+// Prove that envelopeB's fact does NOT belong to project-alpha
+const nonMembershipProof = await pactium.proveWorkspaceMembership({
+  workspaceId: "project-alpha",
+  ledgerEventId: envelopeB.factRef.ledgerEventId
+});
+
+console.log("\nMembership proof for envelopeB in project-alpha:");
+console.log("  Member:", nonMembershipProof.member);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pactium",
-  "version": "0.2.0",
-  "description": "Pactium — the proof-first protocol substrate for LicoLite state recording and recovery.",
+  "version": "0.2.1",
+  "description": "Proof-first protocol substrate for verifiable operation facts, append-only recovery history, and cryptographic state verification.",
   "author": "Unka Y.Y.",
   "license": "GPL-3.0-or-later",
   "repository": {
@@ -12,7 +12,27 @@
     "url": "https://github.com/Unka-Malloc/Pactium/issues"
   },
   "homepage": "https://github.com/Unka-Malloc/Pactium#readme",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/Unka-Malloc"
+  },
+  "keywords": [
+    "merkle",
+    "proof",
+    "transparency-log",
+    "verifiable",
+    "prolly-tree",
+    "append-only",
+    "ledger",
+    "cryptographic",
+    "operation-ledger",
+    "proof-envelope",
+    "workspace",
+    "protocol",
+    "integrity"
+  ],
   "type": "module",
+  "sideEffects": false,
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
   "exports": {
@@ -25,7 +45,8 @@
       "types": "./src/aspects/licolite/index.d.ts",
       "import": "./src/aspects/licolite/index.js",
       "default": "./src/aspects/licolite/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "bin": {
     "pactium": "bin/pactium.mjs"
@@ -39,7 +60,12 @@
     "src/",
     "bin/",
     "examples/",
+    "CHANGELOG.md",
+    "docs/logo.svg",
     "docs/README.md",
+    "docs/API.md",
+    "docs/FAQ.md",
+    "docs/MIGRATION.md",
     "docs/architecture/",
     "docs/protocols/",
     "docs/LICOLITE-ASPECT.md",
@@ -54,16 +80,18 @@
   },
   "scripts": {
     "start": "pactium serve",
+    "docs:sync-version": "node scripts/update-published-doc-versions.mjs --write",
     "test": "node --test tests/pactium/*.test.mjs",
     "test:coverage": "node --test --experimental-test-coverage '--test-coverage-exclude=bin/**' --test-coverage-exclude=src/http.js --test-coverage-lines=95 --test-coverage-functions=95 --test-coverage-branches=90 tests/pactium/*.test.mjs",
     "verify": "npm run verify:release",
     "verify:core": "npm run test:coverage",
+    "verify:docs:versions": "node scripts/update-published-doc-versions.mjs --check",
     "verify:hygiene": "node scripts/verify-pactium-hygiene.mjs",
     "verify:protocol:gates": "node scripts/verify-protocol-gates.mjs",
     "verify:package:contents": "node scripts/verify-package-contents.mjs",
     "verify:release:readiness": "node scripts/verify-release-readiness.mjs",
-    "verify:release": "npm run verify:hygiene && npm run verify:core && npm run verify:protocol:gates && npm run verify:release:readiness && npm run verify:package:contents && npm run pack:dry-run && npm run publish:dry-run",
+    "verify:release": "npm run verify:hygiene && npm run verify:core && npm run verify:protocol:gates && npm run verify:release:readiness && npm run verify:docs:versions && npm run verify:package:contents && npm run pack:dry-run && npm run publish:dry-run",
     "pack:dry-run": "npm pack --dry-run",
-    "publish:dry-run": "npm publish --dry-run"
+    "publish:dry-run": "node scripts/verify-publish-dry-run.mjs"
   }
 }

package/src/index.d.ts

@@ -185,7 +185,7 @@ export interface PactiumCore {
 
 export const PACTIUM_PROTOCOL: "pactium.v0.2";
 export const PACTIUM_SCHEMA_VERSION: "pactium.v0.2.schema.latest";
-export const PACTIUM_PACKAGE_VERSION: "0.2.0";
+export const PACTIUM_PACKAGE_VERSION: "0.2.1";
 export const PACTIUM_INDEX_ENGINE: "pactium.verifiable-index-engine";
 export const PACTIUM_INDEX_SPLITTER: "pactium-cdc-boundary";
 export const PACTIUM_PROOF_BUNDLE_TYPE: "pactium.proof-bundle.indexed";

package/src/protocol/constants.js

@@ -1,6 +1,6 @@
 export const PACTIUM_PROTOCOL = "pactium.v0.2";
 export const PACTIUM_SCHEMA_VERSION = "pactium.v0.2.schema.latest";
-export const PACTIUM_PACKAGE_VERSION = "0.2.0";
+export const PACTIUM_PACKAGE_VERSION = "0.2.1";
 export const PACTIUM_INDEX_ENGINE = "pactium.verifiable-index-engine";
 export const PACTIUM_INDEX_SPLITTER = "pactium-cdc-boundary";
 export const PACTIUM_PROOF_BUNDLE_TYPE = "pactium.proof-bundle.indexed";