mcard-studio 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ben Koo and MCard Studio contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,120 @@
-# Temporary Holding Version
+# MCard Studio
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## The HMI and Presentation Membrane for a Personal Knowledge Container
+
+MCard Studio is a spatial web workbench for browsing, editing, and interacting with content-addressed knowledge artifacts. It is the presentation/HMI layer for a local Personal Knowledge Container (PKC), built on published `clm-kernel` APIs. The Studio UI is not itself the authoritative PKC storage kernel, and this repository does not yet implement a complete authenticated global mesh.
+
+The application separates pure models and projections from UI, client effects, lifecycle wiring, and Node server/storage adapters. Architectural and mathematical terms such as “polynomial interface,” “VCard sandwich,” or “Software Lagrangian” are design models unless a linked interface, guard, or test establishes a concrete behavior.
+
+## Current Stack
+
+| Area | Current dependency/configuration |
+| --- | --- |
+| SSR/web | Astro 7.3.5, `@astrojs/node` |
+| UI | React 19, Dockview React 8.3.1 |
+| Build | Vite 8.3.1, TypeScript 5.9.3 |
+| Kernel | `clm-kernel` 0.0.3 |
+| Server storage | Node 22 `node:sqlite` through `SqliteNodeEngine` and `NodeSqliteBackend` |
+| Browser persistence | IndexedDB for VFS workspace persistence |
+| Tests | Vitest and Playwright |
+| Optional integrations | Tauri v2, MinIO/S3 client, IPFS HTTP API, local/remote LLM providers |
+
+## Application Boundaries
+
+```text
+Human / Agent
+     │ actions and rendered state
+     ▼
+MCard Studio HMI ──► core models and projections
+     │                       ▲
+     ├── edge adapters ──────┤
+     ├── membrane wiring ────┤
+     └── Node server ────────┴── clm-kernel and local persistence
+```
+
+| Source area | Responsibility |
+| --- | --- |
+| `src/core/` | Pure models, intents, events, reducers, and projections. |
+| `src/ui/` | Presentation components driven by state and intent callbacks. |
+| `src/edge/` | Browser/client effect adapters and BFF/host clients. |
+| `src/membrane/` | SPEC-302/Cordis lifecycle wiring. |
+| `src/server/` | Node-only API, runtime, repository, ingestion, and storage adapters. |
+| `src/fiber/` | PTR transition adapter, savepoint helper, and trace model. |
+| `src/packages/mcard-studio/` | Zero-DOM published presentation library. |
+
+The static guards check selected import, side-effect, viewlet, path, dependency, and LOC constraints. See `npm run check:gates` for the current gate battery; a passing guard is not a proof of every theoretical invariant.
+
+## What the Application Provides
+
+- **Spatial workbench** built around Dockview, panels, viewlets, and artifact navigation.
+- **Terminal modes** for browser WASM, JavaScript console, server PTY, and CLM CLI dispatch where configured.
+- **Chat and model integrations** through the Koishi/context layer and configured local/remote providers.
+- **Card VFS** using `clm-kernel`, server-side artifact collections, and browser workspace persistence.
+- **Visual authoring/rendering** for supported Markdown, Mermaid, TikZ, and other registered content types.
+- **Tauri and PWA configuration** with host-specific behavior and optional sync services.
+
+Feature coverage varies by host, configuration, and installed service. Consult the relevant spec and source path before relying on a capability.
+
+## Persistence Boundaries
+
+| Boundary | Current role |
+| --- | --- |
+| `servermemory.db` | Authoritative server-side card collection and handle history, using Node `node:sqlite`. |
+| Browser `clm_workbench_db` | IndexedDB database used by `src/services/vfs/vfsPersistence.ts` for browser workspace persistence. `browsermemory.db` is a logical collection label, not a SQLite/WASM file in this adapter. |
+| `.clm/content_memory.db` | Configured path for the Studio VFS; backend selection depends on host/runtime. |
+| `execution_log.db` | Configured collection for supported execution-result records. It does not imply every command is logged. |
+| MinIO and IPFS | Optional services called by explicit integration paths; neither is an automatic replica for every card. |
+
+The canonical core SQL schema has `card`, `handle_registry`, and `handle_history`. Its documentation link is a symlink to `MCard_TDD/schema/mcard_schema.sql` in the parent workspace. See [`docs/schema/README.md`](docs/schema/README.md) and [persistence boundaries](docs/architecture/06_Four_Store_Persistence_and_Authority.md).
+
+## Mesh and Identity Status
+
+The repository includes LAN discovery with mDNS service `_pkc._tcp.local.`, WebSocket `get_peers`/`webrtc_signal` signalling, a WebRTC peer-runtime utility, and an IPFS HTTP API client. These pieces do not by themselves provide global DHT discovery, consensus, automatic IPFS replication, or authenticated peer identity. The WebSocket `identify` handler binds a client-supplied DID string without proving key possession. Noise XX and WireGuard remain target options, not current capabilities.
+
+## Get Started
+
+Requirements: Node.js 22 or newer and npm.
+
+```bash
+npm install
+npm run dev
+```
+
+The development script starts the Astro server and WebSocket service. Defaults are `http://localhost:5320` and port `5321`; check startup output and local configuration if overridden.
+
+### As an npm package
+
+The repository also builds a runnable `mcard-studio` package (currently `0.0.1`, MIT) with a CLI. In any consumer project:
+
+```bash
+npm install mcard-studio        # plus react/react-dom ^19 peers
+npx mcard-studio init --apply   # merge dev/start scripts into your package.json
+npm run dev                     # or: npx mcard-studio dev
+```
+
+`init` previews host-script changes without writing; `--apply` is explicit and conflict-safe. Data stays under the consumer project — nothing writes inside `node_modules`. Build and verify the artifact yourself with `npm run build:npm-app` and `npm run test:consumer-package` (26 checks against the real `.tgz` outside this repo). See [the npm install guide](docs/guides/INSTALL_MCARD_STUDIO_NPM.md) and [release checklist](docs/guides/NPM_RELEASE_CHECKLIST.md). The package is **not yet published** — registry publication is owner-gated.
+
+## Verify Changes
+
+```bash
+npm run check:gates
+npm test
+npx playwright test
+```
+
+`npm run check` runs the configured static gates, style checks, hermetic check, unit tests, build, and smoke test. Test counts and historical pass reports are snapshots; use current command output for release decisions. See [`docs/guides/RUN_TESTS.md`](docs/guides/RUN_TESTS.md).
+
+For desktop development/build, use `npm run tauri:dev` and `npm run tauri:build`. The repository Compose configuration is a development/deployment template, not a production-readiness guarantee. Review [Production Deployment](docs/guides/PRODUCTION_DEPLOYMENT.md) and set deployment-specific secrets before exposing any services.
+
+## Documentation
+
+- [Documentation home](docs/README.md) and [complete index](docs/INDEX.md)
+- [Architecture](docs/architecture/00_Architecture_Overview.md) and [schema/runtime inventory](docs/schema/README.md)
+- [Engineering conventions](docs/engineering/CODING_CONVENTIONS.md)
+- [Functionality specifications](docs/functionalities/README.md)
+- [Guides and operations](docs/guides/QUICK_START.md)
+- [Sprint roadmap](docs/sprints/README.md), including [graduated Program MI documentation](docs/sprints/04-Networking-Mesh/README.md)
+
+## Design Vocabulary
+
+The polynomial normal form $p(y)=\sum_{s\in p(1)}y^{p[s]}$ describes positions and their available directions as a design model. MCard/PCard/VCard roles are artifacts, processes, and witnesses; they are not a literal SQL type isomorphism. Baldwin's Splitting, Substituting, Augmenting, Excluding, Inverting, and Porting are useful design-review labels, not runtime operations automatically executed by the application.

