@terminals-tech/sdk 1.0.0 → 2.0.0-rc.1

package/README.md

@@ -1,6 +1,6 @@
 # @terminals-tech/sdk
 
-Terminals OS SDK — publish-safe facades and primitives for building observable, coherence-aware software.
+Terminals OS SDK — observable, coherence-aware primitives for building intelligent software. Available as TypeScript (`@terminals-tech/sdk`) and Rust (`terminals-core`).
 
 ## Install
 
@@ -8,6 +8,13 @@ Terminals OS SDK — publish-safe facades and primitives for building observable
 npm install @terminals-tech/sdk
 ```
 
+## Install (Rust)
+
+```toml
+[dependencies]
+terminals-core = "0.1"
+```
+
 ## Quickstart
 
 ```typescript
@@ -32,21 +39,42 @@ const metrics = Brain.calculateCoherence({
 console.log("Coherence:", metrics.overall);
 ```
 
+## Quickstart (Rust)
+
+```rust
+use terminals_core::phase::{kuramoto_step, order_parameter, phase_locking_value, Omega};
+use terminals_core::substrate::{Sematon, witness::ConvergenceWitness, graph::PadicAddr};
+
+// 1. Phase dynamics — same math as Brain.kuramotoStep in TypeScript
+let phases = vec![0.0, 1.2, 2.6, 4.1];
+let next = kuramoto_step(&phases, &Omega::Uniform(0.0), 0.8, None, 0.1, true);
+let op = order_parameter(&next);
+println!("Kuramoto R = {:.3}, psi = {:.3}", op.r, op.psi);
+
+// 2. Sematon — same concept as L0.createSematon in TypeScript
+let witness = ConvergenceWitness { r: 0.95, entropy: 0.3, converged: true, step: 10 };
+let sem = Sematon::new(vec![1.0f32, 2.0, 3.0], witness, PadicAddr::default(), "demo");
+println!("Constructive: {}", sem.constructive);
+```
+
 ## Architecture
 
 The published package exposes a curated surface oriented around stable facades and runtime-safe primitives:
 
-| Surface    | Namespace / Export | Coverage                                                                  |
-| ---------- | ------------------ | ------------------------------------------------------------------------- |
-| Foundation | `L0`               | Core engine math, Sematons, and Deterministic Constructor traces          |
-| Terminal   | `Terminal`         | interaction lifecycle, surface identity, platform types                   |
-| Core       | `Core`             | result types, validation, DAG, registry, retry/event primitives           |
-| Mesh       | `Mesh`             | signals, action bus, delegation helpers                                   |
-| Brain      | `Brain`            | coherence metrics and phase primitives (`Brain.calculateCoherence`, etc.) |
-| Protocol   | `Protocol`         | delegation helpers and the AXON protocol bridge                           |
-| Skill      | `Skill`            | skill manifest types, registry access, signal codes                       |
-| Manifold   | `Manifold`         | annihilation pipeline helpers and ordinal execution surfaces              |
-| Observer   | `Observer`         | observer kernel primitives and witness-oriented runtime inspection        |
+| Surface               | Namespace / Export | Coverage                                                                  | Rust crate                                                                   |
+| --------------------- | ------------------ | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Foundation            | `L0`               | Core engine math, Sematons, and Deterministic Constructor traces          | `terminals_core::substrate` (Sematon, fold/unfold)                           |
+| Brain                 | `Brain`            | coherence metrics and phase primitives (`Brain.calculateCoherence`, etc.) | `terminals_core::phase` (kuramoto, PLV, order parameter)                     |
+| Core                  | `Core`             | result types, validation, DAG, registry, retry/event primitives           | `terminals_core::primitives` (Result, DAG, Registry, Validated)              |
+| Wire (Rust-only)      | —                  | —                                                                         | `terminals_core::wire` (AXON binary protocol)                                |
+| Audio (Rust-only)     | —                  | —                                                                         | `terminals_core::audio` (spectral entropy, band analysis)                    |
+| Substrate (Rust-only) | —                  | —                                                                         | `terminals_core::substrate` (ComputeAtom, ProjectionLayout, SubstrateEngine) |
+| Terminal              | `Terminal`         | interaction lifecycle, surface identity, platform types                   | —                                                                            |
+| Mesh                  | `Mesh`             | signals, action bus, delegation helpers                                   | —                                                                            |
+| Protocol              | `Protocol`         | delegation helpers and the AXON protocol bridge                           | —                                                                            |
+| Skill                 | `Skill`            | skill manifest types, registry access, signal codes                       | —                                                                            |
+| Manifold              | `Manifold`         | annihilation pipeline helpers and ordinal execution surfaces              | —                                                                            |
+| Observer              | `Observer`         | observer kernel primitives and witness-oriented runtime inspection        | —                                                                            |
 
 ## ELI5: The L0 Foundation (Sematons & Constructors)
 
@@ -77,6 +105,23 @@ await bus.publishSDK({
 console.log({ Core, Mesh, Protocol });
 ```
 
+## TypeScript / Rust Parity
+
+The same core math runs in both runtimes. Phase dynamics, sematonic types, DAG, registry, and validation exist in both `@terminals-tech/sdk` (TypeScript) and `terminals-core` (Rust/WASM). Higher-level orchestration (Mesh signals, Protocol delegation, Observer kernel) is TypeScript-only. Low-level substrate and wire protocol are Rust-only.
+
+| Domain               | TypeScript                 | Rust                                     | Status    |
+| -------------------- | -------------------------- | ---------------------------------------- | --------- |
+| Phase dynamics       | `Brain.*`                  | `terminals_core::phase`                  | Both      |
+| Sematon / L0         | `L0.createSematon`         | `terminals_core::substrate::Sematon`     | Both      |
+| DAG                  | `Core.createDAG`           | `terminals_core::primitives::dag`        | Both      |
+| Validation (proof)   | `Core.validated`           | `terminals_core::primitives::validation` | Both      |
+| Coherence scoring    | `Brain.calculateCoherence` | —                                        | TS only   |
+| Mesh signals         | `Mesh.*`                   | —                                        | TS only   |
+| Protocol/AXON bridge | `Protocol.*`               | —                                        | TS only   |
+| AXON wire format     | —                          | `terminals_core::wire`                   | Rust only |
+| Substrate engine     | —                          | `terminals_core::substrate`              | Rust only |
+| Audio analysis       | —                          | `terminals_core::audio`                  | Rust only |
+
 ## Local verification
 
 From the monorepo root:
@@ -99,6 +144,7 @@ npm run -w @terminals-tech/sdk pack:dry-run
 2. Run `npm run sdk:publish:check`
 3. Inspect the dry-run tarball summary
 4. Publish when ready with `npm publish --workspace @terminals-tech/sdk`
+5. For `terminals-core`: `cargo publish --manifest-path crates/terminals-core/Cargo.toml`
 
 ## License
 

package/dist/{WebContainerManager-4LIOGRVM.js → WebContainerManager-NUGGUIWB.js}

@@ -2,15 +2,15 @@ import {
   ProcessPriority,
   WebContainerManager,
   WebContainerManager_default
-} from "./chunk-LLGZTP3G.js";
+} from "./chunk-P4D4RNAV.js";
 import "./chunk-DKFJIILR.js";
 import "./chunk-KHR7ZYCX.js";
+import "./chunk-WGBCRNMB.js";
 import "./chunk-QWZRZKLZ.js";
 import "./chunk-OSSRZOGC.js";
 import "./chunk-TSQ3BGLA.js";
 import "./chunk-2WTYE4SW.js";
 import "./chunk-QJFKEQHF.js";
-import "./chunk-WGBCRNMB.js";
 import "./chunk-3LFMIVJM.js";
 import "./chunk-AFDUOYHD.js";
 import "./chunk-NTMBOESX.js";

package/dist/catalog-XA5VYWXG.js

@@ -0,0 +1,16 @@
+import {
+  getCatalog,
+  listNodes,
+  registerManifestProvider,
+  registerNode,
+  resolveNode
+} from "./chunk-WT6L6DK3.js";
+import "./chunk-XPJ63Y6T.js";
+import "./chunk-2ESYSVXG.js";
+export {
+  getCatalog,
+  listNodes,
+  registerManifestProvider,
+  registerNode,
+  resolveNode
+};

package/dist/{chunk-PWAHFID5.js → chunk-D4MOOUDY.js}

@@ -6,10 +6,10 @@ import {
   createInteractionWithEvents,
   sanitizeTraceSegment,
   transitionStatusWithEvent
-} from "./chunk-BCOQMFKT.js";
+} from "./chunk-TO7ETE5K.js";
 import {
   secureValidate
-} from "./chunk-FOXUEYWK.js";
+} from "./chunk-GOQHOLBG.js";
 import {
   DEFAULT_EMBEDDING_DIM
 } from "./chunk-ZVO47SQV.js";
