scxq2-cc 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,426 @@
+/**
+ * @asx/scxq2-cc - SCXQ2 Compression Calculus Engine
+ * TypeScript Type Definitions
+ *
+ * @version 1.0.0
+ */
+
+/* =============================================================================
+   Engine Constants
+============================================================================= */
+
+/**
+ * CC Engine identity object (frozen)
+ */
+export declare const CC_ENGINE: Readonly<{
+  "@id": "asx://cc/engine/scxq2.v1";
+  "@type": "cc.engine";
+  "@version": "1.0.0";
+  "@status": "frozen";
+  "$schema": "xjson://schema/core/v1";
+}>;
+
+/**
+ * SCXQ2 encoding mode constants (frozen)
+ */
+export declare const SCXQ2_ENCODING: Readonly<{
+  mode: "SCXQ2-DICT16-B64";
+  encoding: "SCXQ2-1";
+}>;
+
+/**
+ * CC operator identifiers (frozen)
+ */
+export declare const CC_OPS: Readonly<{
+  NORM: "cc.norm.v1";
+  DICT: "cc.dict.v1";
+  FIELD: "cc.field.v1";
+  LANE: "cc.lane.v1";
+  EDGE: "cc.edge.v1";
+}>;
+
+/* =============================================================================
+   Compression Options
+============================================================================= */
+
+/**
+ * Options for compression operations
+ */
+export interface CCCompressOptions {
+  /** Maximum dictionary entries (1-65535, default: 1024) */
+  maxDict?: number;
+  /** Minimum token length (2-128, default: 3) */
+  minLen?: number;
+  /** Skip string literal tokens */
+  noStrings?: boolean;
+  /** Skip whitespace tokens */
+  noWS?: boolean;
+  /** Skip punctuation tokens */
+  noPunct?: boolean;
+  /** Enable JSON key extraction (CC.FIELD operator) */
+  enableFieldOps?: boolean;
+  /** Enable edge witnesses (CC.EDGE operator) */
+  enableEdgeOps?: boolean;
+  /** ISO timestamp (auto-generated if omitted) */
+  created_utc?: string;
+  /** Source file identifier */
+  source_file?: string | null;
+}
+
+/**
+ * Flags indicating which token types were processed
+ */
+export interface SCXQ2Flags {
+  noStrings: boolean;
+  noWS: boolean;
+  noPunct: boolean;
+}
+
+/* =============================================================================
+   SCXQ2 Dictionary
+============================================================================= */
+
+/**
+ * SCXQ2 Dictionary object
+ */
+export interface SCXQ2Dict {
+  "@type": "scxq2.dict";
+  "@version": string;
+  mode: "SCXQ2-DICT16-B64";
+  encoding: "SCXQ2-1";
+  created_utc: string;
+  source_sha256_utf8: string;
+  max_dict: number;
+  min_len: number;
+  flags: SCXQ2Flags;
+  dict: string[];
+  dict_sha256_canon: string;
+}
+
+/* =============================================================================
+   SCXQ2 Block
+============================================================================= */
+
+/**
+ * Edge witness tuple [from_index, to_index]
+ */
+export type EdgeWitness = [number, number];
+
+/**
+ * SCXQ2 Block object
+ */
+export interface SCXQ2Block {
+  "@type": "scxq2.block";
+  "@version": string;
+  mode: "SCXQ2-DICT16-B64";
+  encoding: "SCXQ2-1";
+  created_utc: string;
+  source_sha256_utf8: string;
+  dict_sha256_canon: string;
+  original_bytes_utf8: number;
+  b64: string;
+  block_sha256_canon: string;
+  /** Lane identifier (multi-lane packs only) */
+  lane_id?: string;
+  /** Edge witnesses (when enableEdgeOps is true) */
+  edges?: EdgeWitness[];
+}
+
+/* =============================================================================
+   CC Proof
+============================================================================= */
+
+/**
+ * Proof step in the compression trace
+ */
+export interface CCProofStep {
+  op: string;
+  sha?: string;
+  dict_entries?: number;
+  block_sha?: string;
+  roundtrip_sha?: string;
+}
+
+/**
+ * Compression Calculus proof object
+ */
+export interface CCProof {
+  "@type": "cc.proof";
+  "@version": string;
+  engine: string;
+  created_utc: string;
+  source_sha256_utf8: string;
+  dict_sha256_canon: string;
+  block_sha256_canon: string;
+  roundtrip_sha256_utf8: string;
+  ok: boolean;
+  steps: CCProofStep[];
+}
+
+/**
+ * Multi-lane proof object
+ */
+export interface CCLanesProof {
+  "@type": "cc.lanes.proof";
+  "@version": string;
+  engine: string;
+  created_utc: string;
+  dict_sha256_canon: string;
+  lanes: Array<{
+    lane_id: string;
+    source_sha256_utf8: string;
+    block_sha256_canon: string;
+  }>;
+  ok: boolean;
+  steps?: CCProofStep[];
+}
+
+/* =============================================================================
+   CC Audit
+============================================================================= */
+
+/**
+ * Top token info for audit
+ */
+export interface TokenInfo {
+  tok: string;
+  count: number;
+  totalSavings: number;
+}
+
+/**
+ * Compression audit object
+ */
+export interface CCAudit {
+  "@type": "cc.audit";
+  "@version": string;
+  engine: string;
+  created_utc: string;
+  sizes: {
+    original_bytes_utf8: number;
+    encoded_b64_bytes_utf8: number;
+    ratio: number | null;
+  };
+  dict: {
+    entries: number;
+    max_dict: number;
+    min_len: number;
+    flags: SCXQ2Flags;
+  };
+  top_tokens: TokenInfo[];
+}
+
+/**
+ * Multi-lane audit object
+ */
+export interface CCLanesAudit {
+  "@type": "cc.lanes.audit";
+  "@version": string;
+  engine: string;
+  created_utc: string;
+  dict_entries: number;
+  lane_count: number;
+}
+
+/* =============================================================================
+   Compression Results
+============================================================================= */
+
+/**
+ * Single-lane compression result
+ */
+export interface CCResult {
+  dict: SCXQ2Dict;
+  block: SCXQ2Block;
+  proof: CCProof;
+  audit: CCAudit;
+}
+
+/**
+ * Multi-lane compression result
+ */
+export interface CCLanesResult {
+  dict: SCXQ2Dict;
+  lanes: SCXQ2Block[];
+  proof: CCLanesProof;
+  audit: CCLanesAudit;
+}
+
+/**
+ * Lane input for multi-lane compression
+ */
+export interface LaneInput {
+  lane_id: string;
+  text: string | Uint8Array;
+}
+
+/**
+ * Multi-lane compression input
+ */
+export interface LanesInput {
+  lanes: LaneInput[];
+}
+
+/* =============================================================================
+   Main API Functions
+============================================================================= */
+
+/**
+ * Compresses input text into an SCXQ2 language pack.
+ * Uses async hashing for universal compatibility (Node.js, Browser, Worker).
+ *
+ * @param input - Source text or bytes to compress
+ * @param opts - Compression options
+ * @returns Promise resolving to compression result
+ */
+export declare function ccCompress(
+  input: string | Uint8Array,
+  opts?: CCCompressOptions
+): Promise<CCResult>;
+
+/**
+ * Synchronous compression (Node.js only).
+ *
+ * @param input - Source text or bytes to compress
+ * @param opts - Compression options
+ * @returns Compression result
+ * @throws If not running in Node.js
+ */
+export declare function ccCompressSync(
+  input: string | Uint8Array,
+  opts?: CCCompressOptions
+): CCResult;
+
+/**
+ * Compresses multiple lanes with a shared dictionary.
+ *
+ * @param laneInput - Object containing array of lanes
+ * @param opts - Compression options
+ * @returns Promise resolving to multi-lane compression result
+ */
+export declare function ccCompressLanes(
+  laneInput: LanesInput,
+  opts?: CCCompressOptions
+): Promise<CCLanesResult>;
+
+/**
+ * Synchronous multi-lane compression (Node.js only).
+ *
+ * @param laneInput - Object containing array of lanes
+ * @param opts - Compression options
+ * @returns Multi-lane compression result
+ * @throws If not running in Node.js
+ */
+export declare function ccCompressLanesSync(
+  laneInput: LanesInput,
+  opts?: CCCompressOptions
+): CCLanesResult;
+
+/**
+ * Decompresses an SCXQ2 block using its dictionary.
+ *
+ * @param dictJson - SCXQ2 dictionary object
+ * @param blockJson - SCXQ2 block object
+ * @returns Decompressed text
+ * @throws On invalid pack or decoding error
+ */
+export declare function ccDecompress(
+  dictJson: SCXQ2Dict,
+  blockJson: SCXQ2Block
+): string;
+
+/**
+ * Verifies structural validity of an SCXQ2 pack.
+ *
+ * @param dictJson - Dictionary object
+ * @param blockJson - Block object
+ * @returns Success indicator
+ * @throws On verification failure
+ */
+export declare function verifyPack(
+  dictJson: SCXQ2Dict,
+  blockJson: SCXQ2Block
+): { ok: true };
+
+/* =============================================================================
+   Utility Functions
+============================================================================= */
+
+/**
+ * Produces canonical JSON string with sorted keys.
+ *
+ * @param obj - Object to serialize
+ * @returns Canonical JSON string
+ */
+export declare function canon(obj: unknown): string;
+
+/**
+ * Recursively sorts object keys.
+ *
+ * @param value - Any value
+ * @returns Value with sorted object keys
+ */
+export declare function sortKeysDeep<T>(value: T): T;
+
+/**
+ * Creates shallow copy excluding specified fields.
+ *
+ * @param obj - Source object
+ * @param fields - Fields to exclude
+ * @returns New object without excluded fields
+ */
+export declare function strip<T extends object>(
+  obj: T,
+  fields: string[]
+): Partial<T>;
+
+/**
+ * Computes SHA-256 hash of UTF-8 text (async).
+ *
+ * @param text - Text to hash
+ * @returns Promise resolving to hex-encoded hash
+ */
+export declare function sha256HexUtf8(text: string): Promise<string>;
+
+/**
+ * Computes SHA-256 hash of UTF-8 text (sync, Node.js only).
+ *
+ * @param text - Text to hash
+ * @param nodeCrypto - Optional pre-imported crypto module
+ * @returns Hex-encoded hash
+ */
+export declare function sha256HexUtf8Sync(
+  text: string,
+  nodeCrypto?: unknown
+): string;
+
+/**
+ * Gets Node.js crypto module if available.
+ *
+ * @returns Crypto module or null
+ */
+export declare function getNodeCrypto(): unknown | null;
+
+/**
+ * Encodes bytes to base64 string.
+ *
+ * @param bytes - Bytes to encode
+ * @returns Base64-encoded string
+ */
+export declare function bytesToBase64(bytes: Uint8Array | number[]): string;
+
+/**
+ * Decodes base64 string to bytes.
+ *
+ * @param b64 - Base64-encoded string
+ * @returns Decoded bytes
+ */
+export declare function base64ToBytes(b64: string): Uint8Array;
+
+/**
+ * Validates that a string is valid base64.
+ *
+ * @param b64 - String to validate
+ * @returns True if valid base64
+ */
+export declare function isValidBase64(b64: string): boolean;

