@githolon/dsl 0.74.0 → 0.75.0

package/dart/test/watch_surfaces_test.dart

@@ -0,0 +1,240 @@
+// THE REACTIVE PROMISED SURFACES (task #86 gaps 4/5/6): one cluster, three watch lanes the
+// gauntlet build found uncovered from Dart —
+//   • watchSpatial      — the R*Tree bbox probe as a LIVE stream (typed, via the generated client);
+//   • watchCompatibility / onLawChanged — law-change reactivity: subscribe under law v1, install the
+//     evolved v2 IN-SESSION (the real `nomos/installDomain` lane), assert both surfaces fire with the
+//     right shapes and the evolved directive works immediately;
+//   • watchActivity     — declared `.activity()` directives stream as activity rows.
+// House style: numbered legs, phase-timeout-bounded, loud failures, graceful skip.
+@TestOn('vm')
+library;
+
+import 'dart:async';
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:crypto/crypto.dart' show sha256;
+import 'package:nomos_client/nomos_headless.dart';
+import 'package:test/test.dart';
+
+import '../../../bench/scale/fixtures/co2-acceptance/build/dart/src/generated/estate.client.dart';
+
+String get _root => '${Directory.current.path}/../..';
+String get _repoEntry => '$_root/cloud/web-client/runner/node-entry.mjs';
+String get _geoDeploy =>
+    '$_root/bench/scale/fixtures/co2-acceptance/build/co2-acceptance.deploy.json';
+String get _actsDeploy =>
+    '$_root/bench/scale/fixtures/activity-feed/build/activity_repro.deploy.json';
+String get _evoV1Deploy => '$_root/bench/scale/fixtures/evolution/v1/build/evo.deploy.json';
+String get _evoV2Deploy => '$_root/bench/scale/fixtures/evolution/v2/build/evo.deploy.json';
+String get _evoV2Interface =>
+    '$_root/bench/scale/fixtures/evolution/v2/build/evo.interface.json';
+String get _runtimeDir =>
+    Platform.environment['NOMOS_DART_RUNTIME'] ??
+    '${Platform.environment['HOME'] ?? ''}/.holon/runtime';
+
+String? _missingPrereq() {
+  if (!File(_repoEntry).existsSync()) return 'in-repo runner not found at $_repoEntry';
+  for (final e in {
+    _geoDeploy: 'bench/scale/fixtures/co2-acceptance',
+    _actsDeploy: 'bench/scale/fixtures/activity-feed',
+    _evoV1Deploy: 'bench/scale/fixtures/evolution/v1',
+    _evoV2Deploy: 'bench/scale/fixtures/evolution/v2',
+  }.entries) {
+    if (!File(e.key).existsSync()) {
+      return 'missing fixture ${e.key} — compile it: (cd ${e.value} && node ../../../../dsl/compile_package.mjs)';
+    }
+  }
+  if (!File('$_runtimeDir/holon.wasm').existsSync() ||
+      !File('$_runtimeDir/packages.json').existsSync()) {
+    return 'warm ~/.holon/runtime first (run any `githolon` command once)';
+  }
+  return null;
+}
+
+Future<T> _leg<T>(String name, Future<T> Function() body) async {
+  final sw = Stopwatch()..start();
+  // ignore: avoid_print
+  print('▶ WATCH $name …');
+  try {
+    final r = await body();
+    // ignore: avoid_print
+    print('✔ WATCH $name (${sw.elapsedMilliseconds}ms)');
+    return r;
+  } catch (e, st) {
+    throw TestFailure('WATCH $name FAILED after ${sw.elapsedMilliseconds}ms:\n$e\n$st');
+  }
+}
+
+/// Await the first stream element satisfying [where], bounded — a watch that never emits is a
+/// loud, named failure, not a hang.
+Future<T> _firstWhere<T>(Stream<T> s, bool Function(T) where, String what,
+        [Duration limit = const Duration(seconds: 30)]) =>
+    s.firstWhere(where).timeout(limit,
+        onTimeout: () => throw StateError('$what never emitted within ${limit.inSeconds}s'));
+
+void main() {
+  test('reactive surfaces: watchSpatial → watchCompatibility/onLawChanged → watchActivity',
+      () async {
+    final missing = _missingPrereq();
+    if (missing != null) {
+      markTestSkipped(missing);
+      return;
+    }
+    final harness = await NomosTestHarness.cluster(
+      workspaces: {
+        'geo': [_geoDeploy],
+        'acts': [_actsDeploy],
+        'evo': [_evoV1Deploy],
+      },
+      nodeEntry: _repoEntry,
+      runtimeDir: _runtimeDir,
+      phaseTimeout: const Duration(seconds: 120),
+    );
+    try {
+      // ── LEG 1: watchSpatial — the typed reactive bbox probe. Write a point, the bbox watch
+      //    emits it; write a second point inside the box, the watch re-emits with both. ──
+      await _leg('leg 1: watchSpatial (typed sitesByBounds bbox stream)', () async {
+        final estate = EstateClient(harness.session('geo'), actor: 'user:ada');
+        final bbox = NomosBbox(minX: -3, minY: 53, maxX: -2, maxY: 54);
+        Future<void> place(String name, List<double> coords) =>
+            estate.registerSite(RegisterSitePayload(
+              name: name,
+              location: SiteLocation(
+                point: GeoPoint(coordinates: coords),
+                source: SiteLocationSource.addressSearch,
+              ),
+              registeredAt: DateTime.now().toUtc().toIso8601String(),
+            ));
+        await place('inside-1', [-2.24, 53.48]);
+        await place('way-outside', [10.0, 10.0]);
+        final stream = estate.watchSitesByBounds(bbox: bbox).asBroadcastStream();
+        final first = await _firstWhere(
+            stream, (rows) => rows.isNotEmpty, 'watchSpatial first snapshot');
+        expect(first.map((r) => r.name), ['inside-1'],
+            reason: 'the first snapshot holds exactly the in-bbox site (probe, not full scan)');
+        final grown = _firstWhere(stream, (rows) => rows.length >= 2, 'watchSpatial re-emission');
+        await place('inside-2', [-2.5, 53.6]);
+        expect((await grown).map((r) => r.name).toSet(), {'inside-1', 'inside-2'},
+            reason: 'a new in-bbox write re-emits through the live spatial watch');
+      });
+
+      // ── LEG 2: watchCompatibility + onLawChanged — subscribe under v1, install the evolved v2
+      //    (rename + added field + added directive) through the REAL nomos/installDomain lane,
+      //    assert both reactive surfaces fire and the added directive works at once. ──
+      await _leg('leg 2: watchCompatibility/onLawChanged across a live law evolution', () async {
+        final evo = harness.session('evo');
+        final v1Hash = harness.lawHashes('evo').first;
+        final v2Deploy =
+            (jsonDecode(File(_evoV2Deploy).readAsStringSync()) as Map).cast<String, Object?>();
+        final v2Usda = v2Deploy['packageUsda'].toString();
+        final v2Hash = sha256.convert(utf8.encode(v2Usda)).toString();
+        expect(v2Hash, isNot(v1Hash), reason: 'v2 is a genuinely different law');
+        final v2Requirement =
+            (jsonDecode(File(_evoV2Interface).readAsStringSync()) as Map).cast<String, Object?>();
+
+        // Seed a v1 row (written under the OLD field name — the rename's era-1 side).
+        await evo.offerOutcome(
+          domain: 'evo',
+          directiveId: 'registerSite',
+          payload: {'name': 'era-1-site', 'geoPos': '51.5,-0.1'},
+          domainHash: v1Hash,
+        );
+
+        // Arm the compat superpower AS the v2 client would: verdict against the current (v1) law.
+        final before = await evo.checkCompat({'lawHash': v2Hash}, v2Requirement);
+        expect(before, isNotNull);
+        expect(before!.matches, isFalse, reason: 'the workspace still runs v1');
+        expect(before.has('setMood'), isFalse,
+            reason: 'the v2-only directive is dark before the law lands');
+
+        // Subscribe BOTH reactive surfaces before the deploy.
+        final compatStream = evo.watchCompatibility(v2Requirement).asBroadcastStream();
+        final lawChanged = evo.onLawChanged.asBroadcastStream();
+        final firstVerdict = await _firstWhere(
+            compatStream, (v) => v.containsKey('ok'), 'watchCompatibility first snapshot');
+        expect(firstVerdict['ok'], isFalse,
+            reason: 'v2 requirement vs the v1 offer must not verify (setMood missing)');
+        expect(firstVerdict['offerKnown'], isTrue);
+
+        final lawEvent = _firstWhere(
+            lawChanged, (c) => c.has('setMood'), 'onLawChanged after the v2 install',
+            const Duration(seconds: 60));
+        final okVerdict = _firstWhere(
+            compatStream, (v) => v['ok'] == true, 'watchCompatibility after the v2 install',
+            const Duration(seconds: 60));
+
+        // THE EVOLVE: install v2 in-session (the same install lane the deploy endpoint drives).
+        await evo.offerOutcome(
+          domain: 'nomos',
+          directiveId: 'installDomain',
+          payload: {
+            'domainHash': v2Hash,
+            'packageUsda': v2Usda,
+            'installedBy': 'watch-surfaces-test',
+            'dependencies': <Object?>[],
+            'finalizers': <Object?>[],
+          },
+          domainHash: harness.frameworkHash,
+        );
+
+        final changed = await lawEvent;
+        expect(changed.has('setMood'), isTrue, reason: 'the dark member lit up');
+        expect(changed.verdict, 'compatible');
+        expect((await okVerdict)['ok'], isTrue);
+        // The evolved law is live: the ADDED directive works on the era-1 row immediately,
+        // and the era-1 row reads back under the NEW label lineage.
+        final rows = await evo.query('sitesByName', {'name': 'era-1-site'});
+        expect(rows, hasLength(1));
+        final siteId = (rows.single['id'] ?? '').toString();
+        await evo.offerOutcome(
+          domain: 'evo',
+          directiveId: 'setMood',
+          payload: {'siteId': siteId, 'mood': 'thriving'},
+          domainHash: v2Hash,
+        );
+        final after = await evo.queryById(siteId);
+        expect(((after.single['data'] as Map)['mood']), 'thriving');
+      });
+
+      // ── LEG 3: watchActivity — `.activity()`-declared directives stream as activity rows. ──
+      await _leg('leg 3: watchActivity streams declared activity rows', () async {
+        final acts = harness.session('acts');
+        final actsHash = harness.lawHashes('acts').first;
+        final stream = acts.watchActivity().asBroadcastStream();
+        final rowsWithSite = _firstWhere(
+            stream,
+            (rows) => rows
+                .whereType<Map>()
+                .any((r) => r['directiveId'] == 'createSite' && r['domain'] == 'estate'),
+            'watchActivity emission carrying the createSite row');
+        await acts.offerOutcome(
+          domain: 'estate',
+          directiveId: 'createSite',
+          payload: {
+            'name': 'Boiler House',
+            'createdAt': DateTime.now().toUtc().toIso8601String()
+          },
+          actor: 'user:ada',
+          domainHash: actsHash,
+        );
+        final rows = await rowsWithSite;
+        final row = rows
+            .whereType<Map>()
+            .firstWhere((r) => r['directiveId'] == 'createSite')
+            .cast<String, Object?>();
+        expect(row['domain'], 'estate');
+        expect(row['intentId'], isNotNull);
+        expect(row['occurredAt'], isNotNull);
+        expect(((row['payload'] as Map?) ?? const {})['name'], 'Boiler House',
+            reason: 'the activity row carries the DECODED directive payload');
+        // The pull surface agrees with the stream (activityLog is the same read).
+        final log = await acts.activityLog();
+        expect(log.any((r) => r['directiveId'] == 'createSite'), isTrue);
+      });
+    } finally {
+      await harness.dispose().timeout(const Duration(seconds: 30),
+          onTimeout: () => throw StateError('harness disposal hung'));
+    }
+  }, timeout: const Timeout(Duration(minutes: 8)));
+}

