@githolon/dsl 0.108.6 → 0.110.0

package/src/value_object.ts

@@ -12,7 +12,7 @@
  * THE TENANT GAP THIS CLOSES: a structured value on an aggregate was a hand-rolled
  * `t.jsonObject()` plus a privately-kept zod schema per site — untyped in the generated
  * clients, invisible in the package IR. A value object is the NAMED, REUSABLE,
- * COMPOSABLE version of that same leaf:
+ * COMPOSABLE replacement for that opaque leaf:
  *
  *   const PostalAddress = valueObject("PostalAddress", {
  *     streetAddress: z.string(), city: z.string(), countryCode: z.string(),
@@ -28,13 +28,12 @@
  * ONE definition produces: the zod schema (the SAME zod the engine validates — embed
  * `SiteLocation.zod` in a directive payload), the inferred TS type (`SiteLocation.field()`
  * types `set()` and the generated `.client.ts` names the interface), the generated Dart
- * class (typed decode from the projection's json-object value), and a canonical
+ * class (typed decode from the projection's nominal value), and a canonical
  * descriptor that rides the package IR (the additive `nomosValueObjects` USD key) so
  * tooling/visualizers can SEE the structure.
  *
- * STORAGE / MERGE SEMANTICS (the v1 boundary — state it, don't blur it): a VO field IS
- * the existing `t.jsonObject()` value-leaf lane — ONE Lww-class leaf, replaced WHOLESALE
- * on write (exactly the encrypted-envelope rule). There is NO per-subfield merge: two
+ * STORAGE / MERGE SEMANTICS: a VO is encoded as named, recursively typed USDA prims. The field
+ * remains ONE Lww-class value, replaced WHOLESALE on write. There is NO per-subfield merge: two
  * concurrent writes to different subfields of one VO converge to ONE writer's whole
  * value. When subfields must merge independently, model them as aggregate fields or a
  * `t.map(...)` — that is what aggregates/maps are for.
@@ -79,6 +78,8 @@ type ZodInternalDef = {
   entries?: Record<string, string | number>;
   valueType?: z.ZodTypeAny;
   keyType?: z.ZodTypeAny;
+  shape?: Record<string, z.ZodTypeAny> | (() => Record<string, z.ZodTypeAny>);
+  options?: readonly z.ZodTypeAny[];
 };
 function zodDef(zt: z.ZodTypeAny): ZodInternalDef {
   const raw = zt as unknown as { _def?: ZodInternalDef; def?: ZodInternalDef };
@@ -88,6 +89,10 @@ function zodKind(zt: z.ZodTypeAny): string {
   const t = zodDef(zt).type;
   return typeof t === "string" ? t : "unknown";
 }
+function zodObjectShape(zt: z.ZodTypeAny): Record<string, z.ZodTypeAny> {
+  const raw = zodDef(zt).shape;
+  return typeof raw === "function" ? raw() : raw ?? {};
+}
 function zodEnumValues(zt: z.ZodTypeAny): string[] {
   const raw = zt as unknown as { options?: readonly unknown[] };
   if (raw.options !== undefined) return raw.options.map(String);
@@ -142,8 +147,8 @@ export interface ValueObject<T = unknown> {
    *  for an optional aggregate FIELD use `.field().optional()`). */
   optional(): OptionalValueObject<T>;
   /**
-   * Lower this VO to an aggregate FIELD: one `t.jsonObject()`-class value leaf
-   * (kind `json`, `jsonShape:"object"`, Lww) whose whole value is this VO —
+   * Lower this VO to an aggregate FIELD: one nominal structural value (Lww) whose whole value is
+   * this VO —
    * WHOLESALE-REPLACE merge, no per-subfield merge (v1). Chain the usual field
    * modifiers: `.merge(Lww/LwwCausal/LwwBy)` (Lww-class only — the value is replaced
    * whole), `.optional()`, `.encrypted()` (under the existing `requires(cap)` rules).
@@ -152,7 +157,7 @@ export interface ValueObject<T = unknown> {
   /**
    * SUGAR for `.field().merge(driver)` — lower this VO DIRECTLY to an aggregate field with
    * the chosen merge driver: `location: SiteLocation.merge(Lww).optional()`. A VO field is
-   * ONE Lww-class json leaf replaced WHOLESALE, so only the Lww-class family
+   * ONE Lww-class structural value replaced WHOLESALE, so only the Lww-class family
    * (`Lww` / `LwwCausal` / `LwwBy`) is accepted — any other driver throws (field-level merge
    * composition of a VO's subfields is a later slice; model those as aggregate fields / a
    * `t.map(...)`). The returned `Field` chains the usual modifiers (`.optional()`,
@@ -596,6 +601,10 @@ function describeZod(
       const inner = describeZod(voName, path, zodDef(schema).innerType!, deps);
       return { ...inner, optional: true };
     }
+    case "nullable": {
+      const inner = describeZod(voName, path, zodDef(schema).innerType!, deps);
+      return { ...inner, nullable: true };
+    }
     default:
       throw new Error(
         `valueObject '${voName}': field '${path}' uses zod shape '${zodKind(schema)}', which is outside ` +
@@ -651,6 +660,7 @@ function sampleOfDescriptorField(
   includeOptional = false,
   path = fieldName,
 ): unknown {
+  if (f.nullable === true) return null;
   switch (f.type) {
     case "string": return `sample-${fieldName}`;
     case "number": return 1;
@@ -769,7 +779,7 @@ function makeValueObject<T>(
     },
     merge(driver: Driver): Field<T, "json"> {
       const k = driver.kind;
-      if (k !== "FirstWriterWins" && k !== "Lww" && k !== "LwwCausal" && k !== "LwwBy") {
+      if (k !== "FirstWriterWins" && k !== "FirstWriterCandidates" && k !== "Lww" && k !== "LwwCausal" && k !== "LwwBy") {
         throw new Error(
           `valueObject '${name}': .merge(${k}) is not a valid value-object field merge — a VO is ONE ` +
             `wholesale json leaf, so only FirstWriterWins / Lww / LwwCausal / LwwBy apply. Field-level ` +
@@ -867,6 +877,15 @@ type UnionValue<Arms extends Record<string, UnionArmShape>> = {
   [K in keyof Arms & string]: { type: K } & UnionArmValue<Arms[K]>;
 }[keyof Arms & string];
 
+/** Construction provenance is compile-time only; the kernel validates the declared
+ * nominal type from authenticated law, never from a caller-supplied brand. */
+declare const NOMINAL_CASE: unique symbol;
+export type NominalCase<Name extends string, T> = T & { readonly [NOMINAL_CASE]: Name };
+export type VariantCases<Name extends string, Arms extends Record<string, UnionArmShape>> = {
+  readonly [K in keyof Arms & string]: (value: UnionArmValue<Arms[K]>) =>
+    NominalCase<Name, { type: K } & UnionArmValue<Arms[K]>>;
+};
+
 /**
  * Declare a NAMED SUM TYPE (`variant("Shape", { circle: {...}, rect: {...} })`). The blessed,
  * FIXED discriminator is `type` (the geo/RFC 7946 convention); its value is the arm key.
@@ -882,7 +901,7 @@ export function variant<const Name extends string, Arms extends Record<string, U
   name: Name,
   arms: Arms,
   opts?: { example?: UnionValue<Arms> },
-): ValueObject<UnionValue<Arms>> {
+): ValueObject<UnionValue<Arms>> & { readonly name: Name; readonly cases: VariantCases<Name, Arms> } {
   const armKeys = Object.keys(arms).sort();
   if (armKeys.length === 0) throw new Error(`variant '${name}': at least one arm is required.`);
   const deps = new Map<string, ValueObjectDescriptor>();
@@ -935,7 +954,12 @@ export function variant<const Name extends string, Arms extends Record<string, U
   const zodSchema = (armZods.length === 1
     ? armZods[0]!
     : z.discriminatedUnion("type", armZods as [z.ZodObject<z.ZodRawShape>, ...z.ZodObject<z.ZodRawShape>[]])) as unknown as z.ZodType<UnionValue<Arms>>;
-  return makeValueObject(name, zodSchema, descriptor, dependencies, undefined, opts?.example);
+  const cases = Object.fromEntries(armKeys.map((type) => [type,
+    (value: object) => ({ ...value, type }),
+  ])) as unknown as VariantCases<Name, Arms>;
+  return Object.assign(makeValueObject(name, zodSchema, descriptor, dependencies, undefined, opts?.example), {
+    name, cases: Object.freeze(cases),
+  });
 }
 
 // ── geo.* — the RFC 7946 geometry value objects ──────────────────────────────────────
@@ -1073,6 +1097,52 @@ export function collectPayloadValueObjectDescriptors(
   return [...byName.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 }
 
+/** Collect every named value object reachable from arbitrary public Zod
+ * surfaces (notably derived/combined read results). This is the same nominal
+ * vocabulary collector used for stored fields and directive payloads; a value
+ * object does not stop being a public type merely because it is read-only. */
+export function collectSchemaValueObjectDescriptors(
+  schemas: readonly unknown[],
+): ValueObjectDescriptor[] {
+  const byName = new Map<string, ValueObjectDescriptor>();
+  const take = (meta: ValueObjectFieldMeta | undefined): void => {
+    if (meta === undefined) return;
+    for (const descriptor of [meta.descriptor, ...meta.dependencies]) {
+      const existing = byName.get(descriptor.name);
+      if (existing !== undefined && JSON.stringify(existing) !== JSON.stringify(descriptor)) {
+        throw new Error(
+          `value object '${descriptor.name}' has DIVERGENT shapes across public schemas — one name, one shape.`,
+        );
+      }
+      byName.set(descriptor.name, descriptor);
+    }
+  };
+  const visit = (candidate: unknown, active: Set<z.ZodTypeAny>): void => {
+    if (typeof candidate !== "object" || candidate === null) return;
+    const schema = candidate as z.ZodTypeAny;
+    if (active.has(schema)) return;
+    const next = new Set(active).add(schema);
+    take(voMetaOf(schema));
+    const kind = zodKind(schema);
+    const def = zodDef(schema);
+    if (kind === "optional" || kind === "default" || kind === "nullable") {
+      visit(def.innerType, next);
+    } else if (kind === "array") {
+      visit(zodArrayElement(schema), next);
+    } else if (kind === "record") {
+      visit(def.valueType, next);
+    } else if (kind === "object") {
+      for (const value of Object.values(zodObjectShape(schema))) visit(value, next);
+    } else if (kind === "union") {
+      for (const value of def.options ?? []) visit(value, next);
+    }
+  };
+  for (const schema of schemas) visit(schema, new Set());
+  return [...byName.values()].sort((a, b) =>
+    a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
+  );
+}
+
 export function collectValueObjectDescriptors(
   aggregates: readonly { id: string; fields: Record<string, Field> }[],
 ): ValueObjectDescriptor[] {

package/src/wire.ts

@@ -45,6 +45,7 @@ export type WireValue =
       };
     }
   | { Int: number }
+  | { ValueObject: WireValueObject }
   | { Set: string[] }
   | { Map: Record<string, WireField> }
   | {
@@ -72,6 +73,24 @@ export type WireValue =
   | { Position: string }
   | { TwoPhaseSet: { adds: string[]; removes: string[] } };
 
+/** Recursive, nominal application value carried by a value-object field. This is the plan ABI's
+ * typed value algebra, not a serialized document: the kernel converts it directly from QuickJS
+ * objects into nested USDA prims without JSON stringify/parse or a generic map at the public API. */
+export interface WireValueObject {
+  readonly typeName: string;
+  readonly fields: Readonly<Record<string, WireNominalValue>>;
+}
+
+export type WireNominalValue =
+  | { Null: true }
+  | { String: string }
+  | { Bool: boolean }
+  | { Int: number }
+  | { Double: number }
+  | { List: readonly WireNominalValue[] }
+  | { Map: Readonly<Record<string, WireNominalValue>> }
+  | { Object: WireValueObject };
+
 export interface WireOwnedDeviceRequest {
   v: number;
   workspace: string;
@@ -201,6 +220,8 @@ export interface WireIntent {
       | { readonly verifiedParent: true }
       | { readonly verifiedSource: true };
     targetCallUsda: Uint8Array;
+    /** Positions of selected earlier effects. The kernel resolves these to sealed digests. */
+    dependsOn?: readonly number[];
   }[];
 }
 
@@ -266,6 +287,7 @@ export interface WireReadAttestation {
  */
 export type WireDriver =
   | "FirstWriterWins"
+  | "FirstWriterCandidates"
   | "Lww"
   | "LwwCausal"
   | "AddWins"

package/src/wire_encode.ts

@@ -40,12 +40,19 @@ import {
   OWNED_PREMINTED_RECORDS_PAYLOAD_FIELD,
   type AggregateHandle,
 } from "./aggregate.js";
-import { admitsNull, type Field, type EvidenceRefValue } from "./fields.js";
+import {
+  admitsNull,
+  type Field,
+  type EvidenceRefValue,
+  type ValueObjectDescriptor,
+  type ValueObjectFieldDescriptor,
+  type ValueObjectFieldMeta,
+} from "./fields.js";
 import type { Directive, ReferentialMarker } from "./directive.js";
-import { isBusinessIntent } from "./intent.js";
+import { isBusinessIntent, validateWorkspaceEffectDependencies } from "./intent.js";
 import type { PlannedOp, FieldOp } from "./ops.js";
 import { deterministicPorts, type Ports } from "./ctx.js";
-import type { PrincipalFacet } from "./principal_evidence.js";
+import { endorsementOf, type PrincipalFacet } from "./principal_evidence.js";
 import type {
   WireEvent,
   WireHlc,
@@ -55,6 +62,8 @@ import type {
   WireRefMode,
   WireSchema,
   WireValue,
+  WireNominalValue,
+  WireValueObject,
 } from "./wire.js";
 import {
   zodArrayElement,
@@ -113,6 +122,148 @@ function describeShape(value: unknown): string {
   return typeof value;
 }
 
+function nominalRecordEntries(value: unknown, at: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new TypeError(`${at} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function encodeUntypedNominal(value: unknown, at: string): WireNominalValue {
+  if (typeof value === "string") return { String: value };
+  if (typeof value === "boolean") return { Bool: value };
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new TypeError(`${at} must be finite`);
+    if (Number.isInteger(value)) {
+      if (!Number.isSafeInteger(value)) throw new TypeError(`${at} is outside JavaScript's exact integer range`);
+      return { Int: value };
+    }
+    return { Double: value };
+  }
+  if (Array.isArray(value)) {
+    return { List: value.map((member, index) => encodeUntypedNominal(member, `${at}[${index}]`)) };
+  }
+  const object = nominalRecordEntries(value, at);
+  return {
+    Map: Object.fromEntries(
+      Object.entries(object)
+        .filter(([, member]) => member !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, member]) => [key, encodeUntypedNominal(member, `${at}.${key}`)]),
+    ),
+  };
+}
+
+function encodeDescribedNominal(
+  descriptor: ValueObjectFieldDescriptor,
+  value: unknown,
+  types: ReadonlyMap<string, ValueObjectDescriptor>,
+  at: string,
+): WireNominalValue {
+  if (value === null) {
+    if (descriptor.nullable === true) return { Null: true };
+    throw new TypeError(`${at} does not admit null`);
+  }
+  switch (descriptor.type) {
+    case "string":
+    case "enum":
+    case "literal":
+      if (typeof value !== "string") throw new TypeError(`${at} must be a string`);
+      return { String: value };
+    case "boolean":
+      if (typeof value !== "boolean") throw new TypeError(`${at} must be a boolean`);
+      return { Bool: value };
+    case "number":
+      if (typeof value !== "number" || !Number.isFinite(value)) throw new TypeError(`${at} must be a finite number`);
+      if (descriptor.int === true) {
+        if (!Number.isSafeInteger(value)) throw new TypeError(`${at} must be an exact integer`);
+        return { Int: value };
+      }
+      return { Double: value };
+    case "array":
+      if (!Array.isArray(value)) throw new TypeError(`${at} must be an array`);
+      return { List: value.map((member, index) => encodeDescribedNominal(descriptor.items, member, types, `${at}[${index}]`)) };
+    case "map": {
+      const object = nominalRecordEntries(value, at);
+      return {
+        Map: Object.fromEntries(
+          Object.entries(object)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, member]) => [key, encodeDescribedNominal(descriptor.values, member, types, `${at}.${key}`)]),
+        ),
+      };
+    }
+    case "object":
+    case "geometry": {
+      const target = types.get(descriptor.ref);
+      if (target === undefined) throw new TypeError(`${at} references unknown value object '${descriptor.ref}'`);
+      return { Object: encodeNominalValueObject(target, value, types, at) };
+    }
+  }
+}
+
+/** Internal structural encoder, also used by independent storage-codec fixtures.
+ * Not a validator or admission API; callers must validate authored domain data.
+ */
+export function encodeNominalValueObject(
+  descriptor: ValueObjectDescriptor,
+  value: unknown,
+  types: ReadonlyMap<string, ValueObjectDescriptor>,
+  at = descriptor.name,
+): WireValueObject {
+  const object = nominalRecordEntries(value, at);
+  if (descriptor.fields !== undefined) {
+    return {
+      typeName: descriptor.name,
+      fields: Object.fromEntries(
+        Object.entries(descriptor.fields)
+          .sort(([left], [right]) => left.localeCompare(right))
+          .flatMap(([key, member]) => {
+            const fieldValue = object[key];
+            if (fieldValue === undefined && member.optional === true) return [];
+            return [[key, encodeDescribedNominal(member, fieldValue, types, `${at}.${key}`)] as const];
+          }),
+      ),
+    };
+  }
+  if (descriptor.union !== undefined) {
+    const discriminator = object["type"];
+    if (typeof discriminator !== "string") throw new TypeError(`${at}.type must be a string discriminator`);
+    const arm = descriptor.union[discriminator];
+    if (arm === undefined) throw new TypeError(`${at}.type '${discriminator}' is not a declared arm`);
+    const fields: Record<string, WireNominalValue> = { type: { String: discriminator } };
+    if ("ref" in arm) {
+      const target = types.get(arm.ref);
+      if (target === undefined) throw new TypeError(`${at} references unknown value object '${arm.ref}'`);
+      fields["value"] = { Object: encodeNominalValueObject(target, object["value"], types, `${at}.value`) };
+    } else {
+      for (const [key, member] of Object.entries(arm.fields).sort(([left], [right]) => left.localeCompare(right))) {
+        const fieldValue = object[key];
+        if (fieldValue === undefined && member.optional === true) continue;
+        fields[key] = encodeDescribedNominal(member, fieldValue, types, `${at}.${key}`);
+      }
+    }
+    return { typeName: descriptor.name, fields };
+  }
+  // Geometry has a standard fixed shape. Preserve its actual scalar/list/map kinds while retaining
+  // the declared RFC 7946 nominal type at the enclosing prim.
+  return {
+    typeName: descriptor.name,
+    fields: Object.fromEntries(
+      Object.entries(object)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, member]) => [key, encodeUntypedNominal(member, `${at}.${key}`)]),
+    ),
+  };
+}
+
+function encodeValueObject(meta: ValueObjectFieldMeta, value: unknown): WireValueObject {
+  const types = new Map(
+    [meta.descriptor, ...meta.dependencies].map((descriptor) => [descriptor.name, descriptor] as const),
+  );
+  return encodeNominalValueObject(meta.descriptor, value, types);
+}
+
 /** Map an authored op value onto the kernel `Value` shape, given the field kind.
  *  `op` is passed purely for a NAMED diagnostic (aggregate + field + expected VO type) when a value
  *  can't be lowered — never `field '?'`. */
@@ -186,6 +337,9 @@ function encodeKernelValue(field: Field | undefined, value: unknown, op?: FieldO
   if (field?.kind === "json" && voMetaOf(field.zod)?.name === OwnedDeviceRequestValue.name) {
     return { OwnedDeviceRequest: OwnedDeviceRequestValue.zod.parse(value) };
   }
+  if (field?.valueObject !== undefined) {
+    return { ValueObject: encodeValueObject(field.valueObject, field.zod.parse(value)) };
+  }
   // A `t.json()` leaf lowers to the FIRST-CLASS kernel `Value::Json` (RFC 8785 / JCS), NOT a
   // `Value::Str` holding JSON-shaped text. Checked BEFORE the scalar fallthroughs so EVERY json
   // value — object, array, string, number, boolean, null — commits as one consistent value kind
@@ -222,6 +376,9 @@ function encodeKernelValue(field: Field | undefined, value: unknown, op?: FieldO
   // entries, which the kernel's authz fold parses as Str. Routing strings to Json broke
   // relation seating repo-wide (warrant_flip/va_core/relation-bootstrap all red). Objects were
   // previously a REFUSAL here, so giving them the Json lane changes only the case that threw.
+  if (field?.kind === "map" && field.mapValueVo !== undefined) {
+    return { ValueObject: encodeValueObject(field.mapValueVo, value) };
+  }
   if (field?.kind === "map" && field.mapValueKind === "json" && typeof value === "object" && value !== null) {
     return { Json: value };
   }
@@ -243,14 +400,11 @@ function encodeKernelValue(field: Field | undefined, value: unknown, op?: FieldO
         `(instance/existing/ensure(TargetAgg, id)) so the field kind is known.`,
     );
   }
-  // Name the expected VO: a top-level VO field carries it on `valueObject`, a VO-valued MAP entry on
-  // `mapValueVo` (the inner value's VO metadata) — so a bad `t.map(VO.field())` entry names its VO too.
-  const expected = field.valueObject?.name ?? field.mapValueVo?.name;
   const kindLabel = field.kind === "map" ? `map (${field.mapValueKind ?? "?"}-valued)` : field.kind;
   throw new Error(
-    `${aggName}.${fieldName} is a '${kindLabel}' field${expected ? ` (value object ${expected})` : ""}, ` +
+    `${aggName}.${fieldName} is a '${kindLabel}' field, ` +
       `but got ${describeShape(value)} (${JSON.stringify(value)}) — kernel scalars are Str | Bool | Int. ` +
-      `A structured value needs a declared value-object field; a set/map needs its additive write.`,
+      `A structured value needs a declared value-object field; a set/map needs its structural write.`,
   );
 }
 
@@ -320,7 +474,7 @@ function encodeKernelFieldOp(op: FieldOp, field: Field | undefined): WireFieldOp
  * to test domain LIFECYCLE.
  *
  * For a KERNEL-BACKED local harness — admission through the real gate, folds,
- * reads, minted ids, the whole lifecycle on the same engine plane the cloud
+ * reads, minted ids, the whole lifecycle on the same kernel host the cloud
  * edge runs — use the CLI, NOT this function:
  *   • `githolon dev --once` — ONE compile → law-live-locally → proof cycle, then
  *     exit (the CI/smoke lane for lifecycle + id-mint tests — a non-zero exit
@@ -418,20 +572,35 @@ export function executeDirectiveToIntent<P>(
     for (const b of births) meterOps.push(...planBirthRecordOps(b, subject, bornAt));
   }
   const planned = [...__drainAuthoring(), ...returned, ...meterOps];
-  const workspaceEffects = isBusinessIntent(directive)
-    ? directive.workspaceEffects.map((effect) => {
+  const declaredWorkspaceEffects = directive.workspaceEffects ?? [];
+  // Resolve names before filtering: a conditional predecessor that did not run must never
+  // disappear from the dependency graph and accidentally authorize its dependent.
+  validateWorkspaceEffectDependencies(declaredWorkspaceEffects);
+  const selectedWorkspaceEffects = declaredWorkspaceEffects
+    .filter(effect => effect.when?.(parsed, ctx) ?? true);
+  const selectedEffectIndices = new Map(selectedWorkspaceEffects
+    .flatMap((effect, index) => effect.key === undefined ? [] : [[effect.key, index] as const]));
+  const workspaceEffects = selectedWorkspaceEffects
+    .map((effect) => {
+        const dependsOn = (effect.after ?? []).map(key => {
+          const index = selectedEffectIndices.get(key);
+          if (index === undefined) {
+            throw new Error(`Directive '${directive.id}' requires workspace effect '${key}', but its condition did not select it`);
+          }
+          return index;
+        }).sort((a, b) => a - b);
         if (encodeWorkspaceEffect === undefined) {
           throw new Error(
             `Directive '${directive.id}' declares a workspace effect, but its compiled plan has no target-call encoder`,
           );
         }
         const workspace = effect.destination.kind === "workspace"
-          ? effect.destination.address(parsed)
+          ? effect.destination.address(parsed, ctx)
           : "";
         if (effect.destination.kind === "workspace" && workspace.trim().length === 0) {
           throw new Error(`Directive '${directive.id}' produced an empty target workspace address`);
         }
-        const targetPayload = effect.target.payloadSchema.parse(effect.payload(parsed));
+        const targetPayload = effect.target.payloadSchema.parse(effect.payload(parsed, ctx));
         return {
           destination: effect.destination.kind === "workspace"
             ? { workspace }
@@ -443,9 +612,9 @@ export function executeDirectiveToIntent<P>(
             targetPayload,
             workspace,
           ),
+          ...(dependsOn.length ? { dependsOn } : {}),
         };
-      })
-    : [];
+      });
   // Workspace-effect payload mappers are source law and may perform declared captured reads while
   // constructing the target payload. Drain only after both local and cross-workspace consequences.
   const reads = __drainReads();
@@ -525,14 +694,25 @@ export function executeDirectiveToIntent<P>(
     bucket.push(encodeKernelFieldOp(op, field));
   }
 
+  // A `.creates` directive that also declares `.alsoMutates` of its own type (a replacement that supersedes
+  // the row it replaces) addresses TWO rows of that type: the one `create()` marks, and an existing one it
+  // reaches with `existing(...)`. Only the marked row is created; the other is the declared mutate, or the
+  // referential gate refuses it as a create of an id that already exists.
+  const mutatesOwnType =
+    directive.marker === "creates" &&
+    (directive.secondaryOutputs ?? []).some(
+      (output) => output.marker === "mutates" && output.aggregateId === agg.id,
+    ) &&
+    order.some((key) => ownTarget.get(key) === true && explicitMarker.get(key) === "Create");
   const events: WireEvent[] = order.map((bucketKey) => {
     const aggregate = idOf.get(bucketKey)!;
     const ops = byAggregate.get(bucketKey)!;
     const ty = typeOf.get(bucketKey);
     // The directive's marker applies to its OWN target; a FAN-OUT bucket is a Mutate of an
     // existing sibling aggregate (so the id-mint gate never sees a spurious Create for it).
+    const ownMarker = mutatesOwnType && ty !== undefined ? "Mutate" : marker;
     const eventMarker: WireRefMode =
-      explicitMarker.get(bucketKey) ?? (ownTarget.get(bucketKey) ? marker : "Mutate");
+      explicitMarker.get(bucketKey) ?? (ownTarget.get(bucketKey) ? ownMarker : "Mutate");
     if (ty !== undefined) {
       // Stamp provenance FIRST so the fold carries the TYPE + canonical id the
       // structured `view()` projects (the same `__type`/`__id` reserved fields the
@@ -624,6 +804,14 @@ function principalFlowProbeValue(
   }
 }
 
+/** Does `value` hold principal evidence minted by THIS DSL instance anywhere inside it? */
+function carriesUnloweredEvidence(value: unknown, seen = new Set<object>()): boolean {
+  if (typeof value !== "object" || value === null || seen.has(value)) return false;
+  seen.add(value);
+  if (endorsementOf(value) !== null) return true;
+  return Object.values(value as Record<string, unknown>).some(inner => carriesUnloweredEvidence(inner, seen));
+}
+
 /** Extract the principal flows carried by a plan's field ops (those with an `endorsement`). The ONE
  *  op→flow mapping shared by the discovery harvest (compile) and the runtime footprint (Slice B). */
 function flowsFromOps(ops: readonly FieldOp[]): PrincipalFlow[] {
@@ -646,8 +834,14 @@ function flowsFromOps(ops: readonly FieldOp[]): PrincipalFlow[] {
  * the omission is SAFE because the runtime/replay witness (Slice B) refuses any observed flow absent
  * from the manifest. The reasons are static law, so they are intent-independent. SORTED for determinism.
  */
-export function harvestPrincipalFlows(directive: Directive<unknown>, domain?: string): PrincipalFlow[] {
-  const ctx: Ports = deterministicPorts({ principal: "principal:probe" });
+export function harvestPrincipalFlows<P>(directive: Directive<P>, domain?: string): PrincipalFlow[] {
+  // Every composed local step is part of the declared law. A later captured read
+  // can stop a synthetic probe; it must not erase flows already declared by an
+  // earlier step (notably the invitation's possession-proven authority grant).
+  const stepFlows = isBusinessIntent(directive)
+    ? directive.steps.flatMap(step => harvestPrincipalFlows(step.directive, domain)) : [];
+  const ctx: Ports = deterministicPorts({ principal: directive.acceptsVerifiedWorkspaceClaimGate
+    ? "workspace:probe" : "user:probe" });
   let candidate: unknown;
   try {
     candidate = principalFlowProbeValue(directive.payloadSchema as z.ZodTypeAny);
@@ -696,11 +890,24 @@ export function harvestPrincipalFlows(directive: Directive<unknown>, domain?: st
     ops = [...__drainAuthoring(), ...(Array.isArray(returned) ? returned : [])].filter((op): op is FieldOp => op.kind !== "strike");
   } catch {
     try { __drainAuthoring(); __drainReads(); } catch { /* sink already drained */ }
-    return [];
+    return stepFlows;
   } finally {
     if (domain !== undefined) __setDispatchDomain(undefined);
     if (hadNomos && prior !== undefined) g.nomos = prior; else delete g.nomos;
   }
   __drainReads();
-  return flowsFromOps(ops);
+  const ownFlows = flowsFromOps(ops);
+  // AN UNHARVESTABLE ENDORSEMENT IS AN ERROR, not a weaker law. Principal evidence the plan converted
+  // (asAuthoritySubject/asStandingParty) is lowered to its raw principal by the framework before it
+  // reaches an op. Evidence still inside an op was never lowered: the plan ran against a second
+  // @githolon/dsl instance whose registry cannot see this one's endorsements, so the flow would be
+  // missing from the compiled manifest.
+  if (ops.some(op => carriesUnloweredEvidence(op))) {
+    throw new Error(
+      `principal-flow discovery for '${directive.id}' found converted principal evidence its plan never ` +
+      `lowered: the plan ran against a second @githolon/dsl instance, so its endorsed flows cannot be harvested`,
+    );
+  }
+  return [...stepFlows, ...ownFlows].filter((flow, index, all) =>
+    all.findIndex(candidate => candidate.sink === flow.sink && candidate.facet === flow.facet && candidate.reason === flow.reason) === index);
 }

package/src/workspace_sharding.ts

@@ -79,6 +79,7 @@ import { query } from "./query.js";
 import { read } from "./read.js";
 import { sum } from "./sum.js";
 import { min, max } from "./extremum.js";
+import { valueObject } from "./value_object.js";
 import {
   idItem,
   idPayload,
@@ -439,18 +440,26 @@ export const nomosReceiveAssignment = directive("nomosReceiveAssignment")
  * receipt-leg obligation ALONGSIDE the unchanged assignment flip; the host orchestration still runs
  * the move (the obligation is observable on the outbox, not yet consumed). `architecture/sharding_as_outbound_offers.md`.
  */
+export const NomosMoveHomeKeys = valueObject("NomosMoveHomeKeys", {
+  values: z.array(z.string().min(1)).min(1).max(64),
+});
+
+export const NomosMigratedIntentIds = valueObject("NomosMigratedIntentIds", {
+  values: z.array(z.string().min(1)).max(1024),
+});
+
 export const NomosMoveObligation = impureCapabilityAggregate("NomosMoveObligation", {
   // the move-leg params (sealed as typed USDA values in the outbound offer):
   fromShard: t.string().merge(Lww),
   toShard: t.string().merge(Lww),
-  homeKeys: t.json().merge(Lww), // the moving home keys (the leg's work list)
+  homeKeys: NomosMoveHomeKeys.field().merge(Lww), // the moving home keys (the leg's work list)
   leg: t.string().merge(Lww), // one of MOVE_LEGS
   mapVersion: t.int().merge(Lww), // the law-derived map version (S3a), ferried leg-to-leg
   // S3b — the target shard's ADMITTED set, accumulated migrate→seal (the cross-leg state seal-home
   // needs to compute `missing` against the source chain). The LAW unions it (the adapter only ferries
   // arrays it read off the obligation + the shard response — it never accumulates), so the host holds no
   // cross-leg move state and an adapter restart re-derives everything from the on-chain obligation.
-  migratedIds: t.json().merge(Lww), // JSON string array; "[]" until the migrate leg's receipt
+  migratedIds: NomosMigratedIntentIds.field().merge(Lww), // empty until the migrate leg's receipt
 });
 
 /** S1 receipt-leg obligation window (ms) — the leg's soft deadline past its scheduledAt. */
@@ -509,10 +518,10 @@ export const nomosSplitShard = directive("nomosSplitShard")
       .set("status", "requested")
       .set("fromShard", p.fromShard)
       .set("toShard", p.toShard)
-      .set("homeKeys", JSON.stringify(p.homeKeys)) // t.json() stores the stringified JSON
+      .set("homeKeys", { values: p.homeKeys })
       .set("leg", "receipt")
       .set("mapVersion", newMapVersion)
-      .set("migratedIds", "[]"); // nothing migrated yet — the migrate leg's receipt accumulates it
+      .set("migratedIds", { values: [] }); // nothing migrated yet — the migrate leg's receipt accumulates it
     return ops;
   })
   .reads(nomosShardAssignmentByHomeKey);
@@ -573,10 +582,10 @@ export const nomosAdvanceMove = directive("nomosAdvanceMove")
         .set("status", "requested")
         .set("fromShard", p.fromShard)
         .set("toShard", p.toShard)
-        .set("homeKeys", JSON.stringify(p.homeKeys))
+        .set("homeKeys", { values: p.homeKeys })
         .set("leg", nextLeg)
         .set("mapVersion", p.mapVersion) // carry the law-derived version forward (S3a)
-        .set("migratedIds", JSON.stringify(accMigrated)); // S3b — the accumulated admitted set
+        .set("migratedIds", { values: accMigrated }); // S3b — the accumulated admitted set
     }
     return ops;
   });