@githolon/dsl 0.67.0 → 0.69.0

package/src/framework/workspaces.ts

@@ -283,6 +283,27 @@ export const CloudWorkspace = aggregate("CloudWorkspace", {
    * (JSON), never `t.json`: it rides verbatim as a scalar (the kernel `Value` has no JSON variant — the same
    * reasoning as the auth keys). Absent on root (the base of the world tree, born under nothing). */
   bornUnder: t.string().merge(Lww).optional(),
+  /**
+   * SUPERSESSION (recovery verb 3 — {@link rebirthWorkspace}, architecture/rebirth_and_custody_lifecycle.md).
+   * "Supersession, never forgiveness": a chain scarred by a historical LAW violation cannot be retro-blessed;
+   * the lawful remedy is a REBIRTH — a new chain re-genesised from the current law + state that self-verifies
+   * from intent 0. These three ADDITIVE, append-only lineage facts annotate THAT act on the workspace's record
+   * (the workspace NAME survives; the chain identity changes). Absent = the workspace has never been reborn.
+   * The presence of {@link CloudWorkspace.supersededAt} is the committed LAW FACT the bailiff's `/rebirth-custody`
+   * verb gates on — the law authorizes, the bailiff executes the compaction+swap. Era-safe (optional Lww, additive sids).
+   *
+   * `supersededBy` — the new incarnation's genesis oid once custody has built + self-verified it (the receipt,
+   *  authored by the same custodian via a follow-up rebirthWorkspace carrying `incarnation`); `""` until then.
+   */
+  supersededBy: t.string().merge(Lww).optional(),
+  /** WHY the chain was superseded — the custodian's mandatory justification (audit, on the ledger forever). */
+  supersessionReason: t.string().merge(Lww).optional(),
+  /** Epoch-ms the supersession was authored (caller-stamped) — its PRESENCE is the law fact custody gates on. */
+  supersededAt: t.int().merge(Lww).optional(),
+  /** LINEAGE CONTINUITY (ratified 2026-07-09): on a REBORN holon's OWN birth record — the superseded
+   *  incarnation's genesis oid. The reborn holon itself testifies to its ancestry (alongside the UNCHANGED
+   *  `parent` — a rebirth may never claim new parents; see {@link rebirthRetainsLineage}). Additive/era-safe. */
+  rebornFrom: t.string().merge(Lww).optional(),
 });
 
 // AdminGrant / CreationGrant aggregates: DELETED (full-native Zanzibar). Admin/creation authority is
@@ -489,6 +510,10 @@ export function buildGenesisChain(p: {
    * package compiled under the metered-birth DSL) — see the poolSteps note below.
    */
   descendantPool?: number;
+  /** LINEAGE CONTINUITY (rebirth genesis only): the superseded incarnation's genesis oid. Threads onto the
+   *  child's birthCloud record (`rebornFrom`) + the bornUnder commitment — the reborn holon testifies to its
+   *  ancestry while `parent` stays the SUPERSEDED record's parent (a rebirth may never reparent). */
+  rebornFrom?: string;
 }): string {
   const founder = "user:" + p.principal;
   // THE ORDER-DECLARED LAW INSTALL (G3): the child installs the EXACT law the order names — bytes are NOT in
@@ -514,6 +539,7 @@ export function buildGenesisChain(p: {
     lawHash: "",
     authorizationHash: "",
     parentHead: "",
+    ...(p.rebornFrom ? { rebornFrom: p.rebornFrom } : {}),
   });
   // METERED BIRTH (slice A3 — THE POOL CHAINS TO ROOT): when the order carries a `descendantPool`, the
   // child is BORN BOUNDED — a `seedBirthPolicy` genesis step writes the child's own BirthPolicy singleton
@@ -546,7 +572,7 @@ export function buildGenesisChain(p: {
     { domain: "workspaces", directiveId: "seedGenesis", actor: founder, payload: { principal: founder, workspaceId: p.requiresWarrant !== false ? p.name : "", bornAt: p.bornAt } },
     { domain: "workspaces", directiveId: "grantAdmin", actor: founder, payload: { keyHash: p.foundingAdminHash, label: `founding admin (born for ${p.principal})`, grantedBy: p.principal, grantedAt: p.requestedAt } },
     // No `role` — it was a vestigial node-class label (collapsed with `kind`); birthCloud ignores it now.
-    { domain: "workspaces", directiveId: "birthCloud", actor: "", payload: { principal: p.principal, name: p.name, tier: p.tier, bornAt: p.requestedAt, bornUnder } },
+    { domain: "workspaces", directiveId: "birthCloud", actor: "", payload: { principal: p.principal, name: p.name, tier: p.tier, bornAt: p.requestedAt, bornUnder, ...(p.rebornFrom ? { rebornFrom: p.rebornFrom } : {}) } },
   ]);
 }
 