package/assets/add_integers.yaml

@@ -0,0 +1,45 @@
+version: "1.0"
+description: "Browser-local arithmetic: add two integers and return the sum"
+clm:
+  abstract_spec:
+    context: "Simple integer addition executed browser-local via Web Worker"
+    goal: "Add two integers a and b, return their sum as a sealed VCard witness"
+    success_criteria:
+      - "PCard executes entirely in Web Worker"
+      - "No filesystem access"
+      - "No network access"
+      - "VCard witness sealed in-browser via Web Crypto API"
+      - "Result matches expected sum for each test case"
+  concrete_impl:
+    runtime: javascript-browser
+    operation: add_integers
+    process:
+      type: javascript
+      script: 'const input = JSON.parse(intent); const a = Number(input.a) || 0; const b = Number(input.b) || 0; const sum = a + b; return { newMarking: { output: [String(sum)] }, hash: String(sum) };'
+  balanced_exp:
+    expectation: "Adding two integers produces the correct sum in the VCard witness output"
+    test_cases:
+      - id: "positive-add"
+        given: "Two positive integers"
+        when:
+          context: { a: 10, b: 20 }
+        then:
+          result_contains: "30"
+      - id: "negative-plus-positive"
+        given: "A negative and a positive integer"
+        when:
+          context: { a: -5, b: 12 }
+        then:
+          result_contains: "7"
+      - id: "zero-baseline"
+        given: "Adding zero to a number"
+        when:
+          context: { a: 0, b: 42 }
+        then:
+          result_contains: "42"
+      - id: "both-negative"
+        given: "Two negative integers"
+        when:
+          context: { a: -8, b: -3 }
+        then:
+          result_contains: "-11"

package/assets/approval_gate.yaml

@@ -0,0 +1,43 @@
+version: "1.0"
+description: "Sprint 138.4: Human-in-the-loop approval gate hook PCard"
+clm:
+  abstract_spec:
+    context: "Human-in-the-loop approval gate — suspends PCard execution pending EOA sponsor signature"
+    goal: "When a PCard requires EOA sponsorship, suspend execution and surface the approval request to the L4 signing surface. Resume only when sponsor_did is committed."
+    success_criteria:
+      - "PCard execution suspends when on_sponsor_required fires"
+      - "sponsor_did must be committed to run:<run_id>:sponsor handle"
+      - "PCard resumes only after valid sponsor_did signature"
+      - "Invalid or missing sponsor_did causes VCard pre-gate failure"
+  concrete_impl:
+    runtime: system
+    operation: approval_gate
+    gate_type: hook
+    event: on_sponsor_required
+    process:
+      type: shell
+      script: |
+        # Check if sponsor_did is committed for this run
+        RUN_ID="${CLM_RUN_ID:-default}"
+        SPONSOR_HANDLE="run:${RUN_ID}:sponsor"
+        
+        if [ -z "${ACTIVE_AGENT_DID:-}" ] && [ -z "${CLM_SPONSOR_DID:-}" ]; then
+          echo "[VCARD_PRE_ERR] No sponsor_did committed for run ${RUN_ID}"
+          exit 1
+        fi
+        
+        # Verify the sponsor_did is a valid did:key format
+        SPONSOR_DID="${CLM_SPONSOR_DID:-${ACTIVE_AGENT_DID}}"
+        if ! echo "${SPONSOR_DID}" | grep -q '^did:key:z'; then
+          echo "[VCARD_PRE_ERR] Invalid sponsor_did format: ${SPONSOR_DID}"
+          exit 1
+        fi
+        
+        echo "[APPROVAL_GATE] Sponsor authorized: ${SPONSOR_DID}"
+        exit 0
+  balanced_exp:
+    expectation: "PCard suspends until EOA signs, then resumes with valid sponsor_did. Invalid sponsor_did causes VCard pre-gate failure."
+  _meta:
+    clm_name: approval_gate
+    computed_at: "2026-07-09T17:00:00Z"
+    depends_on: ["chat_gateway"]

