@githolon/dsl 0.71.0 → 0.72.0

package/src/codegen_dart.ts

@@ -491,6 +491,14 @@ interface AggFieldSpec {
   nullAdmits?: boolean;
   /** The law-documentation `reason` for a null-admitting field (surfaces in the Dart doc comment). */
   nullReason?: string;
+  /**
+   * SURFACED MERGE CONFLICTS (architecture/surfaced_merge_conflict.md): the field is declared
+   * `.merge(Surfaced(...))`, so its read value is the base scalar OR the pending-conflict
+   * envelope — typed `SurfacedValue<T>?` (T = the base {@link dartType}) and decoded via
+   * `SurfacedValue.decode`. The FIRST driver-conditional generated typing; absent for every
+   * other field (byte-identical to a pre-Surfaced compile).
+   */
+  surfaced?: true;
 }
 
 export interface DartImport {
@@ -546,7 +554,7 @@ function readModelNullableSuffix(s: AggFieldSpec): string {
   return s.optional ? "?" : "";
 }
 
-function dartMemberName(raw: string): string {
+export function dartMemberName(raw: string): string {
   const parts = raw.split(/[^A-Za-z0-9]+/).filter((p) => p !== "");
   const camel =
     parts.length === 0
@@ -748,7 +756,7 @@ function aggFieldSpec(
         // `contracts.dart`); the aggregate class is `<ContractId>` and must not collide, hence the suffix.
         const target = field.foreignRef.targetIsContract === true
           ? `${field.foreignRef.targetAggregateId}Contract`
-          : field.foreignRef.targetAggregateId;
+          : concreteClassName(field.foreignRef.targetAggregateId);
         return {
           name,
           wireName,
@@ -868,11 +876,19 @@ function aggregateFieldSpecs(
         : f.isFromBirth === true
           ? { ...base, optional: false }
           : { ...base, optional: true };
+      // SURFACED MERGE CONFLICTS (architecture/surfaced_merge_conflict.md): a `.merge(Surfaced(...))`
+      // field types `SurfacedValue<T>?` and decodes via `SurfacedValue.decode`. ALWAYS nullable —
+      // even `.fromBirth()` (the wrapper's pending arm has no non-null plain-scalar reading).
+      // aggregate() already v1-scoped the driver to Lww-class scalar kinds; excludes nullAdmits.
+      const surfacedSpec: AggFieldSpec =
+        (f.driver as { kind?: string } | undefined)?.kind === "Surfaced"
+          ? { ...baseSpec, optional: true, surfaced: true }
+          : baseSpec;
       // NULL SEMANTICS (null_semantics.md): a null-admitting scalar carries the tri-state slot.
       const nmeta = nullMetaOf(f);
       const spec: AggFieldSpec = admitsNull(f)
-        ? { ...baseSpec, nullAdmits: true, ...(nmeta.nullReason !== undefined ? { nullReason: nmeta.nullReason } : {}) }
-        : baseSpec;
+        ? { ...surfacedSpec, nullAdmits: true, ...(nmeta.nullReason !== undefined ? { nullReason: nmeta.nullReason } : {}) }
+        : surfacedSpec;
       if (used.has(spec.name)) {
         throw new Error(
           `aggregate '${agg.id}' field '${spec.wireName}' maps to duplicate Dart field '${spec.name}'`,
@@ -901,11 +917,65 @@ export function cap(s: string): string {
 // `TrackableThing → TrackableThingId`, `BuildingAggregate → BuildingId`. The
 // `RootAggregate` strip BEFORE `Aggregate` keeps the proven `SiteId` byte-identical.
 
+// ---- Dart product-name registry (`.dartName`, architecture/dart_naming.md) ----
+// A wire id → declared Dart base name map. When an aggregate declared `.dartName("Site")`,
+// EVERY Dart naming derivation (concrete class, `<stem>ReadModel`, `<stem>Id`,
+// `read/watch<Name>ById`, `ForeignRef<Target>`) consults this instead of stemming the wire id.
+// Populated per-domain by `registerDartNames` at each Dart-emit entry point. NON-law, Dart-only
+// (TS codegen never reads it); empty ⇒ every derivation is byte-identical to before this existed.
+const dartNameByWireId = new Map<string, string>();
+
+/** Register (or reset) the `.dartName` overrides for a set of aggregates before Dart emit. An
+ *  aggregate WITHOUT a `.dartName` deletes any stale entry for its wire id (test hygiene across
+ *  compiles in one process), so a name only ever reflects the aggregate's OWN current declaration. */
+export function registerDartNames(aggregates: readonly AggregateHandle[]): void {
+  for (const a of aggregates) {
+    if (a.dartClassName !== undefined) dartNameByWireId.set(a.id, a.dartClassName);
+    else dartNameByWireId.delete(a.id);
+  }
+  // COLLISION GUARD (dart_naming.md): a `.dartName` must not collide with another aggregate's declared
+  // dartName OR its default id-derived concrete class — that would emit two Dart classes of the same
+  // name (a fail-closed compile error, not a silent last-wins). Checked over the concrete-class tier
+  // (the aggregate-state name); the ReadModel/Id tiers derive from it, so one check covers all tiers.
+  const byClass = new Map<string, string>(); // concrete class → wire id that produced it
+  for (const a of aggregates) {
+    const cls = dartNameByWireId.get(a.id) ?? a.id;
+    const prior = byClass.get(cls);
+    if (prior !== undefined && prior !== a.id) {
+      const how = (id: string) => (dartNameByWireId.get(id) !== undefined ? `.dartName("${cls}")` : `its wire id`);
+      throw new Error(
+        `dart naming collision: aggregate '${a.id}' (${how(a.id)}) and aggregate '${prior}' (${how(prior)}) ` +
+          `both generate the Dart class name '${cls}' — pick a distinct .dartName() for one of them`,
+      );
+    }
+    byClass.set(cls, a.id);
+  }
+}
+
+/** The concrete aggregate class name (aggregate STATE tier): the declared `.dartName` or the wire id
+ *  (already PascalCase by convention). */
+export function concreteClassName(aggregateType: string): string {
+  return dartNameByWireId.get(aggregateType) ?? aggregateType;
+}
+
+/** The Dart naming STEM for an aggregate wire type: the declared `.dartName` (used verbatim), else the
+ *  wire id with a trailing `RootAggregate`/`Aggregate` stripped (the historical id-derived stem). */
+function dartNameStem(aggregateType: string): string {
+  const declared = dartNameByWireId.get(aggregateType);
+  if (declared !== undefined) return declared;
+  let stem = aggregateType;
+  if (stem.endsWith("RootAggregate")) stem = stem.slice(0, -"RootAggregate".length);
+  else if (stem.endsWith("Aggregate")) stem = stem.slice(0, -"Aggregate".length);
+  return cap(stem === "" ? aggregateType : stem);
+}
+
 /** The typed-id class name for an aggregate WIRE TYPE (e.g. `SiteRootAggregate` →
  * `SiteId`). Pure + deterministic: the SAME wire type ALWAYS yields the SAME name,
  * so the id-class decl, the `createX` factory return, and every typed ref field that
- * points at this type all agree. */
-function typedIdClassForAggregateType(aggregateType: string): string {
+ * points at this type all agree. Honours `.dartName` (`Site` → `SiteId`). */
+export function typedIdClassForAggregateType(aggregateType: string): string {
+  const declared = dartNameByWireId.get(aggregateType);
+  if (declared !== undefined) return `${declared}Id`;
   let stem = aggregateType;
   if (stem.endsWith("RootAggregate")) {
     stem = stem.slice(0, -"RootAggregate".length);
@@ -1171,7 +1241,7 @@ function emitAggregate(
   refIdClassForAggregate: (aggregateType: string) => string = typedIdClassForAggregateType,
   ownIdFields: ReadonlySet<string> = new Set(),
 ): string {
-  const className = agg.id; // wire id is already PascalCase by convention.
+  const className = concreteClassName(agg.id); // wire id (already PascalCase) unless `.dartName` overrides.
   const idType = aggregateIdDartType(agg.id);
   const specs = aggregateFieldSpecs(
     agg,
@@ -1203,6 +1273,14 @@ function emitAggregate(
     `  final NomosRef ref;`,
     ...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).
+      if (s.surfaced === true) {
+        return [
+          `  /// Surfaced merge conflicts: [SurfacedResolved] steady state, [SurfacedPending] under conflict.`,
+          `  final SurfacedValue<${s.dartType}>? ${s.name};`,
+        ];
+      }
       // NULL SEMANTICS: a null-admitting field is the sealed tri-state slot (Omitted / ExplicitNull /
       // Present) — omission and explicit-null never collapse. Others keep the plain `T?`.
       return s.nullAdmits === true
@@ -1236,9 +1314,11 @@ function emitAggregate(
     `      aggregateId: ${aggregateIdFromRowExpr(agg.id, "id")},`,
     `      ref: NomosRef(workspace: workspace, type: type.isEmpty ? '${agg.id}' : type, id: id),`,
     ...specs.map((s) =>
-      s.nullAdmits === true
-        ? `      ${s.name}: NomosSlot.decode<${stripNullable(s.dartType)}>(data, '${s.wireName}', ${slotDecodeCallback(s, "aggregate")}),`
-        : `      ${s.name}: ${parseField(s, className)},`,
+      s.surfaced === true
+        ? `      ${s.name}: SurfacedValue.decode<${s.dartType}>(data, '${s.wireName}', ${slotDecodeCallback(s, "aggregate")}),`
+        : s.nullAdmits === true
+          ? `      ${s.name}: NomosSlot.decode<${stripNullable(s.dartType)}>(data, '${s.wireName}', ${slotDecodeCallback(s, "aggregate")}),`
+          : `      ${s.name}: ${parseField(s, className)},`,
     ),
   ].join("\n");
 
@@ -1797,7 +1877,7 @@ function emitAggregateMetaRegistry(
       `    fields: {`,
       ...fieldLines,
       `    },`,
-      `    fromRow: ${agg.id}.fromJson,`,
+      `    fromRow: ${concreteClassName(agg.id)}.fromJson,`,
       `  ),`,
     ].join("\n");
   });
@@ -2367,13 +2447,7 @@ function stripNullable(t: string): string {
  * `BuildingReadModel`, `ThingReadModel`, `TrackableThingReadModel`). Pure + deterministic
  * — the same wire type always yields the same name. */
 export function readModelClassName(aggregateType: string): string {
-  let stem = aggregateType;
-  if (stem.endsWith("RootAggregate")) {
-    stem = stem.slice(0, -"RootAggregate".length);
-  } else if (stem.endsWith("Aggregate")) {
-    stem = stem.slice(0, -"Aggregate".length);
-  }
-  return `${cap(stem === "" ? aggregateType : stem)}ReadModel`;
+  return `${dartNameStem(aggregateType)}ReadModel`;
 }
 
 /** The Dart type for one generated read-model field. */
@@ -2560,6 +2634,13 @@ function emitReadModel(
     `  final NomosRef ref;`,
     ...specs.flatMap((s) => {
       const doc = s.nullReason !== undefined ? [`  /// null semantic: ${s.nullReason}`] : [];
+      // SURFACED MERGE CONFLICTS: pending observations surface typed; resolve = ordinary next write.
+      if (s.surfaced === true) {
+        return [
+          `  /// Surfaced merge conflicts: [SurfacedResolved] steady state, [SurfacedPending] under conflict.`,
+          `  final SurfacedValue<${readModelDartType(s)}>? ${s.name};`,
+        ];
+      }
       return s.nullAdmits === true
         ? [...doc, `  final NomosSlot<${stripNullable(readModelDartType(s))}> ${s.name};`]
         : [`  final ${readModelDartType(s)}${readModelNullableSuffix(s)} ${s.name};`];
@@ -2591,13 +2672,39 @@ function emitReadModel(
     ...combineds.map((c) => `    this.${c.id},`),
   ].join("\n");
 
+  // SURFACED MERGE CONFLICTS: per-Surfaced-field convenience accessors (the pending seam an app
+  // branches on without hand-parsing) — an EXTENSION on the read model, mirroring the ref-traversal
+  // accessor pattern (codegen_dart_client.ts P2). They live HERE (the pure types file), not on the
+  // client: they are pure field reads needing no bridge, and in layered-packages mode the types
+  // package must not depend on the client. A Surfaced-free aggregate emits none (byte-identical).
+  const surfacedSpecs = specs.filter((s) => s.surfaced === true);
+  const surfacedExtension =
+    surfacedSpecs.length === 0
+      ? []
+      : [
+          ``,
+          `/// Pending-conflict accessors for [${className}] (surfaced_merge_conflict.md) — branch on`,
+          `/// pending-ness without hand-parsing; the UI decides what to do (resolution is an ordinary`,
+          `/// next write via the domain's own directive).`,
+          `extension ${className}Surfaced on ${className} {`,
+          ...surfacedSpecs.flatMap((s) => [
+            `  /// True while \`${s.wireName}\` awaits a human resolution (competing observations retained).`,
+            `  bool get has${cap(s.name)}PendingConflict => ${s.name}?.isPending ?? false;`,
+            `  /// The competing observations on \`${s.wireName}\` while pending; empty otherwise.`,
+            `  List<SurfacedObservation<${readModelDartType(s)}>> get ${s.name}PendingObservations => ${s.name}?.pending ?? const [];`,
+          ]),
+          `}`,
+        ];
+
   const parseLines = [
     `      aggregateId: ${aggregateIdFromRowExpr(agg.id, "id")},`,
     `      ref: NomosRef(workspace: workspace, type: type.isEmpty ? '${agg.id}' : type, id: id),`,
     ...specs.map((s) =>
-      s.nullAdmits === true
-        ? `      ${s.name}: NomosSlot.decode<${stripNullable(readModelDartType(s))}>(data, '${s.wireName}', ${slotDecodeCallback(s, "readModel")}),`
-        : `      ${s.name}: ${parseReadModelField(s, wireType)},`,
+      s.surfaced === true
+        ? `      ${s.name}: SurfacedValue.decode<${readModelDartType(s)}>(data, '${s.wireName}', ${slotDecodeCallback(s, "readModel")}),`
+        : s.nullAdmits === true
+          ? `      ${s.name}: NomosSlot.decode<${stripNullable(readModelDartType(s))}>(data, '${s.wireName}', ${slotDecodeCallback(s, "readModel")}),`
+          : `      ${s.name}: ${parseReadModelField(s, wireType)},`,
     ),
     // Derived/combined fields decode from the engine-produced bare JSON leaf.
     ...deriveds.map((d) => `      ${d.id}: ${parseProjectionReturnField(d.id, d.returns)},`),
@@ -2636,6 +2743,7 @@ function emitReadModel(
     `    );`,
     `  }`,
     `}`,
+    ...surfacedExtension,
   ].join("\n");
 }
 
@@ -2968,7 +3076,8 @@ function emitQueryReads(
   refIdClassForAggregate: (aggregateType: string) => string = typedIdClassForAggregateType,
   ownIdFieldsByAggregate: ReadonlyMap<string, ReadonlySet<string>> = new Map(),
 ): string {
-  const agg = q.returns; // the aggregate TYPE id (== the generated class name).
+  const agg = q.returns; // the aggregate TYPE id (== the wire id, used for field/index lookups).
+  const aggClass = concreteClassName(agg); // the generated Dart class name (honours `.dartName`).
   const method = readMethodName(q.id);
   const Method = cap(method);
   // The query registry keys every query on EXACTLY ONE string field; take it as
@@ -2995,17 +3104,17 @@ function emitQueryReads(
   const keyParam = `${keySpec.dartType} ${paramName}`;
   const words = q.id.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase();
   return [
-    `/// Reactive typed read: every \`${agg}\` matching the indexed \`${q.id}\` query`,
+    `/// Reactive typed read: every \`${aggClass}\` matching the indexed \`${q.id}\` query`,
     `/// (${words}), keyed on \`${keyField}\`. Emits the current matches, then re-emits`,
     `/// on each projection tick. O(matches) via the projection index (#140) — never a`,
     `/// workspace scan.`,
-    `Stream<List<${agg}>> watch${Method}(NomosReads reads, ${keyParam}) =>`,
-    `    reads.watchQuery('${q.id}', {${params}}, ${agg}.fromJson);`,
+    `Stream<List<${aggClass}>> watch${Method}(NomosReads reads, ${keyParam}) =>`,
+    `    reads.watchQuery('${q.id}', {${params}}, ${aggClass}.fromJson);`,
     ``,
     `/// One-shot typed read of the \`${q.id}\` query (${words}): the CURRENT matching`,
-    `/// \`${agg}\` list, keyed on \`${keyField}\`. O(matches).`,
-    `List<${agg}> read${Method}(NomosReads reads, ${keyParam}) =>`,
-    `    reads.readQuery('${q.id}', {${params}}, ${agg}.fromJson);`,
+    `/// \`${aggClass}\` list, keyed on \`${keyField}\`. O(matches).`,
+    `List<${aggClass}> read${Method}(NomosReads reads, ${keyParam}) =>`,
+    `    reads.readQuery('${q.id}', {${params}}, ${aggClass}.fromJson);`,
   ].join("\n");
 }
 
@@ -3014,7 +3123,7 @@ function emitQueryReads(
  * off the PK `query_by_id` seam (resolves the unbound singleton by its type-key AND
  * an instance-bound aggregate by its id). */
 function emitAggregateByIdReads(agg: AggregateHandle): string {
-  const cls = agg.id;
+  const cls = concreteClassName(agg.id);
   const idType = aggregateIdDartType(agg.id);
   return [
     `/// Reactive typed by-id read: the \`${cls}\` with kernel aggregate id [id]`,
@@ -3318,7 +3427,7 @@ function emitExistsReads(
  * Returns projected typed aggregates (via `project_by_ids`, `lib.rs:1686`) — not raw ids.
  * Archived aggregates are auto-excluded (the `type_index` row is dropped on archive). */
 function emitOrderedReads(d: OrderedReadDecl): string {
-  const agg = d.of;
+  const agg = concreteClassName(d.of); // the generated Dart class name (honours `.dartName`).
   const method = readMethodName(d.id);
   const Method = cap(method);
   const words = d.id.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase();
@@ -3708,6 +3817,14 @@ export interface DomainModule {
    * (TS + Dart). NOT law, NOT hashed (like {@link autoDeclaredEnsures}). Absent when no role is declared.
    */
   roles?: import("./role.js").RoleMeta[];
+  /**
+   * 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}).
+   * Absent when the domain declares no Surfaced field (byte-identical — the era rule).
+   */
+  surfacedResolvers?: import("./surfaced_lint.js").SurfacedResolverBinding[];
   /**
    * STABLE-ID CONTINUITY (#58 — names are labels, identity is minted). When present
    * (attached by `nomos-compile` from the PRIOR build's identity manifests), the
@@ -3977,6 +4094,7 @@ export interface GenerateDartDomainOptions {
 
 /** Generate the full Dart source for one domain module. */
 export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOptions = {}): string {
+  registerDartNames(mod.aggregates); // `.dartName` overrides for this domain's Dart naming derivations.
   const domainKey = mod.domain ?? mod.name;
   const skipAggregateIds = opts.skipAggregateIds ?? new Set<string>();
   const skipDirectiveIds = opts.skipDirectiveIds ?? new Set<string>();
@@ -4075,7 +4193,13 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
   // `jsonEncode` — the ONE case the generated file needs `dart:convert` (null_semantics.md).
   const needsJsonConvert = localAggregates.some((a) =>
     Object.values(a.fields as Record<string, Field>).some(
-      (f) => admitsNull(f) && f.kind === "json" && f.valueObject === undefined,
+      (f) =>
+        // A null-admitting plain-json slot re-stringifies via jsonEncode…
+        (admitsNull(f) && f.kind === "json" && f.valueObject === undefined) ||
+        // …and so does a Surfaced plain-json field's aggregate-class leaf decode.
+        ((f.driver as { kind?: string } | undefined)?.kind === "Surfaced" &&
+          f.kind === "json" &&
+          f.valueObject === undefined),
     ),
   );
   const localDirectives = mod.directives.filter((d) => !skipDirectiveIds.has(d.id));