@githolon/dsl 0.100.6 → 0.101.0

package/src/codegen_dart.ts

@@ -50,6 +50,9 @@ import type { DerivedDecl } from "./derived.js";
 import type { CombinedDecl } from "./combined.js";
 import { emitProviderSdk, type ImpureCapabilityDecl } from "./codegen_provider_dart.js";
 import type { WorkspaceTypeDecl } from "./workspace_type.js";
+import { defaultActivityDescriptor } from "./activity.js";
+import { activityKey } from "./activity.js";
+import { BUSINESS_CORRECTION_DIRECTIVE } from "./framework/business_corrections.js";
 
 /** A directive of any payload type. `Directive<P>` is invariant in `P`, so the
  * generator (which only introspects shapes) takes the `any`-payload form. */
@@ -873,9 +876,11 @@ function aggregateFieldSpecs(
   ownIdFields: ReadonlySet<string> = new Set(),
 ): AggFieldSpec[] {
   const used = new Set<string>(["aggregateId"]);
+  const internal = new Set(agg.internalFields ?? []);
   // `agg.fields` is STORED fields only — virtual `t.hasMany` inverses are in `agg.hasMany`
   // and never reach Dart materialization (they are served by the inverse read index).
   return Object.entries(agg.fields as Record<string, Field>)
+    .filter(([name]) => !internal.has(name))
     .map(([name, f]) => {
       const valueClass =
         f.kind === "string" && ownIdFields.has(name)
@@ -1315,7 +1320,7 @@ function emitAggregate(
     ...specs.flatMap((s) => {
       const doc = s.nullReason !== undefined ? [`  /// null semantic: ${s.nullReason}`] : [];
       // SURFACED MERGE CONFLICTS: the field reads as the plain scalar, or [SurfacedPending]
-      // while genuinely concurrent writes await a human pick (resolve = an ordinary next write).
+      // while genuinely concurrent writes await a business merge (resolve = an ordinary next write).
       if (s.surfaced === true) {
         return [
           `  /// Surfaced merge conflicts: [SurfacedResolved] steady state, [SurfacedPending] under conflict.`,
@@ -1914,7 +1919,10 @@ function emitAggregateMetaRegistry(
   if (aggregates.length === 0) return "";
   const entries = aggregates.map((agg) => {
     const wireType = `${domainKey}.${agg.id}`;
-    const fieldLines = Object.entries(agg.fields as Record<string, Field>).map(([name, f]) => {
+    const internal = new Set(agg.internalFields ?? []);
+    const fieldLines = Object.entries(agg.fields as Record<string, Field>)
+      .filter(([name]) => !internal.has(name))
+      .map(([name, f]) => {
       const parts: string[] = [`kind: '${f.kind}'`];
       if (f.kind === "enum") {
         try {
@@ -1932,8 +1940,8 @@ function emitAggregateMetaRegistry(
         parts.push(`refType: '${domainKey}.${refTarget}'`);
       }
       if ((f as { isFromBirth?: true }).isFromBirth === true) parts.push(`fromBirth: true`);
-      return `      '${name}': NomosFieldMeta(${parts.join(", ")}),`;
-    });
+        return `      '${name}': NomosFieldMeta(${parts.join(", ")}),`;
+      });
     return [
       `  '${wireType}': NomosAggregateMeta(`,
       `    type: '${wireType}',`,
@@ -2184,27 +2192,88 @@ export function generateDartContracts(
 
 // ── ACTIVITY DESCRIPTORS (architecture/activity_descriptors.md) — shared registry codegen ──
 
-/** One directive's declared activity, tagged with its provenance (domain + directive id). */
+/** One public business directive's activity, tagged with its provenance (domain + directive id). */
 export interface PackageActivityEntry {
   readonly domain: string;
   readonly directiveId: string;
   readonly desc: import("./activity.js").ActivityDescriptor;
+  /** False when Nomos supplied the accountable baseline because the tenant declared no richer prose. */
+  readonly declared: boolean;
+  /** Framework-authored testimony whose refs are derived from the corrected action's sealed events. */
+  readonly correction?: true;
 }
 
-/** Collect every directive's `.activity(...)` descriptor across the package's modules, tagged with its
- *  domain + directive id, sorted by directive id (byte-deterministic switch/registry order). Empty when
- *  no directive opts in — an activity-free package then emits NO registry (byte-identical). Shared by the
- *  flat + layered Dart emit AND the TS client (one source of truth). */
+/**
+ * Collect every PUBLIC business directive across the package. A declared `.activity(...)` descriptor wins;
+ * otherwise Nomos derives a conservative baseline from the verb name + declared output types. This makes
+ * accountability framework-owned: forgetting presentation metadata can make the story less polished, never
+ * incomplete. Framework-private directives remain absent from the application story.
+ */
 export function collectActivityDescriptors(modules: readonly DomainModule[]): PackageActivityEntry[] {
   const out: PackageActivityEntry[] = [];
   for (const mod of modules) {
     const domain = mod.domain ?? mod.name;
     for (const d of mod.directives as AnyDirective[]) {
+      if ((d as { businessBirthInternal?: unknown }).businessBirthInternal === true) {
+        if (d.id === BUSINESS_CORRECTION_DIRECTIVE) {
+          const kind = `${domain}.correction`;
+          out.push({
+            domain,
+            directiveId: d.id,
+            desc: {
+              kind,
+              title: "Correction recorded",
+              message: "{actor} recorded {operation}: {reason}",
+              category: domain,
+              severity: "warning",
+              refs: [],
+              params: [
+                { name: "operation", from: "kind" },
+                { name: "reason", from: "reason" },
+              ],
+              titleKey: activityKey(kind, "title"),
+              messageKey: activityKey(kind, "message"),
+            },
+            declared: false,
+            correction: true,
+          });
+        }
+        continue;
+      }
       const desc = (d as { activityDescriptor?: import("./activity.js").ActivityDescriptor }).activityDescriptor;
-      if (desc !== undefined) out.push({ domain, directiveId: d.id, desc });
+      const outputs = [
+        { marker: d.marker, aggregateId: d.aggregateId },
+        ...(d.secondaryOutputs ?? []),
+      ];
+      const seen = new Set<string>();
+      const refs: Array<{ name: string; type: string; from: string }> = [];
+      for (const output of outputs) {
+        const key = `${output.marker}:${output.aggregateId}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        refs.push({
+          name: refs.length === 0 ? "subject" : `subject${refs.length + 1}`,
+          type: output.aggregateId,
+          from: output.marker === "creates" ? "@created" : "@affected",
+        });
+      }
+      out.push({
+        domain,
+        directiveId: d.id,
+        desc: desc ?? defaultActivityDescriptor({
+          domain,
+          directiveId: d.id,
+          ...(d.description === undefined ? {} : { description: d.description }),
+          refs,
+        }),
+        declared: desc !== undefined,
+      });
     }
   }
-  return out.sort((a, b) => (a.directiveId < b.directiveId ? -1 : a.directiveId > b.directiveId ? 1 : 0));
+  return out.sort((a, b) =>
+    a.domain < b.domain ? -1 : a.domain > b.domain ? 1
+      : a.directiveId < b.directiveId ? -1 : a.directiveId > b.directiveId ? 1 : 0
+  );
 }
 
 /** Dart string literal (single-quoted, backslash/quote/`$` escaped). */
@@ -2212,25 +2281,32 @@ const dartLit = (s: string): string => `'${s.replace(/\\/g, "\\\\").replace(/'/g
 
 /** Emit ONE `case '<directiveId>':` arm folding a raw row into a typed [ActivityEvent]. */
 function emitDartActivityArm(e: PackageActivityEntry): string[] {
-  const { directiveId, desc } = e;
+  const { domain, directiveId, desc } = e;
   const paramEntries = desc.params.map((p) => `        ${dartLit(p.name)}: _activityPayloadPath(payload, ${dartLit(p.from)}),`);
-  const refEntries = desc.refs.map((r) => {
+  const refEntries = e.correction === true
+    ? [
+        `          for (var i = 0; i < affected.length; i++)`,
+        `            'subject\${i + 1}': ActivityRef(workspace: workspace, type: (affected[i]['type'] ?? '') as String, id: (affected[i]['id'] ?? '') as String),`,
+      ]
+    : desc.refs.map((r) => {
     // A `from: "@created"` ref reads the id the LAW MINTED (the row's `created` list, first type match); any
     // other `from` is a payload path. Every ref carries the session workspace (the row's `workspace`).
     const id = r.from === "@created"
-      ? `_activityCreatedId(created, ${dartLit(r.type)})`
-      : `_activityPayloadPath(payload, ${dartLit(r.from)})`;
+      ? `_activityAggregateId(created, ${dartLit(r.type)})`
+      : r.from === "@affected"
+        ? `_activityAggregateId(affected, ${dartLit(r.type)})`
+        : `_activityPayloadPath(payload, ${dartLit(r.from)})`;
     return `          ${dartLit(r.name)}: ActivityRef(workspace: workspace, type: ${dartLit(r.type)}, id: ${id}),`;
-  });
+      });
   return [
-    `    case ${dartLit(directiveId)}:`,
+    `    case ${dartLit(`${domain.length}:${domain}${directiveId}`)}:`,
     `      {`,
     `        final params = <String, String>{`,
     ...paramEntries,
     `        };`,
     `        final vars = <String, String>{'actor': actorSubject, ...params};`,
     `        return ActivityEvent(`,
-    `          eventId: (rawRow['intentId'] ?? '') as String,`,
+    `          eventId: ${e.correction === true ? "_activityOpaqueCorrectionId((rawRow['intentId'] ?? '') as String)" : "(rawRow['intentId'] ?? '') as String"},`,
     `          kind: ${dartLit(desc.kind)},`,
     `          actorSubject: actorSubject,`,
     `          occurredAt: (rawRow['occurredAt'] ?? '') as String,`,
@@ -2246,7 +2322,7 @@ function emitDartActivityArm(e: PackageActivityEntry): string[] {
     ...(desc.icon !== undefined ? [`          icon: ${dartLit(desc.icon)},`] : []),
     `          severity: ActivitySeverity.${desc.severity},`,
     `          domain: (rawRow['domain'] ?? '') as String,`,
-    `          directiveId: ${dartLit(directiveId)},`,
+    `          directiveId: ${dartLit(e.correction === true ? "correction" : directiveId)},`,
     `        );`,
     `      }`,
   ];
@@ -2258,29 +2334,168 @@ function emitDartActivityArm(e: PackageActivityEntry): string[] {
  * flat + layered emit). References only nomos_types (`ActivityEvent`/`ActivityRef`/`ActivitySeverity`/
  * `renderActivityTemplate`), so the file is PURE (frontend-safe, no bridge). A raw row is
  * `{ intentId, domain, directiveId, actorSubject, occurredAt, payload }` (the runtime's per-committed-intent
- * shape); `renderActivity` returns null for a directive with no declared `.activity(...)`.
+ * shape); `renderActivity` returns null only for work outside the generated public business package.
  */
 export function generateDartActivityRegistry(entries: readonly PackageActivityEntry[]): string {
-  const sorted = [...entries].sort((a, b) => (a.directiveId < b.directiveId ? -1 : a.directiveId > b.directiveId ? 1 : 0));
+  const sorted = [...entries].sort((a, b) =>
+    a.domain < b.domain ? -1 : a.domain > b.domain ? 1
+      : a.directiveId < b.directiveId ? -1 : a.directiveId > b.directiveId ? 1 : 0
+  );
   return [
     `// GENERATED by nomos-compile — the package's shared ACTIVITY REGISTRY (architecture/activity_descriptors.md). DO NOT EDIT.`,
-    `// A directive OPT-IN declares its user-facing activity metadata; \`renderActivity\` folds each committed-intent`,
+    `// Every public business directive has an accountable baseline row; optional \`.activity(...)\` metadata`,
+    `// enriches its prose and references. \`renderActivity\` folds each committed-intent`,
     `// raw row into a typed ActivityEvent. Pure (nomos_types only) — the kernel/ledger stays the audit truth.`,
     `//`,
-    `// ignore_for_file: unused_import`,
+    `// Some baseline-only registries need neither payload interpolation nor one of the aggregate lists.`,
+    `// Keep generated packages analyzer-clean without branching the shared renderer shape per directive mix.`,
+    `// ignore_for_file: unused_import, unused_element, unused_local_variable`,
     `library;`,
     ``,
     `import 'package:nomos_client/nomos_client.dart';`,
     ``,
-    `/// A NARRATIVE over the activity log (for an in-app LLM): the filtered [events] + a plain-English`,
-    `/// [transcript] (ONE LINE PER EVENT, oldest-first, \`"<occurredAt> — <title>: <message>"\`) grounded in`,
-    `/// the VERIFIED log, never raw payloads. Produced by the client's \`describe\` / \`describeHistory\`.`,
+    `/// One business-readable difference found while proving a candidate model against history.`,
+    `enum NomosModelDifferenceKind { rules, outcome, evidence }`,
+    ``,
+    `class NomosModelDifference {`,
+    `  final NomosModelDifferenceKind kind;`,
+    `  final String? area;`,
+    `  final String? action;`,
+    `  final String summary;`,
+    `  const NomosModelDifference({required this.kind, this.area, this.action, required this.summary});`,
+    `}`,
+    ``,
+    `class NomosModelReview {`,
+    `  final int checkedActions;`,
+    `  final int candidateActions;`,
+    `  final bool? sameOutcome;`,
+    `  final List<NomosModelDifference> differences;`,
+    `  const NomosModelReview({required this.checkedActions, required this.candidateActions, required this.sameOutcome, required this.differences});`,
+    `}`,
+    ``,
+    `enum NomosModelAdoptionStatus { adopted, needsDecision, blocked }`,
+    ``,
+    `class NomosModelAdoption {`,
+    `  final NomosModelAdoptionStatus status;`,
+    `  final String summary;`,
+    `  final NomosModelReview review;`,
+    `  final Future<NomosModelAdoption> Function(String)? _accept;`,
+    `  const NomosModelAdoption.adopted({required this.summary, required this.review})`,
+    `      : status = NomosModelAdoptionStatus.adopted, _accept = null;`,
+    `  const NomosModelAdoption.blocked({required this.summary, required this.review})`,
+    `      : status = NomosModelAdoptionStatus.blocked, _accept = null;`,
+    `  NomosModelAdoption.needsDecision({required this.summary, required this.review, required Future<NomosModelAdoption> Function(String) accept})`,
+    `      : status = NomosModelAdoptionStatus.needsDecision, _accept = accept;`,
+    `  Future<NomosModelAdoption> accept(String because) {`,
+    `    final reason = because.trim();`,
+    `    final acceptDecision = _accept;`,
+    `    if (status != NomosModelAdoptionStatus.needsDecision || acceptDecision == null) {`,
+    `      throw StateError('This model change is not waiting for a business decision.');`,
+    `    }`,
+    `    if (reason.isEmpty) throw ArgumentError('accept(reason) needs the business reason for changing prior outcomes');`,
+    `    return acceptDecision(reason);`,
+    `  }`,
+    `}`,
+    ``,
+    `enum NomosModelRestorationStatus { restored, needsDecision, blocked }`,
+    ``,
+    `class NomosModelRestoration {`,
+    `  final NomosModelRestorationStatus status;`,
+    `  final String summary;`,
+    `  final NomosModelReview review;`,
+    `  final Future<NomosModelRestoration> Function(String)? _accept;`,
+    `  const NomosModelRestoration.restored({required this.summary, required this.review})`,
+    `      : status = NomosModelRestorationStatus.restored, _accept = null;`,
+    `  const NomosModelRestoration.blocked({required this.summary, required this.review})`,
+    `      : status = NomosModelRestorationStatus.blocked, _accept = null;`,
+    `  NomosModelRestoration.needsDecision({required this.summary, required this.review, required Future<NomosModelRestoration> Function(String) accept})`,
+    `      : status = NomosModelRestorationStatus.needsDecision, _accept = accept;`,
+    `  Future<NomosModelRestoration> accept(String because) {`,
+    `    final reason = because.trim();`,
+    `    final acceptDecision = _accept;`,
+    `    if (status != NomosModelRestorationStatus.needsDecision || acceptDecision == null) {`,
+    `      throw StateError('This model restoration is not waiting for a business decision.');`,
+    `    }`,
+    `    if (reason.isEmpty) throw ArgumentError('accept(reason) needs the business reason for restoring the previous model');`,
+    `    return acceptDecision(reason);`,
+    `  }`,
+    `}`,
+    ``,
+    `/// This generated package's model, bound to one workspace.`,
+    `class NomosModel {`,
+    `  final Future<NomosModelAdoption> Function() _adopt;`,
+    `  final Future<NomosModelRestoration> Function() _restorePrevious;`,
+    `  const NomosModel(Future<NomosModelAdoption> Function() adopt, Future<NomosModelRestoration> Function() restorePrevious)`,
+    `      : _adopt = adopt, _restorePrevious = restorePrevious;`,
+    `  Future<NomosModelAdoption> adopt() => _adopt();`,
+    `  Future<NomosModelRestoration> restorePrevious() => _restorePrevious();`,
+    `}`,
+    ``,
+    `/// A verified narrative over the activity log. \`describeHistory\` returns this narrow form;`,
+    `/// \`describe\` returns the richer linked [NomosDescription] while preserving these two fields.`,
     `class ActivityNarrative {`,
     `  final List<ActivityEvent> events;`,
     `  final String transcript;`,
     `  const ActivityNarrative({required this.events, required this.transcript});`,
     `}`,
     ``,
+    `/// The root page plus the six product questions every generated client can answer.`,
+    `enum NomosDescribeSection { root, model, current, rules, history, decisions, evidence }`,
+    ``,
+    `class NomosDescribeLink {`,
+    `  final NomosDescribeSection section;`,
+    `  final String label;`,
+    `  final String question;`,
+    `  final String summary;`,
+    `  const NomosDescribeLink({required this.section, required this.label, required this.question, required this.summary});`,
+    `}`,
+    ``,
+    `class NomosDescribeItem {`,
+    `  final String kind;`,
+    `  final String id;`,
+    `  final String label;`,
+    `  final String summary;`,
+    `  final Map<String, dynamic>? details;`,
+    `  final List<NomosRef> refs;`,
+    `  const NomosDescribeItem({required this.kind, required this.id, required this.label, required this.summary, this.details, this.refs = const []});`,
+    `}`,
+    ``,
+    `/// A parent-ledger link to another part of the organisation. Open that workspace's generated client`,
+    `/// and call describe() again; each child explains itself in its own installed business language.`,
+    `class NomosDescribeChild {`,
+    `  final String workspace;`,
+    `  final String status;`,
+    `  final String? bornAt;`,
+    `  final NomosDescribeSection section;`,
+    `  final String label;`,
+    `  final String question;`,
+    `  final String summary;`,
+    `  const NomosDescribeChild({`,
+    `    required this.workspace, required this.status, required this.bornAt,`,
+    `    this.section = NomosDescribeSection.root, required this.label, required this.question, required this.summary,`,
+    `  });`,
+    `}`,
+    ``,
+    `class NomosOrganisationDescription {`,
+    `  final bool complete;`,
+    `  final List<NomosDescribeChild> children;`,
+    `  const NomosOrganisationDescription({required this.complete, required this.children});`,
+    `}`,
+    ``,
+    `/// One grounded page in the hierarchical self-description. Root links to exactly six detail pages.`,
+    `class NomosDescription extends ActivityNarrative {`,
+    `  final NomosDescribeSection section;`,
+    `  final String title;`,
+    `  final String summary;`,
+    `  final List<NomosDescribeItem> items;`,
+    `  final List<NomosDescribeLink> links;`,
+    `  final NomosOrganisationDescription organisation;`,
+    `  const NomosDescription({`,
+    `    required this.section, required this.title, required this.summary, required this.items,`,
+    `    required this.links, required this.organisation, required super.events, required super.transcript,`,
+    `  });`,
+    `}`,
+    ``,
     `/// Wrap events into an [ActivityNarrative], building the LLM-ready transcript: one line per event,`,
     `/// OLDEST-FIRST (the log yields newest-first).`,
     `ActivityNarrative activityNarrative(List<ActivityEvent> events) => ActivityNarrative(`,
@@ -2298,29 +2513,42 @@ export function generateDartActivityRegistry(entries: readonly PackageActivityEn
     `  return cur == null ? '' : '\$cur';`,
     `}`,
     ``,
-    `/// The id the LAW minted for a \`from: "@created"\` ref — the first entry of the row's \`created\` list`,
-    `/// whose type matches the declared aggregate (the runtime type is uuid-stripped + may be namespaced, so`,
-    `/// match on equality OR \`<domain>.<Type>\` suffix). '' when the holon returned no created list (era-safe).`,
-    `String _activityCreatedId(List<Map<String, dynamic>> created, String declared) {`,
-    `  for (final c in created) {`,
+    `/// Resolve the first aggregate of a declared type from either the row's minted \`created\` refs or its`,
+    `/// complete touched \`affected\` refs (used by framework-owned baseline stories).`,
+    `String _activityAggregateId(List<Map<String, dynamic>> aggregates, String declared) {`,
+    `  for (final c in aggregates) {`,
     `    final t = (c['type'] ?? '') as String;`,
     `    if (t == declared || t.endsWith('.\$declared')) return (c['id'] ?? '') as String;`,
     `  }`,
     `  return '';`,
     `}`,
     ``,
-    `/// Fold ONE committed-intent raw row into a typed [ActivityEvent], or null when the directive declares`,
-    `/// no \`.activity(...)\`. rawRow = { intentId, domain, directiveId, actorSubject, occurredAt, payload,`,
-    `/// created, workspace } — \`created\` (\`[{type,id}]\`) backs \`from: "@created"\` refs; \`workspace\` stamps them.`,
+    `/// Keep a framework-private correction identity stable and traceable without exposing its internal name.`,
+    `String _activityOpaqueCorrectionId(String id) {`,
+    `  String hash(int seed) {`,
+    `    var h = seed & 0xffffffff;`,
+    `    for (final code in id.codeUnits) h = ((h ^ code) * 16777619) & 0xffffffff;`,
+    `    return h.toRadixString(16).padLeft(8, '0');`,
+    `  }`,
+    `  return 'correction-\${hash(2166136261)}\${hash(2246822507)}';`,
+    `}`,
+    ``,
+    `/// Fold ONE committed-intent raw row into a typed [ActivityEvent], or null for framework/control work`,
+    `/// outside this generated business package. rawRow carries both minted \`created\` and all touched`,
+    `/// \`affected\` aggregate refs; \`workspace\` stamps them.`,
     `ActivityEvent? renderActivity(Map<String, dynamic> rawRow) {`,
     `  final directiveId = (rawRow['directiveId'] ?? '') as String;`,
     `  final actorSubject = (rawRow['actorSubject'] ?? '') as String;`,
+    `  final domain = (rawRow['domain'] ?? '') as String;`,
     `  final workspace = (rawRow['workspace'] ?? '') as String;`,
     `  final payload = ((rawRow['payload'] as Map?)?.cast<String, dynamic>()) ?? const <String, dynamic>{};`,
     `  final created = ((rawRow['created'] as List?) ?? const <dynamic>[])`,
     `      .map((e) => (e as Map).cast<String, dynamic>())`,
     `      .toList();`,
-    `  switch (directiveId) {`,
+    `  final affected = ((rawRow['affected'] as List?) ?? const <dynamic>[])`,
+    `      .map((e) => (e as Map).cast<String, dynamic>())`,
+    `      .toList();`,
+    `  switch ('${'$'}{domain.length}:${'$'}domain${'$'}directiveId') {`,
     ...sorted.flatMap(emitDartActivityArm),
     `    default:`,
     `      return null;`,
@@ -3969,8 +4197,10 @@ export interface DomainModule {
   /**
    * THE DESIGNATED SURFACED RESOLVERS (surfaced_lint.ts) — one binding per `.merge(Surfaced(...))`
    * field, produced (and fail-closed enforced: exactly one `.resolves()` per Surfaced field, every
-   * Surfaced field covered) by `composeDomainModule`. Drives the generated typed `resolve…` helpers
-   * (TS + Dart) and the `pendingConflicts` accessor. NOT law, NOT hashed (like {@link roles}).
+   * Surfaced field covered) by `composeDomainModule`. Drives the generated typed conflict references
+   * (TS + Dart), the `pendingConflicts` accessor, and the manifest's hash-bearing
+   * `conflictResolution` declaration. The traced payload-field names remain codegen metadata;
+   * the aggregate/field/directive binding is law.
    * Absent when the domain declares no Surfaced field (byte-identical — the era rule).
    */
   surfacedResolvers?: import("./surfaced_lint.js").SurfacedResolverBinding[];