@githolon/dsl 0.102.4 → 0.103.0

package/src/compose.ts

@@ -24,7 +24,7 @@
  * `CompositionViolation`, never silently coerced.
  */
 import { createHash } from "node:crypto";
-import { canonicalJson } from "./manifest.js";
+import { canonicalJson } from "./canonical_json.js";
 
 /**
  * A composable law unit (modelled on a directive/role). The typed-rule fields:

package/src/directive.ts

@@ -29,11 +29,24 @@ import { zodDef, zodKind, zodObjectShape } from "./zod_introspection.js";
 import {
   isFromPayloadRef,
   isTrustPolicyDecl,
+  NomosSourceFrontier,
   __registerMonotoneForeignQuery,
   type FromPayloadRef,
   type TrustPolicyDecl,
   type ForeignReadEdge,
 } from "./attested_core.js";
+import {
+  buildPointGuard,
+  evaluatePointGuard,
+  type PointGuardContext,
+  type PointGuardDeclaration,
+  type PointGuardSpec,
+} from "./point_guard.js";
+import {
+  resolveInvariantReadId,
+  type InvariantReadId,
+  type InvariantReadIdPart,
+} from "./framework/workspace_invariant.js";
 
 export type ReferentialMarker = "creates" | "mutates" | "ensures" | "archives";
 
@@ -62,12 +75,20 @@ export interface PreconditionDescriptor {
   readonly fieldNames: readonly string[];
   /** Pure payload → target instance id (no clock, no IO — re-derived identically on every peer). */
   readonly idField: (payload: unknown) => string;
+  /** Typed payload path for native USDA read selection. Legacy callback selectors omit this and
+   * remain compiler-visible migration debt; new code should pass a payload key or `.precondition`. */
+  readonly idPayloadPath?: readonly string[];
+  /** Complete typed USDA id expression. Present for keys, literals and templates; absent only
+   * for legacy arbitrary callbacks that still require migration. */
+  readonly readId?: InvariantReadId;
   /** The fixed-predicate specialization, or `predicate` for the general `.where` form. */
   readonly kind: "exists" | "absent" | "predicate";
   /** The row predicate — `row` is the resolved snapshot or `undefined` when the instance is absent. */
   readonly predicate: (row: Record<string, unknown> | undefined) => boolean;
   /** The typed refusal code emitted when the predicate is false. */
   readonly rejectCode: string;
+  /** Generic point-state algebra lowered from typed USDA directly into the Rust gate. */
+  readonly pointGuard?: PointGuardSpec;
   /**
    * Why this precondition may intentionally make a fact about private state observable through its
    * public refusal. Set by chaining `.declassify(reason)` directly after the precondition marker;
@@ -76,6 +97,56 @@ export interface PreconditionDescriptor {
   readonly declassify?: string;
 }
 
+type PayloadIdSelector<P> =
+  | Extract<keyof P, string>
+  | ((payload: P) => string)
+  | InvariantReadIdPart
+  | readonly InvariantReadIdPart[];
+
+function payloadIdSelector<P>(selector: PayloadIdSelector<P>): {
+  readonly field: (payload: unknown) => string;
+  readonly path?: readonly string[];
+  readonly readId?: InvariantReadId;
+} {
+  if (typeof selector === "string") {
+    const readId: InvariantReadId = {
+      source: "payload",
+      path: [selector],
+      prefix: "",
+      suffix: "",
+      optional: false,
+    };
+    return {
+      field: (payload) => resolveInvariantReadId(readId, payload as Record<string, unknown>) ?? "",
+      path: [selector],
+      readId,
+    };
+  }
+  if (Array.isArray(selector)) {
+    const readId: InvariantReadId = { source: "template", parts: [...selector], optional: false };
+    return {
+      field: (payload) => resolveInvariantReadId(readId, payload as Record<string, unknown>) ?? "",
+      readId,
+    };
+  }
+  if (typeof selector === "object" && selector !== null && "source" in selector) {
+    if (selector.source === "item") {
+      throw new Error("directive precondition ids cannot use item-relative read parts");
+    }
+    const readId: InvariantReadId = selector.source === "literal"
+      ? selector
+      : selector.transform === "none"
+        ? { source: "payload", path: selector.path, prefix: "", suffix: "", optional: false }
+        : { source: "template", parts: [selector], optional: false };
+    return {
+      field: (payload) => resolveInvariantReadId(readId, payload as Record<string, unknown>) ?? "",
+      ...(readId.source === "payload" ? { path: readId.path } : {}),
+      readId,
+    };
+  }
+  return { field: selector as (payload: unknown) => string };
+}
+
 /**
  * A pure, replay-stable derivation of the authz SCOPE an authored intent targets,
  * from its payload — e.g. `(p) => ["site", p.siteId]`. It MUST be a pure function
@@ -90,8 +161,12 @@ export interface PreconditionDescriptor {
 export interface SecondaryOutput {
   readonly marker: ReferentialMarker;
   readonly aggregateId: string;
+  /** Process-local compiler link; canonical law emits the referenced identity, never this object. */
+  readonly aggregate?: AggregateHandle;
   /** This action may affect more than one record of this aggregate type. */
   readonly many?: true;
