@githolon/dsl 0.40.0 → 0.41.0

package/dart/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.30.0
+
+- RUNTIME AGGREGATE METADATA: `NomosAggregateMeta` / `NomosFieldMeta` / `mergeAggregateMeta` (`src/aggregate_meta.dart`) — the support types for the generated per-domain `const Map<String, NomosAggregateMeta> <domain>AggregateMeta` registry (`nomos-compile` ≥0.41 tooling). Generic surfaces (history/audit UIs, op renderers, in-app agents) resolve `NomosAggregateMeta.typeOfId(op.aggregate)` → field kinds, enum wire values, VO/variant names, and the typed `fromJson` decoder — the compiler's knowledge emitted as data, derived from the law's own declarations.
+
 ## 0.29.0
 
 - LAW-MINTED IDS RETURN TO THE CALLER: `NomosBridge.offerCreates(...)` → `NomosOfferOutcome{head, created}` — a `.creates` plan mints its aggregate id inside the sealed intent (payloads never carry one); the offer now hands the minted ids back, so generated create methods return the typed id with no query-after round-trip. New types `NomosOfferOutcome` / `NomosCreated`.

package/dart/lib/nomos_client.dart

@@ -30,6 +30,9 @@ export 'src/offer.dart';
 export 'src/home.dart';
 export 'src/subscriptions.dart';
 export 'src/schema_validation.dart';
+// RUNTIME AGGREGATE METADATA — the generated per-domain registry's support types
+// (lookup by aggregateType for generic surfaces: history UIs, op renderers, agents).
+export 'src/aggregate_meta.dart';
 // THE WEBVIEW BRIDGE (app-binding boundary) — the async Dart runtime that drives the REAL githolon running
 // in a WebView, so the generated typed client never needs a `MemoryPersistence` fake.
 export 'src/webview_bridge.dart';

package/dart/lib/src/aggregate_meta.dart

@@ -0,0 +1,80 @@
+// RUNTIME AGGREGATE METADATA (architecture/dart_codegen_parity.md — the registry slice).
+//
+// Dart is nominal and has no runtime type derivation, so everything the compiler knows about an
+// aggregate's shape is invisible at runtime unless it is EMITTED AS DATA. `nomos-compile`
+// generates one `const Map<String, NomosAggregateMeta>` per domain (keyed by the projection's
+// wire type, e.g. `drawing.Site`), so generic surfaces — history/audit UIs over `historyOf`,
+// undo previews, op renderers, an in-app agent introspecting state — can resolve
+// `(aggregateType, field, rawValue)` to typed knowledge with NO hand-maintained switch.
+//
+// THE LINE THIS HOLDS: this is client-side reflection over the LAW'S DECLARED SHAPE — derived
+// from the same descriptors the package IR carries, never hand-authored, never a second source
+// of truth. If it disagrees with the law, the generator is broken, not the registry.
+
+/// Runtime metadata for ONE field of an aggregate — the compiler's knowledge, emitted as data.
+class NomosFieldMeta {
+  /// The DSL field kind (`string` | `int` | `double` | `bool` | `enum` | `set` | `map` |
+  /// `json` | `ref` | `counter` | `position` | `evidence` | ...).
+  final String kind;
+
+  /// For `enum` kinds: the exact wire values the law's zod validates.
+  final List<String>? enumValues;
+
+  /// For `json` leaves that are DECLARED value objects: the VO / variant name
+  /// (the generated Dart class / sealed base of the same name decodes it).
+  final String? vo;
+
+  /// True when [vo] names a `variant(...)` sum type (decode lands on a sealed hierarchy
+  /// whose `Unknown` arm carries arms this client's law version doesn't know).
+  final bool isVariant;
+
+  /// For `ref` kinds: the referenced aggregate's wire type, when the law declares it.
+  final String? refType;
+
+  const NomosFieldMeta({
+    required this.kind,
+    this.enumValues,
+    this.vo,
+    this.isVariant = false,
+    this.refType,
+  });
+}
+
+/// Runtime metadata for ONE aggregate, keyed by its projection wire type. [fromRow] is the
+/// generated typed decoder (`<Agg>.fromJson`) — the same one every generated accessor uses,
+/// surfaced here so a runtime-dispatched row still decodes to the REAL typed class.
+class NomosAggregateMeta {
+  /// The projection wire type (`<domain>.<Aggregate>`).
+  final String type;
+
+  /// The aggregate's declared label (`Site`).
+  final String label;
+
+  /// Declared field name → its metadata.
+  final Map<String, NomosFieldMeta> fields;
+
+  /// The generated typed decoder (`Site.fromJson`) — returns the generated aggregate class
+  /// (typed as [Object] here; cast at the call site, or drive it generically via [fields]).
+  final Object Function(Map<String, dynamic> data, [String rowId]) fromRow;
+
+  const NomosAggregateMeta({
+    required this.type,
+    required this.label,
+    required this.fields,
+    required this.fromRow,
+  });
+
+  /// The AGGREGATE WIRE TYPE of a kernel aggregate id: minted ids are
+  /// `<domain>.<Type>_<uuidv7>`, so the type is the prefix before the trailing
+  /// `_<uuid>` (the same rule `@githolon/client` applies to Create events).
+  /// Returns the input unchanged when no uuid suffix is present (already a type).
+  static String typeOfId(String aggregateId) =>
+      aggregateId.replaceFirst(RegExp(r'_[0-9a-fA-F-]+$'), '');
+}
+
+/// Merge per-domain registries into one lookup (a package with several domains). Later maps
+/// win on key collisions — collisions only occur when two domains declare the SAME wire type,
+/// which the compiler already refuses.
+Map<String, NomosAggregateMeta> mergeAggregateMeta(
+        Iterable<Map<String, NomosAggregateMeta>> registries) =>
+    {for (final r in registries) ...r};

