@githolon/dsl 0.108.6 → 0.110.0

package/src/shape_compat.ts

@@ -1,352 +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.
-//
-// SHAPE COMPATIBILITY (#72) — the structural contract a client and a workspace
-// negotiate by, INSTEAD of the package hash. See architecture/shape_compatibility.md.
-//
-// A client fits a workspace iff the workspace's installed interface SUBTYPES what the
-// client depends on:
-//   • WRITES are CONTRAVARIANT — for every directive the client calls, the workspace
-//     has that directive id and its CURRENT payload schema ACCEPTS the client's
-//     payload: every field the workspace REQUIRES the client always sends, and every
-//     shared field's kind matches. (Extra client fields are ignored — non-strict zod.)
-//   • READS are COVARIANT by STABLE ID (#58) — for every aggregate the client reads,
-//     the workspace has that aggregate SID and every field the client CONSUMES (by
-//     field sid) is present with a compatible kind. The workspace may serve MORE.
-//
-// Identity is by stable id, not name or hash — that is what makes the relation
-// decidable across renames (a renamed aggregate field keeps its sid, so an old client
-// stays read-compatible). Directive/payload identity is the dispatched id + field
-// names (directives are not sid-tracked yet — a payload rename IS a write break, and
-// is reported precisely).
-
-import { z } from "zod";
-import type { DomainModule } from "./codegen_dart.js";
-import { lowerLawValueType, type LawValueType } from "./law_value_type.js";
-import type { StableIds } from "./stable_ids_types.js";
-import type { Field } from "./fields.js";
-import { isBusinessIntent } from "./intent.js";
-
-/** One payload field's normalized shape: its kind + whether the schema makes it optional. */
-export interface PayloadFieldShape {
-  readonly kind: string;
-  readonly optional: boolean;
-}
-/** A directive's payload contract — the field set + types the gate validates against. */
-export interface DirectivePayloadShape {
-  readonly fields: Record<string, PayloadFieldShape>;
-}
-/** An aggregate's read contract — fields keyed by STABLE ID (rename-safe), each carrying
- *  its current label (for human-readable verdicts) + its read kind. */
-export interface AggregateReadShape {
-  readonly sid: string;
-  readonly label: string;
-  /** keyed by FIELD SID. */
-  readonly fields: Record<string, { kind: string; label: string }>;
-}
-/** A domain's full structural interface — the offer (a workspace's installed law) AND
- *  the requirement (the law a client was generated from) are the SAME vocabulary. */
-export interface DomainInterface {
-  readonly v: 1;
-  readonly domain: string;
-  readonly domainSid?: string;
-  /** keyed by DIRECTIVE ID (the dispatched name). */
-  readonly directives: Record<string, DirectivePayloadShape>;
-  /** keyed by AGGREGATE SID. */
-  readonly aggregates: Record<string, AggregateReadShape>;
-  /** ATTESTED READS (slice B + dynamic policies): directive id → its declared foreign-read edges —
-   *  a STATIC `{queryId, from}` edge or a dynamic `{queryId, policy, fromPayload}` edge — the
-   *  cross-workspace dependencies this law consumes on its write path. OMITTED when none (era rule). */
-  readonly foreignReads?: Record<
-    string,
-    { queryId: string; from?: string; policy?: string; fromPayload?: string }[]
-  >;
-}
-
-/** Remove framework-managed aggregate fields from the client-facing structural interface. Stable ids for
- *  those fields remain in the law/lockfile; clients negotiate only the business shape they can see. */
-export function publicClientInterface(
-  modules: readonly DomainModule[],
-  offered: Readonly<Record<string, DomainInterface>>,
-): Record<string, DomainInterface> {
-  const hidden = new Map<string, Map<string, Set<string>>>();
-  for (const mod of modules) {
-    const domain = mod.domain ?? mod.name;
-    const byAggregate = hidden.get(domain) ?? new Map<string, Set<string>>();
-    hidden.set(domain, byAggregate);
-    for (const aggregate of mod.aggregates ?? []) {
-      const fields = (aggregate as { internalFields?: readonly string[] }).internalFields ?? [];
-      if (fields.length > 0) byAggregate.set(aggregate.id, new Set(fields));
-    }
-  }
-  const result: Record<string, DomainInterface> = {};
-  for (const [domain, value] of Object.entries(offered)) {
-    const byAggregate = hidden.get(domain);
-    if (byAggregate === undefined || byAggregate.size === 0) {
-      result[domain] = value;
-      continue;
-    }
-    const aggregates: Record<string, AggregateReadShape> = {};
-    for (const [sid, aggregate] of Object.entries(value.aggregates)) {
-      const fields = byAggregate.get(aggregate.label);
-      aggregates[sid] = fields === undefined
-        ? aggregate
-        : {
-            ...aggregate,
-            fields: Object.fromEntries(
-              Object.entries(aggregate.fields).filter(([, field]) => !fields.has(field.label)),
-            ),
-          };
-    }
-    result[domain] = { ...value, aggregates };
-  }
-  return result;
-}
-
-/** The verdict: compatible iff nothing is missing and nothing is type-incompatible.
- *  `missing` = a depended-on directive/aggregate/field the workspace doesn't expose;
- *  `incompatible` = present but type-divergent (a payload field kind, a retyped read field). */
-export interface CompatVerdict {
-  readonly ok: boolean;
-  readonly missing: string[];
-  readonly incompatible: string[];
-}
-
-/** Normalize the canonical language-neutral DSL value graph to the compatibility
- * vocabulary. Language generators are projections of this graph, never authorities
- * for it. */
-function payloadFieldKind(value: LawValueType): string {
-  switch (value.kind) {
-    case "enum":
-      return "enum";
-    case "string":
-      return "string";
-    case "integer":
-      return "int";
-    case "number":
-      return "double";
-    case "boolean":
-      return "bool";
-    case "literal":
-      return typeof value.value === "boolean"
-        ? "bool"
-        : typeof value.value === "number"
-          ? Number.isInteger(value.value) ? "int" : "double"
-          : typeof value.value === "string" ? "string" : "json";
-    case "list":
-      return value.element.kind === "string" ? "set" : "json";
-    case "nullable":
-    case "default":
-    case "recursive":
-      return payloadFieldKind(value.value);
-    case "map":
-    case "record":
-    case "sum":
-    case "null":
-    case "unknown":
-    case "recursive-ref":
-      return "json";
-  }
-}
-
-/** The aggregate read kind when no stable-id kind is recorded (pre-#58 fallback): the
- *  field's own declared kind, with the read-collapsed CRDTs normalized to their scalar. */
-function aggFieldReadKind(f: Field): string {
-  switch (f.kind) {
-    case "counter":
-      return "int";
-    case "position":
-      return "string";
-    default:
-      return f.kind;
-  }
-}
-
-/** Extract a domain's structural interface from its loaded module + (optionally) its
- *  stable-id surface. Without stable ids (pre-#58) aggregate fields key by NAME and the
- *  kind comes from the field declaration — a graceful, rename-unaware fallback. */
-export function domainInterface(mod: DomainModule, stableIds?: StableIds): DomainInterface {
-  const isInternal = (value: unknown): boolean =>
-    !!value &&
-    typeof value === "object" &&
-    (value as { businessBirthInternal?: unknown }).businessBirthInternal === true;
-  const enumTypes = new Map<string, string>();
-  // DETERMINISTIC KEY ORDER — directive ids, aggregate sids, and field keys are SORTED, so the
-  // emitted interface is byte-stable and the layered-USD fold (which merges + sorts) reproduces it
-  // byte-identically (the `nomosStableIds`/`nomosReadGate` convention). architecture/shape_compatibility.md.
-  const sortedRec = <T>(entries: Array<[string, T]>): Record<string, T> => {
-    const out: Record<string, T> = {};
-    for (const [k, v] of entries.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))) out[k] = v;
-    return out;
-  };
-  const directives: Record<string, DirectivePayloadShape> = {};
-  const dirEntries: Array<[string, DirectivePayloadShape]> = [];
-  for (const d of (mod.directives ?? []) as Array<{
-    id?: unknown;
-    payloadSchema?: unknown;
-    businessBirth?: { publicPayloadSchema?: unknown };
-  }>) {
-    if (!d || typeof d.id !== "string") continue;
-    if (isInternal(d)) continue;
-    const fieldEntries: Array<[string, PayloadFieldShape]> = [];
-    const schema = d.businessBirth?.publicPayloadSchema ?? d.payloadSchema;
-    if (schema && typeof schema === "object") {
-      const payload = lowerLawValueType(schema as z.ZodTypeAny);
-      if (payload.kind !== "record") {
-        throw new Error(`directive '${d.id}' payload must lower to a typed record`);
-      }
-      for (const field of payload.fields) {
-        fieldEntries.push([field.name, { kind: payloadFieldKind(field.value), optional: !field.required }]);
-      }
-    }
-    dirEntries.push([
-      d.businessBirth === undefined || isBusinessIntent(d) ? d.id : "birth",
-      { fields: sortedRec(fieldEntries) },
-    ]);
-  }
-  Object.assign(directives, sortedRec(dirEntries));
-  const aggregates: Record<string, AggregateReadShape> = {};
-  const aggEntries: Array<[string, AggregateReadShape]> = [];
-  for (const agg of (mod.aggregates ?? []) as Array<{
-    id: string;
-    fields: Record<string, Field>;
-  }>) {
-    if (isInternal(agg)) continue;
-    const label = agg.id;
-    const sa = stableIds?.aggregates?.[label];
-    const aggSid = sa?.sid ?? label;
-    const fieldEntries: Array<[string, { kind: string; label: string }]> = [];
-    for (const [fname, f] of Object.entries(agg.fields ?? {})) {
-      // This is the workspace's complete structural offer and the input to law-evolution
-      // checking, so framework-managed stored fields belong here too. Only the generated
-      // client's view hides them, in publicClientInterface below. Filtering them at both
-      // seams makes an unchanged private field look deleted when the current offer is
-      // compared with the committed identity ledger.
-      if (!f || f.kind === "hasMany") continue;
-      const fsid = sa?.fields?.[fname]?.sid ?? fname;
-      const kind = sa?.fields?.[fname]?.kind ?? aggFieldReadKind(f);
-      fieldEntries.push([fsid, { kind, label: fname }]);
-    }
-    aggEntries.push([aggSid, { sid: aggSid, label, fields: sortedRec(fieldEntries) }]);
-  }
-  Object.assign(aggregates, sortedRec(aggEntries));
-  // ATTESTED READS (slice B): the declared trust edges — so shape-compat + client codegen can
-  // SEE the cross-workspace dependency (typed clients don't call it; it's write-path-internal).
-  type ForeignEdge = { queryId: string; from?: string; policy?: string; fromPayload?: string };
-  const foreignReadEntries: Array<[string, ForeignEdge[]]> = [];
-  for (const d of (mod.directives ?? []) as Array<{ id?: unknown; declaredForeignReads?: ForeignEdge[] }>) {
-    if (!d || typeof d.id !== "string") continue;
-    if (isInternal(d)) continue;
-    if (d.declaredForeignReads !== undefined && d.declaredForeignReads.length > 0) {
-      foreignReadEntries.push([d.id, d.declaredForeignReads.map((e) => ({ ...e }))]);
-    }
-  }
-  const foreignReads = sortedRec(foreignReadEntries);
-  return {
-    v: 1,
-    domain: (mod as { domain?: string; name?: string }).domain ?? (mod as { name?: string }).name ?? "",
-    ...(stableIds?.domain !== undefined ? { domainSid: stableIds.domain } : {}),
-    directives,
-    aggregates,
-    ...(foreignReadEntries.length > 0 ? { foreignReads } : {}),
-  };
-}
-
-/** One member's structural verdict — `ok`, plus the exact break `reason` when not. */
-export interface MemberVerdict {
-  readonly ok: boolean;
-  readonly reason?: string;
-}
-
-/** PER-MEMBER structural verdict (#72b, the compat superpower): the SAME subtype relation as
- *  {@link compatible}, decomposed to ONE verdict per callable MEMBER — keyed by directive id
- *  (writes) AND by aggregate label (reads). A generated client method (or the CLI gate) consults
- *  its own member so a KNOWN-incompatible call refuses CLIENT-SIDE, never as a server 422. */
-export function memberVerdicts(client: DomainInterface, workspace: DomainInterface): Record<string, MemberVerdict> {
-  const out: Record<string, MemberVerdict> = {};
-
-  // WRITES — contravariant, one verdict per directive the client calls.
-  for (const [did, cShape] of Object.entries(client.directives)) {
-    const wShape = workspace.directives[did];
-    if (!wShape) { out[did] = { ok: false, reason: `directive '${did}' is not installed on the workspace` }; continue; }
-    const reasons: string[] = [];
-    for (const [f, wf] of Object.entries(wShape.fields)) {
-      if (wf.optional) continue;
-      const cf = cShape.fields[f];
-      if (!cf || cf.optional) reasons.push(`workspace requires field '${f}' the client does not always send`);
-    }
-    for (const [f, cf] of Object.entries(cShape.fields)) {
-      const wf = wShape.fields[f];
-      if (wf && wf.kind !== cf.kind) reasons.push(`field '${f}' kind ${cf.kind} ≠ workspace ${wf.kind}`);
-    }
-    out[did] = reasons.length ? { ok: false, reason: reasons.join("; ") } : { ok: true };
-  }
-
-  // READS — covariant by stable id, one verdict per aggregate the client reads (keyed by LABEL).
-  for (const [sid, cAgg] of Object.entries(client.aggregates)) {
-    const wAgg = workspace.aggregates[sid];
-    if (!wAgg) { out[cAgg.label] = { ok: false, reason: `aggregate '${cAgg.label}' is not served by the workspace` }; continue; }
-    const reasons: string[] = [];
-    for (const [fsid, cf] of Object.entries(cAgg.fields)) {
-      const wf = wAgg.fields[fsid];
-      if (!wf) reasons.push(`field '${cAgg.label}.${cf.label}' is not served`);
-      else if (wf.kind !== cf.kind) reasons.push(`field '${cAgg.label}.${cf.label}' read kind ${cf.kind} ≠ workspace ${wf.kind}`);
-    }
-    out[cAgg.label] = reasons.length ? { ok: false, reason: reasons.join("; ") } : { ok: true };
-  }
-
-  return out;
-}
-
-/** Decide whether a CLIENT interface is satisfied by a WORKSPACE interface (the offer).
- *  Pure + deterministic — the SAME relation runs at connect() and (mirrored) at the
- *  editor/CI. Names the exact directive / aggregate / field at fault, never a hash. */
-export function compatible(client: DomainInterface, workspace: DomainInterface): CompatVerdict {
-  const missing: string[] = [];
-  const incompatible: string[] = [];
-
-  // WRITES — contravariant. The workspace must accept every payload the client sends.
-  for (const [did, cShape] of Object.entries(client.directives)) {
-    const wShape = workspace.directives[did];
-    if (!wShape) {
-      missing.push(`directive '${did}'`);
-      continue;
-    }
-    // Every field the WORKSPACE requires, the client must ALWAYS send (present + required).
-    for (const [f, wf] of Object.entries(wShape.fields)) {
-      if (wf.optional) continue;
-      const cf = cShape.fields[f];
-      if (!cf || cf.optional) {
-        incompatible.push(`directive '${did}': workspace requires field '${f}' the client does not always send`);
-      }
-    }
-    // Every field both sides know must agree on kind (a payload retype is a write break).
-    for (const [f, cf] of Object.entries(cShape.fields)) {
-      const wf = wShape.fields[f];
-      if (wf && wf.kind !== cf.kind) {
-        incompatible.push(`directive '${did}': field '${f}' kind ${cf.kind} ≠ workspace ${wf.kind}`);
-      }
-    }
-  }
-
-  // READS — covariant by stable id. Every field the client consumes must be served compatibly.
-  for (const [sid, cAgg] of Object.entries(client.aggregates)) {
-    const wAgg = workspace.aggregates[sid];
-    if (!wAgg) {
-      missing.push(`aggregate '${cAgg.label}'`);
-      continue;
-    }
-    for (const [fsid, cf] of Object.entries(cAgg.fields)) {
-      const wf = wAgg.fields[fsid];
-      if (!wf) {
-        missing.push(`field '${cAgg.label}.${cf.label}'`);
-      } else if (wf.kind !== cf.kind) {
-        incompatible.push(`field '${cAgg.label}.${cf.label}': read kind ${cf.kind} ≠ workspace ${wf.kind}`);
-      }
-    }
-  }
-
-  return { ok: missing.length === 0 && incompatible.length === 0, missing, incompatible };
-}