@githolon/runtime 0.110.0

package/runner/nomos-runner.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+    <title>Nomos runner</title>
+  </head>
+  <body>
+    <!-- The Nomos WebView runner. A Flutter app loads this page off-screen; all interaction is via the bridge
+         Runtime v2 protobuf frame port. There is no UI here by design. -->
+    <script src="./nomos-runner.js"></script>
+  </body>
+</html>

package/runner/shims.js

@@ -0,0 +1,17 @@
+// Browser/WebView polyfills for the Node-isms the client's third-party deps assume (the client's OWN code is
+// browser-safe). esbuild injects this ahead of everything so the globals exist before the client loads:
+//   • `Buffer`  — isomorphic-git uses the Node Buffer global (its own source flags this for bundler consumers).
+//   • `process` — a few deps probe `process.env`/`process.platform`; a minimal stub satisfies them.
+import { Buffer } from "buffer";
+globalThis.Buffer = globalThis.Buffer || Buffer;
+
+if (typeof globalThis.queueMicrotask !== "function") {
+  globalThis.queueMicrotask = (callback) => {
+    if (typeof callback !== "function") {
+      throw new TypeError("queueMicrotask callback must be a function");
+    }
+    Promise.resolve().then(callback);
+  };
+}
+
+globalThis.process = globalThis.process || { env: {}, platform: "browser", browser: true, version: "", versions: {}, nextTick: (fn, ...a) => queueMicrotask(() => fn(...a)) };

package/src/admission_decision.ts

@@ -0,0 +1,60 @@
+import { KernelRefusalCode, type OfferResponse } from './protocol/nomos/kernel/v1/kernel_pb.js';
+export { KernelRefusalCode };
+
+export interface DomainRefusalEvidence {
+  readonly lawSha256: Uint8Array;
+  readonly invariant: string;
+  readonly typeIdentity: string;
+  readonly valueUsda: Uint8Array;
+}
+export type AdmissionDecision<S, R> =
+  | { readonly kind: 'admitted'; readonly value: S }
+  | { readonly kind: 'domainRefused'; readonly reason: R; readonly evidence: DomainRefusalEvidence }
+  | { readonly kind: 'frameworkRefused'; readonly code: KernelRefusalCode; readonly message: string }
+  | { readonly kind: 'unsupportedRefusalContract'; readonly evidence: DomainRefusalEvidence };
+
+// Bundles may have separate copies of this module. The shared symbol preserves
+// the typed offer envelope across those copies without class-identity coupling.
+const offerFailure = Symbol.for('nomos.typedOfferFailure.v1');
+export class NomosTypedOfferFailure extends Error {
+  readonly [offerFailure] = true;
+  readonly response: OfferResponse;
+  constructor(response: OfferResponse, message: string) { super(message); this.response = response; }
+  static is(value: unknown): value is NomosTypedOfferFailure {
+    return value instanceof Error && (value as NomosTypedOfferFailure)[offerFailure] === true;
+  }
+}
+const unsupported = Symbol.for('nomos.unsupportedNominalRefusal.v1');
+export class UnsupportedNominalRefusal extends Error {
+  readonly [unsupported] = true;
+}
+
+/** Pure adaptation of a completed offer. Scheduling, retries and policy remain
+ * in Peer Office; transport and dependency failures are deliberately propagated. */
+export async function admissionDecision<S, R>(command: () => Promise<S>,
+  decode: (value: DomainRefusalEvidence) => R | undefined): Promise<AdmissionDecision<S, R>> {
+  try { return { kind: 'admitted', value: await command() }; }
+  catch (error) {
+    if (!NomosTypedOfferFailure.is(error) || error.response?.outcome?.case !== 'refused') throw error;
+    const reply = error.response.outcome.value;
+    const code = reply.refusal?.code ?? KernelRefusalCode.UNSPECIFIED;
+    const value = reply.domainRefusal;
+    if (value === undefined) {
+      if (code === KernelRefusalCode.DOMAIN_REFUSED) throw new TypeError('Kernel domain refusal omitted its nominal value');
+      return { kind: 'frameworkRefused', code, message: reply.refusal?.message ?? '' };
+    }
+    if (code !== KernelRefusalCode.DOMAIN_REFUSED || value.lawSha256.length !== 32
+        || !value.invariant || !value.typeIdentity || !value.valueUsda.length || value.valueUsda.length > 65536) {
+      throw new TypeError('Invalid kernel domain-refusal envelope');
+    }
+    const evidence: DomainRefusalEvidence = Object.freeze({ lawSha256: value.lawSha256.slice(),
+      invariant: value.invariant, typeIdentity: value.typeIdentity, valueUsda: value.valueUsda.slice() });
+    try {
+      const reason = decode(evidence);
+      return reason === undefined ? { kind: 'unsupportedRefusalContract', evidence } : { kind: 'domainRefused', reason, evidence };
+    } catch (error) {
+      if (!(error instanceof Error) || (error as UnsupportedNominalRefusal)[unsupported] !== true) throw error;
+      return { kind: 'unsupportedRefusalContract', evidence };
+    }
+  }
+}