@@ -708,6 +734,9 @@ export const birthCloud = directive("birthCloud")
        *  birth, recorded onto the child's self-record so its OWN chain self-attests its parentage. Absent on
        *  root (born under nothing). Authored by {@link buildGenesisChain} for a child birth. */
       bornUnder: z.string().optional(),
+      /** LINEAGE CONTINUITY: present ONLY on a REBIRTH genesis — the superseded incarnation's genesis oid.
+       *  The reborn holon's own chain testifies to its ancestry; `parent` (in bornUnder) stays UNCHANGED. */
+      rebornFrom: z.string().optional(),
     }),
   )
   .plan((p) => {
@@ -723,6 +752,9 @@ export const birthCloud = directive("birthCloud")
       .set("provisionedAt", p.bornAt);
     // The child's chain self-attests its lineage authorization (the proof-friendly binding); root omits it.
     if (p.bornUnder) rec.set("bornUnder", p.bornUnder);
+    // LINEAGE CONTINUITY: a rebirth genesis records the superseded incarnation it re-genesises (ancestry
+    // testimony in the reborn holon's OWN chain, beside the unchanged parent).
+    if (p.rebornFrom) rec.set("rebornFrom", p.rebornFrom);
     // The self-identity singleton at the CONSTANT id (ungated — birthCloud is not admin-mutating), so the
     // gate's self-record exists before any admin write. ensure() = deterministic-id sibling birth. `name` is
     // the born marker; `role` is no longer written (vestigial node-class — see WorkspaceSelf).
@@ -896,6 +928,106 @@ export const reclaimWorkspace = directive("reclaimWorkspace")
   })
   .requires("admin");
 