package/assets/chat_gateway.yaml

@@ -0,0 +1,34 @@
+version: "1.0"
+description: "Sprint 138.3: Channel PCard — WebSocket Gateway as Channel-typed PCard (runtime: channel)"
+clm:
+  abstract_spec:
+    context: "Channel PCard — WebSocket Gateway (Sprint 138.3)"
+    goal: "Normalize WebSocket input into canonical CLM Flux dispatch cycle. Forward remote PCard firings to clmEval, stream marking transitions back, and return sealed VCard witnesses."
+    success_criteria:
+      - "WebSocket server runs successfully as Channel PCard"
+      - "Inbound WebSocket messages are normalized to canonical Card messages"
+      - "Remote PCard firings dispatch to clmEval via CLM_DISPATCH_SOCK"
+      - "Marking transitions are streamed back as MARKING_UPDATE messages"
+      - "Sealed VCard witnesses are returned as VCARD_SEALED messages"
+      - "Channel PCard is bidirectional: normalizes inbound and denormalizes outbound"
+    channel_pcard:
+      platform: chat_gateway
+      bidirectional: true
+      authentication: "sponsor_did required in FIRE_PCARD action"
+      linked_vcard: true
+  concrete_impl:
+    runtime: channel
+    operation: chat_gateway
+    process:
+      type: javascript
+      script: "const ws = require('ws');\nconst path = require('path');\nconst net = require('net');\nconst fs = require('fs');\n\n// Catch uncaught exceptions to prevent silent IPC socket destruction\nprocess.on('uncaughtException', (err) => {\n  console.error(`[GATEWAY] UNCAUGHT EXCEPTION: ${err.message}`);\n  console.error(err.stack);\n});\n\nconst clmRoot = process.env.CLM_ROOT || process.cwd();\nconst payload = process.env.CLM_PAYLOAD || \"\";\n\nlet host = \"127.0.0.1\";\nlet port = 8080;\nlet timeout = 30000;\n\nif (payload) {\n  const hostMatch = payload.match(/host=([^\\s]+)/);\n  if (hostMatch) host = hostMatch[1];\n  const portMatch = payload.match(/port=(\\d+)/);\n  if (portMatch) port = parseInt(portMatch[1], 10);\n  const timeoutMatch = payload.match(/timeout=(\\d+)/);\n  if (timeoutMatch) timeout = parseInt(timeoutMatch[1], 10);\n}\n\nconst wss = new ws.Server({ host, port }, () => {\n  console.log(`[GATEWAY] WebSocket Gateway server listening on ws://${host}:${port}`);\n});\n\n// Set up connection timeout clean sweep\nlet activeConnections = new Set();\nconst timeoutTimer = setTimeout(() => {\n  console.log(`[GATEWAY] Reached timeout of ${timeout}ms. Shutting down.`);\n  wss.close(() => {\n    process.exit(0);\n  });\n}, timeout);\ntimeoutTimer.unref();\n\n// Safe send helper — prevents unhandled errors from killing IPC connections\nfunction safeSend(socket, data) {\n  try {\n    if (socket.readyState === ws.OPEN) {\n      socket.send(data);\n      return true;\n    }\n  } catch (e) {\n    console.error(`[GATEWAY] safeSend error: ${e.message}`);\n  }\n  return false;\n}\n\nwss.on('connection', (socket) => {\n  console.log(\"[GATEWAY] Client connected successfully.\");\n  activeConnections.add(socket);\n\n  socket.on('message', (messageBuffer) => {\n    let messageStr = messageBuffer.toString().trim();\n    console.log(`[GATEWAY] Received: ${messageStr}`);\n\n    // Support graceful shutdown\n    if (messageStr === \"shutdown\" || messageStr.includes('\"type\":\"shutdown\"')) {\n      console.log(\"[GATEWAY] Graceful shutdown requested.\");\n      socket.send(JSON.stringify({ type: \"shutdown\", status: \"ok\" }));\n      activeConnections.forEach(conn => conn.close());\n      wss.close(() => {\n        clearTimeout(timeoutTimer);\n        process.exit(0);\n      });\n      return;\n    }\n\n    let clmFile = \"\";\n    let clmPayload = \"\";\n\n    let jsonMsg = null;\n    try {\n      jsonMsg = JSON.parse(messageStr);\n    } catch (e) {}\n\n    if (jsonMsg) {\n      if (jsonMsg.type === \"execute\") {\n        clmFile = jsonMsg.clm_file;\n        clmPayload = jsonMsg.payload || \"\";\n      } else if (jsonMsg.type === \"chat\") {\n        messageStr = jsonMsg.message || \"\";\n      } else if (jsonMsg.type === \"ping\") {\n        socket.send(JSON.stringify({ type: \"pong\" }));\n        return;\n      }\n    } else if (messageStr === \"ping\") {\n      socket.send(JSON.stringify({ type: \"pong\" }));\n      return;\n    }\n\n    if (!clmFile) {\n      const lower = messageStr.toLowerCase();\n      if (lower.includes(\"hello world\") || lower.includes(\"hello_world\")) {\n        clmFile = \"computable_knowledge/Abstract/layer5_system/playbooks/hello_world.yaml\";\n      } else if (lower.includes(\"gcd\")) {\n        clmFile = \"tests/test_fixtures/fixture_python_gcd.yaml\";\n        const nums = messageStr.match(/\\d+/g);\n        if (nums && nums.length >= 2) {\n          clmPayload = `${nums[0]} ${nums[1]}`;\n        } else {\n          clmPayload = \"24 36\";\n        }\n      } else if (lower.includes(\"lcm\")) {\n        clmFile = \"tests/test_fixtures/fixture_python_lcm.yaml\";\n        const nums = messageStr.match(/\\d+/g);\n        if (nums && nums.length >= 2) {\n          clmPayload = `${nums[0]} ${nums[1]}`;\n        } else {\n          clmPayload = \"12 18\";\n        }\n      } else if (lower.includes(\"fibonacci\") || lower.includes(\"fib\")) {\n        clmFile = \"tests/test_fixtures/fixture_python_fib.yaml\";\n        const nums = messageStr.match(/\\d+/);\n        if (nums) {\n          clmPayload = nums[0];\n        } else {\n          clmPayload = \"10\";\n        }\n      } else {\n        console.log(\"[GATEWAY] Entering Ollama fallback logic...\");\n        // Natural language fallback to local Ollama LLM\n        const http = require('http');\n        const selectedModel = (jsonMsg && jsonMsg.model) || \"gemma4:latest\";\n        const ollamaUrl = process.env.OLLAMA_URL || \"http://127.0.0.1:11434\";\n        \n        console.log(`[GATEWAY] Using model: ${selectedModel}, Ollama URL: ${ollamaUrl}`);\n        \n        // Parse OLLAMA_URL\n        let ollamaHost = \"127.0.0.1\";\n        let ollamaPort = 11434;\n        try {\n          const urlParsed = new URL(ollamaUrl);\n          ollamaHost = urlParsed.hostname;\n          ollamaPort = urlParsed.port ? parseInt(urlParsed.port, 10) : 80;\n        } catch (urlErr) {\n          console.log(`[GATEWAY] URL parse error: ${urlErr.message}`);\n          const hostMatch = ollamaUrl.match(/:\\/\\/([^:/]+)/);\n          if (hostMatch) ollamaHost = hostMatch[1];\n          const portMatch = ollamaUrl.match(/:(\\d+)\\/?$/);\n          if (portMatch) ollamaPort = parseInt(portMatch[1], 10);\n        }\n\n        console.log(`[GATEWAY] Parsed host: ${ollamaHost}, port: ${ollamaPort}`);\n\n        // Construct system instruction with game context\n        let systemContent = \"You are a friendly and helpful AI math assistant inside the GASING (Gampang, Asyik, Menyenangkan) interactive learning game. Keep your answers brief, encouraging, and clear for kids.\";\n        if (jsonMsg) {\n          if (jsonMsg.gameId) {\n            systemContent += `\\nCurrent Game context:\\n- Game ID: ${jsonMsg.gameId}\\n- Round: ${jsonMsg.round || 1}`;\n            if (jsonMsg.question) systemContent += `\\n- Current Problem: ${jsonMsg.question}`;\n            if (jsonMsg.gasingExplanation) systemContent += `\\n- GASING Methodology/Explanation: ${jsonMsg.gasingExplanation}`;\n          }\n        }\n\n        const postData = JSON.stringify({\n          model: selectedModel,\n          messages: [\n            { role: \"system\", content: systemContent },\n            { role: \"user\", content: messageStr }\n          ],\n          stream: true\n        });\n\n        const options = {\n          hostname: ollamaHost,\n          port: ollamaPort,\n          path: '/api/chat',\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n            'Content-Length': Buffer.byteLength(postData)\n          }\n        };\n\n        console.log(\"[GATEWAY] Sending status back to socket...\");\n        socket.send(JSON.stringify({\n          type: \"status\",\n          status: \"started\",\n          clm: `Ollama (${selectedModel})`,\n          payload: messageStr\n        }));\n\n        console.log(\"[GATEWAY] Triggering HTTP request to Ollama...\");\n        const req = http.request(options, (res) => {\n          console.log(`[GATEWAY] Ollama response status: ${res.statusCode}`);\n          if (res.statusCode !== 200) {\n            let errBody = '';\n            res.on('data', (d) => errBody += d.toString());\n            res.on('end', () => {\n              socket.send(JSON.stringify({\n                type: \"error\",\n                error: `Ollama returned status ${res.statusCode}: ${errBody}`\n              }));\n            });\n            return;\n          }\n\n          let responseBuffer = \"\";\n          res.on('data', (chunk) => {\n            responseBuffer += chunk.toString();\n            let newlineIdx;\n            while ((newlineIdx = responseBuffer.indexOf('\\n')) !== -1) {\n              const line = responseBuffer.substring(0, newlineIdx).trim();\n              responseBuffer = responseBuffer.substring(newlineIdx + 1);\n              if (!line) continue;\n              try {\n                const parsed = JSON.parse(line);\n                if (parsed.message && parsed.message.content) {\n                  const token = parsed.message.content;\n                  console.log(`[GATEWAY] Sending token: \"${token}\"`);\n                  socket.send(JSON.stringify({\n                    type: \"chat_token\",\n                    token: token\n                  }));\n                }\n              } catch (err) {\n                // Ignore parsing errors of partial lines\n              }\n            }\n          });\n\n          res.on('end', () => {\n            console.log(\"[GATEWAY] Ollama stream completed.\");\n            if (responseBuffer.trim()) {\n              try {\n                const parsed = JSON.parse(responseBuffer.trim());\n                if (parsed.message && parsed.message.content) {\n                  const token = parsed.message.content;\n                  console.log(`[GATEWAY] Sending end token: \"${token}\"`);\n                  socket.send(JSON.stringify({\n                    type: \"chat_token\",\n                    token: token\n                  }));\n                }\n              } catch (err) {}\n            }\n            socket.send(JSON.stringify({\n              type: \"completed\",\n              exit_code: 0\n            }));\n          });\n        });\n\n        req.on('error', (err) => {\n          console.error(`[GATEWAY] Ollama request failed: ${err.message}`);\n          socket.send(JSON.stringify({\n            type: \"error\",\n            error: `Ollama is offline or model could not be loaded. Please ensure Ollama is running and the model \"${selectedModel}\" is pulled. Error: ${err.message}`\n          }));\n        });\n\n        req.write(postData);\n        req.end();\n        console.log(\"[GATEWAY] Ollama request successfully written.\");\n        return;\n      }\n    }\n\n    const absoluteClmPath = path.isAbsolute(clmFile) ? clmFile : path.join(clmRoot, clmFile);\n    if (!fs.existsSync(absoluteClmPath)) {\n      socket.send(JSON.stringify({\n        type: \"error\",\n        error: `CLM file not found: ${clmFile}`\n      }));\n      return;\n    }\n\n    // Spawn clmEval VM\n    executeClm(socket, absoluteClmPath, clmPayload);\n  });\n\n  socket.on('close', () => {\n    console.log(\"[GATEWAY] Client disconnected.\");\n    activeConnections.delete(socket);\n  });\n});\n\nfunction executeClm(socket, clmPath, clmPayload) {\n  const dispatchSock = process.env.CLM_DISPATCH_SOCK;\n  if (!dispatchSock) {\n    console.error('[GATEWAY] CLM_DISPATCH_SOCK not set — cannot dispatch execution.');\n    safeSend(socket, JSON.stringify({ type: 'error', error: 'IPC dispatcher not configured (CLM_DISPATCH_SOCK missing)' }));\n    return;\n  }\n\n  console.log(`[GATEWAY] IPC dispatch: ${clmPath} ${clmPayload}`);\n\n  safeSend(socket, JSON.stringify({\n    type: \"status\",\n    status: \"started\",\n    clm: path.basename(clmPath),\n    payload: clmPayload\n  }));\n\n  console.log(`[GATEWAY] Attempting to connect to IPC socket: ${dispatchSock}`);\n  const ipc = net.connect(dispatchSock, () => {\n    console.log(`[GATEWAY] Successfully connected to IPC socket: ${dispatchSock}`);\n  });\n  let ipcBuffer = '';\n\n  ipc.on('connect', () => {\n    console.log('[GATEWAY] IPC connected event triggered.');\n    const request = JSON.stringify({\n      action: 'execute',\n      clm_file: clmPath,\n      payload: clmPayload\n    });\n    ipc.write(request + '\\n');\n    console.log('[GATEWAY] IPC request sent.');\n  });\n\n  ipc.on('data', (chunk) => {\n    const chunkStr = chunk.toString();\n    console.log(`[GATEWAY] IPC data chunk: ${chunkStr.length} bytes`);\n    ipcBuffer += chunkStr;\n\n    let newlineIdx;\n    while ((newlineIdx = ipcBuffer.indexOf('\\n')) !== -1) {\n      const line = ipcBuffer.substring(0, newlineIdx).trim();\n      ipcBuffer = ipcBuffer.substring(newlineIdx + 1);\n      if (!line) continue;\n\n      let msg;\n      try {\n        msg = JSON.parse(line);\n      } catch (e) {\n        console.error(`[GATEWAY] IPC JSON Parse Error: ${e.message} on line: ${line}`);\n        continue;\n      }\n\n      if (msg.type === 'stdout') {\n        // Extract CLM_TRACE_JSON lines and forward as trace events\n        if (msg.data && msg.data.includes('CLM_TRACE_JSON:')) {\n          try {\n            const idx = msg.data.indexOf('CLM_TRACE_JSON:');\n            let jsonStr = msg.data.substring(idx + 'CLM_TRACE_JSON:'.length).trim();\n            // Remove any trailing escape codes\n            jsonStr = jsonStr.replace(/\\x1B\\[[0-9;]*m/g, '');\n            const traceObj = JSON.parse(jsonStr);\n            console.log(`[GATEWAY] Successfully parsed trace for transition: ${traceObj.transition}`);\n            safeSend(socket, JSON.stringify(traceObj));\n          } catch (err) {\n            console.error(`[GATEWAY] Error parsing trace JSON: ${err}`);\n          }\n        }\n      } else if (msg.type === 'stderr') {\n        safeSend(socket, JSON.stringify({\n          type: 'log',\n          message: msg.data || ''\n        }));\n      } else if (msg.type === 'completed') {\n        console.log(`[GATEWAY] Dispatch completed: exit_code=${msg.exit_code}`);\n\n        if (msg.exit_code !== 0) {\n          safeSend(socket, JSON.stringify({\n            type: 'error',\n            error: `Execution failed with exit code ${msg.exit_code}`,\n            exit_code: msg.exit_code\n          }));\n        } else if (msg.witness_hash) {\n          safeSend(socket, JSON.stringify({\n            type: 'completed',\n            exit_code: 0,\n            witness_hash: msg.witness_hash,\n            witness_yaml: msg.witness_yaml || ''\n          }));\n        } else {\n          safeSend(socket, JSON.stringify({\n            type: 'completed',\n            exit_code: 0,\n            result: 'Execution completed successfully'\n          }));\n        }\n        ipc.end();\n      } else if (msg.type === 'error') {\n        safeSend(socket, JSON.stringify({\n          type: 'error',\n          error: msg.error || 'Unknown dispatch error'\n        }));\n        ipc.end();\n      }\n    }\n  });\n\n  ipc.on('error', (err) => {\n    console.error(`[GATEWAY] IPC connection error: ${err.message}`);\n    safeSend(socket, JSON.stringify({\n      type: 'error',\n      error: 'IPC dispatch connection failed: ' + err.message\n    }));\n  });\n\n  ipc.on('close', () => {\n    console.log('[GATEWAY] IPC connection closed.');\n  });\n}"
+  balanced_exp:
+    expectation: "WebSocket server starts, processes inputs, and streams traces successfully."
+  _meta:
+    clm_name: chat_gateway
+    computed_at: "2026-06-02T01:29:34Z"
+    depends_on: []
+    clm_root_hash: sha256:a674515c294081a64b0d909f77d78123509983c57e545febd11340ab2519a729
+    a_hash: sha256:0b8d0568966c3f59f7f9c0a165676cc0a04b2d5f8c918138fbc13d47a425466e
+    c_hash: sha256:01be2971fab81f816e42f9ca2b27c38a404811d7a3be8ec9cb6e66aa6cf87e47
+    b_hash: sha256:eb0c880ae739034c2e3978e39976706f805be7d383cb19e45f389919fb67d9c6

