@githolon/dsl 0.103.18 → 0.104.0

package/src/fulfilment.ts

@@ -0,0 +1,187 @@
+// 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.
+
+/**
+ * fulfilment.ts — COMPLETENESS AS LAW.
+ *
+ * ── The problem this dissolves ───────────────────────────────────────────────
+ * Real business data arrives in stages. A site is dropped as a PIN long before anyone knows its
+ * postcode; a voice note exists before its transcript; a photo before its thumbnail. Modelled
+ * naively, the fields those later stages fill are either
+ *
+ *   • REQUIRED — and then the early write is REFUSED, so the app fabricates placeholders to get
+ *     past the gate (`city: ''`), which is how empty strings and `'Unknown City'` end up
+ *     permanently in a ledger; or
+ *   • OPTIONAL — and then nothing ever guarantees they arrive, "is this complete?" becomes a
+ *     null-check scattered through the UI, and no two screens agree on the answer.
+ *
+ * Both are the same mistake: completeness is a FACT ABOUT THE RECORD, and facts belong in law.
+ *
+ * ── The model ────────────────────────────────────────────────────────────────
+ * A tenant declares TIERS of completeness in ascending order. Each tier names the fields it
+ * GUARANTEES, and optionally the capability that gets a record from the tier below it to here:
+ *
+ * ```ts
+ * export const locationFulfilment = fulfilment("locationFulfilment", {
+ *   pinned:   { guarantees: ["location.geoPoint"] },
+ *   resolved: { guarantees: ["location.postalAddress"], fulfilledBy: reverseGeocode },
+ * });
+ *
+ * export const EstateSite = aggregate("EstateSite", { … }, { fulfils: locationFulfilment });
+ * ```
+ *
+ * The dev has said only business things. What follows is derived:
+ *
+ *   • a tier FIELD (law-state — "how complete is this" is recorded, never inferred from which
+ *     fields happen to be null),
+ *   • a TIER-SCOPED invariant: at tier T, the guarantees of T *and every tier below it* must
+ *     hold — so a pin-only site is fully LEGAL at `pinned` rather than a refusal to work around,
+ *     while a record CLAIMING `resolved` without an address is a typed refusal,
+ *   • a terminal BLOCKED state, so "no address exists here" is distinguishable from "still
+ *     resolving" (the ambiguity that makes progress indicators lie).
+ *
+ * This inverts the failure mode. Missing data used to mean THE WRITE IS REFUSED; now it means a
+ * lower tier, and refusal is reserved for data that is genuinely WRONG — a record asserting a
+ * completeness it does not have.
+ *
+ * ── MONOTONIC (Jack's ruling) ────────────────────────────────────────────────
+ * Tiers only ever climb. If a resolved address is later invalidated that is a NEW FACT (a
+ * correction), not a demotion: the tier is a durable claim about what was once established, so
+ * "was this ever resolved?" stays answerable and the value cannot flap under concurrent merges.
+ * The invariant enforces the claim, and monotonicity is what makes the claim worth having.
+ */
+import type { AggregateInvariantVerdict } from "./aggregate.js";
+
+/** The reserved suffix for the sibling field carrying a terminal blocked REASON. */
+export const FULFILMENT_BLOCKED_SUFFIX = "Blocked";
+
+/** One tier: what it guarantees, and (optionally) what fulfils the climb into it. */
+export interface FulfilmentTierSpec {
+  /**
+   * Field paths this tier guarantees are PRESENT. Dotted paths address value-object subfields
+   * (`"location.postalAddress"`). Cumulative: a tier's guarantees include every lower tier's.
+   */
+  readonly guarantees: readonly string[];
+  /**
+   * The capability that promotes a record INTO this tier. Declaring it is what makes the climb
+   * automatic; omitting it means the tier is reached by ordinary business writes.
+   *
+   * Typed loosely on purpose — this module must not import the capability framework (it would
+   * make every aggregate declaration drag the capability surface). The compiler resolves the
+   * declaration by name.
+   */
+  readonly fulfilledBy?: { readonly name: string };
+}
+
+export interface FulfilmentDecl<Name extends string = string> {
+  readonly __isFulfilmentDecl: true;
+  /** The tier FIELD's name on the aggregate, and the declaration's own id. */
+  readonly name: Name;
+  /** Tier names in ASCENDING order of completeness — declaration order IS the order. */
+  readonly tiers: readonly string[];
+  readonly spec: Readonly<Record<string, FulfilmentTierSpec>>;
+  /** The sibling field carrying a terminal blocked reason. */
+  readonly blockedField: string;
+  /** Every guarantee at `tier` INCLUDING the tiers below it (the cumulative claim). */
+  guaranteesAt(tier: string): readonly string[];
+  /** The invariant the aggregate composes — pure, snapshot-in/verdict-out. */
+  invariant(snapshot: Record<string, unknown>): AggregateInvariantVerdict;
+}
+
+const NAME_RE = /^[a-zA-Z][a-zA-Z0-9_]*$/;
+
+/** Read a dotted path out of a folded snapshot; `undefined` when any hop is absent. */
+function readPath(snapshot: Record<string, unknown>, path: string): unknown {
+  let cursor: unknown = snapshot;
+  for (const hop of path.split(".")) {
+    if (cursor === null || cursor === undefined || typeof cursor !== "object") return undefined;
+    cursor = (cursor as Record<string, unknown>)[hop];
+  }
+  return cursor;
+}
+
+/**
+ * Declare completeness tiers. Refusals are COMPILE-TIME loud (thrown at module load so
+ * `nomos-compile` names them): tiers must be a non-empty, well-named, ascending set, and a tier
+ * must actually guarantee something or it is not a tier.
+ */
+export function fulfilment<const Name extends string>(
+  name: Name,
+  spec: Record<string, FulfilmentTierSpec>,
+): FulfilmentDecl<Name> {
+  if (!NAME_RE.test(name)) {
+    throw new Error(
+      `fulfilment('${name}'): the name must match ${NAME_RE} — it becomes a FIELD on every aggregate that declares it`,
+    );
+  }
+  const tiers = Object.keys(spec);
+  if (tiers.length === 0) {
+    throw new Error(`fulfilment('${name}'): declare at least one tier (a fulfilment with no tiers claims nothing)`);
+  }
+  for (const tier of tiers) {
+    if (!NAME_RE.test(tier)) {
+      throw new Error(`fulfilment('${name}'): tier '${tier}' must match ${NAME_RE}`);
+    }
+    if (spec[tier]!.guarantees.length === 0) {
+      throw new Error(
+        `fulfilment('${name}'): tier '${tier}' guarantees nothing — a tier exists to make a claim about the record; drop it or give it a guarantee`,
+      );
+    }
+  }
+  const blockedField = `${name}${FULFILMENT_BLOCKED_SUFFIX}`;
+
+  const guaranteesAt = (tier: string): readonly string[] => {
+    const index = tiers.indexOf(tier);
+    if (index < 0) return [];
+    // CUMULATIVE: tiers are ascending, so reaching one asserts every claim beneath it too.
+    return tiers.slice(0, index + 1).flatMap((t) => spec[t]!.guarantees);
+  };
+
+  return {
+    __isFulfilmentDecl: true,
+    name,
+    tiers,
+    spec,
+    blockedField,
+    guaranteesAt,
+    invariant(snapshot) {
+      const raw = snapshot[name];
+      // Absent tier ⇒ nothing claimed yet. A record is free to exist below the first tier; it
+      // simply guarantees nothing, which is honest.
+      if (raw === undefined || raw === null || raw === "") return { accept: true };
+      const tier = String(raw);
+      if (!tiers.includes(tier)) {
+        return {
+          reject: `${name} is '${tier}', which is not a declared tier (${tiers.join(" < ")})`,
+        };
+      }
+      // A record parked as terminally unfulfillable keeps whatever it had established; the
+      // point of the blocked state is that it stops CLAIMING more, not that it loses ground.
+      const blocked = snapshot[blockedField];
+      const isBlocked = typeof blocked === "string" && blocked.trim() !== "";
+      for (const path of guaranteesAt(tier)) {
+        const value = readPath(snapshot, path);
+        if (value === undefined || value === null || value === "") {
+          if (isBlocked) continue;
+          return {
+            reject: `${name} claims tier '${tier}' but '${path}' is absent — a tier is a guarantee about the record, so either fill it, drop to a lower tier, or record ${blockedField} to say it can never be filled`,
+          };
+        }
+      }
+      return { accept: true };
+    },
+  };
+}
+
+/** Duck-type guard (the exports walk discovers declarations by shape, never by import). */
+export function isFulfilmentDecl(v: unknown): v is FulfilmentDecl {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    (v as { __isFulfilmentDecl?: boolean }).__isFulfilmentDecl === true
+  );
+}

