@githolon/dsl 0.41.0 → 0.43.0

package/dart/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 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.

package/dart/lib/src/aggregate_meta.dart

@@ -31,12 +31,17 @@ class NomosFieldMeta {
   /// 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,
   });
 }
 

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.30.0
+version: 0.31.0
 
 environment:
   sdk: ^3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.41.0",
+  "version": "0.43.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,8 +309,17 @@ 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 } : {}),
+    // VALUE-FREE INVARIANT (nomosFlowGate rule 4a): when the ONLY invariant is the synthesized
+    // fromBirth presence check, its refusal correlates with STRUCTURE the law itself guarantees
+    // publicly (a fromBirth field is present on every lawful row) — never with a secret VALUE.
+    // The flow gate exempts it from the declassify requirement; ANY user invariant (which may
+    // read plaintext values) re-arms the rule.
+    ...(fromBirthFields.length > 0 && userInvariant === undefined
+      ? { invariantValueFree: true as const }
       : {}),
     ...(opts?.invariantDeclassify !== undefined ? { invariantDeclassify: opts.invariantDeclassify } : {}),
     ...(opts?.cap !== undefined ? { cap: opts.cap } : {}),

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}'`,
@@ -1387,6 +1392,10 @@ function voToJsonExpr(f: ValueObjectFieldDescriptor, expr: string, depth = 0): s
  * per file when the file emits ≥1 VO class (`toJson()`-based value equality). */
 function emitVoHelpers(): string {
   return [
+    `/// The copyWith ABSENT-vs-null sentinel: an omitted optional param keeps the current`,
+    `/// value; an explicit \`null\` clears it. (Dart cannot distinguish the two otherwise.)`,
+    `const Object _voUnset = Object();`,
+    ``,
     `/// Deep json equality for generated value-object classes (toJson-based).`,
     `bool _voJsonEq(Object? a, Object? b) {`,
     `  if (a is Map && b is Map) {`,
@@ -1423,6 +1432,36 @@ function emitVoHelpers(): string {
  * `toJson` (the authored payload shape — optionals OMITTED when null, matching the zod
  * `.optional()` contract), and toJson-based value equality. A `geo.*` VO emits the
  * fixed RFC 7946 shape (typed `coordinates`; `type` is the constant geometry kind). */
+/** The generated `copyWith` for a VO/arm class: non-nullable fields take an optional param
+ * (`?? this.x` — they cannot be cleared; presence is the type's contract); OPTIONAL fields use
+ * the `_voUnset` sentinel so `copyWith()` keeps the value while `copyWith(x: null)` CLEARS it —
+ * the two intents Dart's named params cannot otherwise distinguish. The Dart idiom for the TS
+ * spread (dart_codegen_parity.md P3). */
+function emitCopyWith(
+  cls: string,
+  fields: readonly { member: string; dartType: string; optional: boolean }[],
+): string[] {
+  if (fields.length === 0) return [];
+  const params = fields.map((x) =>
+    x.optional ? `    Object? ${x.member} = _voUnset,` : `    ${x.dartType}? ${x.member},`,
+  );
+  const args = fields.map((x) =>
+    x.optional
+      ? `        ${x.member}: identical(${x.member}, _voUnset) ? this.${x.member} : ${x.member} as ${x.dartType}?,`
+      : `        ${x.member}: ${x.member} ?? this.${x.member},`,
+  );
+  return [
+    `  /// A copy with the given fields replaced. Omitting an optional param keeps its value;`,
+    `  /// passing \`null\` explicitly CLEARS it (the _voUnset sentinel distinguishes the two).`,
+    `  ${cls} copyWith({`,
+    ...params,
+    `  }) =>`,
+    `      ${cls}(`,
+    ...args,
+    `      );`,
+  ];
+}
+
 /** Emit a `union(...)` as a SEALED Dart hierarchy: the sealed base (decode switch on the
  * blessed `type` discriminator + abstract `toJson`), one final arm class per arm (anonymous
  * arms carry their fields; NAMED-VO arms hold a single `value` of the named class), and the
@@ -1459,6 +1498,9 @@ function emitUnionClasses(d: ValueObjectDescriptor): string {
         `      ${cls}(${arm.ref}.fromProjected((m['value']! as Map).cast<String, Object?>()));`,
         `  @override`,
         `  Map<String, Object?> toJson() => <String, Object?>{'type': '${key}', 'value': value.toJson()};`,
+        ``,
+        `  /// A copy with [value] replaced.`,
+        `  ${cls} copyWith({${arm.ref}? value}) => ${cls}(value ?? this.value);`,
         `  @override`,
         `  bool operator ==(Object other) => other is ${cls} && _voJsonEq(other.toJson(), toJson());`,
         `  @override`,
@@ -1507,6 +1549,8 @@ function emitUnionClasses(d: ValueObjectDescriptor): string {
       ...literalToLines,
       ...toLines,
       `      };`,
+      ``,
+      ...emitCopyWith(cls, fields.map((x) => ({ member: x.member, dartType: dartTypeOfVoField(x.f, cls, x.wireName), optional: x.optional }))),
       `  @override`,
       `  bool operator ==(Object other) => other is ${cls} && _voJsonEq(other.toJson(), toJson());`,
       `  @override`,
@@ -1566,6 +1610,7 @@ function emitAggregateMetaRegistry(
       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 [
@@ -1618,6 +1663,8 @@ function emitValueObjectClass(d: ValueObjectDescriptor): string {
       `        'coordinates': coordinates,`,
       `      };`,
       ``,
+      ...emitCopyWith(d.name, [{ member: "coordinates", dartType: coordsType, optional: false }]),
+      ``,
       `  @override`,
       `  bool operator ==(Object other) =>`,
       `      other is ${d.name} && _voJsonEq(other.toJson(), toJson());`,
@@ -1680,6 +1727,8 @@ function emitValueObjectClass(d: ValueObjectDescriptor): string {
     ...toLines,
     `      };`,
     ``,
+    ...emitCopyWith(d.name, fields.map((x) => ({ member: x.member, dartType: dartTypeOfVoField(x.f, d.name, x.wireName), optional: x.optional }))),
+    ``,
     `  @override`,
     `  bool operator ==(Object other) =>`,
     `      other is ${d.name} && _voJsonEq(other.toJson(), toJson());`,

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

@@ -1094,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/flow_gate.ts

@@ -38,6 +38,10 @@ type FlowModule = {
   readonly aggregates?: readonly {
     readonly id: string;
     readonly hasInvariant?: boolean;
+    /** True when the invariant is PROVABLY value-free (only the synthesized fromBirth
+     * presence check — no user predicate). Its refusal correlates with law-guaranteed
+     * structure, never a secret value, so rule 4a exempts it from declassify. */
+    readonly invariantValueFree?: boolean;
     readonly invariantDeclassify?: string;
     readonly encryptedFields?: readonly string[];
     readonly fields?: Record<string, unknown>;
@@ -150,6 +154,9 @@ export function assertFlowGate(m: CanonicalManifest, mod?: FlowModule): void {
     // 4a — an aggregate `invariant` over a private aggregate with a plaintext field.
     for (const a of mod.aggregates ?? []) {
       if (!a.hasInvariant || !privateTypes.has(a.id) || a.invariantDeclassify) continue;
+      // A VALUE-FREE invariant (the synthesized fromBirth presence check alone) refuses only on
+      // ABSENCE of a field the law guarantees present — structure, not secret. No declassify needed.
+      if (a.invariantValueFree === true) continue;
       const enc = new Set(a.encryptedFields ?? []);
       const hasPlaintext = Object.keys(a.fields ?? {}).some((f) => !enc.has(f));
       if (!hasPlaintext) continue; // fully-encrypted: the invariant reads only ciphertext — can't leak this way

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). */