package/dart/pubspec.yaml

@@ -11,7 +11,7 @@ description: >-
   Nomos 2 Dart frontend types — the hand-written kernel wire types plus the
   code-generated per-domain aggregate + directive-payload types. (De)serializes
   the EXACT serde JSON the Rust kernel + projection produce/consume.
-version: 0.29.0
+version: 0.30.0
 
 environment:
   sdk: ^3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/codegen_dart.ts

@@ -1536,6 +1536,60 @@ function emitUnionClasses(d: ValueObjectDescriptor): string {
   return [base, ...armClasses, unknown].join("\n\n");
 }
 
+/** THE RUNTIME AGGREGATE-META REGISTRY (dart_codegen_parity.md): one generated
+ * `const Map<String, NomosAggregateMeta>` per domain, keyed by the projection wire type
+ * (`<domain>.<Aggregate>`). Generic surfaces (history/audit UIs, op renderers, in-app agents)
+ * resolve `op.aggregateType` → field kinds / enum wire values / VO+variant names / the typed
+ * `fromJson` decoder — the compiler's knowledge, emitted as data, derived from the SAME
+ * declarations the law carries (never hand-authored; never a second source of truth). */
+function emitAggregateMetaRegistry(
+  domainKey: string,
+  aggregates: readonly AggregateHandle[],
+): string {
+  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 parts: string[] = [`kind: '${f.kind}'`];
+      if (f.kind === "enum") {
+        try {
+          const values = zodEnumValues(f.zod as z.ZodTypeAny);
+          parts.push(`enumValues: [${values.map((v) => `'${v}'`).join(", ")}]`);
+        } catch { /* enum without introspectable values — kind alone still serves */ }
+      }
+      const vo = (f as { valueObject?: { name: string; descriptor?: { union?: unknown } } }).valueObject;
+      if (vo !== undefined) {
+        parts.push(`vo: '${vo.name}'`);
+        if (vo.descriptor && (vo.descriptor as { union?: unknown }).union !== undefined) parts.push(`isVariant: true`);
+      }
+      const refTarget = (f as { refAggregateId?: string }).refAggregateId;
+      if (f.kind === "ref" && refTarget !== undefined) {
+        parts.push(`refType: '${domainKey}.${refTarget}'`);
+      }
+      return `      '${name}': NomosFieldMeta(${parts.join(", ")}),`;
+    });
+    return [
+      `  '${wireType}': NomosAggregateMeta(`,
+      `    type: '${wireType}',`,
+      `    label: '${agg.id}',`,
+      `    fields: {`,
+      ...fieldLines,
+      `    },`,
+      `    fromRow: ${agg.id}.fromJson,`,
+      `  ),`,
+    ].join("\n");
+  });
+  const mapName = `${dartMemberName(domainKey)}AggregateMeta`;
+  return [
+    `/// RUNTIME lookup of this domain's aggregate shapes by projection wire type`,
+    `/// (\`NomosAggregateMeta.typeOfId(op.aggregate)\` resolves an instance id to its key).`,
+    `/// Derived from the law's own declarations — the compiler's knowledge as const data.`,
+    `const Map<String, NomosAggregateMeta> ${mapName} = {`,
+    ...entries,
+    `};`,
+  ].join("\n");
+}
+
 function emitValueObjectClass(d: ValueObjectDescriptor): string {
   if (d.union !== undefined) return emitUnionClasses(d);
   if (d.geometry !== undefined) {
@@ -3212,6 +3266,8 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
       ),
     )
     .join("\n\n");
+  // the runtime aggregate-meta registry (lookup by op.aggregateType — generic surfaces).
+  const aggregateMetaBlock = emitAggregateMetaRegistry(domainKey, localAggregates);
   const dirBlock = localDirectives
     .map((d) => emitDirective(d, domainKey, dartTypes))
     .join("\n\n");
@@ -3426,6 +3482,13 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
     `// ---- aggregates (projection types) ----`,
     aggBlock,
     ``,
+    ...(aggregateMetaBlock !== ""
+      ? [
+          `// ---- runtime aggregate metadata (lookup by op.aggregateType) ----`,
+          aggregateMetaBlock,
+          ``,
+        ]
+      : []),
     ...(readModelBlock !== ""
       ? [
           `// ---- generated read models (from aggregate DSL fields) ----`,

package/src/compile_package_main.ts

@@ -353,6 +353,9 @@ const DART_SUPPORT_SRC = [
   "offer.dart",
   "subscriptions.dart",
   "provider.dart",
+  // Runtime aggregate-meta support types (NomosAggregateMeta/NomosFieldMeta) — the generated
+  // per-domain registry consts reference them through the barrel.
+  "aggregate_meta.dart",
   // The async WebView bridge runtime (NomosBridge / BridgeTransport) the generated
   // `<name>.client.dart` drives — the barrel re-exports it, so it must be vendored too.
   "webview_bridge.dart",