package/src/application_reception.ts

@@ -0,0 +1,134 @@
+// TENANT-FACING SOURCE. A generated TypeScript application typechecks this file
+// under its OWN tsconfig (`moduleResolution: "Bundler"`, no
+// `allowImportingTsExtensions`), so these specifiers stay `.js` and TypeScript
+// resolves them to the sibling `.ts`. No `.js` file exists or should: the
+// hand-copied `admission_decision.js` that used to be carried between checkouts
+// to keep a Node import honest is gone, and the files Node executes from source
+// (`remote_reception.ts`, `generated_offer_counter.ts`) name `.ts` instead.
+export * from './admission_decision.js';
+export { NominalValue, parseNominalValue } from './nominal_value.js';
+declare const _nomosDigest: unique symbol;
+export type Sha256Digest = string & { readonly [_nomosDigest]: "sha256" };
+export type GitObjectId = string & { readonly [_nomosDigest]: "git-object" };
+
+/** Pure value constructors shared by generated code and the Peer Office. */
+export const sha256Digest = (value: string): Sha256Digest => {
+  if (!/^[0-9a-f]{64}$/.test(value)) {
+    throw new TypeError("expected a 64-character lowercase hexadecimal SHA-256 digest");
+  }
+  return value as Sha256Digest;
+};
+export const gitObjectId = (value: string): GitObjectId => {
+  if (!/^[0-9a-f]{40}$/.test(value)) {
+    throw new TypeError("expected a 40-character lowercase hexadecimal Git object id");
+  }
+  return value as GitObjectId;
+};
+
+/** Exact generated call shape Reception may hand back to the application desk. */
+export interface ReceptionGeneratedCall {
+  readonly domain: string;
+  readonly directive: string;
+  readonly protobufType: string;
+  readonly protobufPayload: Uint8Array;
+  readonly routingCandidates: readonly string[];
+}
+
+export interface ReceptionInvitationFrameworkCalls {
+  readonly invitation?: {
+    redeem(input: {
+      readonly domain: string;
+      readonly workspace: string;
+      readonly directive: string;
+      readonly orderId: string;
+      readonly object: string;
+      readonly relation: string;
+      readonly invitationPublicKey: string;
+      readonly invitationSignature: string;
+      readonly invitationId: string;
+      readonly redeemedAt: string;
+    }): ReceptionGeneratedCall;
+  };
+}
+
+/** Identity already established by the Peer Office for this Reception session. */
+export interface ReceptionUser {
+  readonly identityId: string;
+  readonly identityAddress: string;
+}
+
+/** Presentation-only observations of Peer Office work. */
+export interface ReceptionStatus {
+  readonly phase: "opening" | "current" | "saving" | "receiving" | "catching-up" | "offline" | "attention";
+  readonly localChanges: number;
+  readonly acceptedChanges: number;
+  readonly decisionsNeeded: number;
+  readonly lastUpdatedAt: Date | null;
+  readonly message: string | null;
+}
+
+export interface ReceptionStatusDesk {
+  current(): Promise<ReceptionStatus>;
+  watch(listener: (status: ReceptionStatus) => void): () => void;
+}
+
+export interface ReceptionInvitationMaterial {
+  readonly address: string;
+  readonly token: string;
+}
+
+export interface ReceptionInvitationMatch {
+  readonly orderId: string;
+  readonly object: string;
+  readonly relation: string;
+}
+
+export interface ReceptionInvitationPolicy {
+  readonly domain: string;
+  readonly domainHash: string;
+  readonly redeem: string;
+  readonly pending: (address: string) => Promise<readonly ReceptionInvitationMatch[]>;
+}
+
+/** Result of Reception asking the Peer Office to follow one workspace reference. */
+export interface ReceptionFollow<ApplicationDesk> {
+  readonly reception: ReceptionSession<ApplicationDesk>;
+  /** Background correspondence receipt, not a reason to block the local child handle. */
+  readonly settled: Promise<void>;
+}
+
+/**
+ * Ephemeral language-native Reception state around one Peer Office application
+ * desk. It contains no kernel, custody, placement, credential or sync truth.
+ */
+export interface ReceptionSession<ApplicationDesk> {
+  readonly desk: ApplicationDesk;
+  readonly user: ReceptionUser;
+  readonly status: ReceptionStatusDesk;
+  follow(workspace: string): Promise<ReceptionFollow<ApplicationDesk>>;
+  createInvitation(): Promise<ReceptionInvitationMaterial>;
+  redeemInvitation(
+    link: string,
+    policies: readonly ReceptionInvitationPolicy[],
+    frameworkCalls: ReceptionInvitationFrameworkCalls,
+  ): Promise<void>;
+  close(): Promise<void>;
+}
+
+/** Immutable compatibility requirements emitted from the compiler graph. */
+export interface ApplicationCompatibility {
+  readonly lawIdentity: Sha256Digest;
+  readonly matrixUsda: Uint8Array;
+  readonly readyCommands: readonly {
+    readonly domain: string;
+    readonly packageHash: Sha256Digest;
+    readonly directiveId: string;
+  }[];
+}
+
+/** Stateless compiler output received by a language-native Reception. */
+export interface GeneratedApplication<ApplicationDesk, Application> {
+  readonly name: string;
+  readonly compatibility: ApplicationCompatibility;
+  receive(reception: ReceptionSession<ApplicationDesk>): Application;
+}