package/package.json

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

@@ -231,6 +231,17 @@ export interface AggregateHandle<
    * aggregate is `visibility: requires(cap)` (the scope) and its driver is Lww-class.
    */
   readonly encryptedFields?: string[];
+  /**
+   * ATTRIBUTED READS (architecture/field_provenance.md) — the STORED field names whose
+   * folded values keep AUTHOR PROVENANCE (`.attributed()` per field, or the aggregate
+   * option `{ attributed: true }` covering every eligible Lww-class scalar), SORTED.
+   * PRESENT only when ≥1 field is attributed; OMITTED otherwise (an unattributed
+   * aggregate is byte-identical, and the `nomosAttributedGate` era key is likewise
+   * omitted). The wire schema carries each such field's driver WRAPPED as
+   * `{"Attributed": <inner>}` — a LAW change (the #58 evolve gate applies); the value
+   * semantics are the inner driver's exactly.
+   */
+  readonly attributedFields?: string[];
   /**
    * THE `.meta()` FIELDS (secure-by-default) — the STORED field names marked `.meta()` (plaintext
    * metadata, the indexable opt-out on an owned aggregate), SORTED. PRESENT only when ≥1; OMITTED
@@ -272,7 +283,7 @@ const DART_TYPE_NAME_RE = /^[A-Z][A-Za-z0-9_]*$/;
 export function aggregate<const Id extends string, F extends Record<string, Field>>(
   id: Id,
   fields: F,
-  opts?: { invariant?: AggregateInvariantFn; invariantDeclassify?: string; cap?: number; visibility?: ReadVisibility; global?: boolean },
+  opts?: { invariant?: AggregateInvariantFn; invariantDeclassify?: string; cap?: number; visibility?: ReadVisibility; global?: boolean; attributed?: boolean },
 ): AggregateHandle<Id, F> & AudienceMethods<Id, F> {
   const { stored, hasMany } = partitionFields(fields);
   // FOREIGN-REF SIBLING CHECK (pain point #4): a `t.foreignRef({ workspace, target })` field names a
@@ -345,6 +356,68 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
     }
   }
 
+  // ATTRIBUTED READS (architecture/field_provenance.md): `.attributed()` per field, or the
+  // aggregate-level `{ attributed: true }` covering every ELIGIBLE field. Eligibility =
+  // an Lww-class SCALAR (Lww / LwwCausal / LwwBy — the wrapper's value semantics are the
+  // inner driver's, and "who wrote the current value" only means something for a
+  // wholesale-replaced scalar). A structural CRDT (set/map/counter/position/list) has no
+  // single last author; a `Surfaced` field ALREADY carries per-observation authors (the
+  // retention rung above this) — attributing it is refused as redundant. Per-field
+  // `.attributed()` on an ineligible field THROWS (you asked for something impossible);
+  // the aggregate-level flag SKIPS ineligible fields silently (it means "everything that
+  // can be attributed"). Each attributed field's wire driver is wrapped
+  // `{"Attributed": <inner>}` — the law-era mechanism (old kernels refuse it cleanly;
+  // unattributed fields/domains stay byte-identical).
+  const LWW_CLASS_KINDS = new Set(["Lww", "LwwCausal", "LwwBy"]);
+  const attributableDriver = (f: Field) => LWW_CLASS_KINDS.has((f.driver as { kind?: string }).kind ?? "");
+  const attributableKind = (f: Field) =>
+    f.kind !== "set" && f.kind !== "map" && f.kind !== "counter" && f.kind !== "position";
+  for (const [name, f] of Object.entries(stored)) {
+    const field = f as Field;
+    if (field.isAttributed !== true) continue;
+    if ((field.driver as { kind?: string }).kind === "Surfaced") {
+      throw new Error(
+        `aggregate '${id}': field '${name}' is .attributed() but its driver is Surfaced(...) — a Surfaced field already retains per-observation authors (attributed → surfaced is a ladder, not a stack); drop .attributed()`,
+      );
+    }
+    if (!attributableDriver(field) || !attributableKind(field)) {
+      throw new Error(
+        `aggregate '${id}': field '${name}' is .attributed() but attribution needs an Lww-class SCALAR (Lww/LwwCausal/LwwBy) — a '${field.kind}' field under '${(field.driver as { kind?: string }).kind}' has no single last author`,
+      );
+    }
+  }
+  const attributedFields = Object.entries(stored)
+    .filter(([, f]) => {
+      const field = f as Field;
+      if (field.isAttributed === true) return true;
+      return (
+        opts?.attributed === true &&
+        attributableDriver(field) &&
+        attributableKind(field) &&
+        (field.driver as { kind?: string }).kind !== "Surfaced"
+      );
+    })
+    .map(([name]) => name)
+    .sort();
+  for (const name of attributedFields) {
+    const f = stored[name] as Field;
+    // Clone by PROPERTY DESCRIPTORS (not spread): a lazy `t.ref(() => Agg)` field
+    // exposes `refAggregateId` as a memoized getter that must NOT be forced at
+    // aggregate() time (module consts may not have initialized yet); a spread would
+    // evaluate it. The clone keeps every descriptor and swaps only the driver.
+    const clone = Object.defineProperties(
+      {},
+      Object.getOwnPropertyDescriptors(f),
+    ) as Field;
+    Object.defineProperty(clone, "driver", {
+      value: { kind: "Attributed", inner: f.driver },
+      enumerable: true,
+      configurable: true,
+      writable: false,
+    });
+    (stored as Record<string, Field>)[name] = clone;
+  }
+
   // The `.meta()` fields (plaintext-metadata opt-out on owned aggregates) — recorded for the compiler.
   const metaFields = Object.entries(stored)
     .filter(([, f]) => (f as Field).isMeta === true)
@@ -399,6 +472,7 @@ export function aggregate<const Id extends string, F extends Record<string, Fiel
     ...(opts?.cap !== undefined ? { cap: opts.cap } : {}),
     ...(opts?.global === true ? { global: true } : {}),
     ...(encryptedFields.length > 0 ? { encryptedFields } : {}),
+    ...(attributedFields.length > 0 ? { attributedFields } : {}),
     ...(metaFields.length > 0 ? { metaFields } : {}),
   };
 

package/src/codegen_dart.ts

@@ -1249,6 +1249,10 @@ function emitAggregate(
     refIdClassForAggregate,
     ownIdFields,
   );
+  // ATTRIBUTED READS (field_provenance.md): the `.attributed()` field names — drives the
+  // `$provenance` map + per-field `<field>Provenance` getters + `lastAuthors`. Empty for
+  // an unattributed aggregate ⇒ the generated class is byte-identical to before.
+  const attributedFields = (agg as { attributedFields?: readonly string[] }).attributedFields ?? [];
 
   // GAP 2 — the kernel aggregate id. The projection strips the reserved `__id`/
   // `__type` from each row's flat `data`; the row-level `id` (== the kernel aggregate
@@ -1271,6 +1275,15 @@ function emitAggregate(
     `  /// [NomosRef] (\`nomos://<workspace>/<type>/<id>\`) — composed at decode from the session workspace +`,
     `  /// the row's type/id. Workspace is '' when decoded off the bare bridge (the client accessors fill it).`,
     `  final NomosRef ref;`,
+    ...(attributedFields.length > 0
+      ? [
+          `  /// ATTRIBUTED READS (field_provenance.md): per-field author provenance for the`,
+          `  /// \`.attributed()\` fields, decoded from the row's reserved \`__prov\` map.`,
+          `  /// Metadata beside the values — excluded from ==/hashCode. Prefer the typed`,
+          `  /// \`<field>Provenance\` getters / [lastAuthors] below.`,
+          `  final Map<String, FieldProvenance> \$provenance;`,
+        ]
+      : []),
     ...specs.flatMap((s) => {
       const doc = s.nullReason !== undefined ? [`  /// null semantic: ${s.nullReason}`] : [];
       // SURFACED MERGE CONFLICTS: the field reads as the plain scalar, or [SurfacedPending]
@@ -1291,6 +1304,7 @@ function emitAggregate(
   const ctorParams = [
     `    this.aggregateId = const ${idType}.fromRow(''),`,
     `    this.ref = const NomosRef(workspace: '', type: '${agg.id}', id: ''),`,
+    ...(attributedFields.length > 0 ? [`    this.\$provenance = const {},`] : []),
     ...specs.map(
       // A required scalar stays `required`; an optional scalar OR a collection is not
       // `required` (an absent optional scalar is null; an absent collection is empty).
@@ -1313,6 +1327,9 @@ function emitAggregate(
   const parseLines = [
     `      aggregateId: ${aggregateIdFromRowExpr(agg.id, "id")},`,
     `      ref: NomosRef(workspace: workspace, type: type.isEmpty ? '${agg.id}' : type, id: id),`,
+    ...(attributedFields.length > 0
+      ? [`      \$provenance: FieldProvenance.mapFromJson(data['__prov']),`]
+      : []),
     ...specs.map((s) =>
       s.surfaced === true
         ? `      ${s.name}: SurfacedValue.decode<${s.dartType}>(data, '${s.wireName}', ${slotDecodeCallback(s, "aggregate")}),`
@@ -1376,6 +1393,25 @@ function emitAggregate(
     `    );`,
     `  }`,
     ``,
+    ...(attributedFields.length > 0
+      ? [
+          [
+            ...attributedFields.flatMap((f) => [
+              `  /// Author provenance of [${f}] (who wrote the current value + whether a`,
+              `  /// concurrent competing write was auto-merged away). Null when the field`,
+              `  /// has no folded provenance yet (pre-attribution rows).`,
+              `  FieldProvenance? get ${f}Provenance => \$provenance['${f}'];`,
+            ]),
+            `  /// The last verified author per attributed field (fields with an unknown`,
+            `  /// author are omitted) — the "who last touched this row" convenience.`,
+            `  Map<String, String> get lastAuthors => {`,
+            `        for (final e in \$provenance.entries)`,
+            `          if (e.value.author != null) e.key: e.value.author!,`,
+            `      };`,
+          ].join("\n"),
+          ``,
+        ]
+      : []),
     `  @override`,
     `  bool operator ==(Object other) =>`,
     `      other is ${className} &&`,
@@ -2241,6 +2277,64 @@ export function generateDartActivityRegistry(entries: readonly PackageActivityEn
 
 /** True when ANY aggregate field in the module is `t.evidence()` — gates emitting the
  * shared [emitEvidenceRefClass] once. */