package/dist/index.js

@@ -0,0 +1,48 @@
+/**
+ * @asx/scxq2-cc - SCXQ2 Compression Calculus Engine
+ *
+ * A deterministic, proof-generating compression engine that produces
+ * content-addressable language packs following the frozen SCXQ2 specification.
+ *
+ * @module @asx/scxq2-cc
+ * @version 1.0.0
+ *
+ * @example
+ * // Basic compression
+ * import { ccCompress, ccDecompress } from '@asx/scxq2-cc';
+ *
+ * const pack = await ccCompress('function hello() { console.log("Hello"); }');
+ * console.log(pack.proof.ok); // true
+ *
+ * const roundtrip = ccDecompress(pack.dict, pack.block);
+ * // roundtrip === original input
+ *
+ * @example
+ * // Multi-lane compression
+ * import { ccCompressLanes } from '@asx/scxq2-cc';
+ *
+ * const pack = await ccCompressLanes({
+ *   lanes: [
+ *     { lane_id: 'main', text: 'function main() {}' },
+ *     { lane_id: 'util', text: 'function util() {}' }
+ *   ]
+ * });
+ */
+
+// Re-export engine API
+export {
+  CC_ENGINE,
+  SCXQ2_ENCODING,
+  CC_OPS,
+  ccCompress,
+  ccCompressSync,
+  ccCompressLanes,
+  ccCompressLanesSync,
+  ccDecompress,
+  verifyPack
+} from "./engine.js";
+
+// Re-export utilities for advanced use
+export { canon, sortKeysDeep, strip } from "./canon.js";
+export { sha256HexUtf8, sha256HexUtf8Sync, getNodeCrypto } from "./sha.js";
+export { bytesToBase64, base64ToBytes, isValidBase64 } from "./base64.js";

