@githolon/dsl 0.103.1 → 0.103.2

package/src/compile_package_main.ts

@@ -103,7 +103,11 @@ import {
 import { synthesizePreconditionInvariants } from "./precondition.js";
 import { BIRTH_FRAMEWORK_QUERIES, synthesizeBirthQuotaInvariants } from "./birth_meter.js";
 import { withBirthMeterExports } from "./birth_meter_ensure.js";
-import { expandBusinessBirthExports } from "./business_birth.js";
+import {
+  BUSINESS_BIRTH_POLICY_DOMAINS_EXPORT,
+  bindBusinessBirthPolicyDomains,
+  expandBusinessBirthExports,
+} from "./business_birth.js";
 import { withOwnedCustodyExports } from "./framework/owned_custody.js";
 import { expandRoleExports, rolesOf } from "./role.js";
 import { collectEngineRouting } from "./engine_entry.js";
@@ -158,6 +162,8 @@ import { checkDomainModules, formatFindings, hasRefusal } from "./law_check.js";
 import type { NomosCompat } from "./compat_manifest.js";
 import { requiredKernelFeatures, type FeatureProbeModule } from "./kernel_capabilities.js";
 import { APPLICATION_HOME_DOMAIN } from "./framework/application_home_domain.js";
+import { applicationHomePolicyLaw } from "./framework/application_home.js";
+import { isApplicationHomeGenesis } from "./application_home_genesis.js";
 import { resolveApplicationTopology } from "./application_topology.js";
 import { isBusinessIntent } from "./intent.js";
 import {
@@ -1805,6 +1811,10 @@ function generatedPackageApplication(
   const invitationPolicies = members.flatMap(({ domain, invitationPolicies }) =>
     invitationPolicies.map((policy) => ({ domain, ...policy })));
   const hasInvitations = invitationPolicies.length > 0;
+  const rootMember = members.find(({ domain }) => domain === homeDomain);
+  if (rootMember === undefined) {
+    throw new Error(`generated Dart package application cannot expose the model for home domain '${homeDomain}'`);
+  }
   const duplicate = members.find((candidate, index) =>
     members.findIndex((other) => other.member === candidate.member) !== index);
   if (duplicate !== undefined) {
@@ -1817,6 +1827,7 @@ function generatedPackageApplication(
     ["currentUser", "the generated signed-in application participant"],
     ["currentStatus", "the generated application status"],
     ["watchStatus", "the generated application status watch"],
+    ["model", "the generated model lifecycle"],
     ["recipient", "the generated typed recipient boundary"],
     ["createInvitation", "the generated invitation capability"],
     ["redeemInvitation", "the generated invitation redemption"],
@@ -1836,7 +1847,7 @@ function generatedPackageApplication(
     `import 'package:flutter/widgets.dart';`,
     `import 'package:nomos_flutter/src/application_status.dart' show ApplicationSignIn, ApplicationStatus;`,
     `import 'package:nomos_client/src/nms_generated_runtime.dart' show NmsInternalUsers, NomosSession, User${hasInvitations ? ", Invitation, Recipient" : ""};`,
-    `import 'package:nomos_flutter/src/generated_application_host.dart' show NmsInternalApplicationHost, NmsInternalApplicationUserBinding${hasInvitations ? ", NmsInternalInvitationPolicy" : ""};`,
+    `import 'package:nomos_flutter/src/generated_application_host.dart' show NomosApplicationStartupState, NmsInternalApplicationHost, NmsInternalApplicationUserBinding${hasInvitations ? ", NmsInternalInvitationPolicy" : ""};`,
     ...members.map(({ file, prefix }) =>
       `import '${file}.application.dart' as ${prefix};`),
     ``,
@@ -1866,6 +1877,9 @@ function generatedPackageApplication(
     ]),
     `  const ${application}._({required NomosSession nmsSession, ${hasInvitations ? "required NmsInternalApplicationUserBinding nmsUser, " : ""}required this.currentUser, ${members.map(({ member }) => `required this.${member}`).join(", ")}}) : _nmsSession = nmsSession${hasInvitations ? ", _nmsUser = nmsUser" : ""};`,
     ``,
+    `  /// Prove, adopt or restore the package law against this workspace's exact history.`,
+    `  ${rootMember.prefix}.NomosModel get model => ${rootMember.member}.model;`,
+    ``,
     `  /// Current durability and convergence across this business application.`,
     `  ApplicationStatus get currentStatus => NmsInternalApplicationHost.currentStatus(_nmsSession);`,
     ``,
@@ -1916,10 +1930,12 @@ function generatedPackageApplication(
     `    required Widget Function(BuildContext context, ${application} application) builder,`,
     `    Widget Function(BuildContext context)? loadingBuilder,`,
     `    Widget Function(BuildContext context, Object error, VoidCallback retry)? errorBuilder,`,
+    `    ValueChanged<NomosApplicationStartupState>? onStartupStateChanged,`,
     `  }) => NmsInternalApplicationHost.home<${application}>(`,
     `    key: key, cloud: cloud, application: application, signIn: signIn,`,
     `    bind: nomosInternalBind${application}, builder: builder,`,
     `    loadingBuilder: loadingBuilder, errorBuilder: errorBuilder,`,
+    `    onStartupStateChanged: onStartupStateChanged,`,
     `  );`,
     `}`,
     ``,
@@ -2085,6 +2101,7 @@ function emitDartPackages(
   compat?: NomosCompat,
   describePackageName = packages.client,
   lawUsdzPath?: string,
+  applicationMaxChildWorkspacesPerUser?: number,
 ): { written: string[]; cursed: string[] } {
   for (const [role, name] of Object.entries(packages)) {
     if (typeof name !== "string" || !isPubPackageName(name)) {
@@ -2547,6 +2564,9 @@ function emitDartPackages(
             surfaceName,
             applicationFile,
             applicationModules: perDomain.map(({ dd: candidate }) => candidate.modForDart),
+            ...(applicationMaxChildWorkspacesPerUser === undefined
+              ? {}
+              : { applicationMaxChildWorkspacesPerUser }),
           },
         ),
         "utf8",
@@ -2765,6 +2785,52 @@ async function main(): Promise<void> {
         `rename the tenant domain (Nomos will not silently overwrite or reroute it)`,
     );
   }
+  if (cfg.rootPart !== undefined && cfg.application === undefined) {
+    fail(
+      "published application packages must declare application: { maxChildWorkspacesPerUser }; " +
+        "Nomos will not compile a birth-capable home with an implicit quota",
+    );
+  }
+  // A born application home may carry several co-resident law namespaces. BirthPolicy is namespaced
+  // law-state, so genesis must seed every domain that can itself birth; seeding only the private home
+  // domain would leave (for example) `home/birthEstate` correctly refusing its first offer. Discover the
+  // set from the authored modules and bake it into the private genesis plan. The host never supplies it.
+  const applicationBirthPolicyDomains: string[] = [];
+  let applicationHomeGenesisSource:
+    | { readonly modulePath: string; readonly exportName: string }
+    | undefined;
+  if (cfg.rootPart !== undefined) {
+    applicationBirthPolicyDomains.push(APPLICATION_HOME_DOMAIN);
+  }
+  for (const domain of cfg.domains) {
+    let authored: Mod = {};
+    for (const rel of domain.modules) {
+      const abs = path.resolve(cfgDir, rel);
+      if (!existsSync(abs)) fail(`domain '${domain.key}': module not found: ${abs}`);
+      const imported = await import(pathToFileURL(abs).href) as Mod;
+      authored = { ...authored, ...imported };
+      for (const [exportName, value] of Object.entries(imported)) {
+        if (value !== cfg.application?.homeGenesis || !isApplicationHomeGenesis(value)) continue;
+        if (applicationHomeGenesisSource !== undefined) {
+          fail(
+            "application.homeGenesis is exported from more than one configured law module; " +
+              "keep one canonical declaration",
+          );
+        }
+        applicationHomeGenesisSource = { modulePath: abs, exportName };
+      }
+    }
+    const expanded = expandBusinessBirthExports(authored, domain.key);
+    if (directivesOf(expanded).some((dir) => dir.birthsChild === true)) {
+      applicationBirthPolicyDomains.push(domain.key);
+    }
+  }
+  if (cfg.application?.homeGenesis !== undefined && applicationHomeGenesisSource === undefined) {
+    fail(
+      "application.homeGenesis must be exported by one configured law module; " +
+        "genesis is custody law, not an inline compiler-only callback",
+    );
+  }
   const domainsToCompile: DomainConfig[] = [
     ...cfg.domains,
     ...(cfg.rootPart === undefined
@@ -2944,9 +3010,39 @@ async function main(): Promise<void> {
         }
       }
     }
+    if (mods.some((mod) => Object.prototype.hasOwnProperty.call(mod, BUSINESS_BIRTH_POLICY_DOMAINS_EXPORT))) {
+      fail(
+        `domain '${d.key}' exports reserved compiler binding '${BUSINESS_BIRTH_POLICY_DOMAINS_EXPORT}'; ` +
+          "rename the tenant export",
+      );
+    }
+    if (d.key === APPLICATION_HOME_DOMAIN) {
+      const max = cfg.application?.maxChildWorkspacesPerUser;
+      if (max === undefined) {
+        fail("the private application home has no declared maxChildWorkspacesPerUser policy");
+      }
+      const homeGenesis = cfg.application?.homeGenesis;
+      const policyMod = applicationHomePolicyLaw(
+        max,
+        applicationBirthPolicyDomains,
+        homeGenesis,
+      ) as Mod;
+      mods.push(policyMod);
+      sourceExprs.push(
+        `() => require(${JSON.stringify(path.join(DSL_DIR, "src", "framework", "application_home.ts"))})` +
+          `.applicationHomePolicyLaw(` +
+          `${JSON.stringify(max)}, ${JSON.stringify(applicationBirthPolicyDomains)}, ` +
+          (applicationHomeGenesisSource === undefined
+            ? `undefined)`
+            : `require(${JSON.stringify(applicationHomeGenesisSource.modulePath)})` +
+              `[${JSON.stringify(applicationHomeGenesisSource.exportName)}])`),
+      );
+    }
     let merged: Mod = {};
     for (const m of mods) merged = { ...merged, ...m };
-    merged = expandBusinessBirthExports(merged, d.key);
+    merged[BUSINESS_BIRTH_POLICY_DOMAINS_EXPORT] = applicationBirthPolicyDomains;
+    bindBusinessBirthPolicyDomains(merged, applicationBirthPolicyDomains);
+    merged = expandBusinessBirthExports(merged, d.key, applicationBirthPolicyDomains);
     merged = withOwnedCustodyExports(merged);
     // `capability()` bundles expand into discoverable entries (the CLI plane's
     // merge point) — queries/sums/sid-minting/manifests all see the pieces.
@@ -3055,6 +3151,10 @@ async function main(): Promise<void> {
       }
     }
 
+    sourceExprs.push(
+      `() => ({ ${JSON.stringify(BUSINESS_BIRTH_POLICY_DOMAINS_EXPORT)}: ` +
+        `${JSON.stringify(applicationBirthPolicyDomains)} })`,
+    );
     const domainSource = `    ${JSON.stringify(d.key)}: [${sourceExprs.join(", ")}],`;
     entryDomainSourceByKey.set(d.key, domainSource);
     entryGeneratedSourceExprsByKey.set(d.key, sourceExprs.slice(d.modules.length));
@@ -3562,6 +3662,15 @@ async function main(): Promise<void> {
     // clients/interfaces; using the pre-closure executable module here published a USDA-only `birth` route.
     const graphModule = closedDomainModulesByName.get(mod.name) ?? mod;
     const discoveredGraph = discoverLawGraph(graphModule, continuity, nextIdentity);
+    for (const node of discoveredGraph.graph.nodes) {
+      if (node.kind === "intent" && node.births && node.birthPolicySeed === undefined) {
+        fail(
+          `domain '${identityName}' birth intent '${node.entity.label}' has no declared birth-policy ` +
+            "genesis verb; Nomos will not compile a birth-capable law whose children can enter " +
+            "custody without explicit policy",
+        );
+      }
+    }
     nextIdentity = discoveredGraph.registry;
     nextLock.identity = nextIdentity;
     typedLawGraphs.set(identityName, discoveredGraph.graph);
@@ -4864,7 +4973,14 @@ async function main(): Promise<void> {
   let birthWarnings: string[] = [];
   let proofNotes: string[] = [];
   try {
-    const proofSrc = generateTsProof(presentationDomainModules, { packageName: cfg.name, domainHash, interface: packageInterface });
+    const proofSrc = generateTsProof(presentationDomainModules, {
+      packageName: cfg.name,
+      domainHash,
+      interface: packageInterface,
+      ...(cfg.application?.maxChildWorkspacesPerUser === undefined
+        ? {}
+        : { applicationMaxChildWorkspacesPerUser: cfg.application.maxChildWorkspacesPerUser }),
+    });
     proofPath = path.join(outDir, `${cfg.name}.proof.mts`);
     writeFileSync(proofPath, proofSrc, "utf8");
     // THE PER-DOMAIN LEGS INDEX: every domain with a creating write, so
@@ -5269,7 +5385,7 @@ async function main(): Promise<void> {
     if (dartPackages !== undefined) {
       const r = emitDartPackages(
         presentationDomainModules, dartOut, domainHash, packageInterface, dartPackages,
-        dartNames, nomosCompat, cfg.name, lawUsdzPath,
+        dartNames, nomosCompat, cfg.name, lawUsdzPath, cfg.application?.maxChildWorkspacesPerUser,
       );
       dartFiles = r.written;
       dartCursedHints = r.cursed;

package/src/directive.ts

@@ -447,6 +447,14 @@ export interface Directive<P = unknown> {
    * `attestationAuthorizedGate`/`.attestationAuthorized()` naming convention; the declaration is the noun.)
    */
   readonly birthsChild?: boolean;
+  /** Additional ordinary offers which the born workspace's typed law requires in genesis.
+   * This is compiler/runtime metadata attached only to a birthing directive. It contains no
+   * payload or fallback value: the kernel checks that the re-derived recipe invokes each named
+   * law verb exactly once after installation. */
+  readonly birthGenesisRequirements?: readonly {
+    readonly domain: string;
+    readonly directiveId: string;
+  }[];
   /**
    * PROOF-TOOLING PRODUCER MARKER (relation-seed leg). Declares that this directive ESTABLISHES the named
    * relation(s) — i.e. its `plan` folds a `writeTuple` that grants the relation. Purely a static hint for

package/src/framework/application_home.ts

@@ -9,6 +9,7 @@
 // routable through the runtime OpenAPI, while TS/Dart/OpenAPI business surfaces omit it.
 
 import type { AggregateHandle } from "../aggregate.js";
+import type { ApplicationHomeGenesis } from "../application_home_genesis.js";
 import type { Directive } from "../directive.js";
 import type { QueryDecl } from "../query.js";
 import { APPLICATION_HOME_DOMAIN } from "./application_home_domain.js";
@@ -70,8 +71,24 @@ const aggregate = (value: AggregateHandle): Internal<AggregateHandle> => interna
 const directive = <P>(value: Directive<P>): Internal<Directive<P>> => internal(value);
 const query = (value: QueryDecl): Internal<QueryDecl> => internal(value);
 
-// Parent primitive + the law its born home uses.
-export const __nomos_birthReceivingGroup = directive(birthReceivingGroupForDomain(APPLICATION_HOME_DOMAIN));
+// Parent primitive + the law its born home uses. The compiler supplies the application's explicit
+// allowance through this factory; there is deliberately no static/default route to discover.
+export function applicationHomePolicyLaw(
+  maxChildWorkspacesPerUser: number,
+  birthPolicyDomains: readonly string[],
+  homeGenesis?: ApplicationHomeGenesis,
+) {
+  return {
+    __nomos_birthReceivingGroup: directive(
+      birthReceivingGroupForDomain(
+        APPLICATION_HOME_DOMAIN,
+        maxChildWorkspacesPerUser,
+        birthPolicyDomains,
+        homeGenesis,
+      ),
+    ),
+  };
+}
 export const __nomos_ReceivingGroup = aggregate(ReceivingGroup);
 export const __nomos_seedReceivingGroup = directive(seedReceivingGroup);
 export const __nomos_ReceivingGroupPolicy = aggregate(ReceivingGroupPolicy);

package/src/framework/birth_meter.ts

@@ -8,7 +8,7 @@
  *
  * The meter's STRUCTURE (record + queries + quota invariant + auto-capture) is auto-ensured on every
  * `.births()` law — see `../birth_meter.ts`. THIS module is the part a tenant COMPOSES IN when they
- * want to GOVERN the allowance instead of living on the conservative default:
+ * uses to govern its required, explicitly seeded allowance:
  *
  *   - {@link setBirthPolicy}      — set/amend the workspace's default allowance (admin-gated).
  *   - {@link grantBirthAllowance} — a per-subject override (admin-gated; latest grant wins).
@@ -56,7 +56,6 @@ export {
   childLifecyclesByStatus,
   birthPolicy,
   birthGrantByPrincipal,
-  DEFAULT_MAX_BIRTHS_PER_PRINCIPAL,
   birthQuotaVerdict,
   birthQuotaInvariantId,
 } from "../birth_meter.js";
@@ -238,7 +237,7 @@ export const setBirthPolicy = directive("setBirthPolicy")
   .ensures(BirthPolicy)
   .payload(
     z.object({
-      maxBirthsPerPrincipal: z.number().int().positive(),
+      maxBirthsPerPrincipal: z.number().int().nonnegative(),
       setBy: z.string().min(1),
       /** Caller-stamped (the timestamp doctrine). */
       setAt: z.string().min(1),
@@ -257,7 +256,7 @@ export const seedBirthPolicy = directive("seedBirthPolicy")
   .ensures(BirthPolicy)
   .payload(
     z.object({
-      maxBirthsPerPrincipal: z.number().int().positive(),
+      maxBirthsPerPrincipal: z.number().int().nonnegative(),
       setBy: z.string().min(1),
       setAt: z.string().min(1),
     }),
@@ -274,7 +273,7 @@ export const grantBirthAllowance = directive("grantBirthAllowance")
   .payload(
     z.object({
       principal: z.string().min(1),
-      maxBirths: z.number().int().positive(),
+      maxBirths: z.number().int().nonnegative(),
       grantedBy: z.string().min(1),
       /** epoch-ms — the recency tiebreak (latest grant wins), caller-stamped. */
       grantedAt: z.number().int().nonnegative(),

package/src/framework/home.ts

@@ -25,6 +25,7 @@
  * the result, and the owner-authored lane to maintain it.)
  */
 import { z } from "zod";
+import type { ApplicationHomeGenesis } from "../application_home_genesis.js";
 import { aggregate, instance, OWNED_READ_RELATION } from "../aggregate.js";
 // The device-key-hash wire shape (same validator signing_identity/workspaces use module-locally).
 const sha256Hex = z.string().regex(/^[0-9a-f]{64}$/, "expected lowercase sha256 hex (the owner's device pubkey hash)");
@@ -268,8 +269,8 @@ export function receivingGroupNameOf(principal: string): string {
  * so HomeOwner is seeded and `homeNameBindsOwner` passes (a birth without it would be an invalid, un-owned
  * home).
  */
-// The kernel's era-0 birth-seed resolver retains `home` as its fallback dispatch domain for standalone
-// framework laws. Compiler-composed business applications use the obscure APPLICATION_HOME_DOMAIN instead.
+// Standalone framework law explicitly declares `home`; compiler-composed business applications explicitly
+// declare the obscure APPLICATION_HOME_DOMAIN. The kernel refuses law with no attestation-seed registrar.
 export const RECEIVING_GROUP_LAW_DOMAIN = "home";
 /**
  * Build the private home-birth primitive for the domain key that carries the home law.
@@ -279,11 +280,33 @@ export const RECEIVING_GROUP_LAW_DOMAIN = "home";
  * tenant remains free to model a business concept called "home". The key is closed over
  * here and written into every child-genesis step; it is never a tenant payload field.
  */
-export function birthReceivingGroupForDomain(groupLawDomain: string) {
+export function birthReceivingGroupForDomain(
+  groupLawDomain: string,
+  maxChildWorkspacesPerUser: number,
+  birthPolicyDomains: readonly string[],
+  homeGenesis?: ApplicationHomeGenesis,
+) {
   if (groupLawDomain.length === 0) {
     throw new Error("birthReceivingGroupForDomain requires a non-empty receiving-group law domain");
   }
-  return directive("nomosInternalBirthReceivingGroup7c1f5e")
+  if (!Number.isInteger(maxChildWorkspacesPerUser) || maxChildWorkspacesPerUser < 0) {
+    throw new Error(
+      "birthReceivingGroupForDomain requires an explicit non-negative maxChildWorkspacesPerUser; " +
+        "Nomos has no compiled birth-policy fallback",
+    );
+  }
+  const policyDomains = [...new Set(birthPolicyDomains)];
+  if (
+    policyDomains.length === 0 ||
+    policyDomains.some((domain) => domain.trim().length === 0) ||
+    !policyDomains.includes(groupLawDomain)
+  ) {
+    throw new Error(
+      "birthReceivingGroupForDomain requires every co-resident birth-capable law domain, " +
+        "including its own domain; Nomos will not birth partially configured law",
+    );
+  }
+  const birthDirective = directive("nomosInternalBirthReceivingGroup7c1f5e")
   .creates(ReceivingGroup)
   .payload(
     z.object({
@@ -372,6 +395,32 @@ export function birthReceivingGroupForDomain(groupLawDomain: string) {
         actor: founder,
         payload: { principal: p.owner, workspaceName: groupName, bornAt: p.bornAt },
       },
+      // The receiving group is born with its child-workspace allowance as explicit law-state. The
+      // value is closed over by the package's application policy, so neither the host nor the end
+      // user can substitute it in the offer payload.
+      ...policyDomains.map((domain) => ({
+        domain,
+        directiveId: "seedBirthPolicy",
+        actor: founder,
+        payload: {
+          maxBirthsPerPrincipal: maxChildWorkspacesPerUser,
+          setBy: p.owner,
+          setAt: p.bornAt,
+        },
+      })),
+      // Tenant founding law is an ordered list of ordinary offers. Values derive solely from the
+      // canonical home facts; every payload is parsed by the target directive before it reaches
+      // the child's author gate. There is no host append point and no framework-selected fallback.
+      ...(homeGenesis?.steps ?? []).map((step) => ({
+        domain: step.domain,
+        directiveId: step.directive.id,
+        actor: founder,
+        payload: step.directive.payloadSchema.parse(step.payload({
+          owner: p.owner,
+          workspaceName: groupName,
+          bornAt: p.bornAt,
+        })),
+      })),
       // ENROL THE OWNER'S DEVICE on the warrant-free prefix (when supplied) — enrollSigner self-binds to
       // ctx.principal() (the owner), so this binds `ownerKeyHash` as the owner's signer BEFORE the warrant
       // closes bootstrap. This is what makes the born home SIGNER-READY (able to sign + self-serve-birth its own
@@ -418,9 +467,26 @@ export function birthReceivingGroupForDomain(groupLawDomain: string) {
   })
   .reads(authProviderQuery) // the parent-side AuthProvider capture the inheritance copies (the #58 lane)
   .births(); // BIRTH IS A DECLARED KERNEL PRIMITIVE — emits the `nomosBirthGate` era key; the kernel folds the recipe
+  return {
+    ...birthDirective,
+    ...(homeGenesis === undefined || homeGenesis.steps.length === 0
+      ? {}
+      : {
+          birthGenesisRequirements: homeGenesis.steps.map((step) => ({
+            domain: step.domain,
+            directiveId: step.directive.id,
+          })),
+        }),
+  };
 }
 
-export const birthReceivingGroup = birthReceivingGroupForDomain(RECEIVING_GROUP_LAW_DOMAIN);
+/** Build the standalone framework receiving-group law with an explicit allowance. */
+export const birthReceivingGroup = (maxChildWorkspacesPerUser: number) =>
+  birthReceivingGroupForDomain(
+    RECEIVING_GROUP_LAW_DOMAIN,
+    maxChildWorkspacesPerUser,
+    [RECEIVING_GROUP_LAW_DOMAIN],
+  );
 
 /**
  * THE SHARED-WITH-ME INDEX (§5) — one record per cross-custody attestation delivered to this home holon: