@githolon/dsl 0.102.4 → 0.103.0

package/src/index.ts

@@ -9,6 +9,14 @@
 // ONE import for a domain file: `z` (payload schemas) rides along with the DSL, so
 // authors never juggle a separate zod dependency (or risk a second zod instance).
 export { z } from "zod";
+export {
+  definePackage,
+  validateNomosPackageConfig,
+  type NomosPackageConfig,
+  type NomosPackageDefinition,
+  type NomosPackageDomainConfig,
+} from "./package_config.js";
+export type { RuntimePackageDependency } from "./package_dependencies.js";
 export {
   aggregate,
   instance,
@@ -41,6 +49,10 @@ export {
   jsonWithNullSchema,
   type EvidenceRefValue,
   evidenceRefSchema,
+  type Sha256Digest,
+  sha256Digest,
+  isSha256DigestSchema,
+  NOMOS_SHA256_DIGEST_BRAND,
   // FIELD FACETS (the endorse model — security_model.md): authority/standing/attribution gate
   // set() acceptance of PrincipalEvidence; secret/public are the confidentiality lattice.
   authorityField,
@@ -61,11 +73,15 @@ export {
   idOf,
   idOfMetaOf,
   idOfTargetKindOf,
+  versionedRefOf,
+  versionedRefOfMetaOf,
   brandedId,
   brandedIdMetaOf,
   voMetaOf,
   voSample,
   NOMOS_VO_BRAND,
+  NOMOS_VERSIONED_REF_BRAND,
+  type VersionedRefOfMeta,
   geo,
   type ValueObject,
   type ValueObjectValue,
@@ -478,6 +494,7 @@ export {
   recordShare,
   pruneShare,
   sharedByWorkspace,
+  sharedByObject,
   ReceivingGroup,
   ReceivingGroupPolicy,
   RECEIVING_GROUP_ID,
@@ -594,9 +611,7 @@ export {
 } from "./framework/capability.js";
 export {
   DOMAIN_INSTALLATION_PHASES,
-  PolicyBundle,
   DomainInstallation,
-  policyAggregateId,
   domainInstallationAggregateId,
   installDomain,
   stageDomain,
@@ -623,8 +638,18 @@ export {
 } from "./framework/repair.js";
 export {
   workspaceInvariant,
+  readRef,
+  readSet,
+  idItem,
+  idLiteral,
+  idPayload,
+  idTemplate,
   ref,
   refAs,
+  type InvariantReadBinding,
+  type InvariantReadId,
+  type InvariantReadIdPart,
+  type InvariantReadTransform,
   type WorkspaceInvariantDecl,
   type WorkspaceInvariantVerdict,
   type WorkspaceInvariantReads,
@@ -729,7 +754,10 @@ export {
   type InvariantEvidence,
   type InvariantVerdict,
 } from "./relation.js";
-export { generateDartDomain, type DomainModule } from "./codegen_dart.js";
+// Build-time generators live on explicit package subpaths. Keep the structural type available to
+// authoring tools, but never pull generator implementations into the runtime namespace evaluated by
+// every kernel sandbox.
+export type { DomainModule } from "./codegen_dart.js";
 // SHAPE COMPATIBILITY (#72) — the structural contract a client negotiates with a workspace
 // by, instead of the law hash. Pure + deterministic; the editor/CI mirror imports these.
 export {
@@ -744,28 +772,20 @@ export {
 // turned on by the `--emit-dot` compiler flag). Pure `DomainModule -> string`, deterministic;
 // NOT part of the domain identity. Barrel-safe (no node:* imports), so the engine bundle can
 // import this barrel unaffected.
-export { emitDomainDot, type DotOptions } from "./codegen_dot.js";
+export type { DotOptions } from "./codegen_dot.js";
 // The OPTIONAL OpenUSD `.usda` emitter — a COMPILED DOMAIN as a navigable USD stage (aggregates →
 // Sphere prims, directives → Cube prims carrying their `plan` lump, the creates/mutates/ref flow →
 // BasisCurves). The abstract LAW structure as a maths object (holon-maths projection), NOT the org-data
 // twin. Sibling of `emitDomainDot`: pure `DomainModule -> string`, deterministic, NOT part of the
 // domain identity; barrel-safe (no node:* imports). Open the output in usdview / any USD tool.
-export { emitDomainUsda, type UsdaOptions } from "./codegen_usda.js";
+export type { UsdaOptions } from "./codegen_usda.js";
 // The PROVIDER SDK codegen (symmetric twin of the peer payload classes). `emitProviderSdk`
 // is invoked INSIDE `generateDartDomain` for a module's `impureCapabilities`; the type is exported
 // so the emit script can type its `impureCapabilities` list. A `impureCapability(...)` factory return value
 // satisfies `ImpureCapabilityDecl` structurally.
-export {
-  emitProviderSdk,
-  emitProviderTask,
-  taskBaseName,
-  type ImpureCapabilityDecl,
-} from "./codegen_provider_dart.js";
-// NOTE: the canonical-manifest / domain-hash API (`./manifest.js`) is a BUILD-TIME
-// concern that imports `node:crypto`. It is DELIBERATELY NOT re-exported from this
-// barrel: the deterministic engine bundle (`golden/domain_nomos.js`) imports this
-// barrel, and esbuild `--platform=neutral` cannot resolve `node:crypto`. Build-time
-// consumers import it via the `@githolon/dsl/manifest` subpath instead.
+export type { ImpureCapabilityDecl } from "./codegen_provider_dart.js";
+// Canonical law is emitted as typed USDA. The retired canonical-JSON manifest helper has
+// been removed from both this barrel and the package exports.
 export { encodeKernelSchema, executeDirectiveToIntent, encodeRefMode, intentIdFromHlc } from "./wire_encode.js";
 export type {
   WireEvent,

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,