@githolon/dsl 0.103.3 → 0.103.5

package/src/births.ts

@@ -7,7 +7,7 @@ import { z } from "zod";
 import type { AggregateHandle } from "./aggregate.js";
 import type { AggregateRef } from "./authoring.js";
 import type { Ports } from "./ctx.js";
-import type { Field, FieldValue } from "./fields.js";
+import type { Field, FieldValue, NomosRefValue } from "./fields.js";
 
 /**
  * THE BIRTH EFFECT — birth is an EXPLICIT, DECLARED kernel primitive (G3, the unix model).
@@ -76,6 +76,9 @@ export interface BusinessBirthDecl<
   readonly payloadSchema: z.ZodObject<z.ZodRawShape> & z.ZodType<P>;
   /** A stable business key the caller already knows (an estate reference, account number, etc.). */
   readonly key: (payload: P) => string;
+  /** The complete custody address this declaration gives the born root.
+   * Carry it in parent projections instead of reconstructing workspace names in tenant code. */
+  readonly reference: (payload: P) => NomosRefValue;
   /** The declared business fact used by {@link key}; retained for generated clients to pre-address custody. */
   readonly keyField: string;
   /** Framework-derived initial authoring. Tenant code marks aggregate fields `.fromBirth()` instead. */
@@ -192,11 +195,23 @@ export function birth<F extends Record<string, Field>>(
       );
     }
     type Payload = BusinessBirthPayload<F>;
