scxq2-cc 1.0.0

package/README.md

@@ -0,0 +1,340 @@
+<p align="center">
+  <img src="scxq2-logo.svg" alt="SCXQ2 Logo" width="200" height="200">
+</p>
+
+<h1 align="center">SCXQ2</h1>
+
+<p align="center">
+  <strong>Compression Calculus Engine</strong><br>
+  Deterministic, Proof-Generating, Content-Addressable Language Packs
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#api">API</a> •
+  <a href="#specification">Specification</a> •
+  <a href="#security">Security</a>
+</p>
+
+---
+
+## Overview
+
+SCXQ2 is a **frozen, deterministic compression calculus** that produces **content-addressable language packs**. It implements CC-v1 (Compression Calculus v1) operators to create self-verifying artifacts with cryptographic proofs of reversibility.
+
+### Key Features
+
+- **Deterministic** - Same input always produces identical output
+- **Content-Addressable** - SHA-256 identity hashes for all artifacts
+- **Proof-Generating** - Every compression includes reversibility proof
+- **Universal Runtime** - Works in Node.js, browsers, and workers
+- **Multi-Lane** - Compress multiple sources with shared dictionary
+- **Type-Safe** - Full TypeScript definitions included
+
+### What SCXQ2 Is
+
+- A **representation algebra** for compressing text
+- A **language artifact** format (dict + block + proof)
+- A **deterministic encoding** (DICT16-B64)
+
+### What SCXQ2 Is NOT
+
+- ❌ Not encryption
+- ❌ Not a file format
+- ❌ Not a transport protocol
+- ❌ Not an execution language
+
+---
+
+## Installation
+
+```bash
+npm install @asx/scxq2-cc
+```
+
+**Requirements:** Node.js 18+ or modern browser with WebCrypto
+
+---
+
+## Quick Start
+
+### Basic Compression
+
+```javascript
+import { ccCompress, ccDecompress } from '@asx/scxq2-cc';
+
+// Compress source code
+const source = `
+function hello() {
+  console.log("Hello, World!");
+}
+`;
+
+const pack = await ccCompress(source, { maxDict: 512 });
+
+console.log(pack.proof.ok);           // true - roundtrip verified
+console.log(pack.dict.dict.length);   // number of dictionary entries
+console.log(pack.audit.sizes.ratio);  // compression ratio
+
+// Decompress
+const roundtrip = ccDecompress(pack.dict, pack.block);
+console.log(roundtrip === source);    // true
+```
+
+### Multi-Lane Compression
+
+```javascript
+import { ccCompressLanes, ccDecompress } from '@asx/scxq2-cc';
+
+const pack = await ccCompressLanes({
+  lanes: [
+    { lane_id: 'index', text: 'export * from "./utils";' },
+    { lane_id: 'utils', text: 'export function utils() { return 42; }' },
+    { lane_id: 'types', text: 'export interface Config { value: number; }' }
+  ]
+});
+
+// All lanes share the same dictionary
+console.log(pack.dict.dict.length);    // shared dictionary size
+console.log(pack.lanes.length);        // 3 blocks
+
+// Decompress each lane
+for (const block of pack.lanes) {
+  const text = ccDecompress(pack.dict, block);
+  console.log(`Lane ${block.lane_id}: ${text.length} chars`);
+}
+```
+
+### Synchronous API (Node.js only)
+
+```javascript
+import { ccCompressSync, ccCompressLanesSync } from '@asx/scxq2-cc';
+
+// Sync single-lane
+const pack = ccCompressSync(source);
+
+// Sync multi-lane
+const multiPack = ccCompressLanesSync({ lanes: [...] });
+```
+
+---
+
+## API
+
+### Core Functions
+
+| Function | Description |
+|----------|-------------|
+| `ccCompress(input, opts?)` | Async compression with proof |
+| `ccCompressSync(input, opts?)` | Sync compression (Node.js only) |
+| `ccCompressLanes(input, opts?)` | Async multi-lane compression |
+| `ccCompressLanesSync(input, opts?)` | Sync multi-lane (Node.js only) |
+| `ccDecompress(dict, block)` | Decompress block using dictionary |
+| `verifyPack(dict, block)` | Verify pack structure |
+
+### Compression Options
+
+```typescript
+interface CCCompressOptions {
+  maxDict?: number;        // Max dictionary entries (1-65535, default: 1024)
+  minLen?: number;         // Min token length (2-128, default: 3)
+  noStrings?: boolean;     // Skip string literal tokens
+  noWS?: boolean;          // Skip whitespace tokens
+  noPunct?: boolean;       // Skip punctuation tokens
+  enableFieldOps?: boolean; // Enable JSON key extraction
+  enableEdgeOps?: boolean; // Enable edge witnesses
+  created_utc?: string;    // ISO timestamp
+  source_file?: string;    // Source identifier
+}
+```
+
+### Result Objects
+
+```typescript
+interface CCResult {
+  dict: SCXQ2Dict;    // Dictionary with token array
+  block: SCXQ2Block;  // Encoded block with b64 payload
+  proof: CCProof;     // Reversibility proof
+  audit: CCAudit;     // Compression metrics
+}
+```
+
+### Utility Functions
+
+```javascript
+import {
+  canon,           // Canonical JSON serialization
+  sha256HexUtf8,   // Async SHA-256 hash
+  bytesToBase64,   // Encode bytes to base64
+  base64ToBytes    // Decode base64 to bytes
+} from '@asx/scxq2-cc';
+```
+
+---
+
+## Encoding Format
+
+SCXQ2 uses a simple bytecode format:
+
+| Byte | Meaning |
+|------|---------|
+| `0x00-0x7F` | ASCII literal (1 byte) |
+| `0x80 [hi] [lo]` | Dictionary reference (3 bytes) |
+| `0x81 [hi] [lo]` | UTF-16 code unit (3 bytes) |
+
+### Dictionary Properties
+
+- Maximum 65,535 entries (16-bit index)
+- Ordered longest-first for greedy matching
+- UTF-16 code-unit indexed
+- Immutable once sealed
+
+---
+
+## Specification
+
+SCXQ2 implements the frozen **CC-v1 (Compression Calculus v1)** specification.
+
+### Invariants (Non-Negotiable)
+
+1. **Deterministic Canonical Form** - Canonical JSON, stable UTF-8
+2. **Reversibility** - Every block losslessly decodable
+3. **Single-Hash Identity** - One SHA-256 identifies entire pack
+4. **No Runtime Authority** - No execution, IO, or environment semantics
+5. **Lane Isolation** - Blocks independent except shared dictionary
+6. **Proof-Bound** - Proof inseparable from content
+7. **Compression-Only** - Never introduces meaning, only representation
+
+### Pack Structure
+
+```
+SCXQ2 PACK
+├── Dictionary (shared)
+├── Blocks[] (lanes)
+│   ├── Encoded byte stream (b64)
+│   ├── Optional lane_id
+│   └── Optional edges (EDGE witnesses)
+├── Proof
+└── pack_sha256_canon (identity)
+```
+
+### CC Operators
+
+| Operator | Purpose |
+|----------|---------|
+| `CC.NORM` | Normalize newlines, optional whitespace policy |
+| `CC.DICT` | Extract dictionary from token stream |
+| `CC.FIELD` | Structural JSON key augmentation |
+| `CC.LANE` | Multi-lane product construction |
+| `CC.EDGE` | Adjacency witnesses for analysis |
+
+---
+
+## Security
+
+SCXQ2 is **compression representation**, not encryption.
+
+### Threat Mitigations
+
+- **Memory Safety** - No out-of-bounds access, bounded allocations
+- **Time Safety** - O(n) decode time, predictable worst-case
+- **Deterministic Failure** - Stable error codes, fail-closed
+- **Integrity** - SHA-256 identity prevents silent mutation
+
+### Decompression Bomb Protection
+
+Set `maxOutputUnits` to limit decoded output size:
+
+```javascript
+// Verifier with output limit
+const result = await ccCompress(input, {
+  maxDict: 1024
+  // Implementation can add maxOutputUnits for decode limits
+});
+```
+
+### Security Non-Goals
+
+SCXQ2 does NOT provide:
+- Confidentiality
+- Authentication
+- Authorization
+- Tamper-proofing against hash recomputation
+
+---
+
+## Error Codes
+
+| Code | Phase | Description |
+|------|-------|-------------|
+| `scxq2.error.pack_*` | pack | Pack structure errors |
+| `scxq2.error.dict_*` | dict | Dictionary errors |
+| `scxq2.error.block_*` | block | Block errors |
+| `scxq2.error.decode_*` | decode | Decoding errors |
+| `scxq2.error.proof_*` | proof | Proof verification errors |
+
+---
+
+## Project Structure
+
+```
+scxq2-cc/
+├── package.json
+├── README.md
+├── BRAND.md              # Brand guidelines
+├── SCXQ2_language.md     # Full language specification
+├── SCXQ2_CC_ENGINE_V1.md # Engine specification
+├── NPM.md                # NPM module documentation
+├── scxq2-logo.svg        # Logo
+├── src/
+│   ├── index.js          # Main entry point
+│   ├── engine.js         # Core CC engine
+│   ├── canon.js          # Canonical JSON
+│   ├── sha.js            # SHA-256 utilities
+│   └── base64.js         # Base64 utilities
+└── dist/
+    ├── index.js          # Built entry point
+    ├── index.d.ts        # TypeScript definitions
+    └── ...
+```
+
+---
+
+## Constants
+
+```javascript
+import { CC_ENGINE, SCXQ2_ENCODING, CC_OPS } from '@asx/scxq2-cc';
+
+console.log(CC_ENGINE['@id']);
+// "asx://cc/engine/scxq2.v1"
+
+console.log(SCXQ2_ENCODING);
+// { mode: "SCXQ2-DICT16-B64", encoding: "SCXQ2-1" }
+
+console.log(CC_OPS);
+// { NORM: "cc.norm.v1", DICT: "cc.dict.v1", ... }
+```
+
+---
+
+## Final Law
+
+> **If two SCXQ2 packs have the same `pack_sha256_canon`, they are the same language object.**
+
+Everything else is projection.
+
+---
+
+## License
+
+MIT
+
+---
+
+## Links
+
+- [SCXQ2 Language Specification](./SCXQ2_language.md)
+- [CC Engine Specification](./SCXQ2_CC_ENGINE_V1.md)
+- [NPM Module Documentation](./NPM.md)
+- [Brand Guidelines](./BRAND.md)

