@githolon/dsl 0.108.7 → 0.110.1

package/src/codegen_query_usda.ts

@@ -1,214 +0,0 @@
-import type { LawGraph, LawQueryReadNode } from "./law_graph.js";
-
-export type QueryScalarKind = "string" | "reference" | "token" | "integer" | "boolean";
-
-export interface DartQueryUsdaParameter {
-  readonly authoredPath: string;
-  readonly name: string;
-  readonly type: "String" | "int" | "bool";
-  readonly value: string;
-  readonly kind: QueryScalarKind;
-}
-
-export interface DartQueryUsdaEncoder {
-  readonly functionName: string;
-  readonly call: string;
-  readonly source: readonly string[];
-}
-
-export interface TsQueryUsdaParameter {
-  readonly authoredPath: string;
-  readonly name: string;
-  readonly type: "string" | "number" | "boolean";
-  readonly value: string;
-  readonly kind: QueryScalarKind;
-}
-
-export interface TsQueryUsdaEncoder {
-  readonly functionName: string;
-  readonly call: string;
-  readonly source: readonly string[];
-}
-
-const symbol = (value: string): string =>
-  value.replace(/[^A-Za-z0-9_$]+/g, "_").replace(/^[^A-Za-z_$]/, "_$&");
-
-const pathLeaf = (path: string): string => path.slice(path.lastIndexOf("/") + 1);
-
-const dartString = (value: string): string => JSON.stringify(value);
-
-/**
- * Emit one query-specific USDA encoder from the same composed graph that emitted law.usda.
- *
- * There is intentionally no schema interpreter or generic value bag in the generated runtime:
- * each parameter has one Dart type, one OpenUSD value type and exact query/field relationships.
- */
-export function emitDartQueryUsdaEncoder(
-  graph: LawGraph,
-  paths: ReadonlyMap<string, string>,
-  domain: string,
-  queryId: string,
-  parameters: readonly DartQueryUsdaParameter[],
-): DartQueryUsdaEncoder {
-  const query = graph.nodes.find(
-    (node): node is LawQueryReadNode =>
-      node.kind === "read" && node.readKind === "query" && node.entity.label === queryId,
-  );
-  if (query === undefined) {
-    throw new Error(`query USDA codegen: domain '${domain}' has no law query '${queryId}'`);
-  }
-  const queryPath = paths.get(query.entity.id);
-  if (queryPath === undefined) {
-    throw new Error(`query USDA codegen: '${domain}/${queryId}' has no rendered law path`);
-  }
-  if (query.key.length !== parameters.length) {
-    throw new Error(
-      `query USDA codegen: '${domain}/${queryId}' has ${query.key.length} law keys but ${parameters.length} generated parameters`,
-    );
-  }
-  const functionName = `_nmsQueryUsda_${symbol(domain)}_${symbol(queryId)}`;
-  const signature = parameters.map((parameter) => `${parameter.type} ${parameter.name}`).join(", ");
-  const lines = [
-    `NmsGeneratedQuery ${functionName}(${signature}) {`,
-    `  final out = <String>[`,
-    `    '#usda 1.0',`,
-    `    '(',`,
-    `    '    defaultPrim = "Query"',`,
-    `    ')',`,
-    `    '',`,
-    `    'def NomosQuery "Query"',`,
-    `    '{',`,
-    `    '    custom rel nomos:query = <${queryPath}>',`,
-    `    '',`,
-    `    '    def NomosQueryArguments "Arguments"',`,
-    `    '    {',`,
-    `  ];`,
-  ];
-  for (let index = 0; index < parameters.length; index++) {
-    const parameter = parameters[index]!;
-    const key = query.key[index]!;
-    if (key.authoredPath !== parameter.authoredPath) {
-      throw new Error(
-        `query USDA codegen: '${domain}/${queryId}' key ${index} is '${key.authoredPath}', not '${parameter.authoredPath}'`,
-      );
-    }
-    const fieldPath = paths.get(key.field.id);
-    if (fieldPath === undefined) {
-      throw new Error(
-        `query USDA codegen: '${domain}/${queryId}.${parameter.authoredPath}' has no rendered field path`,
-      );
-    }
-    const valuePath = `/Query/Arguments/${pathLeaf(fieldPath)}`;
-    const [primType, declaredType, expression] = (() => {
-      switch (parameter.kind) {
-        case "string":
-          return ["NomosStringValue", "string", `_nmsUsdaQuote(${parameter.name})`] as const;
-        case "reference":
-          return ["NomosReferenceValue", "string", `_nmsUsdaQuote(${parameter.name})`] as const;
-        case "token":
-          return ["NomosTokenValue", "token", `_nmsUsdaQuote(${parameter.name})`] as const;
-        case "integer":
-          return ["NomosIntValue", "int64", `_nmsUsdaInt(${parameter.name})`] as const;
-        case "boolean":
-          return ["NomosBoolValue", "bool", `${parameter.name} ? 'true' : 'false'`] as const;
-      }
-    })();
-    lines.push(
-      `  _nmsUsdaBegin(out, 2, ${dartString(primType)}, ${dartString(valuePath)});`,
-      `  _nmsUsdaRel(out, 3, 'nomos:field', ${dartString(fieldPath)});`,
-      `  _nmsUsdaLine(out, 3, 'custom uniform string[] nomos:keyPath = [' + _nmsUsdaQuote(${dartString(parameter.authoredPath)}) + ']');`,
-      `  _nmsUsdaLine(out, 3, 'custom uniform ${declaredType} nomos:value = ' + ${expression});`,
-      `  _nmsUsdaClose(out, 2);`,
-    );
-  }
-  lines.push(
-    `  _nmsUsdaClose(out, 1);`,
-    `  _nmsUsdaClose(out, 0);`,
-    `  return NmsInternalGeneratedQueries.create(`,
-    `    domain: ${dartString(domain)},`,
-    `    query: ${dartString(queryId)},`,
-    `    canonicalArgumentsUsda: Uint8List.fromList(utf8.encode('\${out.join('\\n')}\\n')),`,
-    `  );`,
-    `}`,
-    ``,
-  );
-  return {
-    functionName,
-    call: `${functionName}(${parameters.map((parameter) => parameter.value).join(", ")})`,
-    source: lines,
-  };
-}
-
-export function emitTsQueryUsdaEncoder(
-  graph: LawGraph,
-  paths: ReadonlyMap<string, string>,
-  domain: string,
-  queryId: string,
-  parameters: readonly TsQueryUsdaParameter[],
-): TsQueryUsdaEncoder {
-  const query = graph.nodes.find(
-    (node): node is LawQueryReadNode =>
-      node.kind === "read" && node.readKind === "query" && node.entity.label === queryId,
-  );
-  if (query === undefined) throw new Error(`query USDA codegen: domain '${domain}' has no law query '${queryId}'`);
-  const queryPath = paths.get(query.entity.id);
-  if (queryPath === undefined) throw new Error(`query USDA codegen: '${domain}/${queryId}' has no rendered law path`);
-  if (query.key.length !== parameters.length) {
-    throw new Error(`query USDA codegen: '${domain}/${queryId}' key/parameter length differs`);
-  }
-  const functionName = `_nmsQueryUsda_${symbol(domain)}_${symbol(queryId)}`;
-  const lines = [
-    `function ${functionName}(${parameters.map((parameter) => `${parameter.name}: ${parameter.type}`).join(", ")}): NmsGeneratedQuery<${JSON.stringify(domain)}, ${JSON.stringify(queryId)}> {`,
-    `  const out: string[] = [`,
-    `    "#usda 1.0",`,
-    `    "(",`,
-    `    '    defaultPrim = "Query"',`,
-    `    ")",`,
-    `    "",`,
-    `    'def NomosQuery "Query"',`,
-    `    "{",`,
-    `    "    custom rel nomos:query = <${queryPath}>",`,
-    `    "",`,
-    `    '    def NomosQueryArguments "Arguments"',`,
-    `    "    {",`,
-    `  ];`,
-  ];
-  for (let index = 0; index < parameters.length; index++) {
-    const parameter = parameters[index]!;
-    const key = query.key[index]!;
-    if (key.authoredPath !== parameter.authoredPath) {
-      throw new Error(`query USDA codegen: '${domain}/${queryId}' key ${index} identity differs`);
-    }
-    const fieldPath = paths.get(key.field.id);
-    if (fieldPath === undefined) throw new Error(`query USDA codegen: '${domain}/${queryId}.${parameter.authoredPath}' has no field path`);
-    const valuePath = `/Query/Arguments/${pathLeaf(fieldPath)}`;
-    const [primType, declaredType, expression] = (() => {
-      switch (parameter.kind) {
-        case "string": return ["NomosStringValue", "string", `_nmsUsdaQuote(${parameter.name})`] as const;
-        case "reference": return ["NomosReferenceValue", "string", `_nmsUsdaQuote(${parameter.name})`] as const;
-        case "token": return ["NomosTokenValue", "token", `_nmsUsdaQuote(${parameter.name})`] as const;
-        case "integer": return ["NomosIntValue", "int64", `_nmsUsdaInt(${parameter.name})`] as const;
-        case "boolean": return ["NomosBoolValue", "bool", `${parameter.name} ? "true" : "false"`] as const;
-      }
-    })();
-    lines.push(
-      `  _nmsUsdaBegin(out, 2, ${JSON.stringify(primType)}, ${JSON.stringify(valuePath)});`,
-      `  _nmsUsdaRel(out, 3, "nomos:field", ${JSON.stringify(fieldPath)});`,
-      `  _nmsUsdaLine(out, 3, "custom uniform string[] nomos:keyPath = [" + _nmsUsdaQuote(${JSON.stringify(parameter.authoredPath)}) + "]");`,
-      `  _nmsUsdaLine(out, 3, "custom uniform ${declaredType} nomos:value = " + ${expression});`,
-      `  _nmsUsdaClose(out, 2);`,
-    );
-  }
-  lines.push(
-    `  _nmsUsdaClose(out, 1);`,
-    `  _nmsUsdaClose(out, 0);`,
-    `  return _nmsGeneratedQuery(${JSON.stringify(domain)}, ${JSON.stringify(queryId)}, _nmsUsdaUtf8(out.join("\\n") + "\\n"));`,
-    `}`,
-    ``,
-  );
-  return {
-    functionName,
-    call: `${functionName}(${parameters.map((parameter) => parameter.value).join(", ")})`,
-    source: lines,
-  };
-}

