@githolon/dsl 0.68.0 → 0.69.1

package/dart/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 0.46.0
+
+- Custody lifecycle on `NomosBridge`/`NomosSession`: `connect(..., onCustodyBreak: CustodyBreakPolicy)`,
+  `custodyStatus()`, the `custodyEvents` stream, `resolveCustodyBreak()` (the ask lane — put the decision in
+  front of the user), `salvagedIntents`/`reofferSalvaged`/`discardSalvaged`. A rebirth/supersession is a
+  first-class typed event: named truthfully, decided by the app, local work never silently adopted nor lost.
+  Requires `nomos_types >= 0.1.4`.
+
 ## 0.45.0
 
 - `offerOutcome(...)` — the one outcome-returning offer lane generated clients now call for EVERY directive:

package/dart/lib/src/webview_bridge.dart

@@ -26,7 +26,10 @@ import 'package:nomos_types/nomos_types.dart'
         NomosRef,
         NomosForeignReader,
         NomosForeignWorkspaceReader,
-        ForeignAttestation;
+        ForeignAttestation,
+        CustodyBreakPolicy,
+        NomosCustodyEvent,
+        NomosCustodyStatus;
 
 /// The protocol version the runner and the bridge agree on (`webview-runner.mjs` `WEBVIEW_BRIDGE_VERSION`).
 const int kWebviewBridgeVersion = 1;
@@ -656,6 +659,11 @@ class NomosBridge {
       StreamController<Map<String, Object?>>.broadcast();
   final StreamController<Map<String, Object?>> _signalEvents =
       StreamController<Map<String, Object?>>.broadcast();
+  // CUSTODY LIFECYCLE (rebirth_and_custody_lifecycle.md): each `custody` event carries the raw map (session +
+  // custody:{kind,break,…}); a Flutter app binds a break dialog / posture banner to this. Kind "ask" awaits
+  // [resolveCustodyBreak].
+  final StreamController<NomosCustodyEvent> _custodyEvents =
+      StreamController<NomosCustodyEvent>.broadcast();
   final StreamController<Map<String, Object?>> _flameEvents =
       StreamController<Map<String, Object?>>.broadcast();
   final StreamController<Map<String, Object?>> _spanEvents =
@@ -771,6 +779,13 @@ class NomosBridge {
       }
       return;
     }
+    if (event == 'custody') {
+      // Custody lifecycle: { event:'custody', session, custody:{ kind, break, … } }. Decode + fan out so the
+      // app can react (kind "ask" → show a dialog then call resolveCustodyBreak; others are informational).
+      final ev = NomosCustodyEvent.fromMessage(m);
+      if (ev != null && !_custodyEvents.isClosed) _custodyEvents.add(ev);
+      return;
+    }
     if (event == 'transfer') {
       // LIVE pack byte-progress { received, total, kind } — the real loading bar (host Content-Length).
       final tp = TransferProgress.fromMessage(m);
@@ -892,6 +907,7 @@ class NomosBridge {
       String? restoreFrom,
       bool allowUnborn = false,
       bool recover = false,
+      CustodyBreakPolicy? onCustodyBreak,
       String? session,
       int? maxMounted}) async {
     final ws = session ?? workspace;
@@ -917,10 +933,51 @@ class NomosBridge {
       // RECOVER-IN-PLACE over a corrupt restoreFrom snapshot: salvage local-only writes + DLQ, refold fresh
       // from cloud, re-offer the salvaged work. The report lands on [lastRecovery]. Nothing local is lost.
       if (recover) 'recover': true,
+      // CUSTODY-BREAK POLICY (rebirth_and_custody_lifecycle.md): "adopt"/"reject" decide automatically;
+      // "ask" surfaces the break on [custodyEvents] (kind "ask") and awaits [resolveCustodyBreak]. Omitted ⇒
+      // fail closed (the break surfaces as an error on the sync/pull that hit it; the holon stays local).
+      if (onCustodyBreak != null) 'onCustodyBreak': onCustodyBreak.wire,
     }));
     _lastRecovery = (r['recovery'] as Map?)?.cast<String, Object?>();
   }
 
