twin3-sdk 0.2.11-pre-alpha → 0.2.12-pre-alpha

package/README.md

@@ -1,7 +1,7 @@
 # Twin3 SDK (`twin3-sdk`)
 > **The Universal Capability Motherboard for Autonomous AI Agents & Self-Sovereign Humans**
 
-[English](README.md) | [繁體中文](README_ZH.md) | [GitHub: twin3-team/twin3-sdk](https://github.com/twin3-team/twin3-sdk)
+[English](README.md) | [Traditional Chinese](README_ZH.md) | [GitHub: twin3-team/twin3-sdk](https://github.com/twin3-team/twin3-sdk)
 
 [![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://python.org)
 [![Architecture: 7-Layer Symbiosis](https://img.shields.io/badge/Architecture-7--Layer%20Symbiosis-success.svg)](#the-seven-layer-symbiotic-architecture)
@@ -103,22 +103,22 @@ pip install -e /path/to/twin3-sdk
 * Any protocol or algorithm improvement in `twin3-sdk` is reflected in both applications in **0 milliseconds**.
 
 #### 2. Production Distribution
-The next release candidate is `0.2.11-pre-alpha` for npm and `0.2.11a0` for Python. It is not a production dependency until the GitHub release workflows have built, attested, rehearsed, and published the exact tagged artifacts. Consumers must then pin the exact released version and lock its registry integrity; never use a mutable range for a cryptographic protocol dependency. This candidate stays pre-alpha. Marketplace or sales copy may offer it for evaluation; it is not a stable release, and the npm dist-tag is `next`, not `latest`.
+`v0.2.12-pre-alpha` is the current release candidate: `0.2.12-pre-alpha` for npm and `0.2.12a0` for PyPI. Publication is pending. Consumers must pin the exact released version and lock its registry integrity; never use a mutable range for a cryptographic protocol dependency. This release stays pre-alpha. Marketplace or sales copy may offer it for evaluation; it is not a stable release, and the npm dist-tag is `next`, not `latest`.
 
 `package.json` `engines` sets Node.js to `>=18` and does not set an npm engine. Any npm that can install a tarball can consume the package. Packing this repository was checked with npm 10 or newer; the stricter npm version in the release runbook applies only to Trusted Publishing.
 
-After the release workflow has published that exact version, install the pin. These commands are not evidence that the registry already serves the package:
+After publication, install the exact released version from the registry:
 
 ```bash
-npm install twin3-sdk@0.2.11-pre-alpha
-pip install twin3-sdk==0.2.11a0
+npm install twin3-sdk@0.2.12-pre-alpha
+pip install twin3-sdk==0.2.12a0
 ```
 
-Until publication, evaluate the packed npm tarball only. Do not install from a git URL or a version range:
+For local evaluation, you can also use the packed npm tarball. Do not install from a git URL or a version range:
 
 ```bash
 npm pack --ignore-scripts
-npm install ./twin3-sdk-0.2.11-pre-alpha.tgz
+npm install ./twin3-sdk-0.2.12-pre-alpha.tgz
 ```
 
 ---

package/js/local-memory.js

@@ -0,0 +1,64 @@
+"use strict";
+
+const { spawn } = require("node:child_process");
+const path = require("node:path");
+const fs = require("node:fs");
+
+function requiredText(value, limit = 1000) {
+  if (typeof value !== "string" || !value.trim() || value.length > limit || value.includes("\0")) throw new TypeError("local_memory_option_invalid");
+  return value;
+}
+
+function startLocalMemory(options) {
+  if (!options || typeof options !== "object") throw new TypeError("local_memory_options_required");
+  const executable = requiredText(options.pythonExecutable);
+  const databasePath = requiredText(options.databasePath);
+  const directory = path.dirname(databasePath);
+  if (!path.isAbsolute(executable) || !path.isAbsolute(databasePath)) throw new TypeError("local_memory_absolute_path_required");
+  if (!["human", "enterprise"].includes(options.namespace)) throw new TypeError("local_memory_namespace_invalid");
+  const subject = requiredText(options.subject, 200);
+  const ontology = requiredText(options.ontology, 200);
+  if (!Array.isArray(options.dimensions) || !options.dimensions.length || options.dimensions.some(value => typeof value !== "string" || !value || value.includes(","))) throw new TypeError("local_memory_dimensions_invalid");
+  const port = options.port ?? 0;
+  if (!Number.isSafeInteger(port) || port < 0 || port > 65535) throw new TypeError("local_memory_port_invalid");
+  const args = ["-I", "-m", "twin3.memory.runtime", "--database", databasePath, "--subject", subject, "--namespace", options.namespace, "--ontology", ontology, "--dimensions", options.dimensions.join(","), "--port", String(port)];
+  if (options.model) args.push("--model", requiredText(options.model, 200));
+  if (options.embeddingModel) args.push("--embedding-model", requiredText(options.embeddingModel, 200));
+  if (options.modelEndpoint) args.push("--model-endpoint", requiredText(options.modelEndpoint, 200));
+  const child = spawn(executable, args, { shell: false, stdio: ["ignore", "pipe", "pipe"] });
+  return new Promise((resolve, reject) => {
+    let stdout = "";
+    let settled = false;
+    const timer = setTimeout(() => fail("local_memory_start_timeout"), 15000);
+    function fail(code) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.kill("SIGINT");
+      reject(new Error(code));
+    }
+    child.stderr.on("data", () => {});
+    child.on("error", () => fail("local_memory_runtime_unavailable"));
+    child.on("exit", () => fail("local_memory_runtime_unavailable"));
+    child.stdout.on("data", chunk => {
+      if (settled) return;
+      stdout += chunk.toString("utf8");
+      if (stdout.length > 16384) return fail("local_memory_start_invalid");
+      if (!stdout.includes("\n")) return;
+      try {
+        const result = JSON.parse(stdout.split("\n")[0]);
+        const url = new URL(result.url);
+        if (result.capability !== "memory.local-v1" || result.identity_assurance !== "local_workspace_only" || url.protocol !== "http:" || url.hostname !== "127.0.0.1" || !url.port || url.pathname !== "/" || url.search || url.hash || url.username || url.password || typeof result.token_file !== "string" || path.dirname(fs.realpathSync(result.token_file)) !== fs.realpathSync(directory) || path.basename(result.token_file) !== `session-${url.port}.token`) return fail("local_memory_start_invalid");
+        settled = true;
+        clearTimeout(timer);
+        child.stdout.removeAllListeners("data");
+        child.stdout.resume();
+        resolve({ url: result.url, tokenFile: result.token_file, identityAssurance: result.identity_assurance, process: child, stop: () => child.kill("SIGINT") });
+      } catch {
+        fail("local_memory_start_invalid");
+      }
+    });
+  });
+}
+
+module.exports = { startLocalMemory };

package/local-memory.d.ts

@@ -0,0 +1,22 @@
+export interface LocalMemoryOptions {
+  pythonExecutable: string;
+  databasePath: string;
+  namespace: "enterprise" | "human";
+  subject: string;
+  ontology: string;
+  dimensions: string[];
+  port?: number;
+  model?: string;
+  embeddingModel?: string;
+  modelEndpoint?: string;
+}
+
+export interface LocalMemoryProcess {
+  url: string;
+  tokenFile: string;
+  identityAssurance: "local_workspace_only";
+  process: import("node:child_process").ChildProcess;
+  stop(): boolean;
+}
+
+export function startLocalMemory(options: LocalMemoryOptions): Promise<LocalMemoryProcess>;

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "twin3-sdk",
-  "version": "0.2.11-pre-alpha",
+  "version": "0.2.12-pre-alpha",
   "description": "Universal Capability Motherboard for Autonomous AI Agents and Self-Sovereign Humans (JS/Node runtime)",
   "type": "commonjs",
   "main": "./js/index.js",
   "types": "./index.d.ts",
   "exports": {
+    "./local-memory": {
+      "types": "./local-memory.d.ts",
+      "require": "./js/local-memory.js",
+      "default": "./js/local-memory.js"
+    },
     ".": {
       "types": "./index.d.ts",
       "require": "./js/index.js",
@@ -19,6 +24,8 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "js/local-memory.js",
+    "local-memory.d.ts",
     "js/index.js",
     "js/comm/counterparty.js",
     "js/state.js",