@githolon/dsl 0.42.0 → 0.43.0

package/package.json

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

@@ -313,6 +313,14 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
       ? { 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 } : {}),
     ...(opts?.global === true ? { global: true } : {}),

package/src/codegen_dart.ts

@@ -1392,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) {`,
@@ -1428,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
@@ -1464,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`,
@@ -1512,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`,
@@ -1624,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());`,
@@ -1686,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/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