package/src/nominal_value.ts

@@ -0,0 +1,122 @@
+/** Read the kernel's bounded, canonical nominal value syntax. This reader does
+ * not compose layers or interpret law. Generated codecs own schema traversal. */
+export class NominalValue {
+  readonly typeName: string;
+  readonly name: string;
+  readonly properties: ReadonlyMap<string, unknown>;
+  readonly children: readonly NominalValue[];
+  constructor(typeName: string, name: string, properties: ReadonlyMap<string, unknown>, children: readonly NominalValue[]) {
+    this.typeName = typeName; this.name = name; this.properties = properties; this.children = children;
+  }
+  property(name: string): unknown { return this.properties.get(name); }
+  relationship(name: string): string | undefined {
+    const value = this.property(name);
+    return typeof value === 'string' ? value : undefined;
+  }
+  child(name: string): NominalValue {
+    const child = this.children.find(value => value.name === name);
+    if (!child) throw new TypeError(`Missing nominal child ${name}`);
+    return child;
+  }
+  field(path: string): NominalValue | undefined {
+    const values = this.children.filter(value => value.relationship('nomos:field') === path);
+    if (values.length > 1) throw new TypeError(`Duplicate nominal field ${path}`);
+    return values[0];
+  }
+  requiredField(path: string): NominalValue {
+    const field = this.field(path);
+    if (!field) throw new TypeError(`Missing nominal field ${path}`);
+    return field;
+  }
+  stringValue(): string {
+    const value = this.property('nomos:value');
+    if (!['NomosStringValue', 'NomosTokenValue'].includes(this.typeName) || typeof value !== 'string') throw new TypeError('Expected nominal text');
+    return value;
+  }
+  numberValue(integer = false): number {
+    const value = this.property('nomos:value');
+    if (this.typeName !== (integer ? 'NomosIntValue' : 'NomosNumberValue') || typeof value !== 'number'
+        || !Number.isFinite(value) || (integer && !Number.isSafeInteger(value))) throw new TypeError('Expected lossless nominal number');
+    return value;
+  }
+  boolValue(): boolean {
+    const value = this.property('nomos:value');
+    if (this.typeName !== 'NomosBoolValue' || typeof value !== 'boolean') throw new TypeError('Expected nominal boolean');
+    return value;
+  }
+}
+
+export function parseNominalValue(bytes: Uint8Array): NominalValue {
+  if (bytes.length > 65536) throw new TypeError('Nominal refusal exceeds its byte limit');
+  const source = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  if (!source.startsWith('#usda 1.0')) throw new TypeError('Expected canonical nominal USDA');
+  const tokens: string[] = [];
+  const pattern = /\s+|#[^\n]*|"(?:[^"\\]|\\.)*"|<[^<>\n]*>|[{}()=]|[A-Za-z_][A-Za-z_0-9:]*|-?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?/gy;
+  let offset = 0;
+  while (offset < source.length) {
+    pattern.lastIndex = offset;
+    const match = pattern.exec(source);
+    if (!match) throw new TypeError(`Unsupported nominal USDA syntax at ${offset}`);
+    offset = pattern.lastIndex;
+    if (!/^\s|^#/.test(match[0])) tokens.push(match[0]);
+  }
+  let cursor = 0;
+  const take = (): string => {
+    const value = tokens[cursor++];
+    if (value === undefined) throw new TypeError('Truncated nominal USDA');
+    return value;
+  };
+  const expect = (value: string): void => { if (take() !== value) throw new TypeError(`Expected ${value}`); };
+  const string = (value: string): string => {
+    if (!value.startsWith('"')) throw new TypeError('Expected USDA string');
+    // Canonical kernel strings use the JSON-compatible escape subset.
+    const result: unknown = JSON.parse(value);
+    if (typeof result !== 'string') throw new TypeError('Expected USDA string');
+    return result;
+  };
+  const prim = (depth: number): NominalValue => {
+    if (depth > 128) throw new TypeError('Nominal value exceeds nesting limit');
+    expect('def');
+    const typeName = take();
+    const name = string(take());
+    expect('{');
+    const properties = new Map<string, unknown>();
+    const children: NominalValue[] = [];
+    while (tokens[cursor] !== '}') {
+      if (tokens[cursor] === 'def') {
+        const child = prim(depth + 1);
+        if (children.some(value => value.name === child.name)) throw new TypeError('Duplicate nominal child');
+        children.push(child);
+        continue;
+      }
+      while (tokens[cursor] === 'custom' || tokens[cursor] === 'uniform') take();
+      const type = take(), key = take();
+      expect('=');
+      const token = take();
+      let value: unknown;
+      if (type === 'rel') {
+        if (!token.startsWith('</') || !token.endsWith('>')) throw new TypeError('Expected nominal relationship');
+        value = token.slice(1, -1);
+      } else if (type === 'string' || type === 'token') value = string(token);
+      else if (type === 'bool') {
+        if (!['true', 'false', '1', '0'].includes(token)) throw new TypeError('Expected nominal boolean');
+        value = token === 'true' || token === '1';
+      } else if (['int', 'int64', 'uint64', 'double', 'float'].includes(type)) {
+        value = Number(token);
+        if (!Number.isFinite(value) || (type.includes('int') && !Number.isSafeInteger(value))) throw new TypeError('Unsafe nominal number');
+      } else throw new TypeError(`Unsupported nominal property type ${type}`);
+      if (properties.has(key)) throw new TypeError('Duplicate nominal property');
+      properties.set(key, value);
+    }
+    expect('}');
+    return new NominalValue(typeName, name, properties, children);
+  };
+  if (tokens[cursor] === '(') {
+    take(); expect('defaultPrim'); expect('=');
+    if (string(take()) !== 'Value') throw new TypeError('Unexpected default nominal prim');
+    expect(')');
+  }
+  const root = prim(0);
+  if (cursor !== tokens.length || root.name !== 'Value') throw new TypeError('Expected one nominal Value root');
+  return root;
+}

package/src/protocol/nomos/custody/v1/snapshot_pb.d.ts

@@ -0,0 +1,67 @@
+// @generated by protoc-gen-es v2.13.0 with parameter "target=js+dts,import_extension=js"
+// @generated from file nomos/custody/v1/snapshot.proto (package nomos.custody.v1, syntax proto3)
+/* eslint-disable */
+
+import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv2";
+import type { Message } from "@bufbuild/protobuf";
+
+/**
+ * Describes the file nomos/custody/v1/snapshot.proto.
+ */
+export declare const file_nomos_custody_v1_snapshot: GenFile;
+
+/**
+ * Opaque local custody cache. Git tree and checkpoint bytes remain kernel-owned;
+ * the host records only enough typed metadata to offer them back on next open.
+ * Field numbers deliberately match the historical runtime-v1 message so stored
+ * PB3 snapshots remain wire-compatible across this ownership correction.
+ *
+ * @generated from message nomos.custody.v1.LocalCustodySnapshot
+ */
+export declare type LocalCustodySnapshot = Message<"nomos.custody.v1.LocalCustodySnapshot"> & {
+  /**
+   * @generated from field: uint32 format_version = 1;
+   */
+  formatVersion: number;
+
+  /**
+   * @generated from field: optional string workspace = 2;
+   */
+  workspace?: string | undefined;
+
+  /**
+   * @generated from field: bytes tree = 3;
+   */
+  tree: Uint8Array;
+
+  /**
+   * @generated from field: optional bytes checkpoint = 4;
+   */
+  checkpoint?: Uint8Array | undefined;
+
+  /**
+   * @generated from field: optional bytes frontier = 5;
+   */
+  frontier?: Uint8Array | undefined;
+
+  /**
+   * @generated from field: optional string cursor = 6;
+   */
+  cursor?: string | undefined;
+
+  /**
+   * @generated from field: optional string state_root = 7;
+   */
+  stateRoot?: string | undefined;
+
+  /**
+   * @generated from field: optional string synced_base = 8;
+   */
+  syncedBase?: string | undefined;
+};
+
+/**
+ * Describes the message nomos.custody.v1.LocalCustodySnapshot.
+ * Use `create(LocalCustodySnapshotSchema)` to create a new message.
+ */
+export declare const LocalCustodySnapshotSchema: GenMessage<LocalCustodySnapshot>;

package/src/protocol/nomos/custody/v1/snapshot_pb.js

@@ -0,0 +1,18 @@
+// @generated by protoc-gen-es v2.13.0 with parameter "target=js+dts,import_extension=js"
+// @generated from file nomos/custody/v1/snapshot.proto (package nomos.custody.v1, syntax proto3)
+/* eslint-disable */
+
+import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv2";
+
+/**
+ * Describes the file nomos/custody/v1/snapshot.proto.
+ */
+export const file_nomos_custody_v1_snapshot = /*@__PURE__*/
+  fileDesc("Ch9ub21vcy9jdXN0b2R5L3YxL3NuYXBzaG90LnByb3RvEhBub21vcy5jdXN0b2R5LnYxIqACChRMb2NhbEN1c3RvZHlTbmFwc2hvdBIWCg5mb3JtYXRfdmVyc2lvbhgBIAEoDRIWCgl3b3Jrc3BhY2UYAiABKAlIAIgBARIMCgR0cmVlGAMgASgMEhcKCmNoZWNrcG9pbnQYBCABKAxIAYgBARIVCghmcm9udGllchgFIAEoDEgCiAEBEhMKBmN1cnNvchgGIAEoCUgDiAEBEhcKCnN0YXRlX3Jvb3QYByABKAlIBIgBARIYCgtzeW5jZWRfYmFzZRgIIAEoCUgFiAEBQgwKCl93b3Jrc3BhY2VCDQoLX2NoZWNrcG9pbnRCCwoJX2Zyb250aWVyQgkKB19jdXJzb3JCDQoLX3N0YXRlX3Jvb3RCDgoMX3N5bmNlZF9iYXNlYgZwcm90bzM");
+
+/**
+ * Describes the message nomos.custody.v1.LocalCustodySnapshot.
+ * Use `create(LocalCustodySnapshotSchema)` to create a new message.
+ */
+export const LocalCustodySnapshotSchema = /*@__PURE__*/
+  messageDesc(file_nomos_custody_v1_snapshot, 0);

package/src/protocol/nomos/discovery/v1/workspace_placement_pb.d.ts

@@ -0,0 +1,56 @@
+// @generated by protoc-gen-es v2.13.0 with parameter "target=js+dts,import_extension=js"
+// @generated from file nomos/discovery/v1/workspace_placement.proto (package nomos.discovery.v1, syntax proto3)
+/* eslint-disable */
+
+import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv2";
+import type { Message } from "@bufbuild/protobuf";
+
+/**
+ * Describes the file nomos/discovery/v1/workspace_placement.proto.
+ */
+export declare const file_nomos_discovery_v1_workspace_placement: GenFile;
+
+/**
+ * An availability description returned by a workspace discovery provider.
+ *
+ * This is deliberately outside the kernel and peer-runtime protocol packages:
+ * it reports where custody might be reached, but proves neither placement nor
+ * workspace authority. The Peer Office passes policy_usda to the kernel before
+ * acting on it, and every remote mutation still enters through offer.
+ *
+ * @generated from message nomos.discovery.v1.DiscoveredWorkspacePlacement
+ */
+export declare type DiscoveredWorkspacePlacement = Message<"nomos.discovery.v1.DiscoveredWorkspacePlacement"> & {
+  /**
+   * @generated from field: string workspace = 1;
+   */
+  workspace: string;
+
+  /**
+   * @generated from field: optional string frontier = 2;
+   */
+  frontier?: string | undefined;
+
+  /**
+   * @generated from field: bytes policy_usda = 3;
+   */
+  policyUsda: Uint8Array;
+
+  /**
+   * @generated from field: string custody_lease_url = 4;
+   */
+  custodyLeaseUrl: string;
+
+  /**
+   * Provider-supplied availability hint, not committed placement policy.
+   *
+   * @generated from field: string candidate_reception_url = 5;
+   */
+  candidateReceptionUrl: string;
+};
+
+/**
+ * Describes the message nomos.discovery.v1.DiscoveredWorkspacePlacement.
+ * Use `create(DiscoveredWorkspacePlacementSchema)` to create a new message.
+ */
+export declare const DiscoveredWorkspacePlacementSchema: GenMessage<DiscoveredWorkspacePlacement>;

package/src/protocol/nomos/discovery/v1/workspace_placement_pb.js

@@ -0,0 +1,18 @@
+// @generated by protoc-gen-es v2.13.0 with parameter "target=js+dts,import_extension=js"
+// @generated from file nomos/discovery/v1/workspace_placement.proto (package nomos.discovery.v1, syntax proto3)
+/* eslint-disable */
+
+import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv2";
+
+/**
+ * Describes the file nomos/discovery/v1/workspace_placement.proto.
+ */
+export const file_nomos_discovery_v1_workspace_placement = /*@__PURE__*/
+  fileDesc("Cixub21vcy9kaXNjb3ZlcnkvdjEvd29ya3NwYWNlX3BsYWNlbWVudC5wcm90bxISbm9tb3MuZGlzY292ZXJ5LnYxIqYBChxEaXNjb3ZlcmVkV29ya3NwYWNlUGxhY2VtZW50EhEKCXdvcmtzcGFjZRgBIAEoCRIVCghmcm9udGllchgCIAEoCUgAiAEBEhMKC3BvbGljeV91c2RhGAMgASgMEhkKEWN1c3RvZHlfbGVhc2VfdXJsGAQgASgJEh8KF2NhbmRpZGF0ZV9yZWNlcHRpb25fdXJsGAUgASgJQgsKCV9mcm9udGllcmIGcHJvdG8z");
+
+/**
+ * Describes the message nomos.discovery.v1.DiscoveredWorkspacePlacement.
+ * Use `create(DiscoveredWorkspacePlacementSchema)` to create a new message.
+ */
+export const DiscoveredWorkspacePlacementSchema = /*@__PURE__*/
+  messageDesc(file_nomos_discovery_v1_workspace_placement, 0);