@githolon/dsl 0.100.6 → 0.101.0

package/src/conflicts.ts

@@ -0,0 +1,252 @@
+// NOMOS — business-first conflict policy.
+//
+// The aggregate says what the business IS. This separate, composable object says
+// what to do only when offline copies disagree. Ordinary scalar fields already use
+// FirstWriterWins; a policy names exceptions without scattering merge machinery
+// through the happy-path model.
+
+import type { AggregateHandle, StoredFields } from "./aggregate.js";
+import type { Directive } from "./directive.js";
+import type { Field } from "./fields.js";
+import {
+  FirstWriterWins,
+  Lww,
+  Surfaced,
+  type Driver,
+} from "./drivers.js";
+
+const POLICY_BRAND = "__nomos_conflict_policy_v1" as const;
+const RULE_BRAND = "__nomos_conflict_rule_v1" as const;
+
+export interface ConflictRule {
+  readonly [RULE_BRAND]: true;
+  readonly driver: Driver;
+  readonly resolver?: Directive<any>;
+  readonly description: string;
+}
+
+/** Restate the framework default explicitly inside a policy when that improves its prose. */
+export function firstWriterWins(): ConflictRule {
+  return {
+    [RULE_BRAND]: true,
+    driver: FirstWriterWins,
+    description: "the first concurrent writer wins",
+  };
+}
+
+/** Prefer the latest concurrent writer for a field whose business meaning demands it. */
+export function latestWriterWins(): ConflictRule {
+  return {
+    [RULE_BRAND]: true,
+    driver: Lww,
+    description: "the latest concurrent writer wins",
+  };
+}
+
+/** Retain concurrent values and route the typed decision through this business verb. */
+export function manual<P>(resolver: Directive<P>): ConflictRule {
+  if (
+    resolver === null ||
+    typeof resolver !== "object" ||
+    typeof resolver.id !== "string" ||
+    typeof resolver.plan !== "function"
+  ) {
+    throw new Error("manual(resolver) needs a finished Nomos directive — the business verb that decides the conflict");
+  }
+  return {
+    [RULE_BRAND]: true,
+    driver: Surfaced(FirstWriterWins),
+    resolver,
+    description: `hold both values for ${resolver.id}`,
+  };
+}
+
+type ConflictPolicyShape<F extends Record<string, Field>> = Partial<{
+  [K in keyof StoredFields<F>]: ConflictRule;
+}>;
+
+export interface ConflictPolicy<
+  A extends AggregateHandle = AggregateHandle,
+> {
+  readonly [POLICY_BRAND]: true;
+  readonly aggregate: A;
+  readonly fields: Readonly<Record<string, ConflictRule>>;
+}
+
+/**
+ * Attach exceptional offline-conflict policy to one aggregate without interrupting
+ * its declaration. Export the returned object beside the aggregate; the compiler
+ * discovers it and lowers the chosen rules into the aggregate's law.
+ */
+export function conflicts<
+  const Id extends string,
+  F extends Record<string, Field>,
+>(
+  aggregate: AggregateHandle<Id, F>,
+  fields: ConflictPolicyShape<F>,
+): ConflictPolicy<AggregateHandle<Id, F>> {
+  const normalized: Record<string, ConflictRule> = {};
+  for (const [fieldName, rule] of Object.entries(fields)) {
+    const field = (aggregate.fields as Record<string, Field>)[fieldName];
+    if (field === undefined) {
+      throw new Error(
+        `conflicts(${aggregate.id}): '${fieldName}' is not a stored field of ${aggregate.id}`,
+      );
+    }
+    if (
+      field.kind === "set" ||
+      field.kind === "map" ||
+      field.kind === "counter" ||
+      field.kind === "position" ||
+      field.kind === "hasMany"
+    ) {
+      throw new Error(
+        `conflicts(${aggregate.id}): '${fieldName}' is a ${field.kind} with its own compositional merge law; ` +
+          `field policies currently apply to wholesale business values only`,
+      );
+    }
+    const candidate = rule as Partial<ConflictRule> | undefined;
+    if (candidate === undefined || candidate[RULE_BRAND] !== true) {
+      throw new Error(
+        `conflicts(${aggregate.id}): '${fieldName}' needs a conflict rule such as firstWriterWins(), ` +
+          `latestWriterWins(), or manual(resolveVerb)`,
+      );
+    }
+    if (candidate.resolver !== undefined && candidate.resolver.aggregateId !== aggregate.id) {
+      throw new Error(
+        `conflicts(${aggregate.id}): manual resolver '${candidate.resolver.id}' targets ` +
+          `'${candidate.resolver.aggregateId}', not '${aggregate.id}'`,
+      );
+    }
+    normalized[fieldName] = candidate as ConflictRule;
+  }
+  return {
+    [POLICY_BRAND]: true,
+    aggregate,
+    fields: Object.freeze(normalized),
+  };
+}
+
+export function isConflictPolicy(value: unknown): value is ConflictPolicy {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    (value as Record<string, unknown>)[POLICY_BRAND] === true
+  );
+}
+
+/** Collect exported policies without allowing module spread order to hide a collision. */
+export function conflictPoliciesOf(
+  modules: readonly Record<string, unknown>[],
+  domain: string,
+): ConflictPolicy[] {
+  const policies: ConflictPolicy[] = [];
+  const byAggregate = new Map<string, ConflictPolicy>();
+  for (const mod of modules) {
+    for (const value of Object.values(mod)) {
+      if (!isConflictPolicy(value)) continue;
+      const prior = byAggregate.get(value.aggregate.id);
+      if (prior !== undefined && prior !== value) {
+        throw new Error(
+          `domain '${domain}' exports more than one conflict policy for '${value.aggregate.id}' — ` +
+            `an aggregate has exactly one policy object; compose its field rules there`,
+        );
+      }
+      if (prior === undefined) {
+        byAggregate.set(value.aggregate.id, value);
+        policies.push(value);
+      }
+    }
+  }
+  return policies;
+}
+
+function cloneFieldWithDriver(field: Field, driver: Driver): Field {
+  const clone = Object.defineProperties({}, Object.getOwnPropertyDescriptors(field)) as Field;
+  Object.defineProperty(clone, "driver", {
+    value: driver,
+    enumerable: true,
+    configurable: true,
+    writable: false,
+  });
+  return clone;
+}
+
+/** Apply policy to the aggregate handles the composed manifest/codegen consumes. */
+export function applyConflictPoliciesToAggregates(
+  aggregates: readonly AggregateHandle[],
+  policies: readonly ConflictPolicy[],
+  domain: string,
+): AggregateHandle[] {
+  const aggregateIds = new Set(aggregates.map((aggregate) => aggregate.id));
+  for (const policy of policies) {
+    if (!aggregateIds.has(policy.aggregate.id)) {
+      throw new Error(
+        `domain '${domain}' exports a conflict policy for '${policy.aggregate.id}' but not the aggregate itself`,
+      );
+    }
+  }
+  const byAggregate = new Map(policies.map((policy) => [policy.aggregate.id, policy]));
+  return aggregates.map((aggregate) => {
+    const policy = byAggregate.get(aggregate.id);
+    if (policy === undefined) return aggregate;
+    const fields = Object.defineProperties(
+      {},
+      Object.getOwnPropertyDescriptors(aggregate.fields),
+    ) as Record<string, Field>;
+    for (const [name, rule] of Object.entries(policy.fields)) {
+      fields[name] = cloneFieldWithDriver(fields[name]!, rule.driver);
+    }
+    const clone = Object.defineProperties(
+      {},
+      Object.getOwnPropertyDescriptors(aggregate),
+    ) as AggregateHandle;
+    Object.defineProperty(clone, "fields", {
+      value: fields,
+      enumerable: true,
+      configurable: true,
+      writable: false,
+    });
+    return clone;
+  });
+}
+
+/** Apply `manual(resolveVerb)` designations without making the verb declaration lead with edge cases. */
+export function applyConflictPolicyResolvers(
+  directives: readonly Directive<any>[],
+  policies: readonly ConflictPolicy[],
+): Directive<any>[] {
+  const designation = new Map<string, string>();
+  for (const policy of policies) {
+    for (const [field, rule] of Object.entries(policy.fields)) {
+      const resolver = rule.resolver;
+      if (resolver === undefined) continue;
+      const prior = designation.get(resolver.id);
+      if (prior !== undefined && prior !== field) {
+        throw new Error(
+          `manual resolver '${resolver.id}' is assigned to both '${prior}' and '${field}' — ` +
+            `one business verb resolves one field`,
+        );
+      }
+      designation.set(resolver.id, field);
+    }
+  }
+  const exported = new Set(directives.map((directive) => directive.id));
+  for (const resolverId of designation.keys()) {
+    if (!exported.has(resolverId)) {
+      throw new Error(
+        `manual resolver '${resolverId}' is used by conflict policy but is not exported with the domain`,
+      );
+    }
+  }
+  return directives.map((directive) => {
+    const field = designation.get(directive.id);
+    if (field === undefined) return directive;
+    if (directive.resolvesField !== undefined && directive.resolvesField !== field) {
+      throw new Error(
+        `directive '${directive.id}' already resolves '${directive.resolvesField}' but conflict policy assigns '${field}'`,
+      );
+    }
+    return { ...directive, resolvesField: field };
+  });
+}