+/** Does any aggregate in this module declare `.attributed()` fields (field_provenance.md)?
+ * Gates the one-per-file [FieldProvenance] class + the per-aggregate provenance surface —
+ * a provenance-free module's generated Dart is byte-identical to before the feature. */
+function moduleUsesAttribution(aggregates: readonly AggregateHandle[]): boolean {
+  return aggregates.some(
+    (a) => ((a as { attributedFields?: readonly string[] }).attributedFields ?? []).length > 0,
+  );
+}
+
+/** The shared attributed-reads provenance class (architecture/field_provenance.md) —
+ * emitted ONCE per generated file when any aggregate declares `.attributed()` fields
+ * (the EvidenceRef discipline). A typed read of the projection row's reserved
+ * `__prov` map entry: the verified author of the field's CURRENT value + whether an
+ * auto-merge discarded a concurrent competing write since it landed. */
+function emitFieldProvenanceClass(): string {
+  return [
+    `/// Per-field AUTHOR PROVENANCE (attributed reads — field_provenance.md). Read off`,
+    `/// an aggregate's \`<field>Provenance\` getter (generated for \`.attributed()\``,
+    `/// fields only): who wrote the field's CURRENT value, and whether an auto-merge`,
+    `/// discarded a concurrent competing write since it landed (\`wasContested\` —`,
+    `/// escalate the field to Surfaced(...) law if you need the discarded values).`,
+    `class FieldProvenance {`,
+    `  /// The verified authoring principal of the current value; null when unknown`,
+    `  /// (an anonymous or pre-attribution-era write) — never a fabrication.`,
+    `  final String? author;`,
+    `  /// Whether an auto-merge discarded a concurrent competing write since the`,
+    `  /// current value landed (reset by every causally-superseding write).`,
+    `  final bool wasContested;`,
+    ``,
+    `  const FieldProvenance({this.author, this.wasContested = false});`,
+    ``,
+    `  /// Read one entry of the row's \`__prov\` map (\`{author, wasContested}\`).`,
+    `  factory FieldProvenance.fromJson(Map<String, Object?> m) => FieldProvenance(`,
+    `        author: m['author'] as String?,`,
+    `        wasContested: m['wasContested'] == true,`,
+    `      );`,
+    ``,
+    `  /// Decode a row's whole \`__prov\` map (empty when the row carries none).`,
+    `  static Map<String, FieldProvenance> mapFromJson(Object? prov) {`,
+    `    if (prov is! Map) return const {};`,
+    `    return {`,
+    `      for (final e in prov.entries)`,
+    `        if (e.value is Map)`,
+    `          e.key as String:`,
+    `              FieldProvenance.fromJson((e.value as Map).cast<String, Object?>()),`,
+    `    };`,
+    `  }`,
+    ``,
+    `  @override`,
+    `  bool operator ==(Object other) =>`,
+    `      other is FieldProvenance && other.author == author && other.wasContested == wasContested;`,
+    ``,
+    `  @override`,
+    `  int get hashCode => Object.hash(author, wasContested);`,
+    `}`,
+  ].join("\n");
+}
+
 function moduleUsesEvidence(aggregates: readonly AggregateHandle[]): boolean {
   return aggregates.some((a) =>
     Object.values(a.fields as Record<string, Field>).some((f) => f.kind === "evidence"),
@@ -4444,6 +4538,13 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
           ``,
         ]
       : []),
+    ...(moduleUsesAttribution(localAggregates)
+      ? [
+          `// ---- attributed reads (per-field author provenance; field_provenance.md) ----`,
+          emitFieldProvenanceClass(),
+          ``,
+        ]
+      : []),
     ...(voBlock !== ""
       ? [
           `// ---- value objects (named composable json-object leaves; value_object.ts) ----`,