@githolon/dsl 0.1.0 → 0.1.1

package/dart/lib/src/subscriptions.dart

@@ -0,0 +1,549 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded QuickJS engine},
+// byte-identical everywhere. Host JS is only the bridge; domain JS runs inside
+// GitHolon, never as a second execution path.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/// The READ half of the client boundary: typed, reactive subscriptions.
+///
+/// END-STATE (the "dispatch(intent) purge", Jack 2026-06-01): the app's ONLY
+/// Nomos surface is `dispatch(intent)` (write — see `dispatch.dart`) + TYPED
+/// PUB/SUB SUBSCRIPTIONS (read — here + the generated per-domain accessors). The
+/// app reads ONLY through generated typed accessors (`watchSites()`,
+/// `watchSite(id)`, indexed-field queries → typed results); it never hand-writes a
+/// `query_id`, never decodes a `{type,id,data}` row, never folds a workspace.
+///
+/// This file is HAND-WRITTEN and domain-AGNOSTIC (declared ONCE, here): it maps
+/// onto the GitHolon indexed read surface (`query(query_id, params_json)` +
+/// `query_by_id(aggregate_id)`). The generated per-domain code supplies the typed
+/// `fromJson` + the `query_id`; this file turns the synchronous read closure into
+/// the reactive [Stream] the app subscribes to. It invents NO alternate read path.
+///
+/// READ-MODEL ROW SHAPE: both `query()` and `query_by_id()` return a JSON ARRAY of
+/// `{type, id, data}` rows. `data` is the FLAT,
+/// already-decoded field map the projection projects (e.g.
+/// `{"name":"HQ","createdAt":1000,"location":{...}}`) — NOT the `{field:{value,
+/// stamp}}` projection-internal shape. The generated `fromJson` parses THIS flat
+/// map (see `codegen_dart.ts`'s flat-projection realignment).
+library;
+
+import 'dart:async';
+import 'dart:convert';
+
+// ───────────────────────────── the kernel read seams ─────────────────────────────
+
+/// The kernel INDEXED-QUERY read seam: the GitHolon `query` signature, as a
+/// function type. Returns the matching aggregates as a JSON array of `{type, id,
+/// data}` rows (O(matches), never a workspace scan — #140 READ-CLOSURE).
+///
+/// `subscriptions.dart` takes this (rather than importing a host client) so the
+/// generated `nomos_dsl` package stays host-agnostic. The app threads `client.query`
+/// in. `paramsJson` is a JSON object carrying the
+/// key field + value, e.g. `{"estateId":"e-1"}`.
+typedef Queryer = String Function(String queryId, String paramsJson);
+
+/// The kernel PRIMARY-KEY read seam: the GitHolon `queryById` signature, as
+/// a function type. Reads ONE aggregate by its kernel aggregate id and returns the
+/// SAME `[{type,id,data}, …]` array shape (carrying the single matched aggregate,
+/// or an EMPTY array when no aggregate with that id has been folded). Resolves both
+/// an unbound singleton (keyed by its type, e.g. `EstateAggregate`) and an
+/// instance-bound aggregate (by its id).
+typedef QueryByIder = String Function(String aggregateId);
+
+/// The kernel MAINTAINED-COUNT read seam: the GitHolon `count` signature,
+/// as a function type. Reads ONE maintained counter (O(1) PK lookup in the `counts`
+/// table — never a scan). `countId` is the declared count's canonical id; `groupKey`
+/// is the value of the group-by field for this partition, or `''` for a grand total.
+/// Returns the current count (0 when no entry exists for this group).
+///
+/// Slice 1 — this seam is NEW: the generated per-domain accessors
+/// (`watchPublishedCount`, `readPublishedCount`, …) forward here. The app never
+/// hand-types a `countId` or a `groupKey` — that is the generated accessor's job.
+typedef Counter = int Function(String countId, String groupKey);
+
+/// The kernel MAINTAINED-SUM read seam: the GitHolon `sum` signature,
+/// as a function type. Reads ONE maintained sum (O(1) PK lookup in the `sums`
+/// table — never a scan). `sumId` is the declared sum's canonical id; `groupKey`
+/// is the value of the group-by field for this partition, or `''` for a grand total.
+/// Returns the current total (0 when no entry exists for this group).
+///
+/// SUM-OF-0 CAVEAT: a group whose total reaches 0 is pruned; the return value 0
+/// is indistinguishable from absent (acceptable for Slice 1 — Slice 2 adds `exists`).
+typedef Summer = int Function(String sumId, String groupKey);
+
+/// A "projection changed" tick: fires (any value) whenever a write may have
+/// advanced the projection, so the subscription re-runs its indexed read. The
+/// `query()`/`query_by_id()` closures are SYNCHRONOUS point-in-time reads; this tick is what
+/// makes a typed accessor REACTIVE. The app threads its existing post-`dispatch`
+/// invalidation signal in here (today the runtime's ~750ms projection poll / the
+/// write-completion broadcast). A read with no live tick is a one-shot current read.
+typedef ReadTick = Stream<void>;
+
+// ───────────────────────────── the typed-read engine ─────────────────────────────
+
+/// The bundle of kernel read seams + the reactivity tick the app threads in ONCE.
+/// Every generated per-domain accessor takes a [NomosReads] and is a thin typed
+/// wrapper over it — so the app constructs this one object (from its GitHolon port)
+/// and the entire generated read API hangs off it.
+class NomosReads {
+  /// The indexed-query seam (`client.query`).
+  final Queryer query;
+
+  /// The primary-key seam (`client.queryById`).
+  final QueryByIder queryById;
+
+  /// The maintained-count seam (`client.count`). Reads ONE maintained counter
+  /// by `(countId, groupKey)` — O(1) PK lookup, never a scan. Threads in from the
+  /// app's host client (Slice 1). When null, `readCount`/`watchCount` return 0
+  /// (no count seam provided — useful in tests that don't exercise counts).
+  final Counter? counter;
+
+  /// The maintained-sum seam (`client.sum`). Reads ONE maintained sum by
+  /// `(sumId, groupKey)` — O(1) PK lookup, never a scan. Threads in from the
+  /// app's host client (Slice 1). When null, `readSum`/`watchSum` return 0.
+  final Summer? summer;
+
+  /// The "projection changed" tick. When null, every accessor is a ONE-SHOT read
+  /// (a single current value, no further updates) — used in tests / pure snapshots.
+  final ReadTick? tick;
+
+  const NomosReads({
+    required this.query,
+    required this.queryById,
+    this.counter,
+    this.summer,
+    this.tick,
+  });
+
+  /// Decode a `[{type,id,data}, …]` rows JSON array into the typed aggregate list,
+  /// applying [fromJson] to each row's FLAT `data` map AND its row `id`. Skips rows
+  /// whose `data` is not an object (defensive; the projection always emits an object).
+  ///
+  /// GAP 2: the row `id` (the kernel aggregate id — e.g. the siteId) is threaded as
+  /// [fromJson]'s second arg. The projection STRIPS the reserved `__id`/`__type` from
+  /// each row's `data`, so the row-level `id` is the SOLE carrier of the aggregate id;
+  /// passing it here surfaces it on the generated aggregate from BOTH the indexed
+  /// accessors and the by-id accessors (both funnel through this one decoder).
+  static List<T> decodeRows<T>(
+    String rowsJson,
+    T Function(Map<String, dynamic> data, String id) fromJson,
+  ) {
+    final decoded = jsonDecode(rowsJson);
+    if (decoded is! List) {
+      throw FormatException('read rows must be a JSON array, got ${decoded.runtimeType}');
+    }
+    final out = <T>[];
+    for (final row in decoded) {
+      if (row is! Map<String, dynamic>) continue;
+      final data = row['data'];
+      if (data is! Map<String, dynamic>) continue;
+      final rawId = row['id'];
+      final id = rawId is String ? rawId : (rawId?.toString() ?? '');
+      out.add(fromJson(data, id));
+    }
+    return out;
+  }
+
+  // ---- one-shot (current-value) reads ----
+
+  /// Run a registered indexed [queryId] with [params] NOW and return the typed
+  /// matches (O(matches)). The generated accessor supplies [queryId]/[params]/
+  /// [fromJson]; the app never hand-types them.
+  List<T> readQuery<T>(
+    String queryId,
+    Map<String, Object?> params,
+    T Function(Map<String, dynamic> data, String id) fromJson,
+  ) =>
+      decodeRows(query(queryId, jsonEncode(params)), fromJson);
+
+  /// Read ONE aggregate by its kernel [aggregateId] NOW (primary-key lookup),
+  /// returning the typed value or `null` when no such aggregate has been folded.
+  T? readById<T>(
+    String aggregateId,
+    T Function(Map<String, dynamic> data, String id) fromJson,
+  ) {
+    final rows = decodeRows(queryById(aggregateId), fromJson);
+    return rows.isEmpty ? null : rows.first;
+  }
+
+  // ---- reactive subscriptions ----
+
+  /// Subscribe to a registered indexed [queryId]/[params] as a [Stream] of typed
+  /// match lists. Emits the current matches immediately, then re-emits on every
+  /// [tick] (a write may have changed the matches). When [tick] is null this is a
+  /// single-element stream (the current value). Consecutive identical results are
+  /// NOT deduped here — the app's selector layer (Riverpod) handles distinctness.
+  Stream<List<T>> watchQuery<T>(
+    String queryId,
+    Map<String, Object?> params,
+    T Function(Map<String, dynamic> data, String id) fromJson,
+  ) =>
+      _reactive(() => readQuery(queryId, params, fromJson));
+
+  /// Subscribe to ONE aggregate by [aggregateId] as a `Stream<T?>` (null until/
+  /// unless it has been folded). Emits the current value immediately, then re-emits
+  /// on every [tick].
+  Stream<T?> watchById<T>(
+    String aggregateId,
+    T Function(Map<String, dynamic> data, String id) fromJson,
+  ) =>
+      _reactive(() => readById(aggregateId, fromJson));
+
+  // ---- maintained count/sum seams (Slice 1) ----
+
+  /// Read the current maintained counter for [countId] + [groupKey] NOW. Returns 0
+  /// when no entry exists (either truly zero, or no group for this key). O(1) PK
+  /// lookup in the `counts` table — never a scan. Returns 0 when [counter] is null
+  /// (no count seam provided — useful in tests).
+  int readCount(String countId, String groupKey) => counter?.call(countId, groupKey) ?? 0;
+
+  /// Subscribe to the maintained counter for [countId] + [groupKey] as a
+  /// `Stream<int>`. Emits the current count immediately, then re-emits on every
+  /// [tick]. Returns 0 when [counter] is null.
+  Stream<int> watchCount(String countId, String groupKey) =>
+      _reactive(() => readCount(countId, groupKey));
+
+  /// Read the current maintained sum for [sumId] + [groupKey] NOW. Returns 0 when
+  /// no entry exists (a group pruned at 0 is indistinguishable from absent —
+  /// documented Slice-1 caveat). O(1) PK lookup in the `sums` table — never a scan.
+  /// Returns 0 when [summer] is null.
+  int readSum(String sumId, String groupKey) => summer?.call(sumId, groupKey) ?? 0;
+
+  /// Subscribe to the maintained sum for [sumId] + [groupKey] as a `Stream<int>`.
+  /// Emits the current total immediately, then re-emits on every [tick]. Returns 0
+  /// when [summer] is null.
+  Stream<int> watchSum(String sumId, String groupKey) =>
+      _reactive(() => readSum(sumId, groupKey));
+
+  /// Turn a synchronous point-in-time read [read] into a reactive [Stream]: emit
+  /// once now, then once per [tick]. With no tick, a one-shot single-element stream.
+  Stream<R> _reactive<R>(R Function() read) {
+    final tick = this.tick;
+    if (tick == null) {
+      return Stream<R>.value(read());
+    }
+    late StreamController<R> controller;
+    StreamSubscription<void>? sub;
+    void emit() {
+      try {
+        controller.add(read());
+      } catch (e, st) {
+        controller.addError(e, st);
+      }
+    }
+
+    controller = StreamController<R>(
+      onListen: () {
+        emit(); // current value first
+        sub = tick.listen((_) => emit());
+      },
+      onCancel: () async {
+        await sub?.cancel();
+        sub = null;
+      },
+    );
+    return controller.stream;
+  }
+}
+
+// ───────────────────────────── flat-projection field readers ─────────────────────────────
+//
+// The projection's `data` map is FLAT and already-decoded (the Rust `decode_field`
+// has parsed each kernel `Value` back to JSON). These tolerant readers are what the
+// GENERATED `fromJson` calls per field — they realign the typed aggregate onto that
+// flat shape and coerce defensively (the same field can arrive as a bare scalar or,
+// for a `json`-kind field, as a decoded container that must be re-stringified to the
+// aggregate's `String` type).
+
+/// A field that must be present in the flat `data` map. Throws a [FormatException]
+/// naming the aggregate + field when absent (parity with the old `{field:{value}}`
+/// reader's missing-field throw).
+Object _required(Map<String, dynamic> data, String aggregate, String field) {
+  if (!data.containsKey(field) || data[field] == null) {
+    throw FormatException('$aggregate: missing field $field');
+  }
+  return data[field] as Object;
+}
+
+/// Read a `string`/`ref`-kind field as a Dart [String]. The projection emits it as
+/// a bare JSON string; a non-string scalar is `toString`'d defensively.
+String readStr(Map<String, dynamic> data, String aggregate, String field) {
+  final v = _required(data, aggregate, field);
+  return v is String ? v : v.toString();
+}
+
+/// Read an `int`-kind field as a Dart [int] (the projection emits a JSON number).
+int readInt(Map<String, dynamic> data, String aggregate, String field) {
+  final v = _required(data, aggregate, field);
+  if (v is num) return v.toInt();
+  if (v is String) {
+    final n = int.tryParse(v);
+    if (n != null) return n;
+  }
+  throw FormatException('$aggregate.$field: expected int, got ${v.runtimeType}');
+}
+
+/// Read a `set`-kind field as a `Set<String>` (the projection emits a JSON array).
+Set<String> readSet(Map<String, dynamic> data, String aggregate, String field) {
+  final v = _required(data, aggregate, field);
+  if (v is List) return v.map((e) => e.toString()).toSet();
+  throw FormatException('$aggregate.$field: expected a set/array, got ${v.runtimeType}');
+}
+
+/// Read a `map`-kind field as a `Map<String, String>`. The projection may emit it
+/// as a flat `{k:v}` object (the loss-less author path) OR — if it folded through a
+/// kernel `Value::Map` — as the structural `{"Map":{k:{value:{Str:v},…}}}` serde
+/// form; both are reduced to `{k:v}` so the aggregate's typed map is stable.
+Map<String, String> readStrMap(Map<String, dynamic> data, String aggregate, String field) {
+  final v = _required(data, aggregate, field);
+  if (v is Map) {
+    // Structural kernel `Value::Map` form: `{"Map": {k: {value:{Str:..},stamp:..}}}`.
+    final inner = v.length == 1 && v.containsKey('Map') ? v['Map'] : v;
+    if (inner is Map) {
+      final out = <String, String>{};
+      inner.forEach((k, val) {
+        out[k.toString()] = _flattenMapValue(val);
+      });
+      return out;
+    }
+  }
+  throw FormatException('$aggregate.$field: expected a map/object, got ${v.runtimeType}');
+}
+
+/// Reduce one map entry value to a String, peeling the kernel `{value:{Str:..}}`
+/// wrapper when present (structural form) or `toString`-ing a bare scalar.
+String _flattenMapValue(Object? val) {
+  if (val is String) return val;
+  if (val is Map) {
+    final value = val['value'];
+    if (value is Map && value.containsKey('Str')) return value['Str'].toString();
+    if (value is Map && value.containsKey('Int')) return value['Int'].toString();
+  }
+  return val.toString();
+}
+
+/// Read an enum-kind field's wire string from the flat map, applying the generated
+/// enum's [fromWire]. The projection emits the bare wire string.
+E readEnum<E>(
+  Map<String, dynamic> data,
+  String aggregate,
+  String field,
+  E Function(String wire) fromWire,
+) =>
+    fromWire(readStr(data, aggregate, field));
+
+/// Read a `json`-kind field as the Dart [String] the aggregate types it as. The
+/// projection's `decode_field` may have PARSED the stored JSON string back into a
+/// container (object/array); re-stringify so the aggregate keeps a stable `String`
+/// (parity with the kernel-stored `Value::Str(<json>)`). A bare string is returned
+/// as-is.
+String readJsonStr(Map<String, dynamic> data, String aggregate, String field) {
+  final v = _required(data, aggregate, field);
+  if (v is String) return v;
+  return jsonEncode(v);
+}
+
+/// Read a `json`-kind value-object leaf as a structured `Map<String, Object?>` for
+/// generated read models, as opposed to [readJsonStr] which preserves the encoded
+/// string form. The Rust read engine has already decoded the stored
+/// `Value::Str(<json>)` back into structured JSON (`manifest.rs` `decode_json_leaf`), so a
+/// `location` arrives as `{countryCode:…, geoPoint:{…}}` — NOT a JSON string. This reader
+/// surfaces that decoded object directly:
+///   * an already-decoded [Map] (the flat projection) → its `Map<String, Object?>` view;
+///   * a still-encoded JSON string (a path that did not pre-parse) → `jsonDecode`d, and
+///     KEPT only when it decodes to an OBJECT.
+/// A value-object leaf that is NOT an object (a bare scalar / array) is a malformed
+/// value-object for a typed projection field, so it throws a [FormatException] (parity
+/// with the strict-decode contract for a must-be-folded field — never silently coerced).
+Map<String, Object?> readJsonObject(
+    Map<String, dynamic> data, String aggregate, String field) {
+  final v = _required(data, aggregate, field);
+  final obj = _asJsonObject(v);
+  if (obj == null) {
+    throw FormatException(
+        '$aggregate.$field: expected a json object value-object, got ${v.runtimeType}');
+  }
+  return obj;
+}
+
+/// Read an OPTIONAL `json`-kind value-object leaf as a structured `Map<String, Object?>`,
+/// or `null` when absent (a freshly-folded aggregate need not have folded it). A PRESENT
+/// value is decoded exactly as [readJsonObject] (a present-but-non-object value still
+/// throws — only ABSENCE is tolerated).
+Map<String, Object?>? readJsonObjectOrNull(
+    Map<String, dynamic> data, String aggregate, String field) {
+  final v = data[field];
+  if (v == null) return null;
+  final obj = _asJsonObject(v);
+  if (obj == null) {
+    throw FormatException(
+        '$aggregate.$field: expected a json object value-object, got ${v.runtimeType}');
+  }
+  return obj;
+}
+
+/// Coerce an already-decoded projection value to a `Map<String, Object?>` JSON object,
+/// or `null` when it is not an object. Handles BOTH the decoded-[Map] projection form and
+/// a still-encoded JSON string (decoded, kept only if it is itself an object).
+Map<String, Object?>? _asJsonObject(Object? v) {
+  if (v is Map) {
+    return v.map((k, val) => MapEntry(k.toString(), val));
+  }
+  if (v is String) {
+    final decoded = _maybeJsonDecode(v);
+    if (decoded is Map) {
+      return decoded.map((k, val) => MapEntry(k.toString(), val));
+    }
+  }
+  return null;
+}
+
+/// Read a PERMISSIVE `json`-kind leaf (a plain `t.json()` whose decoded shape is
+/// unknown/non-object — e.g. a double/bool/list authored as a JSON leaf, since the
+/// kernel `Value` is Str|Int only) as the read engine's decoded value AS-IS, or `null`
+/// when absent. The generated projection surface for a plain `t.json()` field
+/// (typed `Object?`), as opposed to [readJsonObject] (the strict `t.jsonObject()` surface,
+/// which THROWS on a non-object). NEVER throws on shape: it surfaces whatever the engine
+/// decoded —
+///   * an already-decoded container/scalar (the flat projection) → returned verbatim;
+///   * a still-encoded JSON string → `jsonDecode`d when it parses, else the string as-is.
+/// This is the non-object/ambiguous counterpart to [readJsonObject]: a `scaleX` double
+/// or an `estimatedCost` value-object surfaces as its real decoded value, never coerced
+/// to a map and never thrown.
+Object? readJsonValueOrNull(Map<String, dynamic> data, String field) {
+  final v = data[field];
+  if (v == null) return null;
+  return _maybeJsonDecode(v);
+}
+
+// ───────────────────────────── optional / empty-defaulting readers ──────────────
+//
+// GAP 1: a freshly-created aggregate folds only the fields its `.creates` directive
+// `.plan()` emits — a `.optional()` SCALAR (e.g. `description`/`siteType`) or a
+// COLLECTION (`set`/`map`) it never folded is simply ABSENT from the flat `data`.
+// These readers decode that minimal shape without throwing: an optional scalar reads
+// `null` when absent; a collection reads EMPTY. The generated `fromJson` picks the
+// strict reader for a must-be-folded scalar and one of these for an optional/collection
+// field, deriving the choice from the DSL field schema.
+
+/// Read an OPTIONAL `string`/`ref`-kind field, or `null` when absent. A present
+/// non-string scalar is `toString`'d (parity with [readStr]).
+String? readStrOrNull(Map<String, dynamic> data, String field) {
+  final v = data[field];
+  if (v == null) return null;
+  return v is String ? v : v.toString();
+}
+
+/// Read an OPTIONAL `int`-kind field, or `null` when absent. A present value is
+/// coerced like [readInt]; a present-but-uncoercible value throws (a malformed
+/// fold is still an error — only ABSENCE is tolerated).
+int? readIntOrNull(Map<String, dynamic> data, String aggregate, String field) {
+  final v = data[field];
+  if (v == null) return null;
+  if (v is num) return v.toInt();
+  if (v is String) {
+    final n = int.tryParse(v);
+    if (n != null) return n;
+  }
+  throw FormatException('$aggregate.$field: expected int, got ${v.runtimeType}');
+}
+
+/// Read an OPTIONAL enum-kind field's wire string, or `null` when absent (a present
+/// value still validates against the generated enum via [fromWire]).
+E? readEnumOrNull<E>(
+  Map<String, dynamic> data,
+  String aggregate,
+  String field,
+  E Function(String wire) fromWire,
+) {
+  final wire = readStrOrNull(data, field);
+  return wire == null ? null : fromWire(wire);
+}
+
+/// Read an OPTIONAL `json`-kind field as a [String], or `null` when absent (a present
+/// container is re-stringified like [readJsonStr]).
+String? readJsonStrOrNull(Map<String, dynamic> data, String field) {
+  final v = data[field];
+  if (v == null) return null;
+  if (v is String) return v;
+  return jsonEncode(v);
+}
+
+/// Read a `set`-kind field as a `Set<String>`, defaulting to EMPTY when the flat
+/// `data` lacks it (a freshly-created aggregate need not have folded the set). A
+/// PRESENT-but-non-array value still throws (parity with [readSet]).
+Set<String> readSetOrEmpty(Map<String, dynamic> data, String aggregate, String field) {
+  final v = data[field];
+  if (v == null) return <String>{};
+  if (v is List) return v.map((e) => e.toString()).toSet();
+  throw FormatException('$aggregate.$field: expected a set/array, got ${v.runtimeType}');
+}
+
+/// Read a `map`-kind field as a `Map<String, String>`, defaulting to EMPTY when
+/// absent. A PRESENT value is reduced exactly as [readStrMap] (handling both the flat
+/// `{k:v}` form and the structural kernel `Value::Map` form).
+Map<String, String> readStrMapOrEmpty(Map<String, dynamic> data, String aggregate, String field) {
+  final v = data[field];
+  if (v == null) return <String, String>{};
+  return readStrMap(data, aggregate, field);
+}
+
+/// Read a JSON-VALUED `map`-kind field (`t.map(t.json())`) as a `Map<String, Object?>`,
+/// with each entry value DECODED back to its object. Defaults to EMPTY when absent.
+///
+/// A value-object map (e.g. a site's `customFields`, each entry the canonical
+/// `CustomField.toJson()` written as a JSON string) lowers to a kernel `Value::Map`
+/// whose leaves are `Value::Str(<json>)`. This reader recovers each entry's ORIGINAL
+/// object so a VO's own `fromJson` (e.g. `CustomFieldMap.fromJson`) sees its canonical
+/// nested-map form and round-trips losslessly — unlike [readStrMap], which would
+/// flatten each entry to the raw JSON STRING (forcing the VO into a lossy shorthand
+/// branch). Handles BOTH wire forms: the flat `{k:<object|jsonString>}` projection AND
+/// the structural `{"Map":{k:{value:{Str:<json>},stamp}}}` serde form.
+Map<String, Object?> readJsonMapOrEmpty(
+    Map<String, dynamic> data, String aggregate, String field) {
+  final v = data[field];
+  if (v == null) return <String, Object?>{};
+  if (v is Map) {
+    // Structural kernel `Value::Map` form: `{"Map": {k: {value:{Str:..},stamp:..}}}`.
+    final inner = v.length == 1 && v.containsKey('Map') ? v['Map'] : v;
+    if (inner is Map) {
+      final out = <String, Object?>{};
+      inner.forEach((k, val) {
+        out[k.toString()] = _decodeJsonMapValue(val);
+      });
+      return out;
+    }
+  }
+  throw FormatException('$aggregate.$field: expected a map/object, got ${v.runtimeType}');
+}
+
+/// Decode one JSON-valued map entry to its object: peel the kernel
+/// `{value:{Str:<json>}}` wrapper when present (structural form), then JSON-decode the
+/// resulting string back to its object/list/scalar. A value that is ALREADY a decoded
+/// container (the flat projection re-parsed it) is returned as-is. A bare scalar (int
+/// from a spike path) is returned unchanged.
+Object? _decodeJsonMapValue(Object? val) {
+  if (val is Map && val.containsKey('value')) {
+    final value = val['value'];
+    if (value is Map && value.containsKey('Str')) {
+      return _maybeJsonDecode(value['Str']);
+    }
+    if (value is Map && value.containsKey('Int')) return value['Int'];
+    return value;
+  }
+  return _maybeJsonDecode(val);
+}
+
+/// JSON-decode a String to its object/list; non-strings (already-decoded containers,
+/// numbers) pass through. A String that is not valid JSON is returned verbatim.
+Object? _maybeJsonDecode(Object? v) {
+  if (v is String) {
+    try {
+      return jsonDecode(v);
+    } catch (_) {
+      return v;
+    }
+  }
+  return v;
+}