package/src/compat_manifest.ts

@@ -1,26 +0,0 @@
-// The CLIENT/LAW COMPATIBILITY MANIFEST (architecture/shape_compatibility.md).
-//
-// A DIAGNOSIS surface, NEVER a gate. Clients fit workspaces by STRUCTURAL INTERFACE
-// (stable-id subtyping, #72), not by law-hash pin — the hash pin was a bug we removed.
-// This block is baked into the generated TS + Dart clients and mirrored into the deploy
-// JSON so a connect() can classify: lawHash-equal (silent) vs lawHash-differs-shape-compat
-// (proceed, log) vs structurally-incompatible (warn). It is FRONTEND-ONLY — emitted like
-// the dart codegen hints, it does NOT enter the USD IR / package bytes / domainHash.
-export interface NomosCompat {
-  /** The package name (`cfg.name`). */
-  readonly packageName: string;
-  /** The deploy domainHash — the composed typed USDA closure identity. */
-  readonly lawHash: string;
-  /** sha256 over the CANONICAL serialization of the package structural interface. */
-  readonly interfaceHash: string;
-  /** Per domain key → its canonical typed USDA layer identity. */
-  readonly domains: Record<string, { readonly identityHash?: string }>;
-  /** The generator provenance — the `@githolon/dsl` version + this manifest's schema. */
-  readonly generator: { readonly dsl: string; readonly schema: number };
-  /** Standard OSGi Contract Namespace requirements derived from the law shape. */
-  readonly kernelContracts: readonly {
-    readonly namespace: "osgi.contract";
-    readonly name: string;
-    readonly version: string;
-  }[];
-}