package/dist/sha.js

@@ -0,0 +1,71 @@
+/**
+ * SCXQ2 SHA-256 Utilities
+ *
+ * Universal SHA-256 hashing that works in Node.js, browsers, and workers.
+ * Provides both async (WebCrypto) and sync (Node crypto) implementations.
+ *
+ * @module @asx/scxq2-cc/sha
+ * @version 1.0.0
+ */
+
+/**
+ * Computes SHA-256 hash of UTF-8 text, returning hex string.
+ * Uses WebCrypto when available, falls back to Node crypto.
+ *
+ * @param {string} text - UTF-8 text to hash
+ * @returns {Promise<string>} Hex-encoded SHA-256 hash
+ */
+export async function sha256HexUtf8(text) {
+  // WebCrypto (browser / worker)
+  if (globalThis.crypto?.subtle) {
+    const data = new TextEncoder().encode(text);
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", data);
+    return [...new Uint8Array(digest)]
+      .map(b => b.toString(16).padStart(2, "0"))
+      .join("");
+  }
+
+  // Node.js
+  const { createHash } = await import("crypto");
+  return createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+/**
+ * Synchronous SHA-256 hash (Node.js only).
+ * Throws if crypto module is not available.
+ *
+ * @param {string} text - UTF-8 text to hash
+ * @param {Object} [nodeCrypto] - Pre-imported crypto module (optional)
+ * @returns {string} Hex-encoded SHA-256 hash
+ */
+export function sha256HexUtf8Sync(text, nodeCrypto = null) {
+  if (nodeCrypto) {
+    return nodeCrypto.createHash("sha256").update(text, "utf8").digest("hex");
+  }
+
+  // Dynamic require for Node.js environments
+  if (typeof process !== "undefined" && process.versions?.node) {
+    // Use dynamic import trick for sync context
+    const crypto = require("crypto");
+    return crypto.createHash("sha256").update(text, "utf8").digest("hex");
+  }
+
+  throw new Error("SCXQ2: sync hashing requires Node.js crypto module");
+}
+
+/**
+ * Gets Node.js crypto module if available.
+ * Returns null in browser/worker environments.
+ *
+ * @returns {Object|null} Node crypto module or null
+ */
+export function getNodeCrypto() {
+  if (typeof process !== "undefined" && process.versions?.node) {
+    try {
+      return require("crypto");
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}