+  /** This action affects zero or one record of this aggregate type. */
+  readonly optional?: true;
 }
 
 /**
@@ -133,6 +208,21 @@ export interface Directive<P = unknown> {
   readonly id: string;
   readonly marker: ReferentialMarker;
   readonly aggregateId: string;
+  /**
+   * This declaration contributes certified law metadata but is not an
+   * executable offer. The compiler must never publish a plan route for it.
+   * Used for structural sanctions such as the generated secondary-Ensure
+   * declaration; ordinary tenant and framework actions leave it unset.
+   */
+  readonly manifestOnly?: true;
+  /** Typed declaration target retained for compiler composition; omitted by every wire/law serializer. */
+  readonly aggregate?: AggregateHandle;
+  /**
+   * Business-result cardinality for the primary marker target. The default is
+   * exactly one; `.affectsMany()` and `.affectsOptional()` opt into the other
+   * two generated client shapes without changing the directive's replay law.
+   */
+  readonly outputCardinality?: "many" | "optional";
   /**
    * MULTI-OUTPUT DIRECTIVES: additional aggregates this directive declares it writes, beyond the primary
    * marker target. Present iff the directive chained `.alsoEnsures/.alsoCreates/.alsoMutates/.alsoArchives`
@@ -162,6 +252,13 @@ export interface Directive<P = unknown> {
    * application APIs. Set only through `nomosImplementationDetail(...)`.
    */
   readonly businessBirthInternal?: true;
+  /**
+   * Compiler-generated child seed produced from `birth(..., { initialise })`.
+   * Its effect signature is owned by the lowering pass: tenant authors never
+   * receive this directive and therefore cannot honestly call `.alsoWrites()`
+   * on it themselves. Omitted from canonical law output.
+   */
+  readonly businessBirthSeed?: true;
   /**
    * FRAMEWORK-SHARED brand (Dart-codegen hygiene). Set (by `framework/framework_aggregates.ts`) ONLY on
    * the framework-owned directive singletons declared in `dsl/src/framework/` (the relate/signer/enroll
@@ -445,21 +542,33 @@ export interface RequirableDirective<P> extends Directive<P> {
     genesisField?: string;
     keyHashesField?: string;
   }): RequirableDirective<P>;
+  /** Declare that this action can affect several records of its primary aggregate. */
+  affectsMany(): RequirableDirective<P>;
+  /** Declare that this action can affect zero or one record of its primary aggregate. */
+  affectsOptional(): RequirableDirective<P>;
   /**
    * MULTI-OUTPUT: declare an ADDITIONAL aggregate this directive writes (beyond its primary marker target),
    * so generated docs/proof/client metadata name every output ("writes A + B") instead of one by convention.
    * `.alsoEnsures/.alsoCreates/.alsoMutates/.alsoArchives` are the marker-specific sugar; `.alsoWrites` takes
    * an explicit marker. Chainable + additive (a directive that never calls these is byte-identical). The
-   * kernel folds by the plan's ops regardless — this is descriptive law metadata, not a write-restriction.
+   * The compiler checks observable marked plan outputs against this certified effect signature; an
+   * undeclared secondary output is a compile error rather than a runtime-only projection surprise.
    */
   alsoWrites(aggregate: AggregateHandle, marker: ReferentialMarker): RequirableDirective<P>;
   alsoWritesMany(aggregate: AggregateHandle, marker: ReferentialMarker): RequirableDirective<P>;