package/assets/clm/README.md

@@ -0,0 +1,95 @@
+# `assets/clm/` — CLM-Specific Data Assets (Shared Kernel)
+
+> **MCard Type**: `type/schema`, `type/seed`, `type/runtime/executable_manifest`, `type/config`
+>
+> **Sharing Scope**: Full sovereign state — all PKC nodes must agree on these data
+> assets for the system to function. G-Set CRDT merge semantics apply.
+>
+> **Karpathy Layer**: Layer 1 (raw) — immutable once sealed as MCards. The `card`
+> table is insert-only; version evolution tracked via `handle_history`.
+
+## Subdirectories
+
+| Subdirectory | Content | MCard Type | Sharing Scope |
+|:---|:---|:---|:---|
+| [`schemas/`](schemas/) | Serializable MCard schema definitions (the frozen `mcard_schema.sql` equivalent, plus per-type schemas) | `type/schema` | Full sovereign state (all nodes must agree on schema) |
+| [`seeds/`](seeds/) | Seed data for bootstrapping a new PKC node (initial handles, initial agent identities) | `type/seed` | Full sovereign state (node cloning) |
+| [`manifests/`](manifests/) | Executable manifests (DotSlash-style binary resolution declarations) | `type/runtime/executable_manifest` | Full sovereign state (all nodes must resolve the same binaries) |
+| [`configs/`](configs/) | CLM kernel configurations (observability endpoints, backup schedules, federation parameters) | `type/config` | Selective (some configs are node-specific, some are mesh-wide) |
+
+## Feature Tour
+
+The shared kernel assets demonstrate the core CLM features. Each feature is
+linked to its asset file and specification reference.
+
+| Feature | Description | Asset File | Spec Reference |
+|:---|:---|:---|:---|
+| Universal MCard Ontology | Everything is an MCard — scalars, strings, binaries, directories, networks, devices | [`seeds/mcard_exemplars.yaml`](seeds/mcard_exemplars.yaml) | `docs/spec/20-architecture/card-triad-architecture.md` |
+| Kenotic Programming Model | CLM delegates computation to existing language engines (Python, Rust, JS/TS, Shell) | [`seeds/pcard_exemplars.yaml`](seeds/pcard_exemplars.yaml) | `docs/spec/00-product-overview/product-overview.md` |
+| Hoare Triple Verification | {V_pre} PCard {V_post} — VCards return Bool to gate state commits | [`seeds/vcard_exemplars.yaml`](seeds/vcard_exemplars.yaml) | `docs/spec/40-behavior/hoare_triple_composition_protocol.md` |
+| Function-Number Duality | Every MCard is simultaneously a zero-arity constant function 1→X | [`seeds/pcard_exemplars.yaml`](seeds/pcard_exemplars.yaml) (see `duality_of`) | `docs/spec/40-behavior/baldwin_monadic_pcard_algebra.md` |
+| Type Lattice Vocabulary | Six layers of stratified handles (L0–L5) defining the CLM formal syntax | [`seeds/type_lattice_vocabulary.yaml`](seeds/type_lattice_vocabulary.yaml) | `docs/spec/20-architecture/system-architecture.md` |
+| Petri Net Concurrency | Bipartite Place/Transition net with P-invariant conservation laws | [`seeds/petri_net_topology.yaml`](seeds/petri_net_topology.yaml) | `docs/spec/20-architecture/system-architecture.md` |
+| Cordis Fiber Lifecycle | 5-state spatiotemporal execution with LIFO disposer rollback (<1ms) | [`seeds/cordis_fiber_lifecycle.yaml`](seeds/cordis_fiber_lifecycle.yaml) | `docs/spec/40-behavior/pcard_ioc_composition.md` |
+| Baldwin Modularity Operators | Six closed algebraic operations for systematic module composition | [`seeds/baldwin_operators.yaml`](seeds/baldwin_operators.yaml) | `docs/spec/40-behavior/baldwin_monadic_pcard_algebra.md` |
+| Layer-Specific Execution | Executable manifests for each architectural layer (L0–L5) | [`manifests/layer0_manifest.yaml`](manifests/layer0_manifest.yaml) – [`layer5_manifest.yaml`](manifests/layer5_manifest.yaml) | `docs/spec/20-architecture/system-architecture.md` |
+| PCard/VCard Seed Schemas | Structural schemas for non-MCard seed collections | [`schemas/pcard_seed_schema.yaml`](schemas/pcard_seed_schema.yaml), [`schemas/vcard_seed_schema.yaml`](schemas/vcard_seed_schema.yaml) | `docs/spec/30-interfaces/asset-directory-conformance.md` |
+| Cross-Language Parity | N-Version Consensus (BLAKE3 bit-identical across Python, Rust, TS, Shell) | [`Concrete/e2e/cross_language_parity.yaml`](../../computable_knowledge/Concrete/e2e/cross_language_parity.yaml) | `docs/spec/00-product-overview/product-overview.md` |
+| Continuous Learning Loop | Meta-circular learning loop (Gamma) with epistemic fitness (Delta E) and hypothesis revision | [`Abstract/layer5_system/continuous_learning_stratum.yaml`](../../computable_knowledge/Abstract/layer5_system/continuous_learning_stratum.yaml) | `docs/spec/20-architecture/system-architecture.md` |
+
+### Try It In Action
+
+Developers can immediately verify and explore these features using the following commands:
+1. **Verify Asset Conformance & Envelopes**:
+   ```bash
+   make check-assets
+   ```
+2. **Verify Triadic Transclusions & Zero Dangling Pointers**:
+   ```bash
+   python3 tools/guards/check_triadic_transclusion_invariants.py
+   ```
+3. **Verify Layer Vocabulary Sync & Triad Symmetry**:
+   ```bash
+   make check-boundaries
+   ```
+
+## Separation Principle
+
+`assets/clm/` is the **shared kernel** — every PKC node must agree on these data
+assets. `assets/personal/` is the **sovereign periphery** — each developer's
+personal data assets are their own. These two directories must not cross-reference
+each other. The handle namespace prefix (`asset:clm:*` vs `asset:personal:*`) makes
+this distinction machine-checkable.
+
+## Content-Addressing
+
+All files in `assets/clm/` are content-addressed as MCards via the kernel's
+**parameterized multi-algorithm hash registry** (INV-02, Sprint 164). The active
+algorithm is controlled by `CLM_HASH_CONFIG` — currently `sha256:` by default, with
+BLAKE3 (>2 GB/s) available as a parameterized coexisting algorithm. Each file
+declares its own `hash_algorithm` in its frontmatter, and the registered hash
+MUST match that declaration. The `handle_registry` maps human-readable
+handles (`asset:clm:*`) to current content hashes. The `handle_history` table
+tracks version evolution. This makes every change auditable, reversible, and verifiable.
+
+## Machine Inventory & Verification
+
+- **`index.yaml`** in this directory and each concern subdirectory is the machine-readable
+  OKF-style index (handle, type, hash algorithm, owner, sharing scope, per-file inventory).
+- **`manifests/asset_manifest.yaml`** is the deterministic, committed hash inventory of all
+  shared data assets (`assets/clm/`, `assets/media/`, `assets/webapps/`).
+  `assets/personal/` is deliberately excluded (sovereign periphery).
+- **`make assets-verify`** recomputes hashes and diffs against the manifest (offline-safe).
+- **`make assets-register`** idempotently registers the manifest into the local SQLite CAS
+  (`card`, `handle_registry`, `handle_history` in `db/content_memory.db`).
+- **`make check-assets`** runs the conformance guard
+  (`tools/guards/check_assets_invariants.py`) enforcing the asset MUSTs from
+  [`docs/spec/30-interfaces/asset-directory-conformance.md`](../../docs/spec/30-interfaces/asset-directory-conformance.md).
+
+## References
+
+- [`docs/architecture/sovereign-archive-architecture.md`](../../docs/architecture/sovereign-archive-architecture.md) §11 — The Project Directory as a Single Source of Truth
+- [`docs/sprints/08_rust-native/sprint-145-ssot-directory-exemplar.md`](../../docs/sprints/08_rust-native/sprint-145-ssot-directory-exemplar.md) — Sprint 145 design document (archived from `programs/orc/`)
+- [`docs/architecture/assets-clm-implementation-plan.md`](../../docs/architecture/assets-clm-implementation-plan.md) — Implementation plan for this directory's conformance
+- [`docs/spec/30-interfaces/asset-directory-conformance.md`](../../docs/spec/30-interfaces/asset-directory-conformance.md) — Normative asset MUSTs (RFC 2119)
+- [`types/schemas/mcard_schema.sql`](../../types/schemas/mcard_schema.sql) — Core MCard schema definition