package/src/index.ts

@@ -226,6 +226,14 @@ export {
 // surface). The dev never sees a "prim" — that is the GitHolon's internal OpenUSD IR.
 export { create, existing, ensure, type AggregateRef } from "./authoring.js";
 export { recordContract, isContractHandle, satisfiesContract, type ContractHandle, type ContractField, type ContractSatisfaction } from "./contract.js";
+// COMPLETENESS AS LAW — tiered fulfilment (`fulfilment.ts`).
+export {
+  fulfilment,
+  isFulfilmentDecl,
+  FULFILMENT_BLOCKED_SUFFIX,
+  type FulfilmentDecl,
+  type FulfilmentTierSpec,
+} from "./fulfilment.js";
 export { normalizeActivity, renderActivityTemplate, activityKey, type ActivityInput, type ActivityDescriptor, type ActivityRefInput, type ActivitySeverity } from "./activity.js";
 // The REBIRTH-boundary repair DSL (architecture/repair_dsl.md) — distinct from framework/repair.js (the
 // IN-CHAIN compensating-intent lane): repair() binds a typed replay refusal to a declared re-fold remedy.

package/src/law_graph_usda.ts

@@ -572,6 +572,11 @@ export function emitSparseLawGraphUsda(
     `        def Scope "${domain.entity.id}"`,
     "        {",
     ...entityLabelOpinions(domain.entity, 12),
+    // THE FIELD-PROVENANCE ERA KEY (field_evolution_read_path.md): declared by every
+    // bundle this compiler emits. Only under a declaring bundle does the kernel fold
+    // stamp Field.schema; chains sealed under pre-key law replay byte-identically
+    // forever (the era rule — the law is the era).
+    "            custom uniform bool nomos:fieldProvenance = true",
   ];
   if (domain.parentAttestedBirth !== undefined) {
     lines.push(