+  /// The custody lifecycle stream (rebirth_and_custody_lifecycle.md) — a rebirth/divergence surfaces here as a
+  /// typed [NomosCustodyEvent]. Bind a Flutter break dialog / posture banner to it; for a `CustodyBreakPolicy.
+  /// ask` session, an event of `kind == 'ask'` awaits [resolveCustodyBreak].
+  Stream<NomosCustodyEvent> get custodyEvents => _custodyEvents.stream;
+
+  /// Where a session sits on the custody spectrum (incarnation, posture, pending/salvaged local work,
+  /// supersession history) — for a status banner or a "you're offline on old truth" indicator.
+  Future<NomosCustodyStatus> custodyStatus({String? session}) async =>
+      NomosCustodyStatus.fromJson(
+          _asMap(await _call('custodyStatus', {if (session != null) 'session': session})));
+
+  /// Continue an `ask`-policy custody break with the user's decision (adopt|reject) — the async UX lane.
+  Future<Map<String, Object?>> resolveCustodyBreak(String decision,
+          {String? session}) async =>
+      _asMap(await _call('resolveCustodyBreak', {
+        'decision': decision,
+        if (session != null) 'session': session,
+      }));
+
+  /// The parked salvaged intents (re-offerable local work an `adopt` rescued) — metadata only.
+  Future<List<Map<String, Object?>>> salvagedIntents({String? session}) async {
+    final r = _asMap(await _call('salvagedIntents', {if (session != null) 'session': session}));
+    return ((r['salvaged'] as List?) ?? const [])
+        .map((e) => (e as Map).cast<String, Object?>())
+        .toList();
+  }
+
+  /// Re-offer parked salvaged work under the current (adopted) law — the explicit app move (never automatic
+  /// across incarnations). [id] re-offers one; omitted re-offers all.
+  Future<Map<String, Object?>> reofferSalvaged({String? id, String? session}) async =>
+      _asMap(await _call('reofferSalvaged',
+          {if (id != null) 'id': id, if (session != null) 'session': session}));
+
+  /// Discard one parked salvaged intent — the app's explicit choice.
+  Future<Map<String, Object?>> discardSalvaged(String id, {String? session}) async =>
+      _asMap(await _call('discardSalvaged', {'id': id, if (session != null) 'session': session}));
+
   /// The salvage report from the most recent `connect(recover: true)` — `{ salvagedWrites, requeuedDeadLetters,
   /// unsalvageable }`, or null if the connection didn't recover. Show "recovered N writes" / surface
   /// `unsalvageable` (writes the current law refused — kept in the DLQ, never dropped).