+  alsoWritesOptional(aggregate: AggregateHandle, marker: ReferentialMarker): RequirableDirective<P>;
   alsoEnsures(aggregate: AggregateHandle): RequirableDirective<P>;
   alsoCreates(aggregate: AggregateHandle): RequirableDirective<P>;
   alsoEnsuresMany(aggregate: AggregateHandle): RequirableDirective<P>;
   alsoCreatesMany(aggregate: AggregateHandle): RequirableDirective<P>;
+  alsoEnsuresOptional(aggregate: AggregateHandle): RequirableDirective<P>;
+  alsoCreatesOptional(aggregate: AggregateHandle): RequirableDirective<P>;
   alsoMutates(aggregate: AggregateHandle): RequirableDirective<P>;
   alsoArchives(aggregate: AggregateHandle): RequirableDirective<P>;
+  alsoMutatesMany(aggregate: AggregateHandle): RequirableDirective<P>;
+  alsoArchivesMany(aggregate: AggregateHandle): RequirableDirective<P>;
+  alsoMutatesOptional(aggregate: AggregateHandle): RequirableDirective<P>;
+  alsoArchivesOptional(aggregate: AggregateHandle): RequirableDirective<P>;
   /**
    * Declare the authz pre-condition: the `capability` the actor must hold (defaults
    * to the directive id) at the scope `scopeFrom(payload)` derives (defaults to root).
@@ -702,19 +811,22 @@ class DirectivePlanStep<Id extends string, P> {
    * function of the inferred payload. ONLY valid on a `.creates` directive (it defines the created id).
    * Additive; `.creates(Agg)` with no `.withId` is the minted path (byte-identical).
    */
