@githolon/dsl 0.40.0 → 0.42.0

package/dart/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 0.31.0
+
+- `NomosFieldMeta.fromBirth` — the registry surfaces BIRTH-PRESENCE LAW (`.fromBirth()` fields, tooling ≥0.42): a gate invariant guarantees the field present on every row, and the generated read models type it non-nullable.
+
+## 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,85 @@
+// 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;
+
+  /// True when the field carries BIRTH-PRESENCE LAW (`.fromBirth()`): a gate invariant
+  /// guarantees it present on every row, and the generated read model types it non-nullable.
+  final bool fromBirth;
+
+  const NomosFieldMeta({
+    required this.kind,
+    this.enumValues,
+    this.vo,
+    this.isVariant = false,
+    this.refType,
+    this.fromBirth = false,
+  });
+}
+
+/// 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.31.0
 
 environment:
   sdk: ^3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.40.0",
+  "version": "0.42.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/aggregate.ts

@@ -277,6 +277,31 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
     .map(([name]) => name)
     .sort();
 
+  // BIRTH-PRESENCE LAW (`.fromBirth()`, dart_codegen_parity.md): the declared fields become an
+  // AUTO-GENERATED aggregate invariant — the SAME #41 gate machinery a hand-written invariant
+  // uses, executing on EVERY event touching the type (author, edge admission, verify_chain), so
+  // a plan that leaves one absent is a TYPED refusal and the generated read models may type
+  // these fields NON-NULLABLE (absence is unrepresentable BY LAW, not by convention). Presence
+  // is monotone for the allowed kinds (no op unsets a value leaf), which keeps the claim sound
+  // on every later event. Composed BEFORE any user invariant (presence first, then domain law).
+  const fromBirthFields = Object.entries(stored)
+    .filter(([, f]) => (f as Field).isFromBirth === true)
+    .map(([name]) => name)
+    .sort();
+  const userInvariant = opts?.invariant;
+  const composedInvariant: AggregateInvariantFn | undefined =
+    fromBirthFields.length > 0
+      ? (snapshot) => {
+          for (const name of fromBirthFields) {
+            const v = snapshot[name];
+            if (v === undefined || v === null) {
+              return { reject: `${id}.${name} is fromBirth() — every ${id} must carry it from creation (the plan left it unset)` };
+            }
+          }
+          return userInvariant !== undefined ? userInvariant(snapshot) : { accept: true };
+        }
+      : userInvariant;
+
   // The audience-free DATA shape; the audience is attached below (from the legacy `{visibility}` opt or a
   // fluent `.public()`/`.readableBy()`/`.owned()` call).
   const base = {
@@ -284,9 +309,10 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
     fields: stored as StoredFields<F>,
     hasMany: hasMany as HasManyFields<F>,
     __isAggregateHandle: true as const,
-    ...(opts?.invariant !== undefined
-      ? { hasInvariant: true as const, invariant: opts.invariant }
+    ...(composedInvariant !== undefined
+      ? { hasInvariant: true as const, invariant: composedInvariant }
       : {}),
+    ...(fromBirthFields.length > 0 ? { fromBirthFields } : {}),
     ...(opts?.invariantDeclassify !== undefined ? { invariantDeclassify: opts.invariantDeclassify } : {}),
     ...(opts?.cap !== undefined ? { cap: opts.cap } : {}),
     ...(opts?.global === true ? { global: true } : {}),

package/src/codegen_dart.ts

@@ -743,9 +743,14 @@ function aggregateFieldSpecs(
       // decode would crash mid-fold). `.optional()` on the DSL field no longer
       // changes the read surface; it was nullable in practice — this makes the type
       // honest. Collections are unchanged (they already empty-default when absent).
+      // BIRTH-PRESENCE LAW (`.fromBirth()`): the gate refuses any event that leaves the field
+      // absent, so the read model may type it NON-NULLABLE — the one lawful exception to the
+      // partial-fold nullability doctrine (absence is unrepresentable by law, not convention).
       const spec: AggFieldSpec = isCollectionKind(base.kind)
         ? base
-        : { ...base, optional: true };
+        : f.isFromBirth === true
+          ? { ...base, optional: false }
+          : { ...base, optional: true };
       if (used.has(spec.name)) {
         throw new Error(
           `aggregate '${agg.id}' field '${spec.wireName}' maps to duplicate Dart field '${spec.name}'`,
@@ -1536,6 +1541,61 @@ 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}'`);
+      }
+      if ((f as { isFromBirth?: true }).isFromBirth === true) parts.push(`fromBirth: true`);
+      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 +3272,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 +3488,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/codegen_ts.ts

@@ -527,11 +527,12 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     }
   }
 
-  out.push(`// ── read models (projection \`data\` shapes; every field is partial-fold optional) ──`, ``);
+  out.push(`// ── read models (projection \`data\` shapes; partial-fold optional, EXCEPT .fromBirth()`, `//    fields — their presence is gate law, so the type is non-optional) ──`, ``);
   for (const [typeId, agg] of [...aggByType].sort(([a], [b]) => a.localeCompare(b))) {
     out.push(`export interface ${typeId}Data {`);
     for (const [name, field] of Object.entries(agg.fields)) {
-      out.push(`  ${name}?: ${tsTypeOfField(field as Field)};`);
+      const required = (field as Field).isFromBirth === true;
+      out.push(`  ${name}${required ? "" : "?"}: ${tsTypeOfField(field as Field)};`);
     }
     for (const extra of extrasByType.get(typeId) ?? []) out.push(extra);
     out.push(`}`, ``);

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",
@@ -1091,6 +1094,35 @@ async function main(): Promise<void> {
       }
     }
     if (inferred.length > 0) inferredRenames.push({ domain: identityName, renames: inferred });
+    // ── THE fromBirth EVOLVE GUARD (dart_codegen_parity.md): birth-presence may be declared at a
+    // field's FIRST appearance (fresh sid — every row of the type is born under the invariant) or
+    // carried forward, but NEVER newly added to a sid that existed without it: rows born under the
+    // earlier law may lack the field, and the non-nullable read model would LIE about them. The
+    // lawful adoption path for an existing field is a data migration (backfill every row, then
+    // re-birth/dispositions) — named here so the refusal teaches it. ──
+    if (prior !== undefined) {
+      const priorFromBirthBySid = new Map<string, boolean>();
+      for (const a of Object.values(prior.aggregates)) {
+        for (const f of Object.values(a.fields)) priorFromBirthBySid.set(f.sid, f.fromBirth === true);
+      }
+      for (const agg of mod.aggregates) {
+        const fields = (agg.fields ?? {}) as Record<string, { isFromBirth?: true }>;
+        for (const [fieldName, f] of Object.entries(fields)) {
+          if (f?.isFromBirth !== true) continue;
+          const sid = continuity.aggregates[agg.id]?.fields[fieldName]?.sid;
+          if (sid === undefined) continue; // first appearance — lawful
+          const priorHad = priorFromBirthBySid.get(sid);
+          if (priorHad === false) {
+            throw new Error(
+              `${identityName}.${agg.id}.${fieldName}: .fromBirth() cannot be NEWLY declared on an existing field — ` +
+                `rows born under the earlier law may lack it, and the non-nullable read model would lie about them. ` +
+                `Either declare fromBirth at the field's first appearance, or migrate: backfill every ${agg.id} row, ` +
+                `then adopt via a re-birth (the #58 dispositions lane).`,
+            );
+          }
+        }
+      }
+    }
     // The lockfile records the EMITTED surface (sids + lineage + kinds — the next
     // compile's pair rule reads the kinds), not the bare continuity.
     nextLock.domains[identityName] = {

package/src/fields.ts

@@ -154,6 +154,12 @@ export interface Field<T = unknown, K extends FieldKind = FieldKind> {
   readonly kind: K;
   readonly zod: z.ZodType<T>;
   readonly driver: Driver;
+  /** BIRTH-PRESENCE LAW (`.fromBirth()`): the aggregate() declaration SYNTHESIZES a real
+   * #41 gate invariant requiring this field present on EVERY event touching the type — so
+   * the generated read models type it NON-NULLABLE (absence is law-refused, not convention).
+   * Scalar Lww-class kinds only; mutually exclusive with `.optional()`. Flag named
+   * `isFromBirth` — the `fromBirth()` METHOD sets it (the isOptional/isEncrypted convention). */
+  readonly isFromBirth?: true;
   /** For `t.ref` cross-workspace edges: the foreign workspace id, if any. */
   readonly refWorkspace?: string;
   /** For `t.ref` (the target) AND `t.hasMany` (the child type): the related aggregate's wire id. */
@@ -253,6 +259,9 @@ export interface Field<T = unknown, K extends FieldKind = FieldKind> {
    * schema IS the single source of truth codegen derives required-vs-optional from.
    */
   optional(): Field<T | undefined, K>;
+  /** Declare BIRTH-PRESENCE LAW: aggregate() synthesizes a gate invariant requiring this field
+   * present on every event touching the type; read models type it NON-NULLABLE. */
+  fromBirth(): Field<T, K>;
   /** Phantom to keep T load-bearing for inference. */
   readonly _t?: T;
 }
@@ -266,6 +275,7 @@ function makeField<T, K extends FieldKind = FieldKind>(
     refAggregateId?: string;
     viaField?: string;
     isOptional?: boolean;
+    fromBirth?: true;
     mapValueKind?: FieldKind;
     jsonShape?: "object";
     valueObject?: ValueObjectFieldMeta;
@@ -289,10 +299,14 @@ function makeField<T, K extends FieldKind = FieldKind>(
     ...(extra.valueObject !== undefined ? { valueObject: extra.valueObject } : {}),
     ...(extra.encrypted ? { isEncrypted: true as const } : {}),
     ...(extra.meta ? { isMeta: true as const } : {}),
+    ...(extra.fromBirth ? { isFromBirth: true as const } : {}),
     merge(d: Driver) {
       return makeField<T, K>(kind, zod, d, extra);
     },
     optional(): Field<T | undefined, K> {
+      if (extra.fromBirth) {
+        throw new Error("a .fromBirth() field cannot be .optional() — birth-presence and optionality contradict.");
+      }
       // Wrap the Zod once (`.optional()` is idempotent enough — re-wrapping an
       // already-optional schema stays optional). Carry the flag so codegen reads it
       // directly without re-introspecting Zod.
@@ -301,6 +315,20 @@ function makeField<T, K extends FieldKind = FieldKind>(
         isOptional: true,
       });
     },
+    fromBirth(): Field<T, K> {
+      // BIRTH-PRESENCE LAW: only scalar Lww-class kinds — a set/map/counter/position reads as
+      // an empty/zero default (presence is meaningless), a hasMany is virtual. Presence is
+      // MONOTONE for the allowed kinds (no op unsets a value leaf), which is exactly what makes
+      // the non-nullable read type sound.
+      const allowed: readonly FieldKind[] = ["string", "int", "bool", "enum", "json", "ref", "evidence"];
+      if (!allowed.includes(kind)) {
+        throw new Error(`.fromBirth() is not available on a '${kind}' field — collections/CRDT scalars read as defaults; presence law applies to value leaves (${allowed.join("/")}).`);
+      }
+      if (isOptional) {
+        throw new Error("a .optional() field cannot be .fromBirth() — birth-presence and optionality contradict.");
+      }
+      return makeField<T, K>(kind, zod, driver, { ...extra, fromBirth: true });
+    },
     encrypted(): Field<T, K> {
       // Carry the flag through merge/optional (extra is threaded), so `.merge(Lww).encrypted()`
       // and `.encrypted().merge(Lww)` agree. The wire schema is UNCHANGED (driver-only) — the

package/src/manifest.ts

@@ -978,7 +978,7 @@ function stableIdsForModule(
     const aggSid = prior?.sid ?? mintAggregateSid(domainSid, agg.id);
     const handleFields = (handlesById.get(agg.id)?.fields ?? {}) as Record<
       string,
-      { kind?: string } | undefined
+      { kind?: string; isFromBirth?: true } | undefined
     >;
     const fields: Record<string, StableFieldId> = {};
     for (const fieldName of Object.keys(agg.schema).sort()) {
@@ -989,6 +989,9 @@ function stableIdsForModule(
         ...(pf?.was !== undefined && pf.was.length > 0 ? { was: pf.was } : {}),
         // The CURRENT kind, always from the live module (continuity never supplies it).
         ...(kind !== undefined ? { kind } : {}),
+        // Birth-presence law rides identity: the evolve guard reads it (fromBirth may not be
+        // NEWLY declared on a sid that existed without it).
+        ...(handleFields[fieldName]?.isFromBirth === true ? { fromBirth: true as const } : {}),
       };
     }
     out[agg.id] = {

package/src/stable_ids_types.ts

@@ -21,6 +21,10 @@ export interface StableFieldId {
    * Always set at emission; continuity input may omit it (the current module is the
    * source of the CURRENT kind). */
   readonly kind?: string;
+  /** BIRTH-PRESENCE LAW (`.fromBirth()`): recorded at the field's first fromBirth emission.
+   * The compile guard refuses NEWLY declaring fromBirth on a sid that existed without it
+   * (old rows may lack the field — the non-nullable read type would lie). */
+  readonly fromBirth?: true;
 }
 
 /** One aggregate's stable identity: sid + label lineage + per-field sids (keyed by CURRENT field name). */