@@ -1713,6 +1770,7 @@ class NomosBridge {
     _stopStatusPoll();
     if (!_syncEvents.isClosed) await _syncEvents.close();
     if (!_signalEvents.isClosed) await _signalEvents.close();
+    if (!_custodyEvents.isClosed) await _custodyEvents.close();
     if (!_flameEvents.isClosed) await _flameEvents.close();
     if (!_spanEvents.isClosed) await _spanEvents.close();
     if (!_transferEvents.isClosed) await _transferEvents.close();

package/dart/pubspec.yaml

@@ -11,7 +11,7 @@ description: >-
   Nomos 2 Dart frontend types — the hand-written kernel wire types plus the
   code-generated per-domain aggregate + directive-payload types. (De)serializes
   the EXACT serde JSON the Rust kernel + projection produce/consume.
-version: 0.45.0
+version: 0.46.0
 
 environment:
   sdk: ^3.5.0
@@ -20,7 +20,7 @@ dependencies:
   # The pure-data core (wire types, offer codec, NomosReads, schema validation, error
   # info). nomos_client depends on and re-exports it, so existing imports are unchanged.
   # For local monorepo dev, pubspec_overrides.yaml points this at ../dart_types.
-  nomos_types: ^0.1.3
+  nomos_types: ^0.1.4
   json_schema: ^5.2.2
   crypto: ^3.0.0
 

package/dart_types/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.1.4
+
+- Custody-lifecycle types: `NomosCustodyBreak`, `NomosCustodyStatus`, `NomosCustodyEvent`,
+  `CustodyBreakPolicy` (adopt/reject/ask) — a workspace rebirth surfaces as a typed, app-decidable event.
+  Purely additive.
+
 ## 0.1.3
 
 - `NomosRef` — THE one typed reference `{workspace, type, id}`: value semantics, the canonical

package/dart_types/lib/nomos_types.dart

@@ -33,3 +33,6 @@ export 'src/errors.dart';
 export 'src/foreign_ref.dart';
 export 'src/activity.dart';
 export 'src/nomos_ref.dart';
+// The CUSTODY-LIFECYCLE types (rebirth_and_custody_lifecycle.md): NomosCustodyBreak / NomosCustodyStatus /
+// CustodyBreakPolicy — custody incompatibility as a first-class, typed, app-decidable event. Pure data.
+export 'src/custody.dart';

package/dart_types/lib/src/custody.dart

@@ -0,0 +1,203 @@
+// NOMOS — the CUSTODY-LIFECYCLE types (rebirth_and_custody_lifecycle.md, the client half). Custody
+// incompatibility is a FIRST-CLASS, app-decidable event: a rebirth (rebirthWorkspace) re-genesises a
+// workspace's chain, invalidating every client's local history. The client detects the break, names it
+// truthfully, and hands the app the decision — it NEVER silently adopts foreign truth nor loses local work.
+//
+// Pure data (no bridge/lifecycle/Flutter) so BOTH the layered TYPES package and the runtime `nomos_client`
+// resolve them. The bridge decodes these from the runner's `custody` events + `custodyStatus` reply.
+library;
+
+/// WHY a chain was superseded — the lineage annotation lifted from the workspace status onto a break.
+class NomosCustodySupersession {
+  final String? reason;
+  final String? supersededAt;
+
+  const NomosCustodySupersession({this.reason, this.supersededAt});
+
+  factory NomosCustodySupersession.fromJson(Map<String, dynamic> j) =>
+      NomosCustodySupersession(
+        reason: j['reason'] as String?,
+        supersededAt: j['supersededAt'] as String?,
+      );
+  Map<String, dynamic> toJson() =>
+      {'reason': reason, 'supersededAt': supersededAt};
+}
+
+/// The kind of custody break.
+///  - [superseded]: a LAWFUL rebirth — the remote incarnation differs and the lineage records the
+///    supersession (a reason/attribution rides the break).
+///  - [diverged]: the histories don't reconcile with NO supersession explanation (an unrelated/foreign chain).
+enum NomosCustodyBreakKind {
+  superseded,
+  diverged;
+
+  static NomosCustodyBreakKind fromWire(String? s) =>
+      s == 'diverged' ? NomosCustodyBreakKind.diverged : NomosCustodyBreakKind.superseded;
+  String get wire => this == NomosCustodyBreakKind.diverged ? 'diverged' : 'superseded';
+}
+
+/// A CUSTODY BREAK — the remote incarnation is incompatible with this client's local chain. Carries
+/// everything the app needs to choose adopt vs reject (and to explain WHY to a user).
+class NomosCustodyBreak {
+  final NomosCustodyBreakKind kind;
+
+  /// This client's local chain genesis oid.
+  final String localGenesis;
+
+  /// The remote serving chain's genesis oid (the workspace's current incarnation).
+  final String remoteGenesis;
+  final String remoteIncarnation;
+
+  /// Present for a [NomosCustodyBreakKind.superseded] break — why the old chain was retired.
+  final NomosCustodySupersession? supersession;
+
+  /// How many local-only intents (un-synced authored work) are at stake — never lost by any policy.
+  final int localOnlyIntents;
+
+  /// Epoch-ms of the last successful converge before the break (or null if never synced).
+  final int? lastSyncedAt;
+
+  const NomosCustodyBreak({
+    required this.kind,
+    required this.localGenesis,
+    required this.remoteGenesis,
+    required this.remoteIncarnation,
+    this.supersession,
+    this.localOnlyIntents = 0,
+    this.lastSyncedAt,
+  });
+
+  factory NomosCustodyBreak.fromJson(Map<String, dynamic> j) => NomosCustodyBreak(
+        kind: NomosCustodyBreakKind.fromWire(j['kind'] as String?),
+        localGenesis: (j['localGenesis'] ?? '') as String,
+        remoteGenesis: (j['remoteGenesis'] ?? j['remoteIncarnation'] ?? '') as String,
+        remoteIncarnation: (j['remoteIncarnation'] ?? j['remoteGenesis'] ?? '') as String,
+        supersession: (j['supersession'] is Map)
+            ? NomosCustodySupersession.fromJson(
+                (j['supersession'] as Map).cast<String, dynamic>())
+            : null,
+        localOnlyIntents: (j['localOnlyIntents'] as num?)?.toInt() ?? 0,
+        lastSyncedAt: (j['lastSyncedAt'] as num?)?.toInt(),
+      );
+
+  Map<String, dynamic> toJson() => {
+        'kind': kind.wire,
+        'localGenesis': localGenesis,
+        'remoteGenesis': remoteGenesis,
+        'remoteIncarnation': remoteIncarnation,
+        if (supersession != null) 'supersession': supersession!.toJson(),
+        'localOnlyIntents': localOnlyIntents,
+        'lastSyncedAt': lastSyncedAt,
+      };
+}
+
+/// The app's decision for a custody break (the declared or interactive policy outcome).
+enum CustodyBreakPolicy {
+  /// Salvage local-only work, re-clone the new incarnation, park the salvage re-offerable, resume.
+  adopt,
+
+  /// Stay on local truth, go offline-only (the local holon keeps serving; sync suspends).
+  reject,
+
+  /// Surface the break on [custodyEvents] and await `resolveCustodyBreak(...)` (async UX — a dialog).
+  ask;
+
+  String get wire => name;
+}
+
+/// A supersession entry from the workspace lineage (custody introspection history).
+class NomosSupersededChain {
+  final String? ref;
+  final String? supersededAt;
+  final String? reason;
+
+  const NomosSupersededChain({this.ref, this.supersededAt, this.reason});
+
+  factory NomosSupersededChain.fromJson(Map<String, dynamic> j) => NomosSupersededChain(
+        ref: j['ref'] as String?,
+        supersededAt: j['supersededAt'] as String?,
+        reason: j['reason'] as String?,
+      );
+  Map<String, dynamic> toJson() =>
+      {'ref': ref, 'supersededAt': supersededAt, 'reason': reason};
+}
+
+/// A custody lifecycle event pushed over the bridge (mirrors syncEvents). `kind` is one of
+/// "detected" | "rejected" | "adopting" | "adopted" | "ask"; "ask" awaits `resolveCustodyBreak`.
+class NomosCustodyEvent {
+  final String kind;
+  final String? session;
+  final NomosCustodyBreak? break_;
+  final bool? recloned;
+  final int? parkedIntents;
+
+  const NomosCustodyEvent({
+    required this.kind,
+    this.session,
+    this.break_,
+    this.recloned,
+    this.parkedIntents,
+  });
+
+  /// True when this event is an interactive prompt awaiting a decision.
+  bool get isAsk => kind == 'ask';
+
+  static NomosCustodyEvent? fromMessage(Map<String, dynamic> m) {
+    final c = (m['custody'] as Map?)?.cast<String, dynamic>();
+    if (c == null) return null;
+    final b = (c['break'] as Map?)?.cast<String, dynamic>();
+    return NomosCustodyEvent(
+      kind: (c['kind'] ?? '') as String,
+      session: m['session'] as String?,
+      break_: b != null ? NomosCustodyBreak.fromJson(b) : null,
+      recloned: c['recloned'] as bool?,
+      parkedIntents: (c['parkedIntents'] as num?)?.toInt(),
+    );
+  }
+}
+
+/// Where a holon sits on the custody spectrum ([custodyStatus]).
+class NomosCustodyStatus {
+  /// The chain THIS holon serves (its own genesis oid).
+  final String? incarnation;
+  final String? localGenesis;
+
+  /// The remote serving chain's genesis (or null when unknown / pre-rebirth cloud).
+  final String? remoteIncarnation;
+
+  /// One of: synced | custody-break | custody-break-rejected | adopting.
+  final String syncPosture;
+  final int pendingLocalIntents;
+  final int salvagedIntents;
+  final List<NomosSupersededChain> supersessionHistory;
+
+  /// The unresolved break, when the holon is sitting in a break posture.
+  final NomosCustodyBreak? pendingBreak;
+
+  const NomosCustodyStatus({
+    this.incarnation,
+    this.localGenesis,
+    this.remoteIncarnation,
+    this.syncPosture = 'synced',
+    this.pendingLocalIntents = 0,
+    this.salvagedIntents = 0,
+    this.supersessionHistory = const [],
+    this.pendingBreak,
+  });
+
+  factory NomosCustodyStatus.fromJson(Map<String, dynamic> j) => NomosCustodyStatus(
+        incarnation: j['incarnation'] as String?,
+        localGenesis: j['localGenesis'] as String?,
+        remoteIncarnation: j['remoteIncarnation'] as String?,
+        syncPosture: (j['syncPosture'] ?? 'synced') as String,
+        pendingLocalIntents: (j['pendingLocalIntents'] as num?)?.toInt() ?? 0,
+        salvagedIntents: (j['salvagedIntents'] as num?)?.toInt() ?? 0,
+        supersessionHistory: ((j['supersessionHistory'] as List?) ?? const [])
+            .whereType<Map>()
+            .map((m) => NomosSupersededChain.fromJson(m.cast<String, dynamic>()))
+            .toList(),
+        pendingBreak: (j['pendingBreak'] is Map)
+            ? NomosCustodyBreak.fromJson((j['pendingBreak'] as Map).cast<String, dynamic>())
+            : null,
+      );
+}

package/dart_types/pubspec.yaml

@@ -11,7 +11,7 @@ description: >-
   Pure kernel wire/data types for Nomos Dart frontends — no transport, no bridge,
   no runtime. The hand-written serde-JSON-compatible types plus the offer codec,
   reactive read engine, schema validation, and data-only error/trace types.
-version: 0.1.3
+version: 0.1.4
 
 environment:
   sdk: ^3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.68.0",
+  "version": "0.69.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",

package/src/compile_package_main.ts

@@ -432,6 +432,9 @@ const DART_SUPPORT_CORE_SRC = [
   "foreign_ref.dart",
   "activity.dart",
   "nomos_ref.dart",
+  // The custody-lifecycle types (NomosCustodyBreak/NomosCustodyStatus/CustodyBreakPolicy) — the generated
+  // client + the vendored bridge reference them through the barrel, so they must vendor. Pure data.
+  "custody.dart",
 ] as const;
 // The RUNTIME support files, vendored from `nomos_client` (dsl/dart/lib/src): the async WebView
 // bridge the generated `<name>.client.dart` drives, and the provider surface. Their

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;
+}