package/dist/base64.js

@@ -0,0 +1,83 @@
+/**
+ * SCXQ2 Base64 Utilities
+ *
+ * Universal base64 encoding/decoding that works in Node.js, browsers, and workers.
+ * Handles the "base64:" prefix format used in some SCXQ2 contexts.
+ *
+ * @module @asx/scxq2-cc/base64
+ * @version 1.0.0
+ */
+
+/**
+ * Encodes bytes to base64 string.
+ *
+ * @param {Uint8Array|number[]} bytes - Bytes to encode
+ * @returns {string} Base64-encoded string
+ */
+export function bytesToBase64(bytes) {
+  // Ensure we have a proper array-like
+  const arr = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+
+  // Node.js Buffer
+  if (typeof Buffer !== "undefined" && Buffer.from) {
+    return Buffer.from(arr).toString("base64");
+  }
+
+  // Browser/Worker: use btoa
+  if (typeof btoa === "function") {
+    let binary = "";
+    for (let i = 0; i < arr.length; i++) {
+      binary += String.fromCharCode(arr[i]);
+    }
+    return btoa(binary);
+  }
+
+  throw new Error("SCXQ2: no base64 encoder available");
+}
+
+/**
+ * Decodes base64 string to bytes.
+ * Automatically strips "base64:" prefix if present.
+ *
+ * @param {string} b64 - Base64-encoded string
+ * @returns {Uint8Array} Decoded bytes
+ */
+export function base64ToBytes(b64) {
+  // Strip optional "base64:" prefix
+  const clean = String(b64).startsWith("base64:")
+    ? String(b64).slice(7)
+    : String(b64);
+
+  // Node.js Buffer
+  if (typeof Buffer !== "undefined" && Buffer.from) {
+    return new Uint8Array(Buffer.from(clean, "base64"));
+  }
+
+  // Browser/Worker: use atob
+  if (typeof atob === "function") {
+    const binary = atob(clean);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+  }
+
+  throw new Error("SCXQ2: no base64 decoder available");
+}
+
+/**
+ * Validates that a string is valid base64.
+ *
+ * @param {string} b64 - String to validate
+ * @returns {boolean} True if valid base64
+ */
+export function isValidBase64(b64) {
+  const clean = String(b64).startsWith("base64:")
+    ? String(b64).slice(7)
+    : String(b64);
+
+  // Standard base64 regex
+  const regex = /^[A-Za-z0-9+/]*={0,2}$/;
+  return regex.test(clean) && clean.length % 4 === 0;
+}