package/assets/clm/configs/backup_params.yaml

@@ -0,0 +1,26 @@
+# Storage & Backup Parameters asdfafdsafdsafdsaf
+# Asset Handle: asset:clm:configs:backup_params
+asset_handle: "asset:clm:configs:backup_params"
+asset_mcard_type: "type/config"
+asset_sharing_scope: "selective"
+asset_karpathy_layer: 1
+asset_hash_algorithm: "sha256"
+asset_owner_did: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
+asset_status: "canonical"
+schema_ref: "schema:clm:config:v1"
+config_kind: "sqlite_backup"
+schema_version: "1.0.0"
+sqlite:
+  journal_mode: "WAL"
+  synchronous: "NORMAL"
+  busy_timeout_ms: 5000
+  checkpoint_threshold_pages: 1000
+snapshots:
+  auto_snapshot_enabled: true
+  snapshot_interval_seconds: 300
+  max_retained_snapshots: 10
+  compression: "zstd"
+cas:
+  hash_algorithm: "blake3"
+  deduplication_enabled: true
+  verify_on_read: true

package/assets/clm/configs/index.yaml

@@ -0,0 +1,18 @@
+# OKF-style machine-readable index for assets/clm/configs/ (DEL-B01)
+index_id: "asset:clm:configs:index"
+concern: "configs"
+mcard_type: "type/config"
+sharing_scope: "selective"
+description: >
+  Some configs are node-specific (selective sharing); some are mesh-wide.
+  Consumed by Sprint 196 coeffect gates (config.kernel service).
+files:
+  - path: "backup_params.yaml"
+    handle: "asset:clm:configs:backup_params"
+    config_kind: "sqlite_backup"
+  - path: "network_mesh.yaml"
+    handle: "asset:clm:configs:network_mesh"
+    config_kind: "network_mesh"
+  - path: "observability.yaml"
+    handle: "asset:clm:configs:observability"
+    config_kind: "observability"

