@githolon/runtime 0.110.0

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@githolon/runtime",
+  "version": "0.110.0",
+  "type": "module",
+  "description": "The portable Nomos application runtime, reception contracts, and Node/browser runners.",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Captain-App/nomos2.git",
+    "directory": "peer-office"
+  },
+  "exports": {
+    "./application": {
+      "types": "./src/application_reception.ts",
+      "import": "./dist/application-reception.js"
+    },
+    "./remote-reception": {
+      "types": "./src/remote_reception.public.d.ts",
+      "import": "./dist/remote-reception.js",
+      "require": "./dist/remote-reception.cjs"
+    },
+    "./typescript-reception": {
+      "types": "./src/typescript_application_desk.public.d.ts",
+      "import": "./dist/typescript-application-desk.js"
+    },
+    "./package.json": "./package.json",
+    "./runner/node-entry.mjs": "./runner/node-entry.mjs",
+    "./dist/nomos-runner.html": "./dist/nomos-runner.html",
+    "./dist/nomos-runner.js": "./dist/nomos-runner.js"
+  },
+  "typesVersions": {
+    "*": {
+      "application": [
+        "src/application_reception.ts"
+      ],
+      "remote-reception": [
+        "src/remote_reception.public.d.ts"
+      ],
+      "typescript-reception": [
+        "src/typescript_application_desk.public.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "src",
+    "runner",
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node runner/build.ts",
+    "build:runner": "node runner/build.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "prepare": "npm run build",
+    "prepublishOnly": "node runner/build.ts",
+    "test:unit": "node --expose-gc --test ../test/*.test.ts",
+    "test:runtime": "node --test ../test/peer_runtime_contract.test.ts"
+  },
+  "dependencies": {
+    "@bjorn3/browser_wasi_shim": "0.4.2",
+    "@bufbuild/protobuf": "^2.13.0",
+    "fast-xml-parser": "5.10.1",
+    "uri-js": "^4.4.1"
+  },
+  "devDependencies": {
+    "buffer": "^6.0.3",
+    "isomorphic-git": "^1.38.4"
+  }
+}

package/runner/README.md

@@ -0,0 +1,75 @@
+# Physical shells for the Nomos peer runtime
+
+Every Nomos peer runs the same retained `PeerRuntime` implementation. These
+entry points exist only because browsers, Node processes and app WebViews boot
+code and move bytes differently.
+
+```text
+generated Dart / TypeScript client
+                 │
+                 │ Runtime v2 Protobuf frame
+                 ▼
+┌──────────────────────────────────────────────────────────┐
+│ one PeerRuntime                                          │
+│                                                          │
+│ sessions · custody lifecycle · offers · queries · sync   │
+│ subscriptions · retries · progress                       │
+└────────────────────────────┬─────────────────────────────┘
+                             │ typed effect
+                             ▼
+┌──────────────────────────────────────────────────────────┐
+│ physical platform shell                                  │
+│ kernel execution · filesystem · network · clock · keys   │
+└────────────────────────────┬─────────────────────────────┘
+                             │ typed receipt
+                             └──────────────► same runtime
+```
+
+The shell is not a compatibility layer. It must not contain a command map,
+session table, credential cache, sync controller, retry policy, custody model,
+or a second interpretation of a generated request. It may inspect a typed
+initial `Connect.cloud` only to acquire the selected physical kernel artifact;
+the unchanged request is then handled by the shared runtime.
+
+## Entrypoints
+
+- `runner-entry.ts` boots the browser/WebView kernel plane and forwards exact
+  Runtime v2 frames and events.
+- `node-entry.ts` boots the Node kernel plane and forwards the same frames and
+  events over stdin/stdout.
+- Apple embeds `nomos-native-runtime.js`, built from the same
+  `peer-office/src/peer_office.ts`; JavaScriptCore runs the office and the
+  native host supplies the AOT kernel.
+
+Build the distributable shells with:
+
+```bash
+npm run build:runner
+```
+
+This produces `dist/nomos-runner.js`, `dist/nomos-runner.html`, the Node shell,
+and the Apple runtime bundle. Generated applications consume these artifacts;
+they do not implement lifecycle themselves.
+
+## Non-negotiable boundary
+
+The only application/runtime messages are generated Runtime v2 Protobuf
+frames. Domain values returned by generated calls remain canonical OpenUSD.
+Base64 is permitted only where a browser API physically accepts strings; it is
+an encoding of the unchanged Protobuf bytes, not a second command language.
+
+Inside one Peer Office, desks call typed `RuntimeRequest -> RuntimeResponse`
+functions. Only the external `invoke(bytes)` boundary encodes and decodes
+Runtime v2 frames. Internal sub-requests still pass through the same access,
+recovery, session-binding and observation paths; they do not gain authority by
+being local. Large byte fields are shared read-only, not serialized merely to
+cross a function boundary. The kernel ABI and actual remote HTTP effects are
+separate byte boundaries and still encode their messages.
+
+`peer-office/test/peer_office_wire_boundary.test.ts` meters real protobuf calls
+through the bundled office. A local success or refusal must perform exactly
+one external request decode and one external response encode.
+
+Git custody remains the durable source of truth. SQLite projections and
+compiled OpenUSD layers are disposable frontier-keyed acceleration. No shell
+may serialize a workspace into a private snapshot format to move or park it.

package/runner/build.ts

@@ -0,0 +1,225 @@
+// Build the Nomos client bundles: the @githolon/runtime + a per-host entry + the engine shims, esbuild'd into
+// ONE self-contained IIFE. The browser shell and Apple JavaScriptCore host
+// both retain the same peer-runtime implementation; they differ only in the
+// physical kernel and byte-transport ports they provide.
+// Run: `npm run build:runner`.
+import { build } from "esbuild";
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { isAbsolute, join, relative, resolve } from "node:path";
+
+const here = (p: string) => fileURLToPath(new URL(p, import.meta.url));
+const normalizeGeneratedText = (file: string): void => {
+  const source = readFileSync(file, "utf8");
+  writeFileSync(file, source.replace(/[ \t]+$/gm, ""), "utf8");
+};
+mkdirSync(here("../dist"), { recursive: true });
+// THE BUNDLE STAMP: inject the package version so the runner's ready frame carries exactly the
+// release it was built from (stale-baked-bundle detection — the stamp can never drift or lie).
+const BUNDLE_VERSION = JSON.parse(readFileSync(here("../package.json"), "utf8")).version;
+// The SDK carries the host compatibility contract, not the executable or a fresh-install fallback. Online,
+// the runtime endpoint selects a contract-compatible immutable digest; the runner verifies and durably caches
+// those exact bytes. RAN can therefore promote or roll back compatible kernels without republishing the SDK.
+const KERNEL_RELEASE = {
+  contracts: { "nomos.kernel.v1": "1.0.0" },
+};
+
+const browserBuild = await build({
+  entryPoints: [here("../../../platform-shells/browser/entry.ts")],
+  // Resolve node_modules by the path it is reached at, not its real path: a bundle's module
+  // comments name that path, so a committed-snapshot build (whose node_modules is a link to the
+  // installed one) and a checkout build emit the same bytes.
+  preserveSymlinks: true,
+  bundle: true,
+  platform: "browser",
+  format: "iife",
+  target: "es2020",
+  inject: [here("./shims.js")],
+  define: {
+    global: "globalThis",
+    __NOMOS_BUNDLE_VERSION__: JSON.stringify(BUNDLE_VERSION),
+    __NOMOS_KERNEL_RELEASE__: JSON.stringify(KERNEL_RELEASE),
+  },
+  outfile: here("../dist/nomos-runner.js"),
+  legalComments: "none",
+  metafile: true,
+});
+copyFileSync(here("./nomos-runner.html"), here("../dist/nomos-runner.html"));
+
+// THE TYPED NATIVE RUNTIME — the shared Peer Office executed by the Apple
+// JavaScriptCore host. It accepts only generated Runtime v2
+// protobuf and calls the resident kernel with generated kernel protobuf.
+const nativeBuild = await build({
+  entryPoints: [here("../../src/peer_office.ts")],
+  // Resolve node_modules by the path it is reached at, not its real path: a bundle's module
+  // comments name that path, so a committed-snapshot build (whose node_modules is a link to the
+  // installed one) and a checkout build emit the same bytes.
+  preserveSymlinks: true,
+  bundle: true,
+  platform: "neutral",
+  format: "iife",
+  globalName: "NomosRuntimeComponent",
+  target: "es2022",
+  outfile: here("../dist/nomos-native-runtime.js"),
+  legalComments: "none",
+  metafile: true,
+});
+// APPLICATION RECEPTION — generated facades import only this narrow session
+// surface. The Peer Office owns every runtime lifecycle behind its desks.
+const applicationBuild = await build({
+  entryPoints: [here("../src/application_reception.ts")],
+  // Resolve node_modules by the path it is reached at, not its real path: a bundle's module
+  // comments name that path, so a committed-snapshot build (whose node_modules is a link to the
+  // installed one) and a checkout build emit the same bytes.
+  preserveSymlinks: true,
+  bundle: true,
+  platform: "neutral",
+  format: "esm",
+  target: "es2022",
+  outfile: here("../dist/application-reception.js"),
+  packages: "external",
+  legalComments: "none",
+  logLevel: "warning",
+  metafile: true,
+});
+normalizeGeneratedText(here("../dist/application-reception.js"));
+console.error("✓ built dist/application-reception.js (language-native Reception surface)");
+
+const typescriptReceptionBuild = await build({
+  entryPoints: [here("../../src/reception/typescript_application_desk.ts")],
+  // Resolve node_modules by the path it is reached at, not its real path: a bundle's module
+  // comments name that path, so a committed-snapshot build (whose node_modules is a link to the
+  // installed one) and a checkout build emit the same bytes.
+  preserveSymlinks: true,
+  bundle: true,
+  platform: "neutral",
+  format: "esm",
+  target: "es2022",
+  outfile: here("../dist/typescript-application-desk.js"),
+  packages: "external",
+  legalComments: "none",
+  logLevel: "warning",
+  metafile: true,
+});
+normalizeGeneratedText(here("../dist/typescript-application-desk.js"));
+console.error("✓ built TypeScript Reception application desks");
+
+// REMOTE RECEPTION — a scheduler or another non-resident process may hand one
+// generated call to a remote Peer Office. This bundles only protobuf paper and
+// HTTP correspondence; it must never pull a kernel or workspace lifecycle into
+// the caller.
+const remoteReceptionBuild = await build({
+  entryPoints: [here("../src/remote_reception.ts")],
+  // Resolve node_modules by the path it is reached at, not its real path: a bundle's module
+  // comments name that path, so a committed-snapshot build (whose node_modules is a link to the
+  // installed one) and a checkout build emit the same bytes.
+  preserveSymlinks: true,
+  bundle: true,
+  platform: "neutral",
+  format: "esm",
+  target: "es2022",
+  outfile: here("../dist/remote-reception.js"),
+  packages: "external",
+  legalComments: "none",
+  logLevel: "warning",
+  metafile: true,
+});
+normalizeGeneratedText(here("../dist/remote-reception.js"));
+const remoteReceptionCommonJsBuild = await build({
+  entryPoints: [here("../src/remote_reception.ts")],
+  // Resolve node_modules by the path it is reached at, not its real path: a bundle's module
+  // comments name that path, so a committed-snapshot build (whose node_modules is a link to the
+  // installed one) and a checkout build emit the same bytes.
+  preserveSymlinks: true,
+  bundle: true,
+  platform: "node",
+  format: "cjs",
+  target: "node18",
+  outfile: here("../dist/remote-reception.cjs"),
+  packages: "external",
+  legalComments: "none",
+  logLevel: "warning",
+  metafile: true,
+});
+normalizeGeneratedText(here("../dist/remote-reception.cjs"));
+console.error("✓ built Remote Reception ESM + CommonJS (typed HTTP correspondence only)");
+
+// PROPAGATE the built bundles into nomos_flutter/assets (the Flutter package ships them verbatim — see its
+// pubspec `assets:`). Doing it HERE keeps the asset in lockstep with the build: a stale asset is exactly how a
+// shim fix (e.g. the JSC TextEncoder polyfill) failed to reach the native app and a tenant had to patch the
+// Dart layer instead. One build, one set of bytes, every peer. (nomos_flutter is a sibling package, not an npm
+// dep, so the copy is the sync.)
+const FLUTTER_ASSETS = here("../../../nomos_flutter/assets");
+if (existsSync(FLUTTER_ASSETS)) {
+  for (const f of ["nomos-runner.js", "nomos-runner.html", "nomos-native-runtime.js"]) {
+    copyFileSync(here(`../dist/${f}`), join(FLUTTER_ASSETS, f));
+  }
+  console.error("✓ synced browser shell and shared Peer Office assets → nomos_flutter/assets");
+}
+
+console.error("✓ built browser shell and shared Peer Office runtime bundles");
+
+// ── THE PUBLISHED NODE RUNNER ENTRY (co2 tenant DEFECT P3-002) ────────────────────────────────────────
+// `runner/node-entry.ts` works IN-REPO (node type-strips first-party .ts) but Node REFUSES type-stripping
+// under node_modules (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING) — so every PUBLISHED consumer's runner
+// failed to boot. Bundle a JS twin beside it; consumers (and the Dart harness resolver) prefer the .mjs.
+const nodeBuild = await build({
+  entryPoints: [here("../../../platform-shells/node/stdio/entry.ts")],
+  // Resolve node_modules by the path it is reached at, not its real path: a bundle's module
+  // comments name that path, so a committed-snapshot build (whose node_modules is a link to the
+  // installed one) and a checkout build emit the same bytes.
+  preserveSymlinks: true,
+  bundle: true,
+  platform: "node",
+  format: "esm",
+  define: { __NOMOS_KERNEL_RELEASE__: JSON.stringify(KERNEL_RELEASE) },
+  outfile: here("node-entry.mjs"),
+  logLevel: "warning",
+  metafile: true,
+});
+normalizeGeneratedText(here("node-entry.mjs"));
+console.error("✓ built runner/node-entry.mjs (self-contained published-consumer runner)");
+
+
+// The Dart package carries the same Node platform shells for its tests. It
+// does not carry a second offline installer or custody lifecycle.
+const DART_RUNNER = here("../../../dsl/dart/lib/src/runner");
+if (existsSync(here("../../../dsl/dart"))) {
+  mkdirSync(DART_RUNNER, { recursive: true });
+  copyFileSync(here("node-entry.mjs"), join(DART_RUNNER, "node-entry.mjs"));
+  console.error("✓ synced the stdio node peer → nomos_client/lib/src/runner");
+}
+
+// A cheap, standard freshness proof. Rebuilding bundles merely to discover
+// drift wastes minutes; esbuild already knows the exact source graph it read.
+// Record those inputs as a SHA256SUMS-style manifest so CI can prove both that
+// every source is unchanged and that every delivered copy is byte-identical.
+const repositoryRoot = here("../../../");
+const sourceInputs = new Set<string>([
+  ...Object.keys(browserBuild.metafile.inputs),
+  ...Object.keys(nativeBuild.metafile.inputs),
+  ...Object.keys(applicationBuild.metafile.inputs),
+  ...Object.keys(typescriptReceptionBuild.metafile.inputs),
+  ...Object.keys(remoteReceptionBuild.metafile.inputs),
+  ...Object.keys(remoteReceptionCommonJsBuild.metafile.inputs),
+  ...Object.keys(nodeBuild.metafile.inputs),
+  here("./build.ts"),
+  here("../package.json"),
+  here("../src/typescript_application_desk.public.d.ts"),
+]);
+const sourceLines = [...sourceInputs]
+  .filter((input) => !input.startsWith("<"))
+  .map((input) => {
+    const absolute = isAbsolute(input) ? input : resolve(input);
+    const path = relative(repositoryRoot, absolute);
+    const digest = createHash("sha256").update(readFileSync(absolute)).digest("hex");
+    return `${digest}  ${path}`;
+  })
+  .sort();
+writeFileSync(
+  here("../dist/RUNTIME-SOURCES.sha256"),
+  `${sourceLines.join("\n")}\n`,
+  "utf8",
+);
+console.error("✓ wrote dist/RUNTIME-SOURCES.sha256 (cheap source freshness gate)");