package/dist/canon.js

@@ -0,0 +1,60 @@
+/**
+ * SCXQ2 Canonical JSON Utilities
+ *
+ * Provides deterministic JSON serialization with sorted keys for
+ * content-addressable hashing and reproducible pack identities.
+ *
+ * @module @asx/scxq2-cc/canon
+ * @version 1.0.0
+ */
+
+/**
+ * Recursively sorts object keys for deterministic JSON output.
+ * Arrays are preserved in order, objects have keys sorted alphabetically.
+ *
+ * @param {*} value - Any JSON-serializable value
+ * @returns {*} Value with all nested object keys sorted
+ */
+export function sortKeysDeep(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortKeysDeep);
+  }
+
+  if (value !== null && typeof value === "object") {
+    const sorted = {};
+    const keys = Object.keys(value).sort();
+    for (const key of keys) {
+      sorted[key] = sortKeysDeep(value[key]);
+    }
+    return sorted;
+  }
+
+  return value;
+}
+
+/**
+ * Produces canonical JSON string with sorted keys.
+ * This is the required serialization for all SCXQ2 hash computations.
+ *
+ * @param {*} obj - Object to serialize
+ * @returns {string} Canonical JSON string
+ */
+export function canon(obj) {
+  return JSON.stringify(sortKeysDeep(obj));
+}
+
+/**
+ * Creates a shallow copy of an object with specified fields removed.
+ * Used for computing hashes that exclude the hash field itself.
+ *
+ * @param {Object} obj - Source object
+ * @param {string[]} fields - Fields to exclude
+ * @returns {Object} New object without excluded fields
+ */
+export function strip(obj, fields) {
+  const copy = { ...obj };
+  for (const field of fields) {
+    delete copy[field];
+  }
+  return copy;
+}