package/src/compat_package_main.ts

@@ -1,224 +0,0 @@
-// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
-// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
-// wasm32-wasip1 artifact.  If a file isn't this / hosting this / authoring for this / proving this — it's gone.
-
-/**
- * `githolon compat <target> [--config …] [--domain …] [--json]` — THE CI GATE (task #31, the compat superpower).
- *
- * Compares the CURRENT generated client's carried structural REQUIREMENT against a TARGET's
- * installed law (the workspace OFFER), PER MEMBER, via the #72
- * subtype relation (`memberVerdicts`). Exits NON-ZERO on any incompatible member — so a client/law
- * mismatch is caught in CI, before it ships. The target is:
- *   • a generated `.client.mjs` (or a build/package DIR containing one);
- *   • a LIVE workspace URL (`https://host/v2/workspaces/<ws>` or `https://host --workspace <ws>`) —
- *     connect()s and reads the on-ledger offer (`holon.interfaceOffer()`).
- *
- * Human report by default; `--json` emits the machine surface (the per-member array + verdict).
- */
-import { existsSync, readdirSync, statSync } from "node:fs";
-import path from "node:path";
-
-import { memberVerdicts, type DomainInterface, type MemberVerdict } from "./shape_compat.js";
-
-interface PackageConfig {
-  name: string;
-}
-type InterfaceMap = Record<string, DomainInterface>;
-
-function fail(msg: string): never {
-  console.error(`githolon compat: ${msg}`);
-  process.exit(2);
-}
-
-/** Merge a per-domain interface map into ONE flat interface (directives + aggregates unioned). */
-function mergeInterfaces(byDomain: InterfaceMap | undefined): DomainInterface {
-  const out: DomainInterface = { v: 1, domain: "*", directives: {}, aggregates: {} };
-  for (const di of Object.values(byDomain ?? {})) {
-    if (!di || typeof di !== "object") continue;
-    Object.assign(out.directives, di.directives ?? {});
-    Object.assign(out.aggregates, di.aggregates ?? {});
-  }
-  return out;
-}
-
-/** The package name from `nomos.project.ts` (only field we need — to locate its generated client). */
-async function loadPackageName(configArg: string): Promise<{ name: string; dir: string }> {
-  const configPath = path.resolve(process.cwd(), configArg);
-  if (!existsSync(configPath)) fail(`config not found: ${configPath} (pass the package config, or run from the package dir)`);
-  const { pathToFileURL } = await import("node:url");
-  const cfg = ((await import(`${pathToFileURL(configPath).href}?t=${Date.now()}`)) as { default?: PackageConfig }).default;
-  if (!cfg || typeof cfg.name !== "string") fail(`config must default-export { name, … }`);
-  return { name: cfg.name, dir: path.dirname(configPath) };
-}
-
-const GENERATED_INTERFACE = Symbol.for("nomos.generated-interface");
-
-async function loadClientRequirement(file: string): Promise<InterfaceMap> {
-  const { pathToFileURL } = await import("node:url");
-  let generated: Record<string, unknown>;
-  try {
-    generated = await import(`${pathToFileURL(file).href}?compat=${Date.now()}`) as Record<string, unknown>;
-  } catch (error) {
-    fail(`could not load generated client ${file}: ${(error as Error).message}`);
-  }
-  for (const value of Object.values(generated)) {
-    if (typeof value !== "function") continue;
-    const requirement = (value as unknown as Record<PropertyKey, unknown>)[GENERATED_INTERFACE];
-    if (requirement !== null && typeof requirement === "object") return requirement as InterfaceMap;
-  }
-  fail(`generated client ${file} carries no Nomos structural requirement; recompile it with the current @githolon/dsl`);
-}
-
-/** The CURRENT requirement carried by the generated client that will ship. */
-async function loadCurrentInterface(pkgDir: string, name: string): Promise<InterfaceMap> {
-  const p = path.join(pkgDir, "build", `${name}.client.mjs`);
-  if (!existsSync(p)) {
-    fail(
-      `no current generated client at ${p} — run \`githolon compile\` first.`,
-    );
-  }
-  return loadClientRequirement(p);
-}
-
-/** Read a TARGET requirement from the generated client it will ship. */
-async function loadFileOffer(arg: string): Promise<{ offer: InterfaceMap; source: string }> {
-  const abs = path.resolve(process.cwd(), arg);
-  if (!existsSync(abs)) fail(`target not found: ${abs}`);
-  let file = abs;
-  if (statSync(abs).isDirectory()) {
-    const scan = (d: string): string | undefined => {
-      if (!existsSync(d)) return undefined;
-      const hit = readdirSync(d).find((f) => f.endsWith(".client.mjs"));
-      return hit !== undefined ? path.join(d, hit) : undefined;
-    };
-    const found = scan(abs) ?? scan(path.join(abs, "build"));
-    if (found === undefined) fail(`no *.client.mjs under ${abs}`);
-    file = found;
-  }
-  return { offer: await loadClientRequirement(file), source: file };
-}
-
-/** Read a LIVE workspace's on-ledger offer through the compiler-private runtime bundled with the DSL. */
-/**
- * Parse a live compat target URL into its cloud BASE and workspace. The base is everything BEFORE
- * `/v2/workspaces/` — NOT just the origin — so a gateway mounted under a PATH PREFIX
- * (`https://host/nomos/cloud/v2/workspaces/<ws>`) keeps that prefix. Otherwise the client would fetch the
- * runtime at the wrong base (`https://host/v1/runtime/holon.wasm` 404s instead of
- * `https://host/nomos/cloud/v1/runtime/holon.wasm`). Split on the marker so an arbitrary-depth prefix
- * survives; without the marker the whole URL (a `--workspace`-paired base) is the cloud.
- */
-export function parseLiveTarget(
-  url: string,
-  workspaceFlag?: string,
-): { cloud: string; workspace: string | undefined } {
-  const marker = "/v2/workspaces/";
-  const at = url.indexOf(marker);
-  const cloud = (at >= 0 ? url.slice(0, at) : url.replace(/[?#].*$/, "")).replace(/\/+$/, "");
-  const wsFromUrl = at >= 0 ? url.slice(at + marker.length).split(/[/?#]/)[0] : undefined;
-  const workspace = workspaceFlag ?? (wsFromUrl !== undefined && wsFromUrl !== "" ? wsFromUrl : undefined);
-  return { cloud, workspace };
-}
-
-async function loadLiveOffer(url: string, workspaceFlag?: string): Promise<{ offer: InterfaceMap; source: string }> {
-  if (!/^https?:\/\//.test(url)) fail(`could not parse the live target URL: ${url}`);
-  const { cloud, workspace } = parseLiveTarget(url, workspaceFlag);
-  if (!workspace) fail(`live target needs a workspace — use https://host/v2/workspaces/<ws> or add --workspace <ws>`);
-  let read: (cloud: string, workspace: string) => Promise<Record<string, unknown> | null>;
-  try {
-    const dynamicImport = Function("specifier", "return import(specifier)") as (specifier: string) => Promise<unknown>;
-    const runtime = await dynamicImport(new URL("../runtime/generated-application-host.js", import.meta.url).href) as {
-      nomosInternalReadWorkspaceInterface?: typeof read;
-    };
-    if (typeof runtime.nomosInternalReadWorkspaceInterface !== "function") throw new Error("operator reader absent");
-    read = runtime.nomosInternalReadWorkspaceInterface;
-  } catch {
-    fail(`live target inspection is missing from this @githolon/dsl installation; reinstall the current release`);
-  }
-  const offer = await read(cloud, workspace) as InterfaceMap | null;
-  if (offer === null) fail(`workspace '${workspace}' exposes no on-ledger structural interface (pre-#72e law)`);
-  return { offer, source: `${cloud}/v2/workspaces/${workspace}` };
-}
-
-interface MemberReport {
-  member: string;
-  kind: "directive" | "aggregate";
-  ok: boolean;
-  reason?: string;
-}
-
-async function main(): Promise<void> {
-  const argv = process.argv.slice(2);
-  const flagVal = (name: string): string | undefined => {
-    const i = argv.indexOf(name);
-    if (i >= 0) return argv[i + 1];
-    const inline = argv.find((a) => a.startsWith(`${name}=`));
-    return inline?.slice(name.length + 1);
-  };
-  const asJson = argv.includes("--json");
-  const configArg = flagVal("--config") ?? "nomos.project.ts";
-  const workspaceFlag = flagVal("--workspace");
-  const domainFlag = flagVal("--domain");
-  // The positional target = the first non-flag arg that isn't a flag VALUE.
-  const flagsWithVals = new Set(["--config", "--workspace", "--domain"]);
-  const target = argv.find((a, i) => !a.startsWith("--") && !(i > 0 && flagsWithVals.has(argv[i - 1]!)));
-  if (!target) fail(`usage: githolon compat <workspace-url | client.mjs | dir> [--config <cfg>] [--workspace <ws>] [--domain <name,...>] [--json]`);
-
-  const { name, dir } = await loadPackageName(configArg);
-  const allCurrent = await loadCurrentInterface(dir, name);
-  const requestedDomains = domainFlag?.split(",").map((domain) => domain.trim()).filter(Boolean) ?? [];
-  for (const domain of requestedDomains) {
-    if (allCurrent[domain] === undefined) fail(`current package '${name}' has no domain '${domain}'`);
-  }
-  const current = requestedDomains.length === 0
-    ? allCurrent
-    : Object.fromEntries(requestedDomains.map((domain) => [domain, allCurrent[domain]!]));
-
-  const { offer, source } = /^https?:\/\//.test(target)
-    ? await loadLiveOffer(target, workspaceFlag)
-    : await loadFileOffer(target);
-
-  // The subtype check is PER MEMBER over the merged interfaces (directives keyed by id, aggregates by label).
-  const verdicts = memberVerdicts(mergeInterfaces(current), mergeInterfaces(offer));
-  // Tag each member's kind for the report (a directive id vs an aggregate label).
-  const merged = mergeInterfaces(current);
-  const dirIds = new Set(Object.keys(merged.directives));
-  const reports: MemberReport[] = Object.entries(verdicts)
-    .map(([member, v]: [string, MemberVerdict]) => ({
-      member,
-      kind: (dirIds.has(member) ? "directive" : "aggregate") as MemberReport["kind"],
-      ok: v.ok,
-      ...(v.reason !== undefined ? { reason: v.reason } : {}),
-    }))
-    .sort((a, b) => (a.member < b.member ? -1 : a.member > b.member ? 1 : 0));
-
-  const incompatible = reports.filter((r) => !r.ok);
-  const verdict = incompatible.length > 0 ? "incompatible" : "compatible";
-
-  if (asJson) {
-    process.stdout.write(JSON.stringify({ package: name, target: source, verdict, members: reports }) + "\n");
-    process.exit(incompatible.length > 0 ? 1 : 0);
-  }
-
-  console.log(`githolon compat: package '${name}' vs ${source}`);
-  console.log(`  ${reports.length} member(s) checked — ${verdict.toUpperCase()}`);
-  for (const r of reports) {
-    const mark = r.ok ? "  ✓ " : "  ✗ ";
-    console.log(`${mark}${r.kind} '${r.member}'${r.ok ? "" : ` — ${r.reason}`}`);
-  }
-  if (incompatible.length > 0) {
-    console.log(
-      `\ngitholon compat: ${incompatible.length} incompatible member(s) — this client cannot ship against that law. ` +
-        `Recompile + regenerate the client (githolon compile), or deploy a law that still exposes these members.`,
-    );
-  } else {
-    console.log(`\ngitholon compat: all members compatible — safe to ship.`);
-  }
-  process.exit(incompatible.length > 0 ? 1 : 0);
-}
-
-// Run ONLY as the entry point (the compat launcher), never on import (the test imports parseLiveTarget).
-{
-  const { pathToFileURL } = await import("node:url");
-  const entry = process.argv[1];
-  if (entry !== undefined && import.meta.url === pathToFileURL(entry).href) void main();
-}