package/src/describe_model.ts

@@ -0,0 +1,448 @@
+// NOMOS — compiler-owned product description. This is deliberately a small,
+// JSON-serialisable model: generated TypeScript and Dart clients consume the SAME
+// facts, then join them to the verified runtime state behind `describe()`.
+
+import type { DomainModule } from "./codegen_dart.js";
+import type { Directive } from "./directive.js";
+import { OWNER_FIELD, type AggregateHandle } from "./aggregate.js";
+import type { Field } from "./fields.js";
+import { finishCount } from "./count.js";
+import { finishSum } from "./sum.js";
+import { finishExists } from "./exists.js";
+import { finishExtremum } from "./extremum.js";
+import { isNamespacedAggregate, qualifyReadProjectionType } from "./read_projection_namespace.js";
+
+export const NOMOS_DESCRIBE_SECTIONS = [
+  "model",
+  "current",
+  "rules",
+  "history",
+  "decisions",
+  "evidence",
+] as const;
+
+export type NomosDescribeDetailSection = (typeof NOMOS_DESCRIBE_SECTIONS)[number];
+
+export interface NomosDescribeLinkModel {
+  readonly section: NomosDescribeDetailSection;
+  readonly label: string;
+  readonly question: string;
+  readonly summary: string;
+}
+
+export interface NomosDescribeItemModel {
+  readonly kind: string;
+  readonly id: string;
+  readonly label: string;
+  readonly summary: string;
+  readonly details?: Readonly<Record<string, unknown>>;
+}
+
+export interface NomosDescribePageModel {
+  readonly title: string;
+  readonly summary: string;
+  readonly items: readonly NomosDescribeItemModel[];
+}
+
+export interface NomosDescribeAggregateModel {
+  readonly domain: string;
+  readonly type: string;
+  readonly label: string;
+  readonly audience: string;
+  /** Actual projection type used by the runtime's built-in type index. */
+  readonly queryType: string;
+}
+
+/** The compiler-known half of the one-page-plus-six product description. */
+export interface NomosDescribeModel {
+  readonly packageName: string;
+  readonly title: string;
+  readonly summary: string;
+  readonly links: readonly NomosDescribeLinkModel[];
+  readonly pages: {
+    readonly model: NomosDescribePageModel;
+    readonly rules: NomosDescribePageModel;
+  };
+  /** Public business types the generated client may ask the projection for. */
+  readonly aggregateTypes: readonly NomosDescribeAggregateModel[];
+}
+
+const label = (id: string): string => {
+  const spaced = id
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/[_-]+/g, " ")
+    .trim();
+  return spaced.length === 0 ? id : spaced[0]!.toUpperCase() + spaced.slice(1);
+};
+
+/** Explain concurrency as policy, never as a CRDT/driver name. */
+const mergePolicy = (driver: unknown): string => {
+  if (driver === null || typeof driver !== "object") return "the model's declared policy";
+  const d = driver as { kind?: unknown; inner?: unknown; principal?: unknown };
+  switch (d.kind) {
+    case "FirstWriterWins": return "the first concurrent change wins; a later informed edit may replace it";
+    case "Lww": return "the latest recorded change wins";
+    case "LwwCausal": return "a change based on another wins; truly concurrent changes use a stable tie-break";
+    case "LwwBy": return `${String(d.principal ?? "the declared authority")} is the sole writer`;
+    case "AddWins": return "concurrent additions are kept";
+    case "RemoveWins": return "a concurrent removal wins over an addition";
+    case "Counter": return "concurrent adjustments are added together";
+    case "LastPosition": return "the latest recorded position wins";
+    case "Conflict": return "competing versions wait for a business merge";
+    case "Surfaced": return "competing versions are retained for a business merge";
+    case "MapOf": return `each named entry follows this rule: ${mergePolicy(d.inner)}`;
+    case "Attributed": return `${mergePolicy(d.inner)}, with the winning author's identity retained`;
+    default: return "the model's declared policy";
+  }
+};
+
+const audienceName = (aggregate: AggregateHandle): string => {
+  const audience = aggregate.audience;
+  if (audience?.kind === "public") return "public";
+  if (audience?.kind === "owned") return "owned by its creator";
+  if (audience?.kind === "readableBy") return `readable by ${audience.cap}`;
+  if (aggregate.visibility !== undefined) return `readable by ${aggregate.visibility.requires}`;
+  // A package with this value cannot pass the audience compile gate. Keeping the
+  // fact explicit makes direct unit-codegen honest too.
+  return "undeclared (the compiler will refuse this package)";
+};
+
+const permissionName = (gate: NonNullable<Directive<unknown>["requiresRelationGate"]>): string => {
+  const relation = label(gate.relation).toLowerCase();
+  if (gate.objectFrom !== undefined) return `${relation} for this ${label(gate.objectFrom.recordType).toLowerCase()}`;
+  if (gate.object === "workspace:self") return `${relation} for this workspace`;
+  return `${relation} for ${label(gate.object).toLowerCase()}`;
+};
+
+/** Best-effort field names for human explanation only; law validation remains Zod. */
+const payloadFields = (directive: Directive<unknown>): string[] => {
+  const schema = directive.payloadSchema as unknown as {
+    shape?: unknown;
+    _def?: { shape?: unknown };
+    def?: { shape?: unknown };
+  };
+  const candidate = schema.shape ?? schema._def?.shape ?? schema.def?.shape;
+  try {
+    const shape = typeof candidate === "function" ? candidate() : candidate;
+    return shape !== null && typeof shape === "object" ? Object.keys(shape).sort() : [];
+  } catch {
+    return [];
+  }
+};
+
+type BusinessBirthPresentation = {
+  readonly aggregateId: string;
+  readonly publicPayloadSchema: unknown;
+};
+
+const businessBirthOf = (directive: Directive<unknown>): BusinessBirthPresentation | undefined =>
+  (directive as Directive<unknown> & { businessBirth?: BusinessBirthPresentation }).businessBirth;
+
+const publicAggregates = (mod: DomainModule): AggregateHandle[] =>
+  mod.aggregates.filter((aggregate) =>
+    aggregate.framework !== true
+      && (aggregate as { businessBirthInternal?: unknown }).businessBirthInternal !== true
+  );
+
+const publicDirectives = (mod: DomainModule): Directive<unknown>[] =>
+  (mod.directives as Directive<unknown>[]).filter((directive) =>
+    directive.framework !== true
+      && (directive as { businessBirthInternal?: unknown }).businessBirthInternal !== true
+  );
+
+const businessFields = (aggregate: AggregateHandle): [string, Field][] =>
+  Object.entries(aggregate.fields as Record<string, Field>)
+    .filter(([name]) => name !== OWNER_FIELD);
+
+const aggregateItem = (domain: string, aggregate: AggregateHandle): NomosDescribeItemModel => {
+  const fields = businessFields(aggregate)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([name, field]) => ({
+      name,
+      type: field.kind,
+      merge: mergePolicy(field.driver),
+      optional: field.isOptional,
+      ...(field.isFromBirth === true ? { fromBirth: true } : {}),
+      ...((field.evolutions?.length ?? 0) > 0 ? { understoodEarlierShapes: field.evolutions!.length } : {}),
+    }));
+  const audience = audienceName(aggregate);
+  return {
+    kind: "noun",
+    id: `${domain}.${aggregate.id}`,
+    label: label(aggregate.id),
+    summary: `${label(aggregate.id)} is ${audience}; it has ${fields.length} business field${fields.length === 1 ? "" : "s"}.`,
+    details: {
+      domain,
+      type: aggregate.id,
+      audience,
+      fields,
+      reads: [`${aggregate.id} by id`, `all ${aggregate.id}s`],
+    },
+  };
+};
+
+const actionItem = (domain: string, directive: Directive<unknown>): NomosDescribeItemModel => {
+  const businessBirth = businessBirthOf(directive);
+  const actionId = businessBirth === undefined ? directive.id : "birth";
+  const actionLabel = businessBirth === undefined
+    ? label(directive.id)
+    : `Birth ${label(businessBirth.aggregateId)}`;
+  const outputs = [
+    { effect: directive.marker, type: directive.aggregateId },
+    ...(directive.secondaryOutputs ?? []).map((output) => ({ effect: output.marker, type: output.aggregateId })),
+  ];
+  const effectVerb = (marker: string): string => ({
+    creates: "create",
+    mutates: "change",
+    archives: "archive",
+    ensures: "ensure",
+  }[marker] ?? marker);
+  const effect = outputs.map((output) => `${effectVerb(output.effect)} ${label(output.type)}`).join(", ");
+  const inputs = businessBirth === undefined
+    ? payloadFields(directive)
+    : payloadFields({ ...directive, payloadSchema: businessBirth.publicPayloadSchema } as Directive<unknown>);
+  const gate = directive.requiresRelationGate;
+  return {
+    kind: "verb",
+    id: `${domain}.${actionId}`,
+    label: actionLabel,
+    summary: businessBirth === undefined
+      ? directive.description ?? `${actionLabel} will ${effect}.`
+      : `${actionLabel} will ${effect}.`,
+    details: {
+      domain,
+      action: actionId,
+      inputs,
+      effects: outputs,
+      ...(gate !== undefined
+        ? { permittedWhen: permissionName(gate) }
+        : {}),
+    },
+  };
+};
+
+const questionItems = (mod: DomainModule): NomosDescribeItemModel[] => {
+  const domain = mod.domain ?? mod.name;
+  const items: NomosDescribeItemModel[] = [];
+  const publicAggregateIds = new Set(publicAggregates(mod).map((aggregate) => aggregate.id));
+  const privateAggregateIds = new Set(
+    mod.aggregates
+      .filter((aggregate) => !publicAggregateIds.has(aggregate.id))
+      .map((aggregate) => aggregate.id),
+  );
+  for (const query of mod.queries ?? []) {
+    if (
+      (query as { framework?: unknown }).framework === true
+      || (query as { businessBirthInternal?: unknown }).businessBirthInternal === true
+      || privateAggregateIds.has(query.returns)
+    ) {
+      continue;
+    }
+    items.push({
+      kind: "question",
+      id: `${domain}.${query.id}`,
+      label: label(query.id),
+      summary: `Find ${label(query.returns)} by ${query.key.map(label).join(" and ")}.`,
+      details: { domain, question: query.id, returns: query.returns, by: query.key },
+    });
+  }
+  for (const raw of mod.counts ?? []) {
+    const count = finishCount(raw);
+    items.push({
+      kind: "question",
+      id: `${domain}.${count.id}`,
+      label: label(count.id),
+      summary: `Count ${label(count.of)}${count.by === undefined ? "" : ` by ${label(count.by)}`}.`,
+      details: { domain, question: count.id, returns: "number", counts: count.of, ...(count.by ? { by: count.by } : {}) },
+    });
+  }
+  for (const raw of mod.sums ?? []) {
+    const sum = finishSum(raw);
+    items.push({
+      kind: "question",
+      id: `${domain}.${sum.id}`,
+      label: label(sum.id),
+      summary: `Total ${label(sum.sumField)} across ${label(sum.of)}${sum.by === undefined ? "" : ` by ${label(sum.by)}`}.`,
+      details: { domain, question: sum.id, returns: "number", sums: `${sum.of}.${sum.sumField}`, ...(sum.by ? { by: sum.by } : {}) },
+    });
+  }
+  for (const raw of mod.exists_ ?? []) {
+    const exists = finishExists(raw);
+    items.push({
+      kind: "question",
+      id: `${domain}.${exists.id}`,
+      label: label(exists.id),
+      summary: `Ask whether any ${label(exists.of)} exists${exists.by === undefined ? "" : ` for ${label(exists.by)}`}.`,
+      details: { domain, question: exists.id, returns: "yes or no", checks: exists.of, ...(exists.by ? { by: exists.by } : {}) },
+    });
+  }
+  for (const raw of [...(mod.mins ?? []), ...(mod.maxes ?? [])]) {
+    const extremum = finishExtremum(raw);
+    items.push({
+      kind: "question",
+      id: `${domain}.${extremum.id}`,
+      label: label(extremum.id),
+      summary: `Find the ${extremum.kind === "min" ? "smallest" : "largest"} ${label(extremum.valueField)} among ${label(extremum.of)}${extremum.by === undefined ? "" : ` for ${label(extremum.by)}`}.`,
+      details: { domain, question: extremum.id, returns: "number", from: extremum.of, field: extremum.valueField, ...(extremum.by ? { by: extremum.by } : {}) },
+    });
+  }
+  for (const spatial of mod.spatials ?? []) {
+    items.push({
+      kind: "question",
+      id: `${domain}.${spatial.id}`,
+      label: label(spatial.id),
+      summary: `Find ${label(spatial.of)} within an area using ${label(spatial.on)}.`,
+      details: { domain, question: spatial.id, returns: spatial.of, areaFrom: spatial.on },
+    });
+  }
+  for (const ordered of mod.orderedReads ?? []) {
+    items.push({
+      kind: "question",
+      id: `${domain}.${ordered.id}`,
+      label: label(ordered.id),
+      summary: `Find ${ordered.limit === 1 ? "the first" : `the first ${ordered.limit}`} ${label(ordered.of)} ordered by ${label(ordered.orderKey)}${ordered.orderDesc ? " descending" : ""}.`,
+      details: { domain, question: ordered.id, returns: ordered.of, orderedBy: ordered.orderKey, limit: ordered.limit },
+    });
+  }
+  return items;
+};
+
+const ruleItems = (mod: DomainModule): NomosDescribeItemModel[] => {
+  const domain = mod.domain ?? mod.name;
+  const items: NomosDescribeItemModel[] = [];
+  for (const aggregate of publicAggregates(mod)) {
+    items.push({
+      kind: "access-rule",
+      id: `${domain}.${aggregate.id}.audience`,
+      label: `${label(aggregate.id)} audience`,
+      summary: `${label(aggregate.id)} is ${audienceName(aggregate)}.`,
+      details: { audience: audienceName(aggregate) },
+    });
+    if (aggregate.hasInvariant === true) {
+      items.push({
+        kind: "invariant",
+        id: `${domain}.${aggregate.id}.invariant`,
+        label: `${label(aggregate.id)} must remain valid`,
+        summary: `Every proposed change to ${label(aggregate.id)} is checked before it can be committed.`,
+      });
+    }
+    for (const [fieldName, field] of businessFields(aggregate)) {
+      const merge = mergePolicy(field.driver);
+      const surfaced = ["Surfaced", "Conflict"].includes(String((field.driver as { kind?: unknown }).kind ?? ""));
+      items.push({
+        kind: surfaced ? "conflict-rule" : "merge-rule",
+        id: `${domain}.${aggregate.id}.${fieldName}.merge`,
+        label: `${label(aggregate.id)} ${label(fieldName)}`,
+        summary: surfaced
+          ? `Concurrent ${label(fieldName)} changes are retained for a business merge.`
+          : `For concurrent ${label(fieldName)} changes, ${merge}.`,
+        details: {
+          merge,
+          ...((field.evolutions?.length ?? 0) > 0
+            ? { understoodEarlierShapes: field.evolutions!.length }
+            : {}),
+        },
+      });
+    }
+  }
+  for (const directive of publicDirectives(mod)) {
+    const gate = directive.requiresRelationGate;
+    if (gate !== undefined) {
+      items.push({
+        kind: "permission-rule",
+        id: `${domain}.${directive.id}.permission`,
+        label: `Who may ${label(directive.id).toLowerCase()}`,
+        summary: `${label(directive.id)} requires ${permissionName(gate)}.`,
+      });
+    }
+    if ((directive.preconditions?.length ?? 0) > 0) {
+      items.push({
+        kind: "precondition",
+        id: `${domain}.${directive.id}.preconditions`,
+        label: `${label(directive.id)} preconditions`,
+        summary: `${label(directive.id)} has ${directive.preconditions!.length} declared condition${directive.preconditions!.length === 1 ? "" : "s"} checked before commit.`,
+      });
+    }
+  }
+  // Framework invariants remain certified law, but `describe()` is a product explanation. Only an
+  // invariant attached to an ordinary tenant-visible action belongs here. Birth's quota/attestation/
+  // signer invariants are privately owned by the one generated `birth(...)` action.
+  const ordinaryPublicActionIds = new Set(
+    publicDirectives(mod)
+      .filter((directive) => businessBirthOf(directive) === undefined)
+      .map((directive) => directive.id),
+  );
+  for (const invariant of mod.workspaceInvariants ?? []) {
+    if (
+      (invariant as { businessBirthInternal?: unknown }).businessBirthInternal === true
+      || !ordinaryPublicActionIds.has(invariant.on)
+    ) {
+      continue;
+    }
+    items.push({
+      kind: "workspace-invariant",
+      id: `${domain}.${invariant.id}`,
+      label: label(invariant.id),
+      summary: `The whole workspace must satisfy ${label(invariant.id)} when ${label(invariant.on)} is proposed.`,
+    });
+  }
+  return items;
+};
+
+/**
+ * Build the product description from tenant law only. No executable functions or
+ * framework-private names enter the result, so it is safe to bake into clients.
+ */
+export function buildNomosDescribeModel(
+  modules: readonly DomainModule[],
+  packageName: string,
+): NomosDescribeModel {
+  const aggregates = modules.flatMap((mod) => {
+    const domain = mod.domain ?? mod.name;
+    return publicAggregates(mod).map((aggregate) => ({ domain, aggregate }));
+  });
+  const actions = modules.flatMap((mod) => {
+    const domain = mod.domain ?? mod.name;
+    return publicDirectives(mod).map((directive) => ({ domain, directive }));
+  });
+  const questions = modules.flatMap(questionItems);
+  const nouns = aggregates.map(({ domain, aggregate }) => aggregateItem(domain, aggregate));
+  const verbs = actions.map(({ domain, directive }) => actionItem(domain, directive));
+  const rules = modules.flatMap(ruleItems);
+  const domainCount = new Set(modules.map((mod) => mod.domain ?? mod.name)).size;
+
+  return {
+    packageName,
+    title: label(packageName),
+    summary: `${label(packageName)} models ${nouns.length} business noun${nouns.length === 1 ? "" : "s"}, ${verbs.length} action${verbs.length === 1 ? "" : "s"}, and ${questions.length} named question${questions.length === 1 ? "" : "s"} across ${domainCount} domain${domainCount === 1 ? "" : "s"}.`,
+    links: [
+      { section: "model", label: "The model", question: "What business does this workspace model?", summary: "Its nouns, actions and named questions." },
+      { section: "current", label: "Current state", question: "What exists now?", summary: "The records this reader is allowed to see now." },
+      { section: "rules", label: "The rules", question: "What must always remain true?", summary: "Access, validity, merge and evolution policy." },
+      { section: "history", label: "History", question: "What changed, and who changed it?", summary: "The verified business story in time order." },
+      { section: "decisions", label: "Decisions", question: "What was decided, and what still needs attention?", summary: "Recorded reasons, pending business merges, retained rejected work and conflict policy." },
+      { section: "evidence", label: "Evidence", question: "What proves this answer?", summary: "Workspace, law and verified history identities." },
+    ],
+    pages: {
+      model: {
+        title: "The business model",
+        summary: "The nouns, actions and named questions generated from the installed business law.",
+        items: [...nouns, ...verbs, ...questions],
+      },
+      rules: {
+        title: "The rules",
+        summary: "The access, validity, merge and evolution policy Nomos enforces before accepting change.",
+        items: rules,
+      },
+    },
+    aggregateTypes: aggregates.map(({ domain, aggregate }) => ({
+      domain,
+      type: aggregate.id,
+      label: label(aggregate.id),
+      audience: audienceName(aggregate),
+      queryType: isNamespacedAggregate(aggregate)
+        ? qualifyReadProjectionType(domain, aggregate.id)
+        : aggregate.id,
+    })),
+  };
+}