package/assets/clm/configs/network_mesh.yaml

@@ -0,0 +1,28 @@
+# Network Mesh Configuration
+# Asset Handle: asset:clm:configs:network_mesh
+asset_handle: "asset:clm:configs:network_mesh"
+asset_mcard_type: "type/config"
+asset_sharing_scope: "selective"
+asset_karpathy_layer: 1
+asset_hash_algorithm: "sha256"
+asset_owner_did: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
+asset_status: "canonical"
+schema_ref: "schema:clm:config:v1"
+config_kind: "network_mesh"
+schema_version: "1.0.0"
+topology:
+  mode: "hybrid-mesh"
+  bootstrap_nodes:
+    - "pkc://bootstrap1.local.clm:4433"
+    - "pkc://bootstrap2.local.clm:4433"
+  relay_nodes:
+    - "webrtc://relay.local.clm:8080"
+limits:
+  max_peers: 32
+  heartbeat_interval_ms: 5000
+  connect_timeout_ms: 10000
+  bandwidth_cap_kbps: 10240
+transport:
+  quic_enabled: true
+  webrtc_enabled: true
+  websocket_fallback: true

package/assets/clm/configs/observability.yaml

@@ -0,0 +1,29 @@
+# Observability & Faro Telemetry Configuration
+# Asset Handle: asset:clm:configs:observability
+asset_handle: "asset:clm:configs:observability"
+asset_mcard_type: "type/config"
+asset_sharing_scope: "selective"
+asset_karpathy_layer: 1
+asset_hash_algorithm: "sha256"
+asset_owner_did: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
+asset_status: "canonical"
+schema_ref: "schema:clm:config:v1"
+config_kind: "observability"
+schema_version: "1.0.0"
+telemetry:
+  collector_url: "http://127.0.0.1:12347/collect"
+  app_name: "mcard-studio"
+  app_version: "0.2.0"
+  environment: "development"
+tracing:
+  enabled: true
+  sample_rate: 1.0
+  batch_size: 50
+  flush_interval_ms: 2000
+metrics:
+  web_vitals: true
+  flux_action_latency: true
+  memory_snapshots: true
+logs:
+  min_level: "info"
+  ring_buffer_size: 250

package/assets/clm/index.yaml

@@ -0,0 +1,26 @@
+# OKF-style machine-readable index for assets/clm/ (DEL-B01)
+# Human-readable companion: assets/clm/README.md
+index_id: "asset:clm:index"
+concern: "assets-clm-shared-kernel"
+sharing_scope: "full"
+karpathy_layer: 1
+description: >
+  CLM-specific shared data assets. Every PKC node must agree on these assets
+  for the system to function; G-Set CRDT merge semantics apply.
+concerns:
+  - concern: "schemas"
+    index: "schemas/index.yaml"
+    mcard_type: "type/schema"
+    description: "Serializable MCard schema definitions (frozen structural contracts)"
+  - concern: "seeds"
+    index: "seeds/index.yaml"
+    mcard_type: "type/seed"
+    description: "Seed data for bootstrapping a new PKC node"
+  - concern: "manifests"
+    index: "manifests/index.yaml"
+    mcard_type: "type/runtime/executable_manifest"
+    description: "Executable manifests, the asset hash manifest, and the media type registry"
+  - concern: "configs"
+    index: "configs/index.yaml"
+    mcard_type: "type/config"
+    description: "CLM kernel configurations (observability, backup, mesh parameters)"