@githolon/dsl 0.105.24 → 0.107.0

package/dart/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.64.40
+
+- Clone the workspace ledger directly from Cloudflare Artifacts when the cloud grants a read lease
+  (`/git-read-lease`), falling back to the `/pack` lane; retry transient pack-transport failures. Large
+  ledgers no longer time out the boot clone.
+
 ## 0.64.39
 
 - Resolve kernel compatibility through typed OSGi Contract Namespace requirements and OpenUSD candidate

package/dart/lib/src/runner/node-entry.mjs

@@ -7581,6 +7581,56 @@ async function lsRefs(remote, headers = {}, { service = "git-upload-pack", prefi
   }
   return refs;
 }
+async function fetchPack(remote, headers = {}, { wants = [], haves = [] } = {}) {
+  wants = wants.filter((w) => /^[0-9a-f]{40}$/.test(w) && w !== ZERO_OID);
+  if (!wants.length) return null;
+  const caps = "ofs-delta agent=nomos-cloud";
+  const parts = [];
+  wants.forEach((w, i) => parts.push(pkt(`want ${w}${i === 0 ? " " + caps : ""}
+`)));
+  parts.push(FLUSH);
+  for (const h of haves) if (/^[0-9a-f]{40}$/.test(h) && h !== ZERO_OID) parts.push(pkt(`have ${h}
+`));
+  parts.push(pkt("done\n"));
+  const body = concatBytes(parts);
+  const reqHeaders = { "content-type": "application/x-git-upload-pack-request", "accept": "application/x-git-upload-pack-result", ...headers };
+  const MAX_ATTEMPTS = 6;
+  let buf;
+  for (let attempt = 1; ; attempt++) {
+    try {
+      const r = await fetch(`${remote}/git-upload-pack`, { method: "POST", headers: reqHeaders, body, signal: AbortSignal.timeout(18e4) });
+      if (!r.ok) throw new Error(`upload-pack ${r.status}: ${(await r.text()).slice(0, 180)}`);
+      buf = new Uint8Array(await r.arrayBuffer());
+      break;
+    } catch (e) {
+      const msg = String(e?.message || e);
+      const transient = /terminated|other side closed|socket|ECONNRESET|ECONNREFUSED|UND_ERR|fetch failed|network|aborted|timeout/i.test(msg) && !/upload-pack \d{3}:/.test(msg);
+      if (!transient || attempt >= MAX_ATTEMPTS) throw e;
+      await new Promise((res) => setTimeout(res, Math.min(4e3, 400 * attempt)));
+    }
+  }
+  const { lines, rest } = readPktLines(buf, 0);
+  const packChunks = [];
+  let sideband = false;
+  for (const line of lines) {
+    if (line.length === 0) continue;
+    const head = dec3.decode(line.subarray(0, Math.min(line.length, 3)));
+    if (head === "NAK" || head === "ACK" || head === "ERR" || head.startsWith("sha")) continue;
+    const band = line[0];
+    if (band === 1) {
+      packChunks.push(line.subarray(1));
+      sideband = true;
+    } else if (band === 2) {
+    } else if (band === 3) {
+      throw new Error("upload-pack fatal: " + dec3.decode(line.subarray(1)).slice(0, 180));
+    }
+  }
+  const pack = sideband ? concatBytes(packChunks) : buf.subarray(rest);
+  if (pack.length < 12 || dec3.decode(pack.subarray(0, 4)) !== "PACK") {
+    throw new Error(`upload-pack: no pack in response (${pack.length}B, sideband=${sideband})`);
+  }
+  return pack;
+}
 async function pushPack(remote, headers = {}, { updates = [], pack = null } = {}, fetchImpl = fetch) {
   if (!updates.length) return { ok: true, noop: true };
   const body = concatBytes([receivePackCommandPrefix(updates), pack && pack.length ? pack : EMPTY_PACK]);
@@ -13005,6 +13055,33 @@ ${String(commit).toLowerCase()}`;
   const addReadRemote = async () => {
   };
   const applyPack = (packB64, head) => provider.applyPack(packB64, head);
+  const directFullClone = async (label) => {
+    let lease = null;
+    try {
+      const r = await _fetch(`${base}/v2/workspaces/${workspace}/git-read-lease`, { headers: authHeaders });
+      if (r.ok) {
+        const d = await r.json();
+        if (d && d.ok && typeof d.remote === "string" && typeof d.token === "string") lease = { remote: d.remote, token: d.token };
+      }
+    } catch {
+    }
+    if (!lease) return false;
+    const _f = span("receive", `${label} (direct artifacts)`, "cfetch", {});
+    try {
+      const auth = { Authorization: "Basic " + btoa("x:" + lease.token) };
+      const refs = await lsRefs(lease.remote, auth, { service: "git-upload-pack", prefix: "refs/heads/main" });
+      const head = refs["refs/heads/main"];
+      if (!head || !/^[0-9a-f]{40}$/i.test(head)) return false;
+      const pack = await fetchPack(lease.remote, auth, { wants: [head] });
+      if (!pack || !pack.byteLength) return false;
+      applyPack(nmsInternalSnapshotToBase64(pack), head);
+      return true;
+    } catch {
+      return false;
+    } finally {
+      _f.end();
+    }
+  };
   try {
     await provider.boot({ base, workspace, branch: BRANCH, repoArg, restoreSnapshot: restoreFrom || null, fetchImpl: _fetch, authHeaders });
   } catch (error) {
@@ -13182,7 +13259,7 @@ ${String(commit).toLowerCase()}`;
       _bootLedger.end();
       if (!allowUnborn) throw new Error(`workspace '${workspace}' has no ledger main \u2014 create it first (POST /v2/workspaces/${workspace})`);
     } else {
-      await fetchAndApplyPack("", "boot: fetch full pack");
+      if (!await directFullClone("boot: full pack")) await fetchAndApplyPack("", "boot: fetch full pack");
       const mounted = await mountWithResidency(remoteMain, "boot restore");
       if (mounted && typeof mounted === "object" && mounted.kernelSpans) {
         bootKernelSpans = mounted.kernelSpans;
@@ -13717,7 +13794,7 @@ ${String(commit).toLowerCase()}`;
   const forceFullMainHistory = async (why, _cause) => {
     const _full = span("receive", `${why}: re-pull FULL main`, "cfetch");
     try {
-      await fetchAndApplyPack("", `${why}: full main pack`);
+      if (!await directFullClone(`${why}: full main`)) await fetchAndApplyPack("", `${why}: full main pack`);
     } finally {
       _full.end();
     }

package/dart/lib/src/runner/offline-install.mjs

@@ -6098,13 +6098,23 @@ async function fetchPack(remote, headers = {}, { wants = [], haves = [] } = {})
   for (const h of haves) if (/^[0-9a-f]{40}$/.test(h) && h !== ZERO_OID) parts.push(pkt(`have ${h}
 `));
   parts.push(pkt("done\n"));
-  const r = await fetch(`${remote}/git-upload-pack`, {
-    method: "POST",
-    headers: { "content-type": "application/x-git-upload-pack-request", "accept": "application/x-git-upload-pack-result", ...headers },
-    body: concatBytes(parts)
-  });
-  if (!r.ok) throw new Error(`upload-pack ${r.status}: ${(await r.text()).slice(0, 180)}`);
-  const buf = new Uint8Array(await r.arrayBuffer());
+  const body = concatBytes(parts);
+  const reqHeaders = { "content-type": "application/x-git-upload-pack-request", "accept": "application/x-git-upload-pack-result", ...headers };
+  const MAX_ATTEMPTS = 6;
+  let buf;
+  for (let attempt = 1; ; attempt++) {
+    try {
+      const r = await fetch(`${remote}/git-upload-pack`, { method: "POST", headers: reqHeaders, body, signal: AbortSignal.timeout(18e4) });
+      if (!r.ok) throw new Error(`upload-pack ${r.status}: ${(await r.text()).slice(0, 180)}`);
+      buf = new Uint8Array(await r.arrayBuffer());
+      break;
+    } catch (e) {
+      const msg = String(e?.message || e);
+      const transient = /terminated|other side closed|socket|ECONNRESET|ECONNREFUSED|UND_ERR|fetch failed|network|aborted|timeout/i.test(msg) && !/upload-pack \d{3}:/.test(msg);
+      if (!transient || attempt >= MAX_ATTEMPTS) throw e;
+      await new Promise((res) => setTimeout(res, Math.min(4e3, 400 * attempt)));
+    }
+  }
   const { lines, rest } = readPktLines(buf, 0);
   const packChunks = [];
   let sideband = false;

package/dart/pubspec.yaml

@@ -7,7 +7,7 @@ repository: https://github.com/Captain-App/nomos2
 description: >-
   Nomos 2 Dart client — generated domain values, intent payloads and application
   lifecycle types over the typed Nomos kernel protocol and USDA custody model.
-version: 0.64.39
+version: 0.64.40
 
 environment:
   sdk: ^3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.105.24",
+  "version": "0.107.0",
   "type": "module",
   "sideEffects": false,
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",

package/runtime/generated-application-host.js

@@ -6612,6 +6612,56 @@ async function lsRefs(remote, headers = {}, { service = "git-upload-pack", prefi
   }
   return refs;
 }
+async function fetchPack(remote, headers = {}, { wants = [], haves = [] } = {}) {
+  wants = wants.filter((w) => /^[0-9a-f]{40}$/.test(w) && w !== ZERO_OID);
+  if (!wants.length) return null;
+  const caps = "ofs-delta agent=nomos-cloud";
+  const parts = [];
+  wants.forEach((w, i) => parts.push(pkt(`want ${w}${i === 0 ? " " + caps : ""}
+`)));
+  parts.push(FLUSH);
+  for (const h of haves) if (/^[0-9a-f]{40}$/.test(h) && h !== ZERO_OID) parts.push(pkt(`have ${h}
+`));
+  parts.push(pkt("done\n"));
+  const body = concatBytes(parts);
+  const reqHeaders = { "content-type": "application/x-git-upload-pack-request", "accept": "application/x-git-upload-pack-result", ...headers };
+  const MAX_ATTEMPTS = 6;
+  let buf;
+  for (let attempt = 1; ; attempt++) {
+    try {
+      const r = await fetch(`${remote}/git-upload-pack`, { method: "POST", headers: reqHeaders, body, signal: AbortSignal.timeout(18e4) });
+      if (!r.ok) throw new Error(`upload-pack ${r.status}: ${(await r.text()).slice(0, 180)}`);
+      buf = new Uint8Array(await r.arrayBuffer());
+      break;
+    } catch (e) {
+      const msg = String(e?.message || e);
+      const transient = /terminated|other side closed|socket|ECONNRESET|ECONNREFUSED|UND_ERR|fetch failed|network|aborted|timeout/i.test(msg) && !/upload-pack \d{3}:/.test(msg);
+      if (!transient || attempt >= MAX_ATTEMPTS) throw e;
+      await new Promise((res) => setTimeout(res, Math.min(4e3, 400 * attempt)));
+    }
+  }
+  const { lines, rest } = readPktLines(buf, 0);
+  const packChunks = [];
+  let sideband = false;
+  for (const line of lines) {
+    if (line.length === 0) continue;
+    const head = dec3.decode(line.subarray(0, Math.min(line.length, 3)));
+    if (head === "NAK" || head === "ACK" || head === "ERR" || head.startsWith("sha")) continue;
+    const band = line[0];
+    if (band === 1) {
+      packChunks.push(line.subarray(1));
+      sideband = true;
+    } else if (band === 2) {
+    } else if (band === 3) {
+      throw new Error("upload-pack fatal: " + dec3.decode(line.subarray(1)).slice(0, 180));
+    }
+  }
+  const pack = sideband ? concatBytes(packChunks) : buf.subarray(rest);
+  if (pack.length < 12 || dec3.decode(pack.subarray(0, 4)) !== "PACK") {
+    throw new Error(`upload-pack: no pack in response (${pack.length}B, sideband=${sideband})`);
+  }
+  return pack;
+}
 async function pushPack(remote, headers = {}, { updates = [], pack = null } = {}, fetchImpl = fetch) {
   if (!updates.length) return { ok: true, noop: true };
   const body = concatBytes([receivePackCommandPrefix(updates), pack && pack.length ? pack : EMPTY_PACK]);
@@ -12036,6 +12086,33 @@ ${String(commit).toLowerCase()}`;
   const addReadRemote = async () => {
   };
   const applyPack = (packB64, head) => provider.applyPack(packB64, head);
+  const directFullClone = async (label) => {
+    let lease = null;
+    try {
+      const r = await _fetch(`${base}/v2/workspaces/${workspace}/git-read-lease`, { headers: authHeaders });
+      if (r.ok) {
+        const d = await r.json();
+        if (d && d.ok && typeof d.remote === "string" && typeof d.token === "string") lease = { remote: d.remote, token: d.token };
+      }
+    } catch {
+    }
+    if (!lease) return false;
+    const _f = span("receive", `${label} (direct artifacts)`, "cfetch", {});
+    try {
+      const auth = { Authorization: "Basic " + btoa("x:" + lease.token) };
+      const refs = await lsRefs(lease.remote, auth, { service: "git-upload-pack", prefix: "refs/heads/main" });
+      const head = refs["refs/heads/main"];
+      if (!head || !/^[0-9a-f]{40}$/i.test(head)) return false;
+      const pack = await fetchPack(lease.remote, auth, { wants: [head] });
+      if (!pack || !pack.byteLength) return false;
+      applyPack(nmsInternalSnapshotToBase64(pack), head);
+      return true;
+    } catch {
+      return false;
+    } finally {
+      _f.end();
+    }
+  };
   try {
     await provider.boot({ base, workspace, branch: BRANCH, repoArg, restoreSnapshot: restoreFrom || null, fetchImpl: _fetch, authHeaders });
   } catch (error) {
@@ -12213,7 +12290,7 @@ ${String(commit).toLowerCase()}`;
       _bootLedger.end();
       if (!allowUnborn) throw new Error(`workspace '${workspace}' has no ledger main \u2014 create it first (POST /v2/workspaces/${workspace})`);
     } else {
-      await fetchAndApplyPack("", "boot: fetch full pack");
+      if (!await directFullClone("boot: full pack")) await fetchAndApplyPack("", "boot: fetch full pack");
       const mounted = await mountWithResidency(remoteMain, "boot restore");
       if (mounted && typeof mounted === "object" && mounted.kernelSpans) {
         bootKernelSpans = mounted.kernelSpans;
@@ -12748,7 +12825,7 @@ ${String(commit).toLowerCase()}`;
   const forceFullMainHistory = async (why, _cause) => {
     const _full = span("receive", `${why}: re-pull FULL main`, "cfetch");
     try {
-      await fetchAndApplyPack("", `${why}: full main pack`);
+      if (!await directFullClone(`${why}: full main`)) await fetchAndApplyPack("", `${why}: full main pack`);
     } finally {
       _full.end();
     }

package/src/aggregate.ts

@@ -61,14 +61,20 @@ const READ_CAP_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
 /**
  * THE READ AUDIENCE (secure-by-default rework — `architecture/secure_by_default_dsl.md`). Every
  * aggregate DECLARES who may read it; there is no silent default (the compiler refuses an undeclared
- * aggregate). Three choices:
+ * aggregate). Four choices:
  *   • `public`        — anyone reads (plaintext). The deliberate exception.
  *   • `readableBy`    — holders of `cap` read (gate-enforced). Sugar over the shipped read-visibility
  *                       (`requires(cap)`); per-field `.secret()` escalates to team-E2E.
+ *   • `ownerReadable` — the workspace owner reads (plaintext, gate-enforced). Owner-only WITHOUT the
+ *                       confidentiality of `owned`: authorization and encryption are separable concerns,
+ *                       and a denormalised access index / discovery card needs the first, not the second.
+ *                       Gates on the framework's workspace-level owner-read relation, which every workspace
+ *                       already holds from birth — so an existing chain adopts it with no backfill and the
+ *                       operator can still serve the plaintext. This is `owned` minus the encryption pass.
  *   • `owned`         — the owner reads; owner = the verified authoring principal, stamped into the
  *                       obscure framework field. The read rule is record-grained so later sharing can
  *                       extend one record without changing this declaration; content is operator-blind.
- * `.public()`/`.readableBy(cap)`/`.owned()` are the fluent declarations on the aggregate handle.
+ * `.public()`/`.readableBy(cap)`/`.ownerReadable()`/`.owned()` are the fluent declarations on the handle.
  */
 export type Audience =
   | { readonly kind: "public" }
@@ -320,6 +326,11 @@ export interface AudienceMethods<Id extends string, F extends Record<string, Fie
   public(): NameableHandle<Id, F>;
   /** Holders of `capability` may read (gate-enforced) — sugar over `requires(cap)`. */
   readableBy(capability: string): NameableHandle<Id, F>;
+  /** The workspace owner may read (plaintext, gate-enforced). Owner-only authorization WITHOUT `owned`'s
+   *  operator-blind encryption — for a denormalised access index / discovery card the operator legitimately
+   *  serves. Gates on the framework owner-read relation every workspace holds from birth, so it adopts on an
+   *  existing chain with no backfill. Tenant code never names the framework relation. See {@link owned}. */
+  ownerReadable(): NameableHandle<Id, F>;
   /** The verified creator owns this record. Nomos stamps ownership, seats its per-record read relation and
    *  encrypts every non-`.meta()` content field; tenant code never names the framework field/relation. */
   owned(): NameableHandle<Id, F>;
@@ -679,6 +690,14 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
       const v = requires(cap); // validates the capability name
       return build({ kind: "readableBy", cap: v.requires }, v, contracts, dartNameDecl);
     },
+    // Owner-only, PLAINTEXT. Deliberately a `readableBy` audience gating on the framework owner-read
+    // relation — NOT `kind: "owned"`, so the encryption lowering below is skipped and content stays
+    // operator-readable. The relation is seated at workspace scope (`workspace:self#<rel>`) at birth
+    // (see framework/home.ts genesis), which is why an existing chain resolves it with no backfill.
+    // `owned()` is the same read gate PLUS per-record encryption; this is the confidentiality-free rung.
+    ownerReadable: () => {
+      return build({ kind: "readableBy", cap: OWNED_READ_RELATION }, requires(OWNED_READ_RELATION), contracts, dartNameDecl);
+    },
     owned: () => {
       return build({ kind: "owned", ownerField: OWNER_FIELD }, requires(OWNED_READ_RELATION), contracts, dartNameDecl);
     },

package/src/capability_exports.ts

@@ -57,7 +57,7 @@ export function capabilityDeclarationsOf(v: unknown): Record<string, unknown>[]
 // `relations` carries the receipt fence's relation SCHEMA. It MUST expand with the bundle:
 // `.requires(...)` is inert in a law that declares no relation schema, so omitting it would
 // leave every capability looking fenced while enforcing nothing.
-const PIECES = ["aggregate", "obligation", "complete", "fail", "block", "deadLetter", "tasks", "relations", "grantProvider", "revokeProvider"] as const;
+const PIECES = ["aggregate", "obligation", "complete", "fail", "block", "deadLetter", "reschedule", "tasks", "relations", "grantProvider", "revokeProvider"] as const;
 
 /**
  * Expand every `capability()` bundle in an exports bag into discoverable

package/src/compile_package_main.ts

@@ -1664,8 +1664,8 @@ const NOMOS_TYPES_DEP = "^0.8.8";
 // 0.48.x: session-bound clients (XClient.bind/NomosClientInterface/DomainClientSessionMismatch/
 //         DomainNotInstalledForSession, engine.follow, pendingConflicts lanes) — the generated client
 //         REQUIRES this surface. 0.48.1 fixes NomosSession.watchPendingConflicts delegation.
-const NOMOS_CLIENT_DEP = "^0.64.39";
-const NOMOS_FLUTTER_DEP = "^0.63.64";
+const NOMOS_CLIENT_DEP = "^0.64.40";
+const NOMOS_FLUTTER_DEP = "^0.63.68";
 // DRIFT TRIPWIRE: pubspec_pins.test.ts asserts these equal the CURRENT versions in dsl/dart/pubspec.yaml
 // and dsl/dart_types/pubspec.yaml — a Dart release without this bump fails the suite, so tenants never
 // land back in dependency_overrides (the exact co2 report this closes, third occurrence).

package/src/framework/capability.ts

@@ -53,7 +53,7 @@
  * (`architecture/capability_credentials.md`).
  */
 import { z } from "zod";
-import { instance } from "../aggregate.js";
+import { instance, type AggregateHandle } from "../aggregate.js";
 import type { Field } from "../fields.js";
 import { set, type PlannedOp } from "../ops.js";
 import { query, type QueryDecl } from "../query.js";
@@ -215,6 +215,20 @@ export function capability<
   scheduleAfterMs?: number;
   /** Time from acceptance until the obligation is overdue. Defaults to 24h. */
   deadlineAfterMs?: number;
+  /** How many times an overdue-but-still-`requested` obligation may be RE-OPENED in place by
+   *  the bounded `reschedule` verb before the next reschedule dead-letters it. Defaults to 5. */
+  maxRescheduleAttempts?: number;
+  /**
+   * EXISTENCE PRECONDITIONS on the oblige verb: each entry names a request field carrying a
+   * referenced aggregate id; the oblige REFUSES (typed, kernel-evaluated at every gate) when
+   * that row does not exist, so a typo'd address can never seal an unfulfillable obligation.
+   * `rejectCode` defaults to `"<field>-not-found"`. Era-additive.
+   */
+  requestRefsExist?: ReadonlyArray<{
+    field: keyof Req & string;
+    aggregate: AggregateHandle;
+    rejectCode?: string;
+  }>;
   /**
    * THE ACKNOWLEDGED WAIVER — open this capability's Receipts to any authorised author.
    *
@@ -280,6 +294,7 @@ export function capability<
     failDirectiveId: `fail${pascal}`,
     blockDirectiveId: `block${pascal}`,
     deadLetterDirectiveId: `deadLetter${pascal}`,
+    rescheduleDirectiveId: `reschedule${pascal}`,
     params,
     paramsSchema: requestShape,
     // The loop is dynamic (declared field names), so the per-field `set()` typing
@@ -308,6 +323,18 @@ export function capability<
     ...(spec.deadlineAfterMs !== undefined
       ? { deadlineAfterMs: spec.deadlineAfterMs }
       : {}),
+    ...(spec.maxRescheduleAttempts !== undefined
+      ? { maxRescheduleAttempts: spec.maxRescheduleAttempts }
+      : {}),
+    ...(spec.requestRefsExist !== undefined
+      ? {
+          obligationRefsExist: spec.requestRefsExist.map((pre) => ({
+            aggregate: pre.aggregate,
+            idField: pre.field,
+            rejectCode: pre.rejectCode ?? `${pre.field}-not-found`,
+          })),
+        }
+      : {}),
   });
 
   const camel = pascal[0]!.toLowerCase() + pascal.slice(1);
@@ -382,6 +409,18 @@ export function capability<
     fail: fenced(quartet.fail),
     block: fenced(quartet.block),
     deadLetter: fenced(quartet.deadLetter),
+    // The bounded `reschedule` verb is a DRUM-OPERATOR action: the operator decides to retry (or
+    // dead-letter) a stuck obligation; the provider merely FULFILS. So fence it on the SAME
+    // authority as the obligation REQUEST (`requestRequires`, e.g. admin) — NOT the provider
+    // receipt relation. Otherwise the operator who is allowed to REQUEST work cannot re-open it
+    // when the provider stalls, which is exactly the drum's job. Falls back to provider-fenced
+    // (like the receipts) when the capability declares no `requestRequires`.
+    reschedule: spec.requestRequires === undefined
+      ? fenced(quartet.reschedule)
+      : quartet.reschedule.requires(spec.requestRequires.relation, {
+          ...(spec.requestRequires.object !== undefined ? { object: spec.requestRequires.object } : {}),
+          ...(spec.requestRequires.objectFrom !== undefined ? { objectFrom: spec.requestRequires.objectFrom } : {}),
+        }),
     // The relation SCHEMA rides with the bundle so the gate can never be inert (a law without
     // a relation schema does not enforce `.requires` at all).
     relations: capabilityProviderRelations,
@@ -412,6 +451,7 @@ export function capability<
     declaration.fail,
     declaration.block,
     declaration.deadLetter,
+    declaration.reschedule,
   ]) {
     Object.defineProperty(lifecycle, NOMOS_CAPABILITY_DECLARATIONS, {
       value: Object.freeze([declaration]),

package/src/framework/impure_capability.ts

@@ -72,6 +72,8 @@ import { attributionField, t, type Field } from "../fields.js";
 import { Lww } from "../drivers.js";
 import { set, type PlannedOp } from "../ops.js";
 import { directive, type RequirableDirective } from "../directive.js";
+import { query, type QueryDecl } from "../query.js";
+import { readFrameworkDeclared } from "../read.js";
 import { executeDirectiveToIntent } from "../wire_encode.js";
 import type { WireIntent } from "../wire.js";
 import type { Ports } from "../ctx.js";
@@ -124,6 +126,14 @@ export type ImpureCapabilityStatus = (typeof IMPURE_CAPABILITY_STATUSES)[number]
  *  - nextAction     Lww (OPTIONAL) — human/host-action hint, e.g. refreshAuth.
  *  - deadLetterReason Lww (OPTIONAL) — why the obligation was moved to the DLQ.
  *  - deadLetteredAt Int (OPTIONAL) — epoch-ms the obligation entered the DLQ.
+ *  - attempts       Int (OPTIONAL) — how many times an overdue-but-still-`requested`
+ *                   obligation has been RESCHEDULED in place (the bounded in-law
+ *                   `reschedule` verb). Folded ONLY by a reschedule that re-opens the
+ *                   task, so a freshly-obligated task never writes it — ABSENT decodes as
+ *                   0 (the same read-decode discipline as the other optionals). It is the
+ *                   bound the DLQ cap (`maxRescheduleAttempts`) is judged against: once an
+ *                   overdue task has already been rescheduled that many times, the next
+ *                   reschedule dead-letters it instead of re-opening.
  *
  * The OPTIONALs are `.optional()` so a freshly-obligated task (which folds none of them)
  * decodes on the generated read type — the same read-decode discipline the rest of the
@@ -144,6 +154,19 @@ export const IMPURE_CAPABILITY_ENVELOPE = {
   nextAction: t.string().merge(Lww).optional(),
   deadLetterReason: t.string().merge(Lww).optional(),
   deadLetteredAt: t.int().merge(Lww).optional(),
+  // The RESCHEDULE ATTEMPTS counter (OPTIONAL): how many times an overdue-but-non-terminal
+  // (`requested`) obligation has been re-opened in place by the bounded `reschedule` verb.
+  // MUST be `.optional()` — a freshly-obligated task folds it NEVER, so it decodes as ABSENT
+  // (read as 0); making it required would break decode of every pre-existing task AND the era
+  // rule (old chains fold no `attempts`). Judged against `maxRescheduleAttempts` to bound retries.
+  attempts: t.int().merge(Lww).optional(),
+  // TEMPO LIMIT-BREACH facts (OPTIONAL — era-safe): stamped by the bounded `reschedule` verb
+  // when the drum judges a still-`requested` task past its DECLARED `limitMs` (a tenant request
+  // field, when the capability declares one). Lww-last is enough for the projection — every
+  // stamp is an ordinary Intent in the chain, so the full breach history stays auditable.
+  // Limits are law; ESTIMATE breaches are read-side telemetry and never fold here.
+  limitBreachedAt: t.int().merge(Lww).optional(),
+  limitBreachElapsedMs: t.int().merge(Lww).optional(),
   // The FRAMEWORK Obligation↔Receipt CLOSURE link (OPTIONAL): the id of the Obligation this
   // RECEIPT closes (== the task's own requestId — the reactor mutates the task instance).
   // GENERIC, written by every impureCapability Receipt (complete OR fail), so the read
@@ -246,6 +269,18 @@ const deadLetterSchema = z.object({
   deadLetteredAt: z.number().int(),
 });
 
+/**
+ * The RESCHEDULE payload: which obligation to judge. Deliberately carries ONLY the requestId
+ * — the reschedule verb reads the task's OWN committed lifecycle state (status / deadlineAt /
+ * attempts) through the captured-read lane and reads "now" from the deterministic captured
+ * clock, so a caller cannot spoof the overdue-ness verdict or the fresh timing. The provider /
+ * drum authority authors it; the plan decides in-law whether it is a no-op, an in-place
+ * re-open, or a dead-letter.
+ */
+const rescheduleSchema = z.object({
+  requestId: z.string(),
+});
+
 /**
  * The three plan builders. Each takes the task aggregate handle + the (already
  * Zod-validated) payload and returns the `PlannedOp[]` writing the envelope. A tenant
@@ -372,6 +407,42 @@ export function deadLetterOps(
   ];
 }
 
+/**
+ * rescheduleOps — the IN-PLACE RE-OPEN half of the bounded `reschedule` verb (NOT a receipt,
+ * NOT terminal). Advances the timing window (`scheduledAt`/`deadlineAt`), bumps the `attempts`
+ * counter, and KEEPS `status:'requested'`. Because the task stays `requested` (non-terminal),
+ * the kernel's terminal-once gate does NOT treat this as a terminal transition — it is the one
+ * legal in-place mutation of a live obligation's timing (kernel-verified: mutating a
+ * still-`requested` task is not a receipt against a terminal obligation). Symmetrical with the
+ * terminal op-builders above: it writes ONLY envelope fields, bound to the task instance (#105).
+ */
+export function rescheduleOps(
+  aggregateId: string,
+  p: {
+    requestId: string;
+    scheduledAt: number;
+    deadlineAt: number;
+    attempts: number;
+    /** Present iff this re-open was forced by a DECLARED-LIMIT breach (not the deadline). */
+    limitBreach?: { at: number; elapsedMs: number };
+  },
+): PlannedOp[] {
+  const taskInstance = envelopeInstance(aggregateId, p.requestId);
+  return [
+    set(taskInstance, "scheduledAt", p.scheduledAt),
+    set(taskInstance, "deadlineAt", p.deadlineAt),
+    set(taskInstance, "attempts", p.attempts),
+    // KEEP status:'requested' — re-opening a non-terminal task, never a terminal transition.
+    set(taskInstance, "status", "requested"),
+    ...(p.limitBreach !== undefined
+      ? [
+          set(taskInstance, "limitBreachedAt", p.limitBreach.at),
+          set(taskInstance, "limitBreachElapsedMs", p.limitBreach.elapsedMs),
+        ]
+      : []),
+  ];
+}
+
 /**
  * The generated directive QUARTET for a impure capability. A domain dev calls
  * {@link impureCapability} ONCE and gets:
@@ -412,6 +483,15 @@ export interface ImpureCapability<
   readonly fail: RequirableDirective<z.infer<typeof failSchema>>;
   readonly block: RequirableDirective<z.infer<typeof blockSchema>>;
   readonly deadLetter: RequirableDirective<z.infer<typeof deadLetterSchema>>;
+  /**
+   * The bounded IN-LAW `reschedule` lifecycle verb (provider / drum-authority action). Its plan
+   * reads the task's OWN committed `{status, deadlineAt, attempts}` through the captured-read
+   * lane and judges overdue-ness against the deterministic captured clock, then either NO-OPs
+   * (terminal, or not yet overdue), RE-OPENS in place (`rescheduleOps`, bumping `attempts` +
+   * advancing the window, keeping `status:'requested'`), or DEAD-LETTERS when at/over the
+   * `maxRescheduleAttempts` cap (reusing `deadLetterOps`). Kernel-legal without any kernel change.
+   */
+  readonly reschedule: RequirableDirective<z.infer<typeof rescheduleSchema>>;
   readonly instanceId: (requestId: string) => string;
   /**
    * The CAPABILITY CREDENTIAL this task's provider must hold to fulfil Orders
@@ -485,6 +565,8 @@ export function impureCapability<
   failDirectiveId: FailId;
   blockDirectiveId: string;
   deadLetterDirectiveId: string;
+  /** The wire id for the bounded `reschedule` verb — caller-supplied, like the DLQ id. */
+  rescheduleDirectiveId: string;
   /** The task's request-param FIELDS (merged onto the envelope for the aggregate shape). */
   params: F;
   /** The task's request-param Zod SHAPE (merged onto the obligation envelope schema). */
@@ -526,6 +608,22 @@ export function impureCapability<
   scheduleAfterMs?: number;
   /** Time from acceptance until the task is overdue. Defaults to 24 hours. */
   deadlineAfterMs?: number;
+  /** How many times an overdue-but-still-`requested` obligation may be RE-OPENED in place by
+   *  `reschedule` before the next reschedule dead-letters it instead. Defaults to 5. */
+  maxRescheduleAttempts?: number;
+  /**
+   * OPTIONAL EXISTENCE PRECONDITIONS on the Obligation verb (kernel-lowered point guards):
+   * each entry refuses the oblige when the row the named request field references is ABSENT,
+   * so a typo'd address can never seal an unfulfillable obligation that only surfaces as
+   * tempo-breach noise later. Era-additive — declaring nothing changes nothing on the wire.
+   */
+  obligationRefsExist?: ReadonlyArray<{
+    aggregate: AggregateHandle;
+    /** The obligation request field carrying the referenced aggregate's id. */
+    idField: string;
+    /** The typed refusal code (e.g. `"delivery-product-not-found"`). */
+    rejectCode: string;
+  }>;
 }): ImpureCapability<Id, ParamsShape, F, ReceiptShape> {
   const taskAggregate = impureCapabilityAggregate(spec.aggregateId, spec.params);
   const obligationPayload = z.object(spec.paramsSchema);
@@ -549,13 +647,37 @@ export function impureCapability<
   const typedFailSchema = failSchema.extend(typedRequestId);
   const typedBlockSchema = blockSchema.extend(typedRequestId);
   const typedDeadLetterSchema = deadLetterSchema.extend(typedRequestId);
-
-  const obligation: RequirableDirective<ObligationPayload<ParamsShape>> = directive(
+  const typedRescheduleSchema = rescheduleSchema.extend(typedRequestId);
+  // THE BY-ID SELF-READ (the #58 captured-read lane): the reschedule plan reads the task's OWN
+  // committed lifecycle state by its requestId (== the instance id), keyed on the envelope's
+  // indexed `requestId` field. Declared here in the factory (the `tasks`/TasksByStatus query is
+  // keyed on `status`, so this is the by-id variant the reschedule verb needs) and DECLARED on
+  // the directive via `.reads(...)`; the compiler seats it in the domain automatically off that
+  // declaration, so it is routable even though it is not separately exported.
+  const taskById: QueryDecl = query(`${spec.aggregateId}ById`)
+    .key("requestId")
+    .returns(taskAggregate);
+  const maxRescheduleAttempts = spec.maxRescheduleAttempts ?? 5;
+
+  let obligationBuilder = directive(
     spec.obligationDirectiveId,
   )
     .creates(taskAggregate)
-    .payload(obligationPayload)
-    .plan((p, ctx) => {
+    .payload(obligationPayload);
+  // THE EXISTENCE FENCE (CO2-1624): refuse an oblige whose request references a row that does
+  // not exist. Chained BEFORE `.plan` so each guard lowers into the manifest as a typed point
+  // precondition the kernel evaluates at every gate — author, edge admission, verify_chain.
+  for (const pre of spec.obligationRefsExist ?? []) {
+    obligationBuilder = obligationBuilder.precondition(
+      pre.aggregate,
+      ({ row, intent }) => ({
+        id: intent.field(pre.idField as never) as never,
+        holds: row.exists(),
+      }),
+      pre.rejectCode,
+    );
+  }
+  const obligationDirective = obligationBuilder.plan((p, ctx) => {
       // The caller supplies BUSINESS PARAMS only. Nomos owns the task identity,
       // provenance and lifecycle clock so generated clients cannot accidentally
       // spoof or hand-roll the obligation envelope.
@@ -578,6 +700,7 @@ export function impureCapability<
         .set("status", "requested");
       return spec.writeParams(impureCapabilityInstanceId(requestId), params);
     });
+  const obligation = obligationDirective as RequirableDirective<ObligationPayload<ParamsShape>>;
 
   // The two branches above are distinct object schemas; the declared payload TYPE is the
   // `CompletePayload<ReceiptShape>` conditional, so name it once here rather than leaking a
@@ -614,6 +737,73 @@ export function impureCapability<
     .payload(typedDeadLetterSchema)
     .plan((p) => deadLetterOps(spec.aggregateId, p));
 
+  // THE BOUNDED `reschedule` VERB. It `.mutates` the task and reads THAT SAME task's committed
+  // lifecycle state by id (the captured-read lane, declared via `.reads(taskById)`), judging
+  // overdue-ness IN-LAW against the deterministic captured clock — never `Date.now()`. Three
+  // outcomes, mirroring the consequent-outbox cap discipline (never touch a terminal task; only
+  // re-open genuinely-overdue work; dead-letter once the retry budget is exhausted):
+  //   1. status !== "requested"          → NO-OP (never mutate a terminal task).
+  //   2. now <= deadlineAt AND no declared-limit breach → NO-OP (not overdue yet).
+  //   3. overdue & attempts < cap        → RE-OPEN in place (rescheduleOps): fresh window +
+  //                                        attempts+1, KEEP status:'requested' (kernel-legal —
+  //                                        a still-`requested` task is non-terminal).
+  //   4. overdue & attempts >= cap       → DEAD-LETTER (deadLetterOps, terminal) with the
+  //                                        overdue reason.
+  const reschedule = directive(spec.rescheduleDirectiveId)
+    .mutates(taskAggregate)
+    .payload(typedRescheduleSchema)
+    .plan((p, ctx) => {
+      const now = ctx.clock().physical;
+      // Read the task's OWN committed state by id off the #58 captured-read lane. A framework
+      // plan bundled via the `@githolon/dsl` barrel reads through `readFrameworkDeclared` (the
+      // declared-by-construction twin of `read()`), so it never pins the tenant captured-read
+      // compile marker into the barrel lump; the directive DECLARES `taskById` below.
+      const rows = readFrameworkDeclared<Array<Record<string, unknown>>>(taskById.id, {
+        requestId: p.requestId,
+      });
+      const raw = Array.isArray(rows) && rows.length > 0 ? rows[0] : undefined;
+      // Projected rows are `{type,id,data:{…fields}}`; folded shapes may be flat — accept both.
+      const data = (raw && typeof raw === "object" && typeof (raw as { data?: unknown }).data === "object"
+        ? (raw as { data: Record<string, unknown> }).data
+        : raw) as Record<string, unknown> | undefined;
+      const status = data?.status as string | undefined;
+      // (1) NEVER touch a terminal task — only `requested` is non-terminal.
+      if (status !== "requested") return [];
+      const deadlineAt = Number(data?.deadlineAt ?? 0);
+      // THE DECLARED-LIMIT JUDGMENT (tempo): a capability whose request declares `limitMs`
+      // folds it onto this same task row, and elapsed time past that limit is judged exactly
+      // like overdue-ness — in-law, from the deterministic captured clock, against the task's
+      // own committed `scheduledAt`. Absent `limitMs` (legacy work) ≡ no limit — era-safe.
+      const limitMsRaw = data?.limitMs;
+      const limitMs = typeof limitMsRaw === "number" && limitMsRaw >= 0 ? limitMsRaw : undefined;
+      const scheduledAt = Number(data?.scheduledAt ?? 0);
+      const elapsedMs = now - scheduledAt;
+      const pastLimit = limitMs !== undefined && scheduledAt > 0 && elapsedMs > limitMs;
+      // (2) Neither past the committed deadline NOR past the declared limit — no-op.
+      if (now <= deadlineAt && !pastLimit) return [];
+      const attempts = Number(data?.attempts ?? 0);
+      // (4) Overdue AND the retry budget is exhausted → terminal dead-letter (reuse deadLetterOps).
+      if (attempts >= maxRescheduleAttempts) {
+        return deadLetterOps(spec.aggregateId, {
+          requestId: p.requestId,
+          deadLetterReason: pastLimit
+            ? `overdue: exhausted ${maxRescheduleAttempts} reschedule attempts (declared limit ${limitMs}ms breached; elapsed ${elapsedMs}ms)`
+            : `overdue: exhausted ${maxRescheduleAttempts} reschedule attempts`,
+          deadLetteredAt: now,
+        });
+      }
+      // (3) Overdue (or limit-breached) but under the cap → RE-OPEN in place with a fresh
+      // window + bumped attempts; a limit breach additionally stamps the breach fact.
+      return rescheduleOps(spec.aggregateId, {
+        requestId: p.requestId,
+        scheduledAt: now + (spec.scheduleAfterMs ?? 0),
+        deadlineAt: now + (spec.deadlineAfterMs ?? 24 * 60 * 60 * 1000),
+        attempts: attempts + 1,
+        ...(pastLimit ? { limitBreach: { at: now, elapsedMs } } : {}),
+      });
+    })
+    .reads(taskById);
+
   return {
     aggregate: taskAggregate,
     obligation,
@@ -622,6 +812,7 @@ export function impureCapability<
     fail,
     block,
     deadLetter,
+    reschedule,
     instanceId: impureCapabilityInstanceId,
     // Omit-when-absent (hash discipline): a capability-free declaration carries
     // NO key at all, so its bundled source — and the package hash — is unchanged.

package/src/framework/owned_custody.ts

@@ -39,6 +39,7 @@ export const OWNED_RECOVERY_ACCEPT_DIRECTIVE = "nomos_internal_accept_owned_reco
 const OWNED_RECOVERY_FAIL_DIRECTIVE = "nomos_internal_fail_owned_recovery_7c1f5e";
 const OWNED_RECOVERY_BLOCK_DIRECTIVE = "nomos_internal_block_owned_recovery_7c1f5e";
 const OWNED_RECOVERY_DEAD_LETTER_DIRECTIVE = "nomos_internal_dead_letter_owned_recovery_7c1f5e";
+const OWNED_RECOVERY_RESCHEDULE_DIRECTIVE = "nomos_internal_reschedule_owned_recovery_7c1f5e";
 const keySubject = z.string().regex(/^key:[0-9a-f]{64}$/);
 const principal = z.string().regex(/^user:[A-Za-z0-9][A-Za-z0-9_.-]*$/);
 const b64 = z.string().regex(/^[A-Za-z0-9+/]+={0,2}$/);
@@ -99,6 +100,7 @@ const ownedRecoveryLifecycle = impureCapability({
   failDirectiveId: OWNED_RECOVERY_FAIL_DIRECTIVE,
   blockDirectiveId: OWNED_RECOVERY_BLOCK_DIRECTIVE,
   deadLetterDirectiveId: OWNED_RECOVERY_DEAD_LETTER_DIRECTIVE,
+  rescheduleDirectiveId: OWNED_RECOVERY_RESCHEDULE_DIRECTIVE,
   params: recoveryOrderFields,
   paramsSchema: {
     ownerPrincipal: principal,
@@ -128,6 +130,7 @@ const hiddenRecoveryLifecycle = {
   fail: hidden(ownedRecoveryLifecycle.fail),
   block: hidden(ownedRecoveryLifecycle.block),
   deadLetter: hidden(ownedRecoveryLifecycle.deadLetter),
+  reschedule: hidden(ownedRecoveryLifecycle.reschedule),
 };
 const ownedRecoveryCapability = {
   ...ownedRecoveryLifecycle,
@@ -140,6 +143,7 @@ const ownedRecoveryCapability = {
   fail: hiddenRecoveryLifecycle.fail,
   block: hiddenRecoveryLifecycle.block,
   deadLetter: hiddenRecoveryLifecycle.deadLetter,
+  reschedule: hiddenRecoveryLifecycle.reschedule,
   __isCapabilityDecl: true as const,
 };
 

package/src/framework/sync_lifecycle.ts

@@ -98,6 +98,7 @@ const workspaceSyncTask = impureCapability({
   failDirectiveId: "failWorkspaceSync",
   blockDirectiveId: "blockWorkspaceSync",
   deadLetterDirectiveId: "deadLetterWorkspaceSync",
+  rescheduleDirectiveId: "rescheduleWorkspaceSync",
   params: syncParams,
   paramsSchema: {
     workspaceId: z.string(),