@githolon/dsl 0.4.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",
@@ -17,6 +17,7 @@
   "exports": {
     ".": "./src/index.ts",
     "./manifest": "./src/manifest.ts",
+    "./stable-ids": "./src/stable_ids.ts",
     "./compose": "./src/compose.ts",
     "./usd": "./src/usd.ts",
     "./usd-layers": "./src/usd_layers.ts",

package/src/build_package.ts

@@ -54,6 +54,7 @@ import type { WorkspaceTypeDecl } from "./workspace_type.js";
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
 import { domainHash, emitManifestBytes } from "./manifest.js";
 import { emitUsd } from "./usd.js";
+import { expandCapabilityExports } from "./capability_exports.js";
 
 // ─────────────────────────────────────────────────────────────────────────────────
 // composeDomainModule — the named-keys `module(...)`
@@ -134,6 +135,9 @@ export interface DomainModuleSpec {
 export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
   let merged: Mod = {};
   for (const m of spec.modules) merged = { ...merged, ...m };
+  // `capability()` bundles expand into discoverable entries (the package plane's
+  // merge point) — the quartet validation below then passes without re-exports.
+  merged = expandCapabilityExports(merged);
 
   const byId = new Map<string, AggregateHandle>();
   for (const a of [...aggregatesOf(merged), ...(spec.extraAggregates ?? [])]) byId.set(a.id, a);

package/src/capability_exports.ts

@@ -0,0 +1,55 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded
+// QuickJS engine} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * capability_exports.ts — the ONE-EXPORT expansion for `capability()` bundles
+ * (`architecture/capability_marketplace.md` §4, ruling M2 — "the domain dev
+ * declares ONE thing").
+ *
+ * Every module-exports walk in the house scans TOP-LEVEL exports by shape
+ * (aggregates, directives, queries…). A `capability()` declaration is one
+ * export holding a task aggregate + the five lifecycle directives as
+ * properties — invisible to those walks. This helper, applied at each plane's
+ * merge point (the engine lump's `mergeModules`, the package composer's merge,
+ * the compile CLI's merge), ADDS the bundle's pieces to the exports bag under
+ * synthetic names (`<export>$aggregate`, `<export>$order`, …) so every
+ * existing shape-walk discovers them with ZERO new walk semantics. The
+ * original bundle export stays (config-named lanes still resolve it); the
+ * walks ignore its unmatched shape exactly as before.
+ *
+ * ZERO imports on purpose: this file is bundled into the sealed engine lump
+ * (engine_entry.ts) — it must drag nothing with it.
+ */
+
+/** Duck-type guard: a `capability()` return (the tag is set by the factory). */
+export function isCapabilityDecl(v: unknown): v is Record<string, unknown> {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    (v as { __isCapabilityDecl?: boolean }).__isCapabilityDecl === true
+  );
+}
+
+const PIECES = ["aggregate", "order", "complete", "fail", "block", "deadLetter", "tasks"] as const;
+
+/**
+ * Expand every `capability()` bundle in an exports bag into discoverable
+ * top-level entries. Pure; returns the SAME object when nothing expands (the
+ * common case stays allocation-free and referentially stable).
+ */
+export function expandCapabilityExports<M extends Record<string, unknown>>(mod: M): M {
+  let out: Record<string, unknown> | null = null;
+  for (const [k, v] of Object.entries(mod)) {
+    if (!isCapabilityDecl(v)) continue;
+    out ??= { ...mod };
+    for (const piece of PIECES) {
+      const member = (v as Record<string, unknown>)[piece];
+      if (member !== undefined) out[`${k}$${piece}`] = member;
+    }
+  }
+  return (out ?? mod) as M;
+}

package/src/codegen_dart.ts

@@ -2322,6 +2322,15 @@ export interface DomainModule {
   domain?: string;
   aggregates: AggregateHandle[];
   directives: AnyDirective[];
+  /**
+   * STABLE-ID CONTINUITY (#58 — names are labels, identity is minted). When present
+   * (attached by `nomos-compile` from the PRIOR build's identity manifests), the
+   * canonical manifest's `stableIds` block carries these sids/lineages forward instead
+   * of minting at first appearance — a renamed entity keeps its identity. Keyed by
+   * CURRENT names (the compiler resolves renames BEFORE attaching). Absent ⇒ every
+   * sid mints deterministically at first appearance.
+   */
+  stableIdContinuity?: import("./stable_ids_types.js").StableIds;
   /**
    * The domain's NAMED, INDEXED read declarations (read-side closure step 1).
    * ADDITIVE + OPTIONAL: a domain that declares no query omits this entirely and is

package/src/codegen_proof.ts

@@ -41,6 +41,7 @@ import type { Directive } from "./directive.js";
 import type { DomainModule } from "./codegen_dart.js";
 import type { QueryDecl } from "./query.js";
 import { finishCount } from "./count.js";
+import { mintedCreateField } from "./workspace_routing.js";
 import {
   autoStampFields,
   tsClientFactoryName,
@@ -187,6 +188,77 @@ export interface TsProofOptions {
   readonly domainHash: string;
 }
 
+/** The machine-readable OFFLINE legs for ONE domain (the `@nomos-proof-legs`
+ *  marker shape; the `proof-legs.json` index is a map of these by domain key). */
+export interface ProofLegs {
+  readonly domain: string;
+  readonly directiveId: string;
+  readonly aggregateId: string;
+  readonly payload: Record<string, unknown>;
+  readonly autoStamped: readonly string[];
+  readonly mintField?: string;
+  readonly query?: { readonly id: string; readonly params: Record<string, unknown> };
+  readonly count?: { readonly id: string; readonly group: string };
+}
+
+/** Synthesize the offline legs for one domain module, or `null` when it has no
+ *  creating write (nothing to prove). The SINGLE source of the leg-selection
+ *  logic — `generateTsProof` (the .mts marker) and `proofLegsIndex` (the
+ *  per-domain index) both call this, so the offline lane proves any domain the
+ *  same way the generated proof proves its primary one. */
+export function proofLegsForModule(mod: DomainModule): ProofLegs | null {
+  const createDir = (mod.directives as Directive<unknown>[]).find(
+    (d) => d?.marker === "creates" && typeof d.payloadSchema === "object",
+  );
+  if (createDir === undefined) return null;
+  const domain = mod.domain ?? mod.name;
+  const agg = (mod.aggregates as AggregateHandle[]).find((a) => a.id === createDir.aggregateId);
+  if (agg === undefined) return null;
+  const synth = synthesizePayload(createDir.payloadSchema as z.ZodTypeAny, `${domain}/${createDir.id}`);
+  const mintField = mintedCreateField(createDir, agg);
+  const baseValue: Record<string, unknown> = { ...synth.value };
+  if (mintField !== undefined) delete baseValue[mintField];
+  const query = ((mod.queries ?? []) as QueryDecl[]).find(
+    (q) => q.returns === agg.id && q.key.length > 0 && q.key.every((k) => !k.includes(".") && baseValue[k] !== undefined),
+  );
+  const count = (mod.counts ?? [])
+    .map((raw) => finishCount(raw))
+    .find((c) => c.of === agg.id && (c as { where?: unknown }).where == null && (c.by == null || baseValue[c.by] !== undefined));
+  return {
+    domain,
+    directiveId: createDir.id,
+    aggregateId: agg.id,
+    payload: baseValue,
+    autoStamped: synth.autoStamped,
+    ...(mintField !== undefined ? { mintField } : {}),
+    ...(query ? { query: { id: query.id, params: Object.fromEntries(query.key.map((k) => [k, baseValue[k]])) } } : {}),
+    ...(count ? { count: { id: count.id, group: count.by != null ? String(baseValue[count.by]) : "" } } : {}),
+  };
+}
+
+/** The per-domain legs index for `build/<name>.proof-legs.json` — every domain
+ *  with a creating write, plus the default (the first, which the .mts proves).
+ *  `githolon proof [--domain <key>]` runs any of these offline. */
+export function proofLegsIndex(modules: readonly DomainModule[]): { default: string; domains: Record<string, ProofLegs> } | null {
+  const domains: Record<string, ProofLegs> = {};
+  let first: string | undefined;
+  for (const mod of modules) {
+    // FAIL SOFT per-module: a sibling domain whose payload can't be synthesized
+    // (an exotic zod shape synthesizePayload throws on) must not lose the index
+    // for the domains that DO synthesize — skip it, keep the rest.
+    let legs: ProofLegs | null;
+    try {
+      legs = proofLegsForModule(mod);
+    } catch {
+      continue;
+    }
+    if (legs === null) continue;
+    domains[legs.domain] = legs;
+    if (first === undefined) first = legs.domain;
+  }
+  return first === undefined ? null : { default: first, domains };
+}
+
 export function generateTsProof(modules: readonly DomainModule[], opts: TsProofOptions): string {
   // The proof drives the FIRST domain that has a creating write — without one
   // there is nothing to author, so there is nothing to prove.
@@ -202,7 +274,11 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
   const factory = tsClientFactoryName(domain);
   const hashConst = tsHashConstName(opts.packageName);
 
-  const createDir = (mod.directives as Directive<unknown>[]).find((d) => d?.marker === "creates")!;
+  // SAME predicate as the mod selection above AND proofLegsForModule — so the
+  // proof body, its marker, and the index can never describe different directives.
+  const createDir = (mod.directives as Directive<unknown>[]).find(
+    (d) => d?.marker === "creates" && typeof d.payloadSchema === "object",
+  )!;
   const agg = (mod.aggregates as AggregateHandle[]).find((a) => a.id === createDir.aggregateId);
   if (agg === undefined) {
     throw new Error(
@@ -211,10 +287,21 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
   }
   const synth = synthesizePayload(createDir.payloadSchema as z.ZodTypeAny, `${domain}/${createDir.id}`);
 
+  // THE MINTED-ID RULE (the gate's `check_create_ids`): a `.creates` payload field
+  // that IS the target's own id must be KERNEL-MINTED — a hand-written sample id
+  // refuses typed at admission (`NotMinted`). The marker-driven trace names the
+  // field (never name-guessed); the generated proof MINTS it at runtime
+  // (`holon.mint`) instead of synthesizing a sample, so the proof admits
+  // everywhere the law does.
+  const mintField = mintedCreateField(createDir, agg);
+  const baseValue: Record<string, unknown> = { ...synth.value };
+  if (mintField !== undefined) delete baseValue[mintField];
+
   // The first declared query that can READ BACK the create: returns the created
-  // aggregate and every key field has a synthesized payload value to probe with.
+  // aggregate and every key field has a synthesized payload value to probe with
+  // (a query keyed on the MINTED field is skipped — its value exists only at runtime).
   const query = ((mod.queries ?? []) as QueryDecl[]).find(
-    (q) => q.returns === agg.id && q.key.length > 0 && q.key.every((k) => !k.includes(".") && synth.value[k] !== undefined),
+    (q) => q.returns === agg.id && q.key.length > 0 && q.key.every((k) => !k.includes(".") && baseValue[k] !== undefined),
   );
 
   // The first declared count the create moves: counts the created aggregate,
@@ -226,7 +313,7 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
       (c) =>
         c.of === agg.id &&
         (c as { where?: unknown }).where == null &&
-        (c.by == null || synth.value[c.by] !== undefined),
+        (c.by == null || baseValue[c.by] !== undefined),
     );
 
   const concurrency = findConcurrencyLeg(mod.directives as Directive<unknown>[], agg);
@@ -239,10 +326,19 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
       .replace(/^-+|-+$/g, "")
       .slice(0, 24) || "domain";
 
-  const payloadLit = JSON.stringify(synth.value);
-  const queryParams = query ? JSON.stringify(Object.fromEntries(query.key.map((k) => [k, synth.value[k]]))) : "";
+  const payloadLit =
+    mintField !== undefined
+      ? `{ ...${JSON.stringify(baseValue)}, ${JSON.stringify(mintField)}: __minted }`
+      : JSON.stringify(baseValue);
+  const queryParamsObj = query ? Object.fromEntries(query.key.map((k) => [k, baseValue[k]])) : undefined;
+  const queryParams = queryParamsObj ? JSON.stringify(queryParamsObj) : "";
   const listAccessor = `list${agg.id}s`;
 
+  // THE MACHINE-READABLE LEGS (parsed by `githolon`'s offline proof runner —
+  // cli/src/proof_offline.ts). The ONE leg-synthesis (`proofLegsForModule`) feeds
+  // both this marker and the per-domain `proof-legs.json` index, so they never drift.
+  const legsMarker = JSON.stringify(proofLegsForModule(mod));
+
   let step = 0;
   const n = () => ++step;
   const out: string[] = [];
@@ -256,6 +352,7 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
     `//`,
     `// The flow mirrors the scaffold's test/e2e.mts (docs/ in a scaffolded app explains`,
     `// every call — start at docs/01-mental-model.md). Regenerated on every compile; do not edit.`,
+    `// @nomos-proof-legs ${legsMarker}`,
     `import { readFileSync } from "node:fs";`,
     `import { connect } from "@githolon/client";`,
     `import { ${factory}, ${hashConst} } from "./${opts.packageName}.client.ts";`,
@@ -266,18 +363,25 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
     `// IDENTITY NOTE: this proof uses the bare x-nomos-principal lane so it is`,
     `// SELF-CONTAINED (a throwaway workspace, no stored credentials). Real apps use`,
     `// \`githolon login --agent\` (a VERIFIED identity) + \`githolon ws create/deploy\`.`,
-    `const fail: (m: string) => never = (m) => { console.error("✗ " + m); process.exit(1); };`,
+    `const fail: (m: string) => never = (m) => { throw new Error(m); };`,
     `const ok = (m: string) => console.log("✓ " + m);`,
     ``,
     `const deploy = JSON.parse(readFileSync(new URL(${JSON.stringify(`./${opts.packageName}.deploy.json`)}, import.meta.url), "utf8"));`,
     ``,
+    `// CLEANUP CONTRACT: the throwaway workspace is RETIRED on every exit (green or`,
+    `// jammed) — a proof never leaves orphans. PROOF_KEEP=1 (githolon proof --live --keep)`,
+    `// keeps it and prints the FULL secret once, with the persist command.`,
+    `let SECRET = "";`,
+    `let runError: unknown = null;`,
+    `try {`,
+    ``,
     `// ${n()}. a throwaway workspace (the ONE-TIME secret comes back on create)`,
     `let r = await fetch(\`\${CLOUD}/v1/workspaces/\${WS}\`, { method: "POST", headers: { "x-nomos-principal": "githolon-proof" } });`,
     `let d = await r.json();`,
     `if (!d.ok) fail(\`create workspace: \${JSON.stringify(d)}\`);`,
-    `const SECRET: string = d.workspaceSecret;`,
+    `SECRET = d.workspaceSecret;`,
     `if (!SECRET?.startsWith("nws_v1_")) fail(\`no workspaceSecret returned: \${JSON.stringify(d)}\`);`,
-    `ok(\`workspace \${WS} created — secret \${SECRET.slice(0, 10)}…\`);`,
+    `ok(\`workspace \${WS} created (one-time secret held for cleanup — PROOF_KEEP=1 keeps the workspace and prints it)\`);`,
     ``,
     `// ${n()}. deploy YOUR compiled law (build/${opts.packageName}.deploy.json) WITH the secret`,
     `r = await fetch(\`\${CLOUD}/v1/workspaces/\${WS}/domains\`, { method: "POST", headers: { "content-type": "application/json", authorization: \`Bearer \${SECRET}\` }, body: JSON.stringify(deploy) });`,
@@ -297,8 +401,16 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
     `const realFetch = globalThis.fetch;`,
     `globalThis.fetch = (() => { throw new Error("OFFLINE PROOF VIOLATED: local authoring touched the network"); }) as typeof fetch;`,
     ``,
+    ...(mintField !== undefined
+      ? [
+          `// the target's own id is KERNEL-MINTED (never hand-written — the gate's`,
+          `// check_create_ids refuses sample ids typed): the local wasm mints, the id`,
+          `// rides the payload, replay reads the capture.`,
+          `const __minted = await holon.mint(${JSON.stringify(agg.id)});`,
+        ]
+      : []),
     `await app.${createDir.id}(${payloadLit});`,
-    `ok("dispatch ${domain}/${createDir.id} — offline write under the pulled law (payload synthesized from YOUR schema)");`,
+    `ok("dispatch ${domain}/${createDir.id} — offline write under the pulled law (payload synthesized from YOUR schema${mintField !== undefined ? `; \`${mintField}\` kernel-minted` : ``})");`,
     ``,
   );
 
@@ -326,7 +438,7 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
 
   if (count) {
     const accessor = lcFirst(camel(count.id));
-    const callArg = count.by != null ? JSON.stringify(String(synth.value[count.by])) : "";
+    const callArg = count.by != null ? JSON.stringify(String(baseValue[count.by])) : "";
     out.push(
       `// ${n()}. the first declared count — the maintained O(1) tally, locally`,
       `const localCount = await app.${accessor}(${callArg});`,
@@ -370,7 +482,7 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
   if (count) {
     out.push(
       `// ${n()}. the EDGE maintains the same count (same wasm, same law)`,
-      `d = await (await fetch(\`\${CLOUD}/v1/workspaces/\${WS}/counts/${count.id}${count.by != null ? `?group=\${encodeURIComponent(${JSON.stringify(String(synth.value[count.by]))})}` : ``}\`)).json();`,
+      `d = await (await fetch(\`\${CLOUD}/v1/workspaces/\${WS}/counts/${count.id}${count.by != null ? `?group=\${encodeURIComponent(${JSON.stringify(String(baseValue[count.by]))})}` : ``}\`)).json();`,
       `if (!(d.ok && d.count === 1)) fail(\`cloud count ${count.id}: \${JSON.stringify(d)}\`);`,
       `ok("cloud count ${count.id} = 1 — the O(1) maintained read, at the edge too");`,
       ``,
@@ -424,6 +536,22 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
     ``,
     `console.log(\`\\nALL GREEN — generated proof for "${opts.packageName}": deploy → offline write → local reads → admission → cloud reads${concurrency ? ` → AddWins merge` : ``} → convergence (\${WS})\`);`,
     ``,
+    `} catch (e) {`,
+    `  runError = e;`,
+    `  console.error("✗ " + ((e as Error)?.message ?? e));`,
+    `} finally {`,
+    `  // THE CLEANUP CONTRACT: never an orphaned cloud workspace. Retired on every`,
+    `  // exit path; PROOF_KEEP=1 keeps it and prints the FULL secret exactly once.`,
+    `  if (SECRET && process.env.PROOF_KEEP === "1") {`,
+    `    console.log(\`workspace \${WS} KEPT — secret \${SECRET}\`);`,
+    `    console.log(\`  persist it: githolon secret set \${WS} <the secret above>   (then: githolon ws retire \${WS} when done)\`);`,
+    `  } else if (SECRET) {`,
+    `    const rr = await fetch(\`\${CLOUD}/v1/workspaces/\${WS}/retire\`, { method: "POST", headers: { authorization: \`Bearer \${SECRET}\` } }).then((x) => x.json()).catch(() => ({}));`,
+    `    console.log(\`  retired \${WS}: \${(rr as { ok?: boolean }).ok === true}\`);`,
+    `  }`,
+    `  process.exit(runError ? 1 : 0);`,
+    `}`,
+    ``,
   );
 
   return out.join("\n");