package/dist/cli.mjs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+/**
+ * SCXQ2 CLI
+ *
+ * Commands:
+ *   verify <pack.json>             - Verify pack integrity
+ *   decode <pack.json> [--lane ID] - Decode block to stdout
+ *   inspect <pack.json>            - Print pack summary
+ *
+ * @version 1.0.0
+ */
+
+import fs from "fs";
+import path from "path";
+import { scxq2PackVerify, scxq2DecodeUtf16, SCXQ2_DEFAULT_POLICY } from "./verify.js";
+
+/* =============================================================================
+   Helpers
+============================================================================= */
+
+function usage() {
+  console.log(`
+scxq2 <command> [args]
+
+Commands:
+  verify <pack.json>               Verify pack (default policy)
+  decode <pack.json> [--lane ID]   Decode first block or matching lane_id
+  inspect <pack.json>              Print pack summary (hashes, lanes, sizes)
+
+Flags:
+  --no-roundtrip       Skip roundtrip verification
+  --no-proof           Skip proof verification
+  --maxOutputUnits N   Set max output code units
+
+Examples:
+  scxq2 verify mypack.json
+  scxq2 decode mypack.json --lane main
+  scxq2 inspect mypack.json
+`);
+  process.exit(2);
+}
+
+function readJson(fp) {
+  try {
+    const s = fs.readFileSync(fp, "utf8");
+    return JSON.parse(s);
+  } catch (e) {
+    console.error(`Error reading ${fp}: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("--")) {
+      out._.push(a);
+    } else {
+      const k = a.slice(2);
+      const v = (i + 1 < argv.length && !argv[i + 1].startsWith("--"))
+        ? argv[++i]
+        : true;
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+function applyPolicyFlags(args) {
+  const p = { ...SCXQ2_DEFAULT_POLICY };
+  if (args["no-roundtrip"]) p.requireRoundtrip = false;
+  if (args["no-proof"]) p.requireProof = false;
+  if (args.maxOutputUnits) p.maxOutputUnits = Number(args.maxOutputUnits);
+  return p;
+}
+
+function b64ToBytes(b64) {
+  return Buffer.from(b64, "base64");
+}
+
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}
+
+/* =============================================================================
+   Commands
+============================================================================= */
+
+function cmdVerify(pack, policy) {
+  const res = scxq2PackVerify(pack, policy);
+  if (!res.ok) {
+    console.error(JSON.stringify(res, null, 2));
+    process.exit(1);
+  }
+  console.log(JSON.stringify(res, null, 2));
+  process.exit(0);
+}
+
+function cmdInspect(pack) {
+  const blocks = pack.blocks || [];
+  const lanes = blocks.map((b, i) => ({
+    index: i,
+    lane_id: b.lane_id ?? null,
+    b64_bytes: b.b64 ? Buffer.from(b.b64, "base64").length : null,
+    original_bytes: b.original_bytes_utf8 ?? null,
+    block_sha: b.block_sha256_canon?.slice(0, 16) + "..." ?? null
+  }));
+
+  const dictSize = pack.dict?.dict?.length ?? 0;
+  const totalB64 = blocks.reduce((acc, b) => acc + (b.b64 ? Buffer.from(b.b64, "base64").length : 0), 0);
+
+  const summary = {
+    pack_sha256_canon: pack.pack_sha256_canon ?? null,
+    dict_sha256_canon: pack.dict?.dict_sha256_canon ?? null,
+    dict_entries: dictSize,
+    blocks: lanes.length,
+    total_encoded_bytes: totalB64,
+    total_encoded_display: formatBytes(totalB64),
+    lanes
+  };
+
+  console.log(JSON.stringify(summary, null, 2));
+  process.exit(0);
+}
+
+function cmdDecode(pack, policy, laneId) {
+  const blocks = pack.blocks || [];
+
+  if (!blocks.length) {
+    console.error("Error: no blocks in pack");
+    process.exit(1);
+  }
+
+  let block = blocks[0];
+
+  if (laneId != null && laneId !== true) {
+    const hit = blocks.find(x => String(x.lane_id) === String(laneId));
+    if (!hit) {
+      console.error(`Error: lane not found: ${laneId}`);
+      console.error(`Available lanes: ${blocks.map(b => b.lane_id ?? "(unnamed)").join(", ")}`);
+      process.exit(1);
+    }
+    block = hit;
+  }
+
+  const bytes = b64ToBytes(block.b64);
+  const dec = scxq2DecodeUtf16(pack.dict.dict, bytes, { maxOutputUnits: policy.maxOutputUnits });
+
+  if (!dec.ok) {
+    console.error(JSON.stringify(dec, null, 2));
+    process.exit(1);
+  }
+
+  process.stdout.write(dec.value);
+  process.exit(0);
+}
+
+/* =============================================================================
+   Main
+============================================================================= */
+
+const args = parseArgs(process.argv.slice(2));
+const cmd = args._[0];
+const file = args._[1];
+
+if (!cmd) usage();
+if (cmd === "help" || cmd === "--help" || cmd === "-h") usage();
+if (!file) {
+  console.error("Error: missing pack file argument");
+  usage();
+}
+
+const pack = readJson(file);
+const policy = applyPolicyFlags(args);
+
+switch (cmd) {
+  case "verify":
+    cmdVerify(pack, policy);
+    break;
+  case "inspect":
+    cmdInspect(pack);
+    break;
+  case "decode":
+    cmdDecode(pack, policy, args.lane);
+    break;
+  default:
+    console.error(`Unknown command: ${cmd}`);
+    usage();
+}