@githolon/dsl 0.15.0 → 0.16.0

package/src/workspace_sharding.ts

@@ -73,7 +73,10 @@ import { t } from "./fields.js";
 import { Lww } from "./drivers.js";
 import { directive } from "./directive.js";
 import { set, strike, withMarker, type PlannedOp } from "./ops.js";
+import { create } from "./authoring.js";
+import { impureCapabilityAggregate } from "./framework/impure_capability.js";
 import { query } from "./query.js";
+import { read } from "./read.js";
 import { sum } from "./sum.js";
 import { min, max } from "./extremum.js";
 import { refAs, workspaceInvariant } from "./framework/workspace_invariant.js";
@@ -156,6 +159,15 @@ export const checkpointSealRowId = (seq: number | string): string => `nomos-chec
 /** The LATEST seal (the head pointer — same aggregate, well-known id; O(1) to find). */
 export const NOMOS_CHECKPOINT_HEAD_ID = "nomos-checkpoint-seal:head";
 
+/** THE MOVE OBLIGATION id (P6 — sharding orchestration as outbound offers): one obligation per
+ *  (move, leg), keyed deterministically so re-entry is idempotent (the receipt-leg obligation re-folds
+ *  to the same row, never a duplicate). `<from>-<to>` names the move; the leg names the step. */
+export const moveObligationRowId = (fromShard: string, toShard: string, leg: string): string =>
+  `nomos-move-obligation:${fromShard}-${toShard}:${leg}`;
+/** The move-leg sequence the coordinator emits as outbound offers (architecture/sharding_as_outbound_offers.md). */
+export const MOVE_LEGS = ["receipt", "migrate", "seal", "open", "handoff"] as const;
+export type MoveLeg = (typeof MOVE_LEGS)[number];
+
 /** The estate-total bucket of a scoped read's group (`nomosEstateSummary` group key).
  *  `|` — printable (the kernel's canonical event decode refuses raw control bytes);
  *  unambiguous because a SCOPED read's id may not contain `|` (compile-refused);
@@ -201,6 +213,13 @@ export const NomosShardAssignment = aggregate("NomosShardAssignment", {
   placedAt: t.string().merge(Lww),
 });
 
+/** The home's CURRENT assignment row, keyed by home key. Top-level so the §6 move directives can
+ *  CAPTURED-READ it (P6 S3a — the map version is derived in law, not by the host). Also routed by
+ *  the law module under the same id. */
+export const nomosShardAssignmentByHomeKey = query("nomosShardAssignmentByHomeKey")
+  .key("homeKey")
+  .returns(NomosShardAssignment);
+
 /**
  * THE SHARD'S OWN IDENTITY — law-state in the shard's OWN chain (§3's "its assignment"
  * fact, the slice-3a slice of it): which shard label this workspace IS. An Ensure
@@ -313,6 +332,13 @@ export const NomosSummarySubtotal = aggregate("NomosSummarySubtotal", {
   empty: t.int().merge(Lww).optional(),
 });
 
+/** Per-(shard) committed subtotal rows, keyed by shard. Top-level so the derived placement directive can
+ *  CAPTURED-READ each open shard's load (the `nomosShardRows` subtotal) to pick LEAST-LOADED IN THE PLAN
+ *  (holon-native placement, P6 slice 3 — the host no longer picks). Also routed by the law module. */
+export const nomosSummarySubtotalByShard = query("nomosSummarySubtotalByShard")
+  .key("shard")
+  .returns(NomosSummarySubtotal);
+
 /** THE PER-SHARD DELTA FRONTIER watermark (§5.2 step 1 — contiguity law-state). */
 export const NomosSummaryFrontier = aggregate("NomosSummaryFrontier", {
   shard: t.string().merge(Lww),
@@ -394,7 +420,36 @@ export const nomosReceiveAssignment = directive("nomosReceiveAssignment")
 //      `shard = target` and the map version BUMPED (wrong-home refusals carry it;
 //      clients refresh and retry — §4's self-healing lane).
 
-/** Begin a move: flip each home's assignment to `moving:<toShard>` (gate-verified). */
+/**
+ * THE MOVE OBLIGATION (P6 — sharding orchestration as outbound offers, slice S1): one
+ * impure-capability-shaped row per (move, leg), driven through the obligation lifecycle the
+ * KERNEL already enforces (`scan_requested` emits it on the outbox; `OrphanReceipt`/terminal-once
+ * gate its receipt). The coordinator EMITS the move as data; the bailiff delivers each leg + relays
+ * the shard's gate verdict as a receipt; each receipt mints the next leg (S2). It carries the
+ * `requested`-status lifecycle envelope (`scheduledAt`/`deadlineAt` are required ints — the reactor
+ * skips a row missing them) PLUS the move-leg params. S1 is ADDITIVE: `nomosSplitShard` mints the
+ * receipt-leg obligation ALONGSIDE the unchanged assignment flip; the host orchestration still runs
+ * the move (the obligation is observable on the outbox, not yet consumed). `architecture/sharding_as_outbound_offers.md`.
+ */
+export const NomosMoveObligation = impureCapabilityAggregate("NomosMoveObligation", {
+  // the move-leg params (the non-envelope fields scan_requested returns as the order's `params`):
+  fromShard: t.string().merge(Lww),
+  toShard: t.string().merge(Lww),
+  homeKeys: t.json().merge(Lww), // the moving home keys (the leg's work list)
+  leg: t.string().merge(Lww), // one of MOVE_LEGS
+  mapVersion: t.int().merge(Lww), // the law-derived map version (S3a), ferried leg-to-leg
+  // S3b — the target shard's ADMITTED set, accumulated migrate→seal (the cross-leg state seal-home
+  // needs to compute `missing` against the source chain). The LAW unions it (the adapter only ferries
+  // arrays it read off the obligation + the shard response — it never accumulates), so the host holds no
+  // cross-leg move state and an adapter restart re-derives everything from the on-chain obligation.
+  migratedIds: t.json().merge(Lww), // JSON string array; "[]" until the migrate leg's receipt
+});
+
+/** S1 receipt-leg obligation window (ms) — the leg's soft deadline past its scheduledAt. */
+const MOVE_OBLIGATION_WINDOW_MS = 300_000;
+
+/** Begin a move: flip each home's assignment to `moving:<toShard>` (gate-verified) AND mint the
+ *  receipt-leg move obligation (P6 S1 — additive; observable on the outbox, not yet consumed). */
 export const nomosSplitShard = directive("nomosSplitShard")
   .mutates(NomosShardAssignment)
   .payload(
@@ -403,6 +458,9 @@ export const nomosSplitShard = directive("nomosSplitShard")
       toShard: z.string().regex(/^s\d+$/),
       homeKeys: z.array(z.string().min(1)).min(1).max(64),
       startedAt: z.string(),
+      // P6 S1: the caller-stamped epoch-ms the move begins (the obligation's scheduledAt). The
+      // timestamp rides IN the payload (the determinism doctrine — no clock in the plan).
+      scheduledAt: z.number().int().min(0),
     }),
   )
   .plan((p) => {
@@ -412,10 +470,107 @@ export const nomosSplitShard = directive("nomosSplitShard")
     if (new Set(p.homeKeys).size !== p.homeKeys.length) {
       throw new Error("split-duplicate: a home key appears twice in one split");
     }
-    return p.homeKeys.flatMap((homeKey) => {
+    const ops = p.homeKeys.flatMap((homeKey) => {
       const row = instance(NomosShardAssignment, shardAssignmentRowId(homeKey));
       return [set(row, "status", movingStatus(p.toShard))];
     });
+    // P6 S3a — THE MAP VERSION IS DERIVED IN LAW, not by the host. CAPTURED-READ each moving home's
+    // CURRENT assignment (the pre-apply committed state; the gate re-derives at verify, CAS-refusing on
+    // drift) and bump: newMapVersion = max(1, max held) + 1 — the SAME arithmetic `_runSplitMigration`
+    // used to do in JS, now on the chain. The floor of 1 guarantees ≥2 (the handoff gate's minimum). The
+    // obligation carries it forward (nomosAdvanceMove ferries it leg-to-leg) so the host NEVER computes it.
+    let maxHeld = 1;
+    for (const homeKey of p.homeKeys) {
+      const rows = read(nomosShardAssignmentByHomeKey, { homeKey }) as Array<{ data?: { mapVersion?: number } }>;
+      for (const r of rows) {
+        const v = r?.data?.mapVersion;
+        if (typeof v === "number" && v > maxHeld) maxHeld = v;
+      }
+    }
+    const newMapVersion = maxHeld + 1;
+    // P6 S1/S2 — mint the receipt-leg obligation (the standard obligation API: `create` mints the id; its
+    // ops are ambient-harvested + merged with these returned ops). status:'requested' + the lifecycle
+    // envelope ⇒ the outbox (`scan_requested`) surfaces it as an outbound offer; the move-leg params ride
+    // as the order's params. Re-entry is idempotent via the MOVE GATE (a double `nomosSplitShard` refuses
+    // `not-active:moving:*` before this runs). The host orchestration is UNCHANGED — observable, not consumed.
+    create(NomosMoveObligation)
+      .set("requestedBy", "coordinator")
+      .set("requestedAt", p.scheduledAt)
+      .set("scheduledAt", p.scheduledAt)
+      .set("deadlineAt", p.scheduledAt + MOVE_OBLIGATION_WINDOW_MS)
+      .set("status", "requested")
+      .set("fromShard", p.fromShard)
+      .set("toShard", p.toShard)
+      .set("homeKeys", JSON.stringify(p.homeKeys)) // t.json() stores the stringified JSON
+      .set("leg", "receipt")
+      .set("mapVersion", newMapVersion)
+      .set("migratedIds", "[]"); // nothing migrated yet — the migrate leg's receipt accumulates it
+    return ops;
+  })
+  .reads(nomosShardAssignmentByHomeKey);
+
+/**
+ * P6 S2 — THE MOVE RECEIPT (the leg sequence becomes LAW): a leg's receipt COMPLETES its obligation
+ * (a terminal status ⇒ the kernel's receipt gate enforces terminal-once + no-orphan, since
+ * NomosMoveObligation carries the full impure-capability envelope) AND MINTS THE NEXT leg's obligation —
+ * so the order receipt→migrate→seal→open→handoff lives on the chain, not in the host's `_runSplitMigration`
+ * JS. The bailiff offers this after delivering a leg + taking the shard's gate verdict (that wiring is S3;
+ * S2 drives it directly to prove the chain). The SEAL leg, when `missing` writes raced in on the source,
+ * re-mints `migrate` (the bounded re-migrate) instead of advancing to `open`. The LAST leg (handoff) mints
+ * nothing — the move is done. (architecture/sharding_as_outbound_offers.md)
+ */
+export const nomosAdvanceMove = directive("nomosAdvanceMove")
+  .mutates(NomosMoveObligation)
+  .payload(
+    z.object({
+      requestId: z.string().min(1), // the leg obligation being completed (its runtime-minted id)
+      leg: z.enum(MOVE_LEGS),
+      fromShard: z.string().regex(/^s\d+$/),
+      toShard: z.string().regex(/^s\d+$/),
+      homeKeys: z.array(z.string().min(1)).min(1).max(64),
+      mapVersion: z.number().int().min(2), // the law-derived version (S3a), ferried leg-to-leg
+      scheduledAt: z.number().int().min(0),
+      completedAt: z.number().int().min(0),
+      missing: z.array(z.string()).optional(), // seal leg: writes that raced in, still on the source
+      // S3b — the migrated-id ferry (the adapter passes through arrays it READ; the LAW unions them).
+      // `priorMigratedIds`: the current obligation's accumulated set (off the obligation). `migratedIds`:
+      // THIS leg's shard delta (off the migrate-in response; [] for non-migrate legs). The plan unions
+      // them onto the next obligation, so the seal leg's obligation carries the full admitted set.
+      priorMigratedIds: z.array(z.string()).default([]),
+      migratedIds: z.array(z.string()).default([]),
+    }),
+  )
+  .plan((p) => {
+    // THE RECEIPT — drive the current leg obligation TERMINAL (the kernel's terminal-once anchors on this
+    // terminal-status set; a second receipt on the same obligation refuses ReceiptOnTerminalObligation).
+    const cur = instance(NomosMoveObligation, p.requestId);
+    const ops = [
+      set(cur, "status", "completed"),
+      set(cur, "completedAt", p.completedAt),
+      set(cur, "closesObligation", p.requestId), // the closure link (the O(1) closure read)
+    ];
+    // MINT THE NEXT LEG — the order is law. Seal + raced `missing` re-mints `migrate` (bounded re-migrate).
+    const idx = MOVE_LEGS.indexOf(p.leg);
+    let nextLeg: MoveLeg | undefined = MOVE_LEGS[idx + 1];
+    if (p.leg === "seal" && p.missing !== undefined && p.missing.length > 0) nextLeg = "migrate";
+    if (nextLeg !== undefined) {
+      // THE LAW UNIONS the migrated ids (the host never accumulates): the next obligation carries the
+      // accumulated admitted set forward, so the seal leg POSTs the full set + a re-migrate keeps growing it.
+      const accMigrated = [...new Set([...p.priorMigratedIds, ...p.migratedIds])].sort();
+      create(NomosMoveObligation)
+        .set("requestedBy", "coordinator")
+        .set("requestedAt", p.completedAt)
+        .set("scheduledAt", p.scheduledAt)
+        .set("deadlineAt", p.scheduledAt + MOVE_OBLIGATION_WINDOW_MS)
+        .set("status", "requested")
+        .set("fromShard", p.fromShard)
+        .set("toShard", p.toShard)
+        .set("homeKeys", JSON.stringify(p.homeKeys))
+        .set("leg", nextLeg)
+        .set("mapVersion", p.mapVersion) // carry the law-derived version forward (S3a)
+        .set("migratedIds", JSON.stringify(accMigrated)); // S3b — the accumulated admitted set
+    }
+    return ops;
   });
 
 /**
@@ -942,6 +1097,7 @@ export function shardingLawModule(spec: ShardingLawSpec): Record<string, unknown
     NomosSummaryFrontier,
     NomosDeepVerify,
     NomosCheckpointSeal,
+    NomosMoveObligation, // P6 S1 — the move-leg obligation `nomosSplitShard` emits
     nomosDeclareShardIdentity,
     nomosReceiveAssignment,
     nomosOpenShard,
@@ -951,17 +1107,14 @@ export function shardingLawModule(spec: ShardingLawSpec): Record<string, unknown
     nomosRecordDeepVerify,
     nomosCheckpointSeal,
     nomosSplitShard,
+    nomosAdvanceMove, // P6 S2 — the move receipt: completes a leg + mints the next
     nomosSealHandoff,
     nomosSealHome,
-    nomosShardAssignmentByHomeKey: query("nomosShardAssignmentByHomeKey")
-      .key("homeKey")
-      .returns(NomosShardAssignment),
+    nomosShardAssignmentByHomeKey, // top-level (P6 S3a — captured-read by the move directives)
     nomosShardIdentityByScope: query("nomosShardIdentityByScope")
       .key("scope")
       .returns(NomosShardIdentity),
-    nomosSummarySubtotalByShard: query("nomosSummarySubtotalByShard")
-      .key("shard")
-      .returns(NomosSummarySubtotal),
+    nomosSummarySubtotalByShard, // top-level (P6 slice 3 — captured-read by the placement directive)
     nomosShardRegistryByStatus: query("nomosShardRegistryByStatus")
       .key("status")
       .returns(NomosShardRegistry),
@@ -1228,27 +1381,52 @@ export function shardingLawModule(spec: ShardingLawSpec): Record<string, unknown
     // by the dispatching client/worker over committed load subtotals — law-state,
     // never a live read a plan takes); the row id is the home key (ONE active
     // assignment per home, by construction); a conflicting re-offer refuses typed.
+    // HOLON-NATIVE PLACEMENT (P6 slice 3): the PLAN picks least-loaded — the host no longer chooses the
+    // shard. `shard` is GONE from the payload. The plan CAPTURED-READS the home's held assignment (idempotent
+    // reuse) and each open shard's committed `nomosShardRows` subtotal (least-loaded, ties → lowest ordinal),
+    // both #58 declared reads the gate re-derives at verify (CAS — a load that moved refuses typed). Pure over
+    // committed coordinator state ⇒ every peer places identically. (architecture/holon_native_routing.md)
+    const pool = axis.shardCount;
     mod[dirId] = directive(dirId)
       .ensures(NomosShardAssignment)
       .payload(
         z.object({
           [keyField]: z.string().min(1),
-          shard: z.string().regex(/^s\d+$/),
           placedAt: z.string(),
         }),
       )
       .plan((p: Record<string, string>) => {
         const homeKey = p[keyField]!;
         const row = instance(NomosShardAssignment, shardAssignmentRowId(homeKey));
+        // IDEMPOTENCY: a home already placed reuses ITS shard (re-offer is a no-op; the uniqueness
+        // invariant guards a mid-move / moved home). A fresh home picks least-loaded over the open pool.
+        const held = read(nomosShardAssignmentByHomeKey, { homeKey }) as Array<{ data?: { shard?: string } }>;
+        const heldShard = held[0]?.data?.shard;
+        let shard: string;
+        if (typeof heldShard === "string" && heldShard) {
+          shard = heldShard;
+        } else {
+          let best = "s0";
+          let bestLoad = Infinity;
+          for (let i = 0; i < pool; i++) {
+            const label = `s${i}`;
+            const subs = read(nomosSummarySubtotalByShard, { shard: label }) as Array<{ data?: { readId?: string; value?: number } }>;
+            const sub = subs.find((r) => r?.data?.readId === NOMOS_SHARD_ROWS_READ);
+            const load = typeof sub?.data?.value === "number" ? sub.data!.value! : 0;
+            if (load < bestLoad) { best = label; bestLoad = load; } // strict < ⇒ ties keep the lowest ordinal
+          }
+          shard = best;
+        }
         return [
           withMarker(set(row, "homeType", axisType), "ensures"),
           set(row, "homeKey", homeKey),
-          set(row, "shard", p.shard!),
+          set(row, "shard", shard),
           set(row, "mapVersion", 1),
           set(row, "status", "active"),
           set(row, "placedAt", p.placedAt!),
         ];
-      });
+      })
+      .reads(nomosShardAssignmentByHomeKey, nomosSummarySubtotalByShard);
     // PLACEMENT UNIQUENESS (task #42 item 5): an idempotent re-offer (same shard)
     // re-folds the same row; a CONFLICTING one refuses typed with the held shard.
     // THE MOVE-LANE GUARD (slice 5): a re-offer may only reproduce a FRESH placement
@@ -1262,17 +1440,17 @@ export function shardingLawModule(spec: ShardingLawSpec): Record<string, unknown
       .reads(({ intent }) => [
         refAs("held", "NomosShardAssignment", `pre:${shardAssignmentRowId(String(intent[keyField] ?? ""))}`),
       ])
-      .assert((snapshots, ctx) => {
+      .assert((snapshots) => {
         const held = snapshots["held"] ?? {};
         const heldShard = held["shard"];
-        if (typeof heldShard !== "string" || heldShard.length === 0) return { accept: true };
+        if (typeof heldShard !== "string" || heldShard.length === 0) return { accept: true }; // a virgin home — place it
         const target = movingTargetOf(held["status"]);
         if (target !== undefined) return { reject: `home-moving:${target}` };
         const heldVersion = typeof held["mapVersion"] === "number" ? (held["mapVersion"] as number) : 1;
-        const offered = ctx?.intent?.["shard"];
-        return offered === heldShard && heldVersion === 1
-          ? { accept: true } // the idempotent re-offer — same home, same shard, fresh era
-          : { reject: `placement-exists:${heldShard}` };
+        // The plan REUSES the held shard for an already-placed home (holon-native placement, slice 3), so a
+        // re-offer to a FRESH placement (v1) is byte-identical — admit. A MOVED home (v>1) would regress its
+        // version to 1, so it refuses typed (the routed client answers such re-offers from the held row).
+        return heldVersion === 1 ? { accept: true } : { reject: `placement-exists:${heldShard}` };
       });
   }
   return mod;

package/src/workspace_type.ts

@@ -367,6 +367,7 @@ export function deriveHoming(
     "NomosShardAssignment", "NomosShardIdentity", "NomosHomeReceipt", "NomosShardRegistry",
     "NomosShardPolicy", "NomosSummarySubtotal", "NomosSummaryFrontier", "NomosDeepVerify",
     "NomosCheckpointSeal",
+    "NomosMoveObligation", // P6 — the move-leg obligation is coordinator law-state (no homing t.ref)
   ]);
   const childIdsAll = new Set([...types.values()].flatMap((t) => [...t.childIds]));
   const coordinators = [...types.values()]