@githolon/dsl 0.106.0 → 0.107.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.106.0",
+  "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/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";
@@ -218,6 +218,17 @@ export function capability<
   /** 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.
    *
@@ -315,6 +326,15 @@ export function capability<
     ...(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);

package/src/framework/impure_capability.ts

@@ -160,6 +160,13 @@ export const IMPURE_CAPABILITY_ENVELOPE = {
   // (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
@@ -411,7 +418,14 @@ export function deadLetterOps(
  */
 export function rescheduleOps(
   aggregateId: string,
-  p: { requestId: string; scheduledAt: number; deadlineAt: number; attempts: number },
+  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 [
@@ -420,6 +434,12 @@ export function rescheduleOps(
     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),
+        ]
+      : []),
   ];
 }
 
@@ -591,6 +611,19 @@ export function impureCapability<
   /** 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);
@@ -626,12 +659,25 @@ export function impureCapability<
     .returns(taskAggregate);
   const maxRescheduleAttempts = spec.maxRescheduleAttempts ?? 5;
 
-  const obligation: RequirableDirective<ObligationPayload<ParamsShape>> = directive(
+  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.
@@ -654,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
@@ -696,7 +743,7 @@ export function impureCapability<
   // 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               → NO-OP (not overdue yet).
+  //   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).
@@ -723,23 +770,36 @@ export function impureCapability<
       // (1) NEVER touch a terminal task — only `requested` is non-terminal.
       if (status !== "requested") return [];
       const deadlineAt = Number(data?.deadlineAt ?? 0);
-      // (2) Not overdue yet — the deterministic clock has not passed the committed deadline.
-      if (now <= deadlineAt) return [];
+      // 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: `overdue: exhausted ${maxRescheduleAttempts} reschedule attempts`,
+          deadLetterReason: pastLimit
+            ? `overdue: exhausted ${maxRescheduleAttempts} reschedule attempts (declared limit ${limitMs}ms breached; elapsed ${elapsedMs}ms)`
+            : `overdue: exhausted ${maxRescheduleAttempts} reschedule attempts`,
           deadLetteredAt: now,
         });
       }
-      // (3) Overdue but under the cap → RE-OPEN in place with a fresh window + bumped attempts.
+      // (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);