-  withId(idFn: (payload: P) => string): DirectivePlanStep<Id, P> {
+  withId(idSelector: PayloadIdSelector<P>): DirectivePlanStep<Id, P> {
     if (this.marker !== "creates") {
       throw new Error(
         `directive('${this.id}').withId(...) is only valid on a .creates(...) directive — it fixes the ` +
           `CREATED aggregate's caller-supplied id (a .${this.marker} directive targets an existing id).`,
       );
     }
-    const idField = idFn as (payload: unknown) => string;
+    const selected = payloadIdSelector(idSelector);
+    const idField = selected.field;
     return this.with(
       {
         aggregateId: this.aggregate.id,
         fieldNames: Object.keys(this.aggregate.fields).sort(),
         idField,
+        ...(selected.path === undefined ? {} : { idPayloadPath: selected.path }),
+        ...(selected.readId === undefined ? {} : { readId: selected.readId }),
         kind: "absent",
         predicate: (row) => row === undefined,
         rejectCode: `${shortName(this.aggregate.id)}-exists`,
@@ -730,13 +842,16 @@ class DirectivePlanStep<Id extends string, P> {
    */
   requiresExisting<F extends Record<string, Field>>(
     aggregate: AggregateHandle<string, F>,
-    idFn: (payload: P) => string,
+    idSelector: PayloadIdSelector<P>,
     rejectCode?: string,
   ): DirectivePlanStep<Id, P> {
+    const selected = payloadIdSelector(idSelector);
     return this.with({
       aggregateId: aggregate.id,
       fieldNames: Object.keys(aggregate.fields).sort(),
-      idField: idFn as (payload: unknown) => string,
+      idField: selected.field,
+      ...(selected.path === undefined ? {} : { idPayloadPath: selected.path }),
+      ...(selected.readId === undefined ? {} : { readId: selected.readId }),
       kind: "exists",
       predicate: (row) => row !== undefined,
       rejectCode: rejectCode ?? `${shortName(aggregate.id)}-not-found`,
@@ -752,20 +867,65 @@ class DirectivePlanStep<Id extends string, P> {
    */
   where<F extends Record<string, Field>>(
     aggregate: AggregateHandle<string, F>,
-    idFn: (payload: P) => string,
+    idSelector: PayloadIdSelector<P>,
     predicate: (row: ReadModelRow<F> | undefined) => boolean,
     rejectCode: string,
   ): DirectivePlanStep<Id, P> {
+    const selected = payloadIdSelector(idSelector);
     return this.with({
       aggregateId: aggregate.id,
       fieldNames: Object.keys(aggregate.fields).sort(),
-      idField: idFn as (payload: unknown) => string,
+      idField: selected.field,
+      ...(selected.path === undefined ? {} : { idPayloadPath: selected.path }),
+      ...(selected.readId === undefined ? {} : { readId: selected.readId }),
       kind: "predicate",
       predicate: predicate as (row: Record<string, unknown> | undefined) => boolean,
       rejectCode,
     });
   }
 
+  /**
+   * A kernel-lowerable point precondition. Unlike `.where(...)`, this callback builds a small typed
+   * algebraic value; it is not tenant code executed at admission. The resulting aggregate lookup,
+   * predicate tree, and refusal code are preserved as typed USDA and evaluated directly by Rust.
+   *
+   *     .precondition(Site, ({ row, intent, all }) => ({
+   *       id: intent.field("siteId"),
+   *       holds: all(row.exists(), row.field("status").ne("deleted")),
+   *     }), "site-not-found-or-deleted")
+   */
+  precondition<F extends Record<string, Field>>(
+    aggregate: AggregateHandle<string, F>,
+    build: (ctx: PointGuardContext<P, F>) => PointGuardDeclaration,
+    rejectCode: string,
+  ): DirectivePlanStep<Id, P> {
+    const pointGuard = buildPointGuard(aggregate, build, rejectCode);
+    return this.with({
+      aggregateId: aggregate.id,
+      fieldNames: Object.keys(aggregate.fields).sort(),
+      idField: (payload) => {
+        let current: unknown = payload;
+        for (const part of pointGuard.idPayloadPath) {
+          if (current === null || typeof current !== "object") return "";
+          current = (current as Record<string, unknown>)[part];
+        }
+        return typeof current === "string" ? current : "";
+      },
+      idPayloadPath: pointGuard.idPayloadPath,
+      readId: {
+        source: "payload",
+        path: pointGuard.idPayloadPath,
+        prefix: "",
+        suffix: "",
+        optional: false,
+      },
+      kind: "predicate",
+      predicate: (row) => evaluatePointGuard(pointGuard.predicate, row, undefined),
+      rejectCode,
+      pointGuard,
+    });
+  }
+
   /**
    * Acknowledge that the MOST RECENT write-path precondition may intentionally reveal one fact about
    * private state through its typed refusal. This is business policy, so it stays beside the condition
@@ -808,6 +968,7 @@ class DirectivePlanStep<Id extends string, P> {
       id: this.id,
       marker: this.marker,
       aggregateId: this.aggregate.id,
+      aggregate: this.aggregate,
       payloadSchema: this.payloadSchema,
       plan: fn,
       declaredReads: [],
@@ -859,20 +1020,32 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
   const alsoWrites = (
     aggregate: AggregateHandle,
     marker: ReferentialMarker,
-    many = false,
+    cardinality: "one" | "many" | "optional" = "one",
   ): RequirableDirective<P> => {
     // Dedup by (marker, aggregateId) + the primary target — declaring the same output twice is a no-op, and
     // re-declaring the primary aggregate is ignored (it is already the marker target). Sorted at emit time.
     const next: SecondaryOutput = {
       marker,
       aggregateId: aggregate.id,
-      ...(many ? { many: true as const } : {}),
+      aggregate,
+      ...(cardinality === "many" ? { many: true as const } : {}),
+      ...(cardinality === "optional" ? { optional: true as const } : {}),
     };
-    const isPrimary = aggregate.id === base.aggregateId;
+    // Only the exact primary EFFECT is already declared. The same aggregate under a
+    // different marker is a distinct lawful consequence: a `.mutates(A)` directive
+    // may deliberately emit an Archive for A and must retain `.alsoArchives(A)` in
+    // its typed effect signature.
+    const isPrimary = aggregate.id === base.aggregateId && marker === base.marker;
     const existing = (base.secondaryOutputs ?? []).find(
       (s) => s.marker === marker && s.aggregateId === aggregate.id,
     );
-    if (isPrimary || (existing !== undefined && (!many || existing.many === true))) {
+    if (
+      isPrimary ||
+      (existing !== undefined &&
+        (cardinality === "one" ||
+          (cardinality === "many" && existing.many === true) ||
+          (cardinality === "optional" && existing.optional === true)))
+    ) {
       return makeRequirable(base);
     }
     if (existing !== undefined) {
@@ -887,6 +1060,8 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
   };
   return {
     ...base,
+    affectsMany: () => makeRequirable({ ...base, outputCardinality: "many" }),
+    affectsOptional: () => makeRequirable({ ...base, outputCardinality: "optional" }),
     example(payload: P): RequirableDirective<P> {
       if (isRuntimeLaw()) {
         // The Node authoring pass already proved this example. Executable law retains it as proof
@@ -991,15 +1166,29 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
     },
     alsoWrites,
     alsoWritesMany: (aggregate: AggregateHandle, marker: ReferentialMarker) =>
-      alsoWrites(aggregate, marker, true),
+      alsoWrites(aggregate, marker, "many"),
+    alsoWritesOptional: (aggregate: AggregateHandle, marker: ReferentialMarker) =>
+      alsoWrites(aggregate, marker, "optional"),
     alsoEnsures: (aggregate: AggregateHandle) => alsoWrites(aggregate, "ensures"),
     alsoCreates: (aggregate: AggregateHandle) => alsoWrites(aggregate, "creates"),
     alsoEnsuresMany: (aggregate: AggregateHandle) =>
-      alsoWrites(aggregate, "ensures", true),
+      alsoWrites(aggregate, "ensures", "many"),
     alsoCreatesMany: (aggregate: AggregateHandle) =>
-      alsoWrites(aggregate, "creates", true),
+      alsoWrites(aggregate, "creates", "many"),
+    alsoEnsuresOptional: (aggregate: AggregateHandle) =>
+      alsoWrites(aggregate, "ensures", "optional"),
+    alsoCreatesOptional: (aggregate: AggregateHandle) =>
+      alsoWrites(aggregate, "creates", "optional"),
     alsoMutates: (aggregate: AggregateHandle) => alsoWrites(aggregate, "mutates"),
     alsoArchives: (aggregate: AggregateHandle) => alsoWrites(aggregate, "archives"),
+    alsoMutatesMany: (aggregate: AggregateHandle) =>
+      alsoWrites(aggregate, "mutates", "many"),
+    alsoArchivesMany: (aggregate: AggregateHandle) =>
+      alsoWrites(aggregate, "archives", "many"),
+    alsoMutatesOptional: (aggregate: AggregateHandle) =>
+      alsoWrites(aggregate, "mutates", "optional"),
+    alsoArchivesOptional: (aggregate: AggregateHandle) =>
+      alsoWrites(aggregate, "archives", "optional"),
     requires(
       relation: string,
       opts?: { object?: string; objectFrom?: { recordType: string; idField: string } },
@@ -1158,7 +1347,11 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
       const byKey = new Map<string, ForeignReadEdge>(prior.map((e) => [canon(e), e]));
       byKey.set(canon(entry), entry);
       const merged = [...byKey.values()].sort((a, b) => (canon(a) < canon(b) ? -1 : canon(a) > canon(b) ? 1 : 0));
-      return makeRequirable({ ...base, declaredForeignReads: merged });
+      // Every admitted foreign read advances the reader-local source frontier in-band.
+      // This is a framework consequence of `.readsFrom`, so make it part of the typed
+      // effect signature here; tenant authors must not know the bookkeeping aggregate.
+      return makeRequirable({ ...base, declaredForeignReads: merged })
+        .alsoEnsures(NomosSourceFrontier);
     },
     emits(eventType: string, opts?: { max?: number }): RequirableDirective<P> {
       // Accumulate one event type onto any prior emits; a `max` bound is recorded only