@githolon/dsl 0.103.4 → 0.103.5

package/src/idof_lint.ts

@@ -105,72 +105,86 @@ export function assertIdOfLintForDirective(dir: Directive<unknown>, where: strin
   // tenant-facing idOf lint here would force framework wire schemas to masquerade as public
   // application schemas and, worse, reject every aggregate that opts into owned custody.
   if ((dir as { businessBirthInternal?: unknown }).businessBirthInternal === true) return;
-  const probed = probePlanOps(dir, where);
-  if (probed === undefined) return;
   let shape: Record<string, z.ZodTypeAny>;
   try {
     shape = zodObjectShape(dir.payloadSchema as z.ZodTypeAny);
   } catch {
     return;
   }
-  // Reverse index: sampled STRING value → the top-level payload field name(s) that produced it.
-  // `synthesizePayload` gives every string-kind field a DISTINCT `"sample-<field>"` value (or a
-  // schema-constrained fallback), so an exact match is unambiguous in practice.
-  const byValue = new Map<string, string>();
-  for (const [name, value] of Object.entries(probed.synth.value)) {
-    if (typeof value === "string") byValue.set(value, name);
-  }
-  for (const op of probed.ops) {
-    // A bound mutation addresses one existing aggregate instance. The payload field carrying that
-    // address is therefore not "some string" or merely "some branded id": it must be idOf(the exact
-    // aggregate being mutated). This is the identity spine of the generated application API. Without
-    // this guard a model can compile `entryId: z.string()`, after which every generated caller can mix
-    // unrelated record ids and is encouraged to reconstruct identity as application state.
-    const effectiveMarker = op.marker ?? (op.aggregateType === dir.aggregateId ? dir.marker : "mutates");
-    if (op.aggregateType !== undefined && (effectiveMarker === "mutates" || effectiveMarker === "archives")) {
-      const payloadField = byValue.get(op.aggregateId);
-      if (payloadField !== undefined) {
-        const fieldSchema = shape[payloadField];
-        const actualTarget = fieldSchema === undefined ? undefined : idOfMetaOf(fieldSchema);
-        if (actualTarget !== op.aggregateType) {
-          const expected = shortAggName(op.aggregateType);
-          const actual = actualTarget === undefined
-            ? "an untyped string"
-            : `idOf(${shortAggName(actualTarget)})`;
-          const verb = effectiveMarker === "archives" ? "archive" : "mutate";
-          throw new IdOfLintError(
+  // Probe both payload presences. The ordinary proof deliberately omits optional fields, but that
+  // would make `optional().setOptional(...)` invisible to the identity lint: exactly the shape that
+  // can smuggle a business string into a typed aggregate reference. The second probe includes every
+  // sampleable top-level optional and deliberately ignores a possibly sparse author example. It is
+  // lint-only; all existing proof/effect consumers retain the ordinary omitted-optional semantics.
+  const probedVariants = [
+    probePlanOps(dir, where),
+    probePlanOps(dir, `${where} (optional fields present)`, {
+      includeOptionalTopLevel: true,
+      useDirectiveExample: false,
+    }),
+  ];
+  if (probedVariants.every((variant) => variant === undefined)) return;
+  for (const probed of probedVariants) {
+    if (probed === undefined) continue;
+    // Reverse index: sampled STRING value → the top-level payload field name(s) that produced it.
+    // `synthesizePayload` gives every string-kind field a DISTINCT `"sample-<field>"` value (or a
+    // schema-constrained fallback), so an exact match is unambiguous in practice.
+    const byValue = new Map<string, string>();
+    for (const [name, value] of Object.entries(probed.synth.value)) {
+      if (typeof value === "string") byValue.set(value, name);
+    }
+    for (const op of probed.ops) {
+      // A bound mutation addresses one existing aggregate instance. The payload field carrying that
+      // address is therefore not "some string" or merely "some branded id": it must be idOf(the exact
+      // aggregate being mutated). This is the identity spine of the generated application API. Without
+      // this guard a model can compile `entryId: z.string()`, after which every generated caller can mix
+      // unrelated record ids and is encouraged to reconstruct identity as application state.
+      const effectiveMarker = op.marker ?? (op.aggregateType === dir.aggregateId ? dir.marker : "mutates");
+      if (op.aggregateType !== undefined && (effectiveMarker === "mutates" || effectiveMarker === "archives")) {
+        const payloadField = byValue.get(op.aggregateId);
+        if (payloadField !== undefined) {
+          const fieldSchema = shape[payloadField];
+          const actualTarget = fieldSchema === undefined ? undefined : idOfMetaOf(fieldSchema);
+          if (actualTarget !== op.aggregateType) {
+            const expected = shortAggName(op.aggregateType);
+            const actual = actualTarget === undefined
+              ? "an untyped string"
+              : `idOf(${shortAggName(actualTarget)})`;
+            const verb = effectiveMarker === "archives" ? "archive" : "mutate";
+            throw new IdOfLintError(
               `directive '${dir.id}': payload field '${payloadField}' selects the ${expected} record to ${verb} ` +
               `but carries ${actual} — declare it as idOf(${expected}) so create, update, find and watch use ` +
               `the same generated NomosRef<${expected}>.`,
-          );
+            );
+          }
         }
       }
-    }
-    if (op.kind !== "set" && op.kind !== "setEntry") continue;
-    if (typeof op.value !== "string") continue;
-    const targetAgg = refTargetOf(op);
-    if (targetAgg === undefined) continue; // not a ref-kind field (or one the DSL can't name a target for)
-    const payloadField = byValue.get(op.value);
-    if (payloadField === undefined) continue; // not traceable to a top-level payload field — no verdict
-    const fieldSchema = shape[payloadField];
-    if (fieldSchema === undefined) continue;
-    const onAgg = shortAggName(op.aggregateType ?? op.aggregateId);
-    const targetName = shortAggName(targetAgg);
-    const actualTarget = idOfMetaOf(fieldSchema);
-    if (actualTarget === targetAgg) continue;
-    if (actualTarget !== undefined) {
+      if (op.kind !== "set" && op.kind !== "setEntry") continue;
+      if (typeof op.value !== "string") continue;
+      const targetAgg = refTargetOf(op);
+      if (targetAgg === undefined) continue; // not a ref-kind field (or one the DSL can't name a target for)
+      const payloadField = byValue.get(op.value);
+      if (payloadField === undefined) continue; // not traceable to a top-level payload field — no verdict
+      const fieldSchema = shape[payloadField];
+      if (fieldSchema === undefined) continue;
+      const onAgg = shortAggName(op.aggregateType ?? op.aggregateId);
+      const targetName = shortAggName(targetAgg);
+      const actualTarget = idOfMetaOf(fieldSchema);
+      if (actualTarget === targetAgg) continue;
+      if (actualTarget !== undefined) {
+        throw new IdOfLintError(
+          `directive '${dir.id}': payload field '${payloadField}' feeds ref field '${onAgg}.${op.field}' ` +
+            `(-> ${targetName}) but carries idOf(${shortAggName(actualTarget)}) — declare it as ` +
+            `idOf(${targetName}) so generated callers carry NomosRef<${targetName}>.`,
+        );
+      }
+      if (!isBareString(fieldSchema) && brandedIdMetaOf(fieldSchema) === undefined) continue;
       throw new IdOfLintError(
         `directive '${dir.id}': payload field '${payloadField}' feeds ref field '${onAgg}.${op.field}' ` +
-          `(-> ${targetName}) but carries idOf(${shortAggName(actualTarget)}) — declare it as ` +
-          `idOf(${targetName}) so generated callers carry NomosRef<${targetName}>.`,
+          `(-> ${targetName}) but is not idOf(${targetName}) — declare it as idOf(${targetName}) so generated ` +
+          `Dart/TS carry NomosRef<${targetName}>, matching the read model. (dart_codegen_parity.md P2)`,
       );
     }
-    if (!isBareString(fieldSchema) && brandedIdMetaOf(fieldSchema) === undefined) continue;
-    throw new IdOfLintError(
-      `directive '${dir.id}': payload field '${payloadField}' feeds ref field '${onAgg}.${op.field}' ` +
-        `(-> ${targetName}) but is not idOf(${targetName}) — declare it as idOf(${targetName}) so generated ` +
-        `Dart/TS carry NomosRef<${targetName}>, matching the read model. (dart_codegen_parity.md P2)`,
-    );
   }
 }
 

package/src/index.ts

@@ -56,10 +56,16 @@ export {
   jsonWithNullSchema,
   type EvidenceRefValue,
   evidenceRefSchema,
+  type NomosRefValue,
+  nomosRefValueSchema,
   type Sha256Digest,
+  type GitObjectId,
   sha256Digest,
+  gitObjectId,
   isSha256DigestSchema,
+  isGitObjectIdSchema,
   NOMOS_SHA256_DIGEST_BRAND,
+  NOMOS_GIT_OBJECT_ID_BRAND,
   // FIELD FACETS (the endorse model — security_model.md): authority/standing/attribution gate
   // set() acceptance of PrincipalEvidence; secret/public are the confidentiality lattice.
   authorityField,
@@ -80,6 +86,8 @@ export {
   idOf,
   idOfMetaOf,
   idOfTargetKindOf,
+  refOf,
+  refOfMetaOf,
   versionedRefOf,
   versionedRefOfMetaOf,
   brandedId,
@@ -87,7 +95,9 @@ export {
   voMetaOf,
   voSample,
   NOMOS_VO_BRAND,
+  NOMOS_REFOF_BRAND,
   NOMOS_VERSIONED_REF_BRAND,
+  type RefOfMeta,
   type VersionedRefOfMeta,
   geo,
   type ValueObject,
@@ -617,13 +627,21 @@ export {
 } from "./framework/capability.js";
 export {
   DOMAIN_INSTALLATION_PHASES,
+  DOMAIN_LIFECYCLE_DIRECTIVES,
+  MODEL_LIFECYCLE_AUTHORITY,
   DomainInstallation,
+  DomainInstallExecutor,
+  DomainInstallationPhase,
+  currentLawReference,
+  domainInstallGenesisOffer,
   domainInstallationAggregateId,
   installDomain,
   stageDomain,
   promoteDomain,
   rollbackDomain,
-  type DomainInstallationPhase,
+  type DomainLifecycleDirectiveId,
+  type CurrentLawReference,
+  type LawClosureReference,
 } from "./framework/domain_lifecycle.js";
 export {
   WORKSPACE_SYNC_DIRECTIONS,
@@ -666,6 +684,7 @@ export {
 // NATIVE ZANZIBAR RELATION SCHEMA (P1) — the userset-rewrite law as pure data.
 export {
   relationType,
+  relationRef,
   isRelationTypeDecl,
   validateRelationType,
   self,
@@ -691,6 +710,7 @@ export {
   selfObject,
   objectOf,
   type RelationObjectToken,
+  type RelationRef,
   type RelationTypeDecl,
   type RelationTypeBuilder,
   type RelationDefAst,

package/src/intent.ts

@@ -24,7 +24,11 @@ import type {
   InvariantReadIdPart,
   WorkspaceInvariantDecl,
 } from "./framework/workspace_invariant.js";
-import { businessBirthConsequence, type BusinessBirthDirective } from "./business_birth.js";
+import {
+  BUSINESS_BIRTH_POLICY_BINDING,
+  businessBirthConsequence,
+  type BusinessBirthDirective,
+} from "./business_birth.js";
 import type { BusinessBirthDecl } from "./births.js";
 import type { WorkspaceSharingPolicy } from "./workspace_sharing.js";
 
@@ -164,6 +168,7 @@ function remapNativeReads(
 
 export interface BusinessIntent<I = unknown> extends Directive<I> {
   readonly [INTENT_BRAND]: true;
+  readonly [BUSINESS_BIRTH_POLICY_BINDING]?: (domains: readonly string[]) => void;
   readonly steps: readonly IntentStep<I, any>[];
   /** The complete public business boundary. Runtime lowering still uses Directive.payloadSchema privately. */
   readonly contract: IntentContract<I>;
@@ -433,6 +438,8 @@ class IntentBuilder<I> {
     };
 
     const businessBirth = (birthSteps[0]?.directive as BusinessBirthDirective | undefined)?.businessBirth;
+    const bindBusinessBirthPolicy =
+      (birthSteps[0]?.directive as BusinessBirthDirective | undefined)?.[BUSINESS_BIRTH_POLICY_BINDING];
     return {
       [INTENT_BRAND]: true,
       id: this.id,
@@ -472,6 +479,9 @@ class IntentBuilder<I> {
         ? {}
         : {
             birthsChild: true,
+            ...(bindBusinessBirthPolicy === undefined
+              ? {}
+              : { [BUSINESS_BIRTH_POLICY_BINDING]: bindBusinessBirthPolicy }),
             businessBirth: {
               ...businessBirth,
               publicPayloadSchema: this.contractDeclaration.accepts,

package/src/law_graph.ts

@@ -31,6 +31,7 @@ import {
   lowerLawValueType,
   type LawConstant,
   type LawLiteral,
+  type LawValueMember,
   type LawValueConstraint,
   type LawValueType,
 } from "./law_value_type.js";
@@ -176,6 +177,47 @@ export interface LawPayloadContractNode {
   readonly fields: readonly LawStructuralRef<"value-field">[];
 }
 
+/** Compiler-owned facts used to author `.owned()` effects. These are part of the
+ * internal typed USDA call contract, never the tenant-facing business contract. */
+const OWNED_AUTHORING_PAYLOAD_MEMBERS = [
+  {
+    name: OWNED_KEY_PAYLOAD_FIELD,
+    required: false,
+    value: { kind: "string", constraints: [] },
+  },
+  {
+    name: OWNED_CUSTODY_PAYLOAD_FIELD,
+    required: false,
+    value: { kind: "string", constraints: [] },
+  },
+  {
+    name: OWNED_PREMINTED_RECORDS_PAYLOAD_FIELD,
+    required: false,
+    value: {
+      kind: "list",
+      element: {
+        kind: "record",
+        fields: [
+          { name: "type", required: true, value: { kind: "string", constraints: [] } },
+          { name: "id", required: true, value: { kind: "string", constraints: [] } },
+        ],
+      },
+    },
+  },
+] as const satisfies readonly LawValueMember[];
+
+function internalPayloadContract(
+  tenantContract: LawValueType,
+  capabilities: ReadonlySet<"owned-authoring">,
+): LawValueType {
+  if (tenantContract.kind !== "record") return tenantContract;
+  if (!capabilities.has("owned-authoring")) return tenantContract;
+  return {
+    kind: "record",
+    fields: [...tenantContract.fields, ...OWNED_AUTHORING_PAYLOAD_MEMBERS],
+  };
+}
+
 export interface LawReadParameter {
   readonly name: string;
   readonly field?: LawFieldPathRef;
@@ -1112,7 +1154,7 @@ export function discoverLawGraph(
   const intentNodes: LawIntentNode[] = intents.map((intent) => {
     const intentEntity = intentEntities.get(intent.id)!;
     const businessBirth = (intent as {
-      businessBirth?: { publicPayloadSchema?: z.ZodTypeAny };
+      businessBirth?: { publicPayloadSchema?: z.ZodTypeAny; owned?: boolean };
     }).businessBirth;
     const payloadContractEntity = ownedEntity(
       "contract",
@@ -1122,21 +1164,32 @@ export function discoverLawGraph(
       `${intent.id}#accepts`,
       options.source?.("intent", intent.id, module.name),
     );
-    const payloadShape = lowerAnonymousContractFields(
-      lowerLawValueType(isBusinessIntent(intent) ? intent.contract.accepts : intent.payloadSchema),
-      payloadContractEntity,
+    // A business birth has two deliberately different typed boundaries:
+    //
+    //   * `contract.accepts` / `businessBirth.publicPayloadSchema` is the tenant-facing input;
+    //   * `payloadSchema` is the executable call contract after Nomos has added its private
+    //     principal, timestamp and (when needed) sealed-genesis facts.
+    //
+    // Collapsing both to `contract.accepts` made the generated client author the correct private
+    // facts into a USDA call whose `nomos:accepts` contract did not declare them. Keep ordinary
+    // compound intents on their public contract because they have no framework-only birth carrier;
+    // only a declared business birth owns this second typed boundary.
+    const tenantPayloadContract = lowerLawValueType(
+      isBusinessIntent(intent) && businessBirth === undefined
+        ? intent.contract.accepts
+        : intent.payloadSchema,
     );
-    for (const node of payloadShape.nodes) anonymousValueNodes.set(node.entity.id, node);
-    for (const fieldRef of payloadShape.fields) {
-      const field = anonymousValueNodes.get(fieldRef.id);
-      if (field?.structuralKind !== "value-field") continue;
-      const reserved = [
+    if (tenantPayloadContract.kind !== "record") {
+      fail(`directive '${intent.id}': payload must lower to a record`);
+    }
+    for (const field of tenantPayloadContract.fields) {
+      const reserved = new Set<string>([
         OWNED_KEY_PAYLOAD_FIELD,
         OWNED_CUSTODY_PAYLOAD_FIELD,
         OWNED_PREMINTED_RECORDS_PAYLOAD_FIELD,
         BUSINESS_BIRTH_SEED_PAYLOAD_FIELD,
-      ];
-      if (!reserved.includes(field.name)) continue;
+      ]);
+      if (!reserved.has(field.name)) continue;
       const frameworkBirthCarrier = field.name === BUSINESS_BIRTH_SEED_PAYLOAD_FIELD && businessBirth !== undefined;
       if (frameworkBirthCarrier) continue;
       fail(
@@ -1145,6 +1198,23 @@ export function discoverLawGraph(
           `a different name.`,
       );
     }
+    const affectedAggregateIds = [
+      intent.aggregateId,
+      ...(intent.secondaryOutputs ?? []).map((output) => output.aggregateId),
+    ];
+    const frameworkCapabilities = new Set<"owned-authoring">();
+    if (
+      businessBirth?.owned === true ||
+      affectedAggregateIds.some((aggregateId) =>
+        aggregateByLabel.get(aggregateId)?.node.ownerField !== undefined)
+    ) {
+      frameworkCapabilities.add("owned-authoring");
+    }
+    const payloadShape = lowerAnonymousContractFields(
+      internalPayloadContract(tenantPayloadContract, frameworkCapabilities),
+      payloadContractEntity,
+    );
+    for (const node of payloadShape.nodes) anonymousValueNodes.set(node.entity.id, node);
     payloadContractNodes.push({
       kind: "payload-contract",
       entity: payloadContractEntity,

package/src/relation_schema.ts

@@ -108,6 +108,24 @@ export interface RelationTypeDecl {
   readonly __isRelationType: true;
 }
 
+/**
+ * A relation name that has deliberately crossed the authoring boundary.
+ *
+ * Plain strings remain accepted by the low-level DSL while existing tenant law migrates, but framework
+ * vocabulary should be coined once with {@link relationRef} and then reused by relation declarations,
+ * gates and tuple writes. That makes a rename a compiler-guided change instead of three unrelated string
+ * edits which can produce valid-looking, permanently unauthorized law.
+ */
+declare const NOMOS_RELATION_REF: unique symbol;
+export type RelationRef<Name extends string = string> = Name & {
+  readonly [NOMOS_RELATION_REF]: "NomosRelationRef";
+};
+
+/** Create one typed relation handle after validating the wire token once. */
+export function relationRef<const Name extends string>(name: Name): RelationRef<Name> {
+  return requireName(name, "relation") as RelationRef<Name>;
+}
+
 export function isRelationTypeDecl(v: unknown): v is RelationTypeDecl {
   return typeof v === "object" && v !== null && (v as { __isRelationType?: unknown }).__isRelationType === true;
 }

package/src/shape_compat.ts

@@ -130,6 +130,9 @@ function payloadFieldKind(spec: PayloadFieldSpec): string {
     case "ref":
       // NomosRef<T> is aggregate-typed in the client and remains a string id on the wire.
       return "string";
+    case "addressRef":
+      // A workspace-qualified NomosRef<T> preserves its complete address object.
+      return "json";
     case "recipient":
       // Recipient<User> is nominal in clients and an opaque delivery address on the law wire.
       return "string";

package/src/stable_ids_for_module.ts

@@ -254,7 +254,13 @@ function safeIdentityProjection(sourceShape: unknown, targetShape: unknown): boo
   const target = targetShape as Record<string, unknown>;
   const physical = (shape: Record<string, unknown>) => {
     const { kind, mapValueKind, jsonShape, encrypted } = shape;
-    return { kind, mapValueKind, jsonShape, encrypted };
+    // `t.ref` and `t.foreignRef` store the target aggregate id as the same Str
+    // value as `t.string`; `ref` is a semantic/codegen contract, not a distinct
+    // kernel encoding. The JSON-schema subset check below still prevents an
+    // atomic NomosRef object (or any other non-string reference contract) from
+    // being mistaken for this identity migration.
+    const encodingKind = kind === "ref" ? "string" : kind;
+    return { kind: encodingKind, mapValueKind, jsonShape, encrypted };
   };
   return canonicalJson(physical(source)) === canonicalJson(physical(target))
     && jsonSchemaSubset(source.jsonSchema, target.jsonSchema);

package/src/value_object.ts

@@ -321,6 +321,46 @@ const nomosAddressSchema = z.object({
   id: z.string().min(1),
 });
 
+/**
+ * THE WORKSPACE-QUALIFIED REFERENCE BRAND — `refOf(CatalogueWorkspace)` is
+ * wire-identical to Nomos' typed `{ workspace, type, id }` address, while
+ * generated clients expose it as `NomosRef<CatalogueWorkspace>`.  Unlike
+ * `idOf(...)`, this deliberately preserves the workspace because it is the
+ * canonical payload shape for cross-workspace navigation and custody effects.
+ */
+export const NOMOS_REFOF_BRAND: unique symbol = Symbol.for("nomos.refOf");
+
+export interface RefOfMeta {
+  readonly aggregateType: string;
+  readonly targetKind: "aggregate" | "contract";
+}
+
+export function refOf(target: RefTarget): z.ZodType<z.infer<typeof nomosAddressSchema>> {
+  const resolved = refTargetMeta(target, "refOf");
+  const schema = nomosAddressSchema.strict();
+  Object.defineProperty(schema, NOMOS_REFOF_BRAND, {
+    value: {
+      aggregateType: resolved.type,
+      targetKind: resolved.kind,
+    } satisfies RefOfMeta,
+    enumerable: false,
+  });
+  return schema;
+}
+
+/** Resolve `refOf(...)` metadata through omission/null wrappers. */
+export function refOfMetaOf(zt: z.ZodTypeAny): RefOfMeta | undefined {
+  let cur: z.ZodTypeAny | undefined = zt;
+  for (let hops = 0; cur !== undefined && hops < 16; hops++) {
+    const branded = (cur as unknown as Record<symbol, unknown>)[NOMOS_REFOF_BRAND];
+    if (typeof branded === "object" && branded !== null) return branded as RefOfMeta;
+    const kind = zodKind(cur);
+    if (kind !== "optional" && kind !== "default" && kind !== "nullable") return undefined;
+    cur = zodDef(cur).innerType;
+  }
+  return undefined;
+}
+
 /**
  * A payload field holding an immutable publication and its stable current-version
  * series. The kernel receives `{pinned, series}`; `current` is compiled law and