@githolon/dsl 0.102.5 → 0.103.0

package/src/intent.ts

@@ -18,7 +18,12 @@ import type { Ports } from "./ctx.js";
 import type { PlannedOp } from "./ops.js";
 import type { Field } from "./fields.js";
 import type { AggregateHandle } from "./aggregate.js";
-import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
+import type {
+  InvariantReadBinding,
+  InvariantReadId,
+  InvariantReadIdPart,
+  WorkspaceInvariantDecl,
+} from "./framework/workspace_invariant.js";
 import { businessBirthConsequence, type BusinessBirthDirective } from "./business_birth.js";
 import type { BusinessBirthDecl } from "./births.js";
 import type { WorkspaceSharingPolicy } from "./workspace_sharing.js";
@@ -31,6 +36,132 @@ export interface IntentStep<I = unknown, P = unknown> {
   readonly payload: (facts: I) => P;
 }
 
+const PAYLOAD_TRACE_PATH = Symbol("nomos.intent.payload-trace-path");
+
+type PayloadTrace = {
+  readonly [PAYLOAD_TRACE_PATH]: readonly string[];
+};
+
+/**
+ * An inert symbolic business payload used only while compiling application-language
+ * composition. A private payload mapping may carry a public field through unchanged;
+ * in that case the trace proves the exact public path without parsing JavaScript source.
+ * Any computation/coercion loses the trace and therefore cannot be miscompiled as a
+ * native read recipe.
+ */
+function payloadTrace(path: readonly string[] = []): PayloadTrace {
+  const target = Object.create(null) as PayloadTrace;
+  return new Proxy(target, {
+    get(_target, property) {
+      if (property === PAYLOAD_TRACE_PATH) return path;
+      if (property === "then") return undefined;
+      if (property === Symbol.toPrimitive || property === "toString" || property === "valueOf") {
+        return () => {
+          throw new Error("computed application-language payload field is not a direct path");
+        };
+      }
+      return payloadTrace([...path, String(property)]);
+    },
+  });
+}
+
+function tracedPath(value: unknown): readonly string[] | undefined {
+  if (value === null || typeof value !== "object") return undefined;
+  const path = (value as Partial<PayloadTrace>)[PAYLOAD_TRACE_PATH];
+  return Array.isArray(path) ? path : undefined;
+}
+
+function valueAtPath(value: unknown, path: readonly string[]): unknown {
+  let current = value;
+  for (const part of path) {
+    if (current === null || (typeof current !== "object" && typeof current !== "function")) {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+function remapPayloadPath(
+  mapped: unknown,
+  privatePath: readonly string[],
+): readonly string[] | undefined {
+  return tracedPath(valueAtPath(mapped, privatePath));
+}
+
+function remapStepPayloadPath(
+  step: IntentStep<any, any>,
+  privatePath: readonly string[],
+): readonly string[] | undefined {
+  try {
+    return remapPayloadPath(step.payload(payloadTrace()), privatePath);
+  } catch {
+    return undefined;
+  }
+}
+
+function remapReadPart(
+  part: InvariantReadIdPart,
+  mapped: unknown,
+): InvariantReadIdPart | undefined {
+  if (part.source !== "payload") return part;
+  const path = remapPayloadPath(mapped, part.path);
+  return path === undefined ? undefined : { ...part, path };
+}
+
+function remapReadId(id: InvariantReadId, mapped: unknown): InvariantReadId | undefined {
+  if (id.source === "literal") return id;
+  if (id.source === "payload") {
+    const path = remapPayloadPath(mapped, id.path);
+    return path === undefined ? undefined : { ...id, path };
+  }
+  const parts: InvariantReadIdPart[] = [];
+  for (const part of id.parts) {
+    const remapped = remapReadPart(part, mapped);
+    if (remapped === undefined) return undefined;
+    parts.push(remapped);
+  }
+  return { ...id, parts };
+}
+
+/** Rewrite a private effect's typed point-read recipe onto its public business facts.
+ * Returns undefined unless every payload dependency is structurally proven. */
+function remapNativeReads(
+  reads: readonly InvariantReadBinding[],
+  step: IntentStep<any, any>,
+): readonly InvariantReadBinding[] | undefined {
+  const needsPayload = reads.some((read) =>
+    read.eachPayloadPath !== undefined ||
+    read.id.source === "payload" ||
+    (read.id.source === "template" && read.id.parts.some((part) => part.source === "payload"))
+  );
+  if (!needsPayload) return reads;
+
+  let mapped: unknown;
+  try {
+    mapped = step.payload(payloadTrace());
+  } catch {
+    return undefined;
+  }
+
+  const out: InvariantReadBinding[] = [];
+  for (const read of reads) {
+    const eachPayloadPath = read.eachPayloadPath === undefined
+      ? undefined
+      : remapPayloadPath(mapped, read.eachPayloadPath);
+    if (read.eachPayloadPath !== undefined && eachPayloadPath === undefined) return undefined;
+
+    const id = remapReadId(read.id, mapped);
+    if (id === undefined) return undefined;
+    out.push({
+      ...read,
+      ...(eachPayloadPath === undefined ? {} : { eachPayloadPath }),
+      id,
+    });
+  }
+  return out;
+}
+
 export interface BusinessIntent<I = unknown> extends Directive<I> {
   readonly [INTENT_BRAND]: true;
   readonly steps: readonly IntentStep<I, any>[];
@@ -235,10 +366,33 @@ class IntentBuilder<I> {
     }
 
     const preconditions: PreconditionDescriptor[] = this.steps.flatMap((step) =>
-      (step.directive.preconditions ?? []).map((condition) => ({
-        ...condition,
-        idField: (facts: unknown) => condition.idField(step.payload(facts as I)),
-      })),
+      (step.directive.preconditions ?? []).map((condition) => {
+        const {
+          idPayloadPath: privateIdPayloadPath,
+          readId: privateReadId,
+          ...rest
+        } = condition;
+        const publicIdPayloadPath = privateIdPayloadPath === undefined
+          ? undefined
+          : remapStepPayloadPath(step, privateIdPayloadPath);
+        let publicReadId: InvariantReadId | undefined;
+        if (privateReadId !== undefined) {
+          try {
+            publicReadId = remapReadId(
+              privateReadId,
+              step.payload(payloadTrace() as unknown as I),
+            );
+          } catch {
+            publicReadId = undefined;
+          }
+        }
+        return {
+          ...rest,
+          ...(publicIdPayloadPath === undefined ? {} : { idPayloadPath: publicIdPayloadPath }),
+          ...(publicReadId === undefined ? {} : { readId: publicReadId }),
+          idField: (facts: unknown) => condition.idField(step.payload(facts as I)),
+        };
+      }),
     );
     const queryReads = dedupeBy(
       this.steps.flatMap((step) => step.directive.declaredQueryReads ?? []),
@@ -289,6 +443,14 @@ class IntentBuilder<I> {
       },
       marker: primary.marker as ReferentialMarker,
       aggregateId: primary.aggregateId,
+      // Keep the typed local target on the lowered public intent. A narrow
+      // runtime plan may retain only this intent export; without the handle the
+      // engine cannot rebuild its aggregate registry entry and silently drops
+      // compound intents that also birth a child.
+      ...(primary.aggregate === undefined ? {} : { aggregate: primary.aggregate }),
+      ...(primary.outputCardinality !== undefined
+        ? { outputCardinality: primary.outputCardinality }
+        : {}),
       ...(secondaryOutputs.length > 0 ? { secondaryOutputs } : {}),
       payloadSchema: (birthSteps[0]?.directive.payloadSchema ?? this.contractDeclaration.accepts) as unknown as z.ZodType<I>,
       plan,
@@ -571,10 +733,20 @@ export function remapWorkspaceInvariantsForLanguage(
         // still validates every mapped consequence before it can commit.
         return (parsed.success ? parsed.data : mapped) as Record<string, unknown>;
       };
+      // Never carry a private payload path blindly onto a public intent. Prove the
+      // mapping structurally with inert path values; otherwise leave the selector
+      // compiler-visible so the native-only gate can name the exact unmapped law.
+      const remappedNativeReads = invariant.__nomosReadBindings === undefined
+        ? undefined
+        : remapNativeReads(invariant.__nomosReadBindings, use.step);
+      const { __nomosReadBindings: _privateReads, ...withoutPrivateReads } = invariant;
       out.push({
-        ...invariant,
+        ...withoutPrivateReads,
         id: `${use.intent.id}__${invariant.id}`,
         on: use.intent.id,
+        ...(remappedNativeReads === undefined
+          ? {}
+          : { __nomosReadBindings: remappedNativeReads }),
         reads: (ctx) => invariant.reads({ ...ctx, intent: mapFacts(ctx.intent) }),
         assert: (snapshots, ctx) => invariant.assert(
           snapshots,

package/src/law_check.ts

@@ -443,7 +443,9 @@ function unreadPayloadFindings(domain: string, dir: Directive<unknown>, probe: P
   // ROUTING lane consumes (the plan may pass it straight to read(…, {from}) without a tracked property
   // read on the sampled path) — a declared trust-edge field is never a dead field.
   for (const e of (dir as { declaredForeignReads?: ForeignReadEdge[] }).declaredForeignReads ?? []) {
-    if ("fromPayload" in e && typeof e.fromPayload === "string") gateConsumed.add(e.fromPayload);
+    if ("fromPayload" in e && typeof e.fromPayload === "string") {
+      gateConsumed.add(e.fromPayload.split(".")[0]!);
+    }
   }
   const out: Finding[] = [];
   for (const f of requiredPayloadFields(dir.payloadSchema as z.ZodTypeAny)) {
@@ -1077,10 +1079,14 @@ function topLevelPortReadFindings(mod: DomainModule, portReadingDomains: Readonl
 // (b) a trustPolicy whose allow-list aggregate has no directive writing it → WARN (unpopulatable);
 // (c) a query declared BOTH as a local .reads() premise AND a foreign policy read → REFUSE (laundering).
 
-/** The FOREIGN query ids a directive's plan actually reads (`read(q, …, { from })`) on the one probe
- *  sample — `undefined` when the plan can't be probed (unsynthesizable payload / it threw). A clean re-run
- *  under a read port that answers both lanes; every side-effect sink is drained (never leaks). */
-function foreignReadsPerformed(dir: Directive<unknown>, where: string): Set<string> | undefined {
+/** The local and FOREIGN query ids a directive's plan actually reads on the one probe sample —
+ *  `undefined` when the plan can't be probed (unsynthesizable payload / it threw). This semantic
+ *  check is deliberately independent of bundle layout: moving the DSL runtime into an authenticated
+ *  shared USDA base must never make an undeclared read disappear from author-time diagnostics. */
+function readsPerformed(
+  dir: Directive<unknown>,
+  where: string,
+): { readonly local: Set<string>; readonly foreign: Set<string> } | undefined {
   let synth: SynthesizedPayload;
   try {
     synth = synthesizeDirectivePayload(dir, where);
@@ -1089,7 +1095,8 @@ function foreignReadsPerformed(dir: Directive<unknown>, where: string): Set<stri
   }
   const payload: Record<string, unknown> = { ...synth.value };
   for (const f of synth.autoStamped) payload[f] = "2026-01-01T00:00:00Z";
-  const performed = new Set<string>();
+  const local = new Set<string>();
+  const foreign = new Set<string>();
   let ok = true;
   withBirthProbeGlobals(() => {
     const g = globalThis as unknown as { nomos: Record<string, unknown> };
@@ -1107,7 +1114,8 @@ function foreignReadsPerformed(dir: Directive<unknown>, where: string): Set<stri
     try {
       dir.plan(payload as never, deterministicPorts({ physical: 1, replica: 1, principal: "principal:probe" }));
       for (const r of __drainReads()) {
-        if ((r as { attestation?: unknown }).attestation !== undefined) performed.add(r.queryId);
+        if ((r as { attestation?: unknown }).attestation !== undefined) foreign.add(r.queryId);
+        else local.add(r.queryId);
       }
     } catch {
       ok = false;
@@ -1117,7 +1125,7 @@ function foreignReadsPerformed(dir: Directive<unknown>, where: string): Set<stri
       g.nomos.read = prevRead;
     }
   });
-  return ok ? performed : undefined;
+  return ok ? { local, foreign } : undefined;
 }
 
 function attestedReadFindings(mod: DomainModule): Finding[] {
@@ -1158,10 +1166,23 @@ function attestedReadFindings(mod: DomainModule): Finding[] {
       }
     }
 
-    // (a) an undeclared foreign read — the plan routes read(q, …, { from }) with no trust edge for q.
-    const performed = foreignReadsPerformed(dir, `${domain}/${dir.id}`);
+    const performed = readsPerformed(dir, `${domain}/${dir.id}`);
     if (performed !== undefined) {
-      for (const qid of performed) {
+      // An ordinary captured read is a declared premise, not an incidental function call. Catch it
+      // against the directive itself so package slicing/runtime-base changes cannot hide the error.
+      for (const qid of performed.local) {
+        if (!localQueryIds.has(qid)) {
+          findings.push({
+            domain,
+            directiveId: dir.id,
+            level: "refuse",
+            what: `directive '${dir.id}' references read() for query '${qid}', but NO directive declares a captured-read query for that premise`,
+            fix: `declare the read on this directive: .reads(theQueryDecl) (the same QueryDecl passed to read())`,
+          });
+        }
+      }
+      // (a) an undeclared foreign read — the plan routes read(q, …, { from }) with no trust edge for q.
+      for (const qid of performed.foreign) {
         if (!declaredQueryIds.has(qid)) {
           findings.push({
             domain,