+    const aggregateNoun = aggregate.id
+      .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+      .toLowerCase();
+    const namespace = (spec.namespace ?? aggregateNoun)
+      .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+      .toLowerCase();
+    const rootId = `${aggregateNoun}:self`;
     const declaration = {
       __isBusinessBirth: true,
       aggregate,
       payloadSchema,
       key: (payload: Payload) => String(payload[spec.key]),
+      reference: (payload: Payload): NomosRefValue => ({
+        workspace: workspaceNameForKey(namespace, String(payload[spec.key])),
+        type: aggregate.id,
+        id: rootId,
+      }),
       keyField: spec.key,
       plan: (root: AggregateRef<F>, payload: Payload, ctx: Ports) => {
         const writable = root as unknown as { set(field: string, value: unknown): unknown };

package/src/business_birth.ts

@@ -48,16 +48,36 @@ import {
   identityRelations,
   signerDelegationByUser,
 } from "./framework/signing_identity.js";
+import {
+  DomainInstallExecutor,
+  currentLawReference,
+  domainInstallGenesisOffer,
+} from "./framework/domain_lifecycle.js";
 
-/** Private recipe selectors. The kernel resolves these against the parent's current installed law. */
-export const CURRENT_LAW_PREFIX = "nomos:current-law:";
 /** @internal Compiler-only domain enumeration. It carries no allowance or authority. */
 export const BUSINESS_BIRTH_POLICY_DOMAINS_EXPORT = "__nomos_birth_policy_domains_c9f14a";
 
+/**
+ * Typed compiler seam carried by an already-lowered birth consequence.
+ *
+ * A narrow plan can retain a public intent whose closure contains a child birth
+ * without retaining the child module's top-level declaration export.  The
+ * symbol keeps the compiler's namespace binding attached to that executable
+ * value, without another string-key convention or a scan of function source.
+ */
+export const BUSINESS_BIRTH_POLICY_BINDING = Symbol("nomos.business-birth-policy-binding");
+
+export interface BusinessBirthPolicyBinding {
+  readonly [BUSINESS_BIRTH_POLICY_BINDING]: (domains: readonly string[]) => void;
+}
+
 export interface BusinessBirthMetadata {
   readonly aggregateId: string;
   /** Owning law domain for closure-safe cross-workspace intent linking. */
   readonly domain: string;
+  /** The born root uses Nomos-owned custody, so the compiler must type the private
+   *  authoring facts carried beside (but never exposed as) the tenant payload. */
+  readonly owned: boolean;
   readonly publicPayloadSchema: z.ZodObject<z.ZodRawShape>;
   readonly rootId: string;
   readonly namespace: string;
@@ -71,7 +91,8 @@ export interface BusinessBirthMetadata {
   readonly founderScope: string;
 }
 
-export interface BusinessBirthDirective extends Directive<Record<string, unknown>> {
+export interface BusinessBirthDirective
+  extends Directive<Record<string, unknown>>, BusinessBirthPolicyBinding {
   readonly businessBirth: BusinessBirthMetadata;
 }
 
@@ -92,11 +113,8 @@ function internalSurface<T extends object>(value: T): T & { readonly businessBir
 const INTERNAL_FIELDS = [
   "principal",
   "bornAt",
-  "ownerKeyHash",
-  "birthCert",
   BUSINESS_BIRTH_SEED_PAYLOAD_FIELD,
 ] as const;
-const sha256Hex = z.string().regex(/^[0-9a-f]{64}$/);
 
 /**
  * Every business-born workspace verifies its own travelling birth certificate against its warrant owner.
@@ -117,6 +135,14 @@ function businessBirthsOf(mod: Record<string, unknown>): BusinessBirthDecl[] {
   );
 }
 
+function businessBirthPolicyBindingsOf(mod: Record<string, unknown>): BusinessBirthPolicyBinding[] {
+  return Object.values(mod).filter((value): value is BusinessBirthPolicyBinding =>
+    value !== null &&
+    typeof value === "object" &&
+    BUSINESS_BIRTH_POLICY_BINDING in value
+  );
+}
+
 // A declared birth remains reusable as framework law, but once a wider business
 // intent composes it there must not also be a generated direct-birth lane. That
 // second lane could skip the intent's parent-workspace consequences and let two
@@ -151,8 +177,6 @@ function lowerOne<P extends Record<string, unknown>, F extends Record<string, Fi
   const seedSchema = publicSchema.extend({
     principal: z.string().min(1),
     bornAt: z.string().min(1),
-    ownerKeyHash: sha256Hex.optional(),
-    birthCert: z.string().optional(),
   });
   const parentSchema = seedSchema.extend({
     ...(encryptedBirth ? { [BUSINESS_BIRTH_SEED_PAYLOAD_FIELD]: z.string().min(1) } : {}),
@@ -234,20 +258,16 @@ function lowerOne<P extends Record<string, unknown>, F extends Record<string, Fi
       }
       delete childPayload[BUSINESS_BIRTH_SEED_PAYLOAD_FIELD];
       const chain: Array<Record<string, unknown>> = [
-        {
-          domain: "bootstrap",
-          directiveId: "installDomain",
-          actor: founder,
-          payload: { domainHash: `${CURRENT_LAW_PREFIX}nomos` },
-          domainHash: `${CURRENT_LAW_PREFIX}nomos`,
-        },
-        {
-          domain: "nomos",
-          directiveId: "installDomain",
-          actor: founder,
-          payload: { domainHash: `${CURRENT_LAW_PREFIX}${domain}` },
-          domainHash: `${CURRENT_LAW_PREFIX}${domain}`,
-        },
+        domainInstallGenesisOffer(
+          DomainInstallExecutor.StageZero,
+          currentLawReference("nomos"),
+          founder,
+        ),
+        domainInstallGenesisOffer(
+          DomainInstallExecutor.LifecycleController,
+          currentLawReference(domain),
+          founder,
+        ),
         ...(decl.__nomosBirthPolicyDomains ?? initialBirthPolicyDomains).map((policyDomain) => ({
           domain: policyDomain,
           directiveId: "seedBirthPolicy",
@@ -275,21 +295,6 @@ function lowerOne<P extends Record<string, unknown>, F extends Record<string, Fi
         const v = ap?.[k];
         return typeof v === "string" && v.length > 0 ? v : undefined;
       };
-      let verified = false;
-      try { verified = typeof p.birthCert === "string" && JSON.parse(p.birthCert).verified === true; } catch {}
-      if (typeof p.ownerKeyHash === "string") {
-        chain.push({
-          domain,
-          directiveId: "enrollSigner",
-          actor: founder,
-          payload: {
-            keyHash: p.ownerKeyHash,
-            grantedBy: founder,
-            grantedAt: 1,
-            ...(verified && apStr("issuer") ? { verifiedVia: apStr("issuer") } : {}),
-          },
-        });
-      }
       if (apStr("issuer")) {
         chain.push({
           domain,
@@ -319,6 +324,7 @@ function lowerOne<P extends Record<string, unknown>, F extends Record<string, Fi
   const metadata: BusinessBirthMetadata = {
     aggregateId: decl.aggregate.id,
     domain,
+    owned: decl.aggregate.audience?.kind === "owned",
     publicPayloadSchema: publicSchema,
     rootId,
     namespace,
@@ -337,6 +343,9 @@ function lowerOne<P extends Record<string, unknown>, F extends Record<string, Fi
   const parent = {
     ...birthBase,
     businessBirth: metadata,
+    [BUSINESS_BIRTH_POLICY_BINDING]: (domains: readonly string[]) => {
+      decl.__nomosBirthPolicyDomains = domains;
+    },
     ...(applicationIntentOnlyBirths.has(decl) ? { businessBirthInternal: true } : {}),
   } as BusinessBirthDirective;
   return {
@@ -417,7 +426,11 @@ export function bindBusinessBirthPolicyDomains(
   domains: readonly string[],
 ): void {
   const declarations = businessBirthsOf(mod);
-  if (declarations.length === 0) return;
+  const bindings = businessBirthPolicyBindingsOf(mod);
+  // Packages without a birth surface have no policy value to bind. In
+  // particular, an application-less package legitimately has no application
+  // birth-policy namespace inventory.
+  if (declarations.length === 0 && bindings.length === 0) return;
   const unique = [...new Set(domains)];
   if (unique.length === 0 || unique.some((value) => value.trim().length === 0)) {
     throw new Error("birth policy namespaces must be a non-empty list of domain names");
@@ -425,6 +438,9 @@ export function bindBusinessBirthPolicyDomains(
   for (const declaration of declarations) {
     declaration.__nomosBirthPolicyDomains = unique;
   }
+  for (const binding of bindings) {
+    binding[BUSINESS_BIRTH_POLICY_BINDING](unique);
+  }
 }
 
 /** Lower the one tenant-facing birth declaration into ordinary, gate-visible framework directives. */
@@ -434,13 +450,7 @@ export function expandBusinessBirthExports<M extends Record<string, unknown>>(
   birthPolicyDomains?: readonly string[],
 ): Record<string, unknown> {
   const declarations = businessBirthsOf(mod);
-  if (declarations.length === 0) return mod;
-  if (declarations.length > 1) {
-    throw new Error(
-      `domain '${domain}' declares ${declarations.length} business births; one generated birth(payload) cannot be ` +
-        "ambiguous — model one born aggregate root per domain",
-    );
-  }
+  if (declarations.length === 0 && businessBirthPolicyBindingsOf(mod).length === 0) return mod;
   const compiledDomains = mod[BUSINESS_BIRTH_POLICY_DOMAINS_EXPORT];
   const selectedDomains = birthPolicyDomains ?? (
     Array.isArray(compiledDomains) && compiledDomains.every((value) => typeof value === "string")
@@ -449,9 +459,20 @@ export function expandBusinessBirthExports<M extends Record<string, unknown>>(
   );
   const policyDomains = [...new Set(selectedDomains)];
   if (policyDomains.length === 0 || policyDomains.some((value) => value.trim().length === 0)) {
-    throw new Error(`birth(${declarations[0]!.aggregate.id}): compiled law declares no policy namespaces`);
+    const subject = declarations[0]?.aggregate.id ?? `domain '${domain}'`;
+    throw new Error(`birth(${subject}): compiled law declares no policy namespaces`);
   }
   bindBusinessBirthPolicyDomains(mod, policyDomains);
+  // A sliced parent intent may carry an already-lowered child birth through the
+  // typed binding above while exporting no raw BusinessBirthDecl of its own.
+  // Binding that closure is the complete job for this domain.
+  if (declarations.length === 0) return mod;
+  if (declarations.length > 1) {
+    throw new Error(
+      `domain '${domain}' declares ${declarations.length} business births; one generated birth(payload) cannot be ` +
+        "ambiguous — model one born aggregate root per domain",
+    );
+  }
   const lowered = lowerOne(declarations[0]!, domain, policyDomains);
   for (const [key, generated] of Object.entries(lowered)) {
     if (!Object.prototype.hasOwnProperty.call(mod, key)) continue;

package/src/codegen_dart.ts

@@ -29,12 +29,12 @@
  * generated, so they stay reproducible from the domain definitions.
  */
 import { z } from "zod";
-import { voMetaOf, collectPayloadValueObjectDescriptors, idOfMetaOf, idOfTargetKindOf, versionedRefOfMetaOf, brandedIdMetaOf, NOMOS_UNIT_BRAND } from "./value_object.js";
+import { voMetaOf, collectPayloadValueObjectDescriptors, idOfMetaOf, idOfTargetKindOf, refOfMetaOf, versionedRefOfMetaOf, brandedIdMetaOf, NOMOS_UNIT_BRAND } from "./value_object.js";
 import { recursiveTypeBaseName, zodUnwrapLazy } from "./zod_lazy.js";
 import type { AggregateHandle } from "./aggregate.js";
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
 import type { RelationTypeDecl } from "./relation_schema.js";
-import { isSha256DigestSchema, type Field, type FieldKind, type ValueObjectDescriptor, type ValueObjectFieldDescriptor } from "./fields.js";
+import { isGitObjectIdSchema, isSha256DigestSchema, type Field, type FieldKind, type ValueObjectDescriptor, type ValueObjectFieldDescriptor } from "./fields.js";
 import { admitsNull, nullMetaOf, nullDocLine } from "./null_meta.js";
 import type { Directive } from "./directive.js";
 import { executeDirectiveToIntent } from "./wire_encode.js";
@@ -84,6 +84,7 @@ export type ToJsonWrap =
   | "voList" // a list of value objects — emit `.map((e) => e.toJson()).toList()`.
   | "wrapped" // a standalone branded-id or unit extension type — emit `.value`.
   | "ref" // an aggregate-specific NomosRef<T> — emit its `.id` wire scalar.
+  | "addressRef" // a workspace-qualified NomosRef<T> — preserve its complete typed address.
   | "versionedRef" // a publication pin + stable series — emit the atomic address pair.
   | "recipient"; // a framework-created Recipient<User> — emit its private delivery address.
 
@@ -426,7 +427,8 @@ export function collectPayloadIdOfTargets(directives: readonly { payloadSchema?:
       continue;
     }
     for (const zt of Object.values(shape)) {
-      const target = idOfMetaOf(zt as z.ZodTypeAny);
+      const target = idOfMetaOf(zt as z.ZodTypeAny)
+        ?? refOfMetaOf(zt as z.ZodTypeAny)?.aggregateType;
       if (target !== undefined) out.add(target);
     }
   }
@@ -443,6 +445,18 @@ function introspectField(
   enumDartTypes: Map<string, string>,
   lazyNames?: Map<z.ZodTypeAny, string>,
 ): Omit<PayloadFieldSpec, "optional"> {
+  const addressed = refOfMetaOf(zt);
+  if (addressed !== undefined) {
+    const target = addressed.targetKind === "contract"
+      ? contractTypeName(addressed.aggregateType)
+      : concreteClassName(addressed.aggregateType);
+    return {
+      name,
+      dartType: `NomosRef<${target}>`,
+      referenceType: addressed.aggregateType,
+      toJson: "addressRef",
+    };
+  }
   const versioned = versionedRefOfMetaOf(zt);
   if (versioned !== undefined) {
     const target = versioned.targetKind === "contract"
@@ -518,6 +532,9 @@ function introspectField(
       if (isSha256DigestSchema(zt)) {
         return { name, dartType: "Sha256Digest", toJson: "wrapped", wrappedScalarKind: "string" };
       }
+      if (isGitObjectIdSchema(zt)) {
+        return { name, dartType: "GitObjectId", toJson: "wrapped", wrappedScalarKind: "string" };
+      }
       // brandedId("SiteId"): a standalone nominal string → the generated extension type.
       const brand = brandedIdMetaOf(zt);
       if (brand !== undefined) {
@@ -625,7 +642,7 @@ interface AggFieldSpec {
   kind: MaterializedFieldKind;
   dartType: string;
   /** A canonical semantic string wrapper whose wire representation remains String. */
-  semanticString?: "sha256";
+  semanticString?: "sha256" | "git-object-id";
   enumValues?: string[];
   /** For an own-id string field represented as `NomosRef<TAggregate>`. */
   valueClass?: string;
@@ -845,6 +862,9 @@ function readKeyParamSpec(
   if (fieldSpec.semanticString === "sha256") {
     return { dartType: "Sha256Digest", valueExpr: `${paramName}.value` };
   }
+  if (fieldSpec.semanticString === "git-object-id") {
+    return { dartType: "GitObjectId", valueExpr: `${paramName}.value` };
+  }
   return { dartType: "String", valueExpr: paramName };
 }
 
@@ -954,12 +974,19 @@ function aggFieldSpec(
         wireName,
         kind: field.kind,
         dartType: valueClass === undefined
-          ? isSha256DigestSchema(field.zod as z.ZodTypeAny) ? "Sha256Digest" : "String"
+          ? isSha256DigestSchema(field.zod as z.ZodTypeAny)
+            ? "Sha256Digest"
+            : isGitObjectIdSchema(field.zod as z.ZodTypeAny)
+              ? "GitObjectId"
+              : "String"
           : `NomosRef<${valueClass}>`,
         optional,
         ...(valueClass === undefined && isSha256DigestSchema(field.zod as z.ZodTypeAny)
           ? { semanticString: "sha256" as const }
           : {}),
+        ...(valueClass === undefined && isGitObjectIdSchema(field.zod as z.ZodTypeAny)
+          ? { semanticString: "git-object-id" as const }
+          : {}),
         ...(valueClass !== undefined && valueAggregateType !== undefined
           ? { valueClass, valueAggregateType }
           : {}),
@@ -2610,19 +2637,29 @@ export function generateDartActivityRegistry(entries: readonly PackageActivityEn
     `  const NomosModelReview({required this.checkedActions, required this.candidateActions, required this.sameOutcome, required this.differences});`,
     `}`,
     ``,
-    `enum NomosModelAdoptionStatus { adopted, needsDecision, blocked }`,
+    `enum NomosModelAdoptionStatus { adopted, needsStaging, needsDecision, blocked }`,
     ``,
     `class NomosModelAdoption {`,
     `  final NomosModelAdoptionStatus status;`,
     `  final String summary;`,
     `  final NomosModelReview review;`,
+    `  final Future<NomosModelAdoption> Function()? _stage;`,
     `  final Future<NomosModelAdoption> Function(String)? _accept;`,
     `  const NomosModelAdoption.adopted({required this.summary, required this.review})`,
-    `      : status = NomosModelAdoptionStatus.adopted, _accept = null;`,
+    `      : status = NomosModelAdoptionStatus.adopted, _stage = null, _accept = null;`,
     `  const NomosModelAdoption.blocked({required this.summary, required this.review})`,
-    `      : status = NomosModelAdoptionStatus.blocked, _accept = null;`,
+    `      : status = NomosModelAdoptionStatus.blocked, _stage = null, _accept = null;`,
+    `  NomosModelAdoption.needsStaging({required this.summary, required this.review, required Future<NomosModelAdoption> Function() stage})`,
+    `      : status = NomosModelAdoptionStatus.needsStaging, _stage = stage, _accept = null;`,
     `  NomosModelAdoption.needsDecision({required this.summary, required this.review, required Future<NomosModelAdoption> Function(String) accept})`,
-    `      : status = NomosModelAdoptionStatus.needsDecision, _accept = accept;`,
+    `      : status = NomosModelAdoptionStatus.needsDecision, _stage = null, _accept = accept;`,
+    `  Future<NomosModelAdoption> stage() {`,
+    `    final stageCandidate = _stage;`,
+    `    if (status != NomosModelAdoptionStatus.needsStaging || stageCandidate == null) {`,
+    `      throw StateError('This model change is not waiting to be staged.');`,
+    `    }`,
+    `    return stageCandidate();`,
+    `  }`,
     `  Future<NomosModelAdoption> accept(String because) {`,
     `    final reason = because.trim();`,
     `    final acceptDecision = _accept;`,
@@ -2974,6 +3011,11 @@ function parseField(s: AggFieldSpec, aggregate: string): string {
             ? `() { final v = ${reader}; return v == null ? null : Sha256Digest(v); }()`
             : `Sha256Digest(${reader})`;
         }
+        if (s.semanticString === "git-object-id") {
+          return opt
+            ? `() { final v = ${reader}; return v == null ? null : GitObjectId(v); }()`
+            : `GitObjectId(${reader})`;
+        }
         return reader;
       }
     case "json":
@@ -3060,7 +3102,9 @@ function slotDecodeCallback(s: AggFieldSpec, mode: "aggregate" | "readModel"): s
       }
       return s.semanticString === "sha256"
         ? `(v) => Sha256Digest(v as String)`
-        : `(v) => v as String`;
+        : s.semanticString === "git-object-id"
+          ? `(v) => GitObjectId(v as String)`
+          : `(v) => v as String`;
     case "json":
       if (s.voClass !== undefined) {
         return `(v) => ${s.voClass}.fromProjected((v as Map).cast<String, Object?>())`;
@@ -3208,6 +3252,11 @@ function parseReadModelField(s: AggFieldSpec, aggregate: string): string {
             ? `() { final v = ${reader}; return v == null ? null : Sha256Digest(v); }()`
             : `Sha256Digest(${reader})`;
         }
+        if (s.semanticString === "git-object-id") {
+          return opt
+            ? `() { final v = ${reader}; return v == null ? null : GitObjectId(v); }()`
+            : `GitObjectId(${reader})`;
+        }
         return reader;
       }
     case "json":
@@ -3630,6 +3679,8 @@ export function toJsonExpr(spec: PayloadFieldSpec, accessor: string): string {
       return `${accessor}.value`;
     case "ref":
       return `NmsInternalNomosRefs.id(${accessor})`;
+    case "addressRef":
+      return `NmsInternalNomosRefs.toJson(${accessor})`;
     case "versionedRef":
       return `{'pinned': NmsInternalNomosRefs.toJson(${accessor}.pinned), 'series': NmsInternalNomosRefs.toJson(${accessor}.series)}`;
     case "recipient":
@@ -4309,7 +4360,8 @@ function buildProbePayload(
       zt = zodInnerType(zt);
     }
     const sentinel = fieldBySentinel.get(name);
-    out[name] = sentinel !== undefined && zodTypeName(zt) === "ZodString" && !isSha256DigestSchema(zt)
+    out[name] = sentinel !== undefined && zodTypeName(zt) === "ZodString" &&
+      !isSha256DigestSchema(zt) && !isGitObjectIdSchema(zt)
       ? sentinel
       : sampleFromZod(zt);
   }
@@ -4324,7 +4376,11 @@ function sampleFromZod(zt: z.ZodTypeAny): unknown {
   }
   switch (zodTypeName(t)) {
     case "ZodString":
-      return isSha256DigestSchema(t) ? "0".repeat(64) : "x";
+      return isSha256DigestSchema(t)
+        ? "0".repeat(64)
+        : isGitObjectIdSchema(t)
+          ? "0".repeat(40)
+          : "x";
     case "ZodNumber":
       return 1;
     case "ZodBoolean":