+/**
+ * rebirthWorkspace — LAWFUL SUPERSESSION (recovery verb 3, architecture/rebirth_and_custody_lifecycle.md +
+ * lawful_recovery.md). "Supersession, never forgiveness": where {@link certifyEra} vouches IDENTITY (heals a
+ * ForgedPrincipal/BadSignature scar) and cannot paper over a LAW violation, rebirth is the remedy for a chain
+ * scarred UNRECOVERABLY (e.g. an evolve-gate retype with no dispositions) — a NEW chain re-genesised from the
+ * current law + state that self-verifies from intent 0, with the OLD chain SUPERSEDED in lineage (annotated,
+ * kept in custody, never deleted). Mirrors reclaim's law-act/custody-act split:
+ *   • LAW ACT (this directive): the custodian records the supersession on the workspace's lineage record —
+ *     {@link CloudWorkspace.supersededAt} (its PRESENCE is the committed fact the bailiff gates on),
+ *     `supersessionReason` (mandatory), and `supersededBy` (the new incarnation oid — `""` on the first
+ *     offer, filled by a follow-up offer once custody has built + verified the incarnation).
+ *   • CUSTODY ACT: the internal `/rebirth-custody` worker verb builds the compacted incarnation, self-verifies
+ *     it through the upload-birth `verify_chain` lane (GREEN from intent 0 REQUIRED before any repoint),
+ *     births it into FRESH custody (ONE LEDGER PER REPO — a repo IS a holon; lineage forms the holarchy),
+ *     REPOINTS the workspace NAME to it, and FREEZES the old repo untouched at its own custody address —
+ *     retained whole, never rewritten (GC-later = deleting that repo wholesale).
+ *
+ * THE FIXED POINT (inherited from reclaim): the law REFUSES to rebirth ROOT — root is the seat of the very law
+ * that authorizes rebirth, so the law can re-genesise everything it governs EXCEPT itself. Enforced BY LAW here
+ * (the {@link rebirthNotRoot} invariant reads the target record's identity at the one gate on every lane), not
+ * merely by the bailiff. Gated `.requires("admin")` — the strongest control-plane authority (a custodian act).
+ */
+export const rebirthWorkspace = directive("rebirthWorkspace")
+  .mutates(CloudWorkspace)
+  .payload(
+    z.object({
+      /** The target CloudWorkspace AGGREGATE id (the minted lineage-record id; root-custody registry). */
+      workspaceId: z.string().min(1),
+      /** MANDATORY — the custodian's justification for superseding this chain (audit, on the ledger forever). */
+      reason: z.string().min(1),
+      /** Epoch-ms the supersession was authored (caller-stamped — the timestamp doctrine). Its presence on the
+       *  record is the LAW FACT the `/rebirth-custody` verb gates on. */
+      rebornAt: epochMs,
+      /** The new incarnation's genesis oid — OPTIONAL: absent/`""` on the first (decision) offer; the custodian
+       *  re-offers carrying it once custody has built + self-verified the incarnation (the receipt). */
+      incarnation: z.string().optional(),
+      /** LINEAGE CONTINUITY: the parent the new incarnation CLAIMS (carried on the receipt leg for the
+       *  audit record). When present it MUST equal the superseded record's parent — a reparenting rebirth
+       *  is a typed refusal ({@link rebirthRetainsLineage}). Absent ⇒ the parent is unchanged by definition. */
+      parent: z.string().optional(),
+    }),
+  )
+  .plan((p) => {
+    const ws = instance(CloudWorkspace, p.workspaceId);
+    return [
+      set(ws, "supersessionReason", p.reason),
+      set(ws, "supersededAt", p.rebornAt),
+      set(ws, "supersededBy", p.incarnation ?? ""),
+    ];
+  })
+  .requires("admin");
+
+/**
+ * rebirthNotRoot — THE FIXED POINT AS LAW. The one gate reads the target record's identity (its `name`) at the
+ * pre-apply position and REFUSES a rebirth of the genesis workspace `root` — the seat of the very law that
+ * authorizes rebirth (mirroring the bailiff's `ws === ROOT_WS` fixed point in `/rebirth-custody`, and reclaim's
+ * root carve-out). NOTE `parent` is NOT the test: every workspace's OWN birthCloud self-record carries
+ * `parent: ""` (lineage lives in the PARENT's registry), so `parent === ""` would reject every workspace. A
+ * record read of the target (no NEW declared query) ⇒ the read manifest is unchanged (era-/evolve-safe).
+ * Enforced on every lane (author / edge admission / verify_chain).
+ */
+export const rebirthNotRoot = workspaceInvariant("RebirthNotRoot")
+  .on("rebirthWorkspace")
+  .reads((ctx) => [
+    refAs("target", "CloudWorkspace", "pre:" + String((ctx?.intent ?? {}).workspaceId ?? "")),
+  ])
+  .assert((refs) => {
+    const target = (refs as { target?: { name?: string } }).target;
+    return target?.name === "root"
+      ? { reject: "rebirth-refuses-root: root is the seat of the authorizing law and cannot supersede itself" }
+      : { accept: true };
+  });
+
+/**
+ * rebirthRetainsLineage — LINEAGE CONTINUITY AS LAW (ratified 2026-07-09). A rebirth/incarnation of an
+ * existing workspace MUST retain its lineage: the parent the offer claims for the new incarnation must equal
+ * the SUPERSEDED record's `parent` — a reparenting rebirth is a TYPED refusal at the one gate on every lane.
+ * WHY: the holarchy must stay TOTALLY REPLAYABLE from root genesis — every birth/supersession/rebirth an
+ * ordered law fact; a reborn holon that claimed new parents would fork the lineage graph out-of-history.
+ * (The reborn holon's OWN chain additionally testifies via `rebornFrom` + the unchanged parent in bornUnder.)
+ */
+export const rebirthRetainsLineage = workspaceInvariant("RebirthRetainsLineage")
+  .on("rebirthWorkspace")
+  .reads((ctx) => [
+    refAs("target", "CloudWorkspace", "pre:" + String((ctx?.intent ?? {}).workspaceId ?? "")),
+  ])
+  .assert((refs, ctx) => {
+    const target = (refs as { target?: { parent?: string } }).target;
+    const claimed = (ctx?.intent as { parent?: string } | undefined)?.parent;
+    // No claim ⇒ the parent is untouched (the plan never writes parent) — lineage retained by construction.
+    if (claimed === undefined || claimed === "") return { accept: true };
+    return claimed === (target?.parent ?? "")
+      ? { accept: true }
+      : { reject: "rebirth-must-retain-lineage: a rebirth cannot claim new parents — the incarnation keeps the superseded record's parent" };
+  });
+
+/** supersededWorkspaces — the bailiff/CLI reads workspaces carrying a supersession fact (audit + the
+ *  `/rebirth-custody` drain's queue). Keyed on `supersededBy` is unhelpful; the flat record read via
+ *  {@link workspaceByName} suffices for the custody gate, so this stays a by-name lookup upstream. */
+
 // ─────────────────────────── BIRTH AS A NOMOS PRIMITIVE ──────────────────────────────────────────────
 // (birthPlatform is GONE — the tier collapsed onto #creator; birthChild is the one birth directive.)
 // THE RECORD IS THE OBLIGATION (architecture/githolon_host_contract.md "Birth is a capability" +