@@ -175,7 +175,7 @@ async function emitInteractionEvent(interactionId, type, payload, metadata) {
   const userId = enrichedMeta.userId ?? enrichedMeta.user_id;
   if (userId && typeof window !== "undefined") {
     try {
-      const { appendSupabaseMeshEvent } = await import("./supabaseService-6AYP2VY3.js");
+      const { appendSupabaseMeshEvent } = await import("./supabaseService-O4ZFFLZP.js");
       await appendSupabaseMeshEvent({
         user_id: userId,
         interaction_id: interactionId,

package/dist/{chunk-FOXUEYWK.js → chunk-GOQHOLBG.js}

@@ -1,10 +1,10 @@
+import {
+  require_ajv
+} from "./chunk-QJFKEQHF.js";
 import {
   untrusted,
   validate
 } from "./chunk-EXI3LJVJ.js";
-import {
-  require_ajv
-} from "./chunk-QJFKEQHF.js";
 import {
   __toESM
 } from "./chunk-2ESYSVXG.js";
@@ -37,6 +37,7 @@ function secureValidate(data, schema) {
 }
 
 export {
+  getValidator,
   validateWithSchema,
   secureValidate
 };

package/dist/{chunk-STMI72WH.js → chunk-ICFYWOI5.js}

@@ -1,19 +1,19 @@
+import {
+  onMeshFeedback,
+  orchestratorToMesh
+} from "./chunk-UB5OINTA.js";
 import {
   getGlobalStore
 } from "./chunk-VZA2NUH3.js";
 import {
   resolveSecretValue
 } from "./chunk-QWXPVB2L.js";
-import {
-  onMeshFeedback,
-  orchestratorToMesh
-} from "./chunk-Q2VI6ICE.js";
-import {
-  registerManifestProvider
-} from "./chunk-OCLSAUCD.js";
 import {
   safeDbOperation
 } from "./chunk-WGBCRNMB.js";
+import {
+  getValidator
+} from "./chunk-GOQHOLBG.js";
 import {
   getDB,
   isDatabaseReady,
@@ -30,29 +30,6 @@ function buildScheduleTriggerContext(config, scheduleId) {
   };
 }
 
-// ../../lib/terminals-tech/machines/core/stacksStore.ts
-var globalStore = globalThis;
-var memStacks = globalStore.__memStacks || /* @__PURE__ */ new Map();
-globalStore.__memStacks = memStacks;
-var pendingDeletes = globalStore.__pendingStackDeletes || /* @__PURE__ */ new Set();
-globalStore.__pendingStackDeletes = pendingDeletes;
-registerManifestProvider("stacksStore", loadStack);
-async function loadStack(id) {
-  const { getDB: getDB2, safeDbOperation: safeDbOperation2 } = await import("./pgliteService-IUGNNOVU.js");
-  const dbResult = await safeDbOperation2(async () => {
-    const db = await getDB2();
-    await db.query(`ALTER TABLE stacks ADD COLUMN IF NOT EXISTS deleted_at TIMESTAMP`);
-    const r = await db.query(
-      `SELECT manifest FROM stacks WHERE id = $1 AND deleted_at IS NULL`,
-      [id]
-    );
-    if (!r.rows[0]) return null;
-    return r.rows[0].manifest;
-  }, null);
-  if (dbResult) return dbResult;
-  return memStacks.get(id)?.manifest || null;
-}
-
 // ../../lib/terminals-tech/machines/core/manifests.ts
 function isNodeManifest(manifest) {
   return "kind" in manifest && "entrypoints" in manifest;
@@ -567,7 +544,7 @@ var OrchestratorV0 = class {
       return true;
     }
     try {
-      const { neuroState } = await import("./neuro-state-XHRGIRVO.js");
+      const { neuroState } = await import("./neuro-state-KINIFV2D.js");
       const currentState = await new Promise((resolve) => {
         let resolved = false;
         let subscription = null;
@@ -690,8 +667,8 @@ var OrchestratorV0 = class {
       };
       let shapeHash;
       try {
-        const { computeShapeHash: computeShapeHash2 } = await import("./topology-CIWWNVAN.js");
-        shapeHash = await computeShapeHash2(stack);
+        const { computeShapeHash } = await import("./topology-CIWWNVAN.js");
+        shapeHash = await computeShapeHash(stack);
       } catch (err) {
         console.error("[OrchestratorV0] Failed to compute shape hash:", err);
       }
@@ -705,6 +682,27 @@ var OrchestratorV0 = class {
           ...baseInput,
           ...opts.configOverrides?.[node.id] || {}
         };
+        if (isNodeManifest(manifest) && manifest.inputsSchema && opts.configOverrides?.[node.id]) {
+          try {
+            const validator = getValidator(manifest.inputsSchema);
+            const publicInput = {};
+            for (const [k, v] of Object.entries(input)) {
+              if (!k.startsWith("__")) publicInput[k] = v;
+            }
+            const isValid = validator(publicInput);
+            if (!isValid) {
+              console.warn(
+                `[OrchestratorV0] configOverrides for node "${node.id}" produced input that does not match inputsSchema:`,
+                validator.errors
+              );
+            }
+          } catch (schemaErr) {
+            console.warn(
+              `[OrchestratorV0] Failed to validate configOverrides for node "${node.id}":`,
+              schemaErr
+            );
+          }
+        }
         if (opts.triggerContext) {
           input.__triggerContext = opts.triggerContext;
         }
@@ -922,10 +920,10 @@ var OrchestratorV0 = class {
     void stackId;
     void node;
     if (typeof window === "undefined") {
-      const { ensureServerRunnersRegistered } = await import("./server-VW6DYDLH.js");
+      const { ensureServerRunnersRegistered } = await import("./server-JXM4Y2T6.js");
       await ensureServerRunnersRegistered();
     }
-    const { runners } = await import("./registry-5WTDYQVQ.js");
+    const { runners } = await import("./registry-UARRB6CF.js");
     const tierRunner = runners.getRunner(tier);
     if (tierRunner) {
       return await tierRunner(manifest, input, {
@@ -971,7 +969,7 @@ var OrchestratorV0 = class {
       return { ...input };
     }
     if (tier === "webcontainer") {
-      const { runInWebContainer } = await import("./webcontainer-XWCE56F3.js");
+      const { runInWebContainer } = await import("./webcontainer-PMWNRO4I.js");
       return await runInWebContainer(manifest, input, {
         stackId,
         nodeId: node.id,
@@ -979,7 +977,7 @@ var OrchestratorV0 = class {
       });
     }
     if (tier === "wasm-hvm") {
-      const { runInHVM } = await import("./hvm-CBEP3M4F.js");
+      const { runInHVM } = await import("./hvm-A7DGZ3Q5.js");
       return await runInHVM(manifest, input, {
         stackId,
         nodeId: node.id,
@@ -1000,6 +998,5 @@ var OrchestratorV0 = class {
 
 export {
   buildScheduleTriggerContext,
-  loadStack,
   OrchestratorV0
 };

package/dist/chunk-PKINKOW2.js

@@ -0,0 +1,335 @@
+// ../../lib/terminals-tech/core/L0/information.ts
+function entropy(probabilities) {
+  if (probabilities.length === 0) return 0;
+  const sum = probabilities.reduce((a, b) => a + b, 0);
+  const normalized = sum === 0 ? probabilities : probabilities.map((p) => p / sum);
+  return normalized.reduce((h, p) => {
+    if (p <= 0) return h;
+    return h - p * Math.log2(p);
+  }, 0);
+}
+function jointEntropy(jointProbabilities) {
+  const flat = jointProbabilities.flat();
+  return entropy(flat);
+}
+function conditionalEntropy(jointProbabilities) {
+  const hXY = jointEntropy(jointProbabilities);
+  const pX = jointProbabilities.map((row) => row.reduce((a, b) => a + b, 0));
+  const hX = entropy(pX);
+  return hXY - hX;
+}
+function mutualInformation(pX, pY, pXY) {
+  const hX = entropy(pX);
+  const hY = entropy(pY);
+  const hXY = jointEntropy(pXY);
+  return Math.max(0, hX + hY - hXY);
+}
+function measurePreservation(source, transformed, roundTrip) {
+  if (source.length === 0) {
+    return {
+      retention: 1,
+      sourceEntropy: 0,
+      targetEntropy: 0,
+      mutualInfo: 0,
+      lossless: true
+    };
+  }
+  const sourceFreq = countFrequencies(source.map(String));
+  const transformedFreq = countFrequencies(transformed.map(String));
+  const n = source.length;
+  const sourceProbabilities = Object.values(sourceFreq).map((c) => c / n);
+  const transformedProbabilities = Object.values(transformedFreq).map((c) => c / n);
+  const sourceEntropy = entropy(sourceProbabilities);
+  const targetEntropy = entropy(transformedProbabilities);
+  let retention = 1;
+  let lossless = true;
+  if (roundTrip) {
+    const matches = source.filter((s, i) => String(s) === String(roundTrip[i])).length;
+    retention = matches / source.length;
+    lossless = matches === source.length;
+  } else {
+    const sourceCardinality = Object.keys(sourceFreq).length;
+    const targetCardinality = Object.keys(transformedFreq).length;
+    retention = Math.min(1, targetCardinality / sourceCardinality);
+    lossless = targetCardinality >= sourceCardinality;
+  }
+  const minEntropy = Math.min(sourceEntropy, targetEntropy);
+  const mutualInfo = retention * minEntropy;
+  return {
+    retention,
+    sourceEntropy,
+    targetEntropy,
+    mutualInfo,
+    lossless
+  };
+}
+function calculateSemanticDensity(tokens, baselineTokensPerBit = 2) {
+  if (tokens.length === 0) {
+    return {
+      tokenCount: 0,
+      informationBits: 0,
+      density: 0,
+      compressionRatio: 1
+    };
+  }
+  const freq = countFrequencies(tokens);
+  const probabilities = Object.values(freq).map((c) => c / tokens.length);
+  const informationBits = entropy(probabilities) * tokens.length;
+  const density = tokens.length > 0 ? informationBits / tokens.length : 0;
+  const baselineBits = tokens.length / baselineTokensPerBit;
+  const compressionRatio = baselineBits > 0 ? informationBits / baselineBits : 1;
+  return {
+    tokenCount: tokens.length,
+    informationBits,
+    density,
+    compressionRatio
+  };
+}
+function estimateComplexity(data) {
+  if (data.length === 0) return 0;
+  const seen = /* @__PURE__ */ new Set();
+  let uniqueSubstrings = 0;
+  const windowSize = 8;
+  for (let i = 0; i <= data.length - windowSize; i++) {
+    const substr = data.slice(i, i + windowSize);
+    if (!seen.has(substr)) {
+      seen.add(substr);
+      uniqueSubstrings++;
+    }
+  }
+  const totalPatterns = Math.max(1, data.length - windowSize + 1);
+  return uniqueSubstrings / totalPatterns;
+}
+function klDivergence(p, q) {
+  if (p.length !== q.length) {
+    throw new Error("Distributions must have same length");
+  }
+  let divergence = 0;
+  for (let i = 0; i < p.length; i++) {
+    if (p[i] > 0 && q[i] > 0) {
+      divergence += p[i] * Math.log2(p[i] / q[i]);
+    } else if (p[i] > 0 && q[i] === 0) {
+      return Infinity;
+    }
+  }
+  return divergence;
+}
+function jsDivergence(p, q) {
+  if (p.length !== q.length) {
+    throw new Error("Distributions must have same length");
+  }
+  const m = p.map((pi, i) => 0.5 * (pi + q[i]));
+  let jsd = 0;
+  for (let i = 0; i < p.length; i++) {
+    if (p[i] > 0 && m[i] > 0) {
+      jsd += 0.5 * p[i] * Math.log2(p[i] / m[i]);
+    }
+    if (q[i] > 0 && m[i] > 0) {
+      jsd += 0.5 * q[i] * Math.log2(q[i] / m[i]);
+    }
+  }
+  return jsd;
+}
+function countFrequencies(values) {
+  const freq = {};
+  for (const v of values) {
+    const key = String(v);
+    freq[key] = (freq[key] || 0) + 1;
+  }
+  return freq;
+}
+function normalize(values) {
+  const sum = values.reduce((a, b) => a + b, 0);
+  if (sum === 0) return values.map(() => 1 / values.length);
+  return values.map((v) => v / sum);
+}
+function cosineSimilarity(a, b) {
+  if (a.length !== b.length || a.length === 0) return 0;
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+  return denominator === 0 ? 0 : dot / denominator;
+}
+
+// ../../lib/terminals-tech/core/L0/sematon.ts
+var sematonCounter = 0;
+function fnv1a(input) {
+  let hash = 2166136261;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+function computePayloadEntropy(payload) {
+  const json = JSON.stringify(payload);
+  if (!json || json.length === 0) return 0;
+  const freq = {};
+  for (let i = 0; i < json.length; i++) {
+    const ch = json[i];
+    freq[ch] = (freq[ch] || 0) + 1;
+  }
+  const probabilities = Object.values(freq).map((c) => c / json.length);
+  return entropy(probabilities);
+}
+function computeDensity(payload, entropyBits) {
+  const json = JSON.stringify(payload);
+  const tokenCount = json ? json.split(/\s+|[,{}[\]":]+/).filter(Boolean).length : 0;
+  return tokenCount > 0 ? entropyBits / tokenCount : 0;
+}
+function generatePadicAddress(kind, counter) {
+  const kindIndex = [
+    "signal",
+    "context",
+    "fractal",
+    "witness",
+    "combinator",
+    "interaction",
+    "custom"
+  ].indexOf(kind);
+  return `${kindIndex}.0.${counter}`;
+}
+function createSematon(config) {
+  const counter = ++sematonCounter;
+  const id = `sem_${config.kind}_${counter}_${Date.now().toString(36)}`;
+  const payloadEntropy = computePayloadEntropy(config.payload);
+  const density = computeDensity(config.payload, payloadEntropy);
+  const padicAddress = config.padicAddress ?? generatePadicAddress(config.kind, counter);
+  const hashInput = [
+    config.kind,
+    JSON.stringify(config.payload),
+    config.witness.R.toFixed(6),
+    config.witness.converged.toString(),
+    padicAddress
+  ].join("|");
+  const shapeHash = fnv1a(hashInput);
+  const constructive = config.witness.converged && Number.isFinite(payloadEntropy) && payloadEntropy > 0 && JSON.stringify(config.payload) !== "null" && JSON.stringify(config.payload) !== "undefined";
+  const impedance = density > 0 && config.witness.R > 0 ? payloadEntropy / (density * config.witness.R) : Infinity;
+  return {
+    id,
+    kind: config.kind,
+    payload: config.payload,
+    witness: { ...config.witness },
+    padicAddress,
+    entropy: payloadEntropy,
+    density,
+    impedance,
+    shapeHash,
+    constructive,
+    createdAt: Date.now(),
+    source: config.source ?? "unknown"
+  };
+}
+function sematonEntropy(sematon) {
+  return sematon.entropy;
+}
+function sematonDensity(sematon) {
+  return sematon.density;
+}
+function isRealizable(sematon) {
+  return sematon.constructive;
+}
+function sematonDistance(a, b) {
+  const vecA = payloadToVector(a.payload);
+  const vecB = payloadToVector(b.payload);
+  const cosSim = cosineSimilarity(vecA, vecB);
+  const rProximity = 1 - Math.abs(a.witness.R - b.witness.R);
+  const similarity = 0.7 * Math.max(0, cosSim) + 0.3 * rProximity;
+  return 1 - similarity;
+}
+function payloadToVector(payload) {
+  const json = JSON.stringify(payload);
+  const vec = new Array(128).fill(0);
+  if (!json) return vec;
+  for (let i = 0; i < json.length; i++) {
+    const code = json.charCodeAt(i);
+    if (code < 128) {
+      vec[code]++;
+    }
+  }
+  const sum = vec.reduce((s, v) => s + v, 0);
+  if (sum > 0) {
+    for (let i = 0; i < vec.length; i++) {
+      vec[i] /= sum;
+    }
+  }
+  return vec;
+}
+function foldSematon(sematon) {
+  return {
+    id: sematon.id,
+    kind: sematon.kind,
+    payload: JSON.stringify(sematon.payload),
+    witness: { ...sematon.witness },
+    padicAddress: sematon.padicAddress,
+    entropy: sematon.entropy,
+    density: sematon.density,
+    impedance: sematon.impedance,
+    shapeHash: sematon.shapeHash,
+    constructive: sematon.constructive,
+    createdAt: sematon.createdAt,
+    source: sematon.source
+  };
+}
+function unfoldSematon(folded) {
+  return {
+    id: folded.id,
+    kind: folded.kind,
+    payload: JSON.parse(folded.payload),
+    witness: { ...folded.witness },
+    padicAddress: folded.padicAddress,
+    entropy: folded.entropy,
+    density: folded.density,
+    impedance: folded.impedance,
+    shapeHash: folded.shapeHash,
+    constructive: folded.constructive,
+    createdAt: folded.createdAt,
+    source: folded.source
+  };
+}
+
+export {
+  entropy,
+  jointEntropy,
+  conditionalEntropy,
+  mutualInformation,
+  measurePreservation,
+  calculateSemanticDensity,
+  estimateComplexity,
+  klDivergence,
+  jsDivergence,
+  normalize,
+  cosineSimilarity,
+  createSematon,
+  sematonEntropy,
+  sematonDensity,
+  isRealizable,
+  sematonDistance,
+  foldSematon,
+  unfoldSematon
+};
+/**
+ * L0 Sematon — The Smallest Meaning-Bearing Unit
+ *
+ * The sematon is the atomic unit of operational meaning in Terminals OS.
+ * It carries a typed payload, convergence witness, p-adic address,
+ * information-theoretic metrics, and a constructor flag that guarantees
+ * the Deutsch-Marletto invariant: after transforming an input, the
+ * sematon retains the ability to transform again.
+ *
+ * The sematon unifies Signal<T>, ContextNode, FractalSnapshot,
+ * ConvergenceWitness, and CombinatorEvent into a single formal type
+ * at the L0 foundation layer.
+ *
+ * Core Engine Primitive.
+ *
+ * @license BUSL-1.1
+ * @copyright © 2026 Intuition Labs LLC. All rights reserved. Patent Pending.
+ * @module core/L0/sematon
+ */