package/src/index.ts

@@ -137,6 +137,9 @@ export {
 export { create, existing, ensure, type AggregateRef } from "./authoring.js";
 export { contract, isContractHandle, satisfiesContract, type ContractHandle, type ContractField, type ContractSatisfaction } from "./contract.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.
+export { repair, repairsOf, isRepairDecl, type RepairDecl, type RepairMatcher, type RepairVerb, type RepairRefusalKind, type RetypeMapping } from "./repair.js";
 // THE CAPTURED READ — a plan reads O(1) DSL queries via `read(query, args)`; the result is committed as
 // the intent's read footprint (deterministic replay + stale-premise detection). The dev calls typed DSL
 // queries; the library routes them here. The host capability is `nomos.read` (twin of `nomos.rng`).

package/src/repair.ts

@@ -0,0 +1,151 @@
+// NOMOS — THE REPAIR DSL (architecture/repair_dsl.md). A REPAIR binds a KNOWN replay failure (a TYPED
+// refusal matcher — kind + stable ids, never error prose) to a DECLARED remedy (a verb from the small
+// deterministic palette), authored as CODE in the tenant repo's `repairs/` folder. Repairs IMPORT the
+// domain; the domain never imports repairs. The repair manifest is NOT law and never hashed — the LAW facts
+// are the supersession + certificate the execution emits (a custodian-gated rebirth-with-transform at the
+// producer's reserved `transformState` seam).
+//
+//   import { repair } from "@githolon/dsl";
+//   import { EstateAsset } from "../src/domains/estate";
+//
+//   export const healAssetTypeRetype = repair("heal-assettype-retype")
+//     .matches({ refusal: "evolve-gate", stableId: "2c6d2218ad784422" })
+//     .reason("assetType retyped string→json in 0.54; history re-expressed through the mapping")
+//     .retypes(EstateAsset, "assetType", { through: "wrapAsJson" });
+//
+// DX (the product): `githolon replay` names the matching repair on refusal; `--repair` executes it
+// (plan → confirm → rebirth → certificate); replay again is green. A repair costs one file + two commands.
+import type { AggregateHandle } from "./aggregate.js";
+
+/** The refusal kinds a matcher may bind (v1 — extend deliberately; each addition is a design conversation). */
+export type RepairRefusalKind = "evolve-gate";
+
+/** A typed refusal matcher — binds to the refusal's KIND + the stable id it names, never to prose. */
+export interface RepairMatcher {
+  readonly refusal: RepairRefusalKind;
+  /** The stable id the refusal names (a field/aggregate sid from the lockfile lineage). */
+  readonly stableId: string;
+  /** Optionally pin the domain (when the same sid could appear in more than one — defensive). */
+  readonly domain?: string;
+}
+
+/** The NAMED deterministic mapping palette for `.retypes` — like merge drivers, a closed set the engine
+ *  implements identically on every peer (determinism or death applies to repairs too). v1:
+ *  - `wrapAsJson`: a scalar value v re-expresses as the json value v (string "x" → json "x") — the
+ *    string→json retype lane (co2's assetType wound). */
+export type RetypeMapping = "wrapAsJson";
+
+/** A declared repair verb (v1 palette — designed against the three real cases). */
+export type RepairVerb =
+  | { readonly kind: "retypes"; readonly aggregateId: string; readonly field: string; readonly through: RetypeMapping }
+  | { readonly kind: "strikes"; readonly aggregateId: string; readonly whereField: string; readonly equals: string }
+  | { readonly kind: "shreds"; readonly aggregateId: string; readonly field: string };
+
+/** The finished, serializable repair declaration (what the compiler emits into the repairs manifest). */
+export interface RepairDecl {
+  readonly id: string;
+  readonly matcher: RepairMatcher;
+  readonly reason: string;
+  readonly verb: RepairVerb;
+  readonly __isRepair: true;
+}
+
+/** True iff `x` is a finished repair declaration (the discovery duck-type). */
+export function isRepairDecl(x: unknown): x is RepairDecl {
+  return typeof x === "object" && x !== null && (x as { __isRepair?: unknown }).__isRepair === true;
+}
+
+const RETYPE_MAPPINGS: ReadonlySet<string> = new Set(["wrapAsJson"]);
+const REFUSAL_KINDS: ReadonlySet<string> = new Set(["evolve-gate"]);
+const SID_RE = /^[0-9a-f]{16}$/i;
+
+interface RepairNeedsMatcher {
+  /** Bind the KNOWN failure: the typed refusal this repair remedies. Validated: known kind, sid-shaped id. */
+  matches(m: RepairMatcher): RepairNeedsReason;
+}
+interface RepairNeedsReason {
+  /** MANDATORY human reason — rides the plan, the certificate, and the lineage supersession fact. */
+  reason(text: string): RepairNeedsVerb;
+}
+interface RepairNeedsVerb {
+  /** Historical RETYPE through a NAMED deterministic mapping (the co2-assetType lane). */
+  retypes(agg: AggregateHandle, field: string, opts: { through: RetypeMapping }): RepairDecl;
+  /** Drop matching rows' history at the re-fold (the data-purge lane). v1 predicate: field equality. */
+  strikes(agg: AggregateHandle, where: { field: string; equals: string }): RepairDecl;
+  /** Carry the field forward ABSENT — crypto-shred / PII erasure (the GDPR verb). */
+  shreds(agg: AggregateHandle, field: string): RepairDecl;
+}
+
+/**
+ * Declare a REPAIR — a known replay failure bound to a declared remedy. Staged builder so a half-finished
+ * repair is unrepresentable: `repair(id).matches(...).reason(...).<verb>(...)` yields the {@link RepairDecl}.
+ */
+export function repair(id: string): RepairNeedsMatcher {
+  if (typeof id !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(id)) {
+    throw new Error(`repair(id): the id must be a kebab-case slug (got '${id}') — it names the remedy in plans, certificates, and lineage.`);
+  }
+  const requireAgg = (agg: AggregateHandle, verb: string): string => {
+    if (typeof agg !== "object" || agg === null || (agg as { __isAggregateHandle?: unknown }).__isAggregateHandle !== true) {
+      throw new Error(`repair('${id}').${verb}: the first argument must be an aggregate handle (import it from your domain).`);
+    }
+    return agg.id;
+  };
+  const requireField = (agg: AggregateHandle, field: string, verb: string): void => {
+    if (!(field in agg.fields)) {
+      throw new Error(
+        `repair('${id}').${verb}: aggregate '${agg.id}' has no field '${field}' (known: ${Object.keys(agg.fields).sort().join(", ")}).`,
+      );
+    }
+  };
+  return {
+    matches(m: RepairMatcher): RepairNeedsReason {
+      if (!REFUSAL_KINDS.has(m?.refusal)) {
+        throw new Error(`repair('${id}').matches: unknown refusal kind '${m?.refusal}' (known: ${[...REFUSAL_KINDS].join(", ")}).`);
+      }
+      if (typeof m.stableId !== "string" || !SID_RE.test(m.stableId)) {
+        throw new Error(`repair('${id}').matches: 'stableId' must be the 16-hex stable id the refusal names (got '${m.stableId}').`);
+      }
+      return {
+        reason(text: string): RepairNeedsVerb {
+          if (typeof text !== "string" || text.trim().length === 0) {
+            throw new Error(`repair('${id}').reason: a non-empty reason is mandatory — it rides the plan, certificate, and lineage.`);
+          }
+          const finish = (verb: RepairVerb): RepairDecl => ({ id, matcher: { refusal: m.refusal, stableId: m.stableId, ...(m.domain !== undefined ? { domain: m.domain } : {}) }, reason: text, verb, __isRepair: true });
+          return {
+            retypes(agg, field, opts) {
+              const aggregateId = requireAgg(agg, "retypes");
+              requireField(agg, field, "retypes");
+              if (!RETYPE_MAPPINGS.has(opts?.through)) {
+                throw new Error(`repair('${id}').retypes: unknown mapping '${opts?.through}' (known: ${[...RETYPE_MAPPINGS].join(", ")}) — mappings are a NAMED deterministic palette, never closures.`);
+              }
+              return finish({ kind: "retypes", aggregateId, field, through: opts.through });
+            },
+            strikes(agg, where) {
+              const aggregateId = requireAgg(agg, "strikes");
+              requireField(agg, where?.field ?? "", "strikes");
+              if (typeof where?.equals !== "string") throw new Error(`repair('${id}').strikes: 'where.equals' must be a string.`);
+              return finish({ kind: "strikes", aggregateId, whereField: where.field, equals: where.equals });
+            },
+            shreds(agg, field) {
+              const aggregateId = requireAgg(agg, "shreds");
+              requireField(agg, field, "shreds");
+              return finish({ kind: "shreds", aggregateId, field });
+            },
+          };
+        },
+      };
+    },
+  };
+}
+
+/** Collect every exported repair from a module's exports bag (the discovery duck-type, like aggregatesOf). */
+export function repairsOf(mod: Record<string, unknown>): RepairDecl[] {
+  const out: RepairDecl[] = [];
+  for (const v of Object.values(mod)) if (isRepairDecl(v)) out.push(v);
+  // deterministic order + duplicate-id refusal (two repairs with one id would make --repair ambiguous)
+  out.sort((a, b) => a.id.localeCompare(b.id));
+  for (let i = 1; i < out.length; i++) {
+    if (out[i]!.id === out[i - 1]!.id) throw new Error(`repairs: duplicate repair id '${out[i]!.id}' — repair ids must be unique.`);
+  }
+  return out;
+}