@githolon/dsl 0.1.0 → 0.1.2

package/dart/lib/src/wire.dart

@@ -0,0 +1,439 @@
+// 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} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/// The kernel's wire shapes — byte-compatible with serde_json's
+/// externally-tagged enum encoding. These types mirror
+/// `nomos2/kernel/src/lib.rs` EXACTLY; the shape was discovered empirically
+/// (see ../../FINDINGS.md) by serializing real kernel values.
+///
+/// serde externally-tags enums:
+///   - unit variant      -> bare string:  Driver::Lww             => "Lww"
+///   - newtype variant   -> {Tag: inner}: Value::Int(10)          => {"Int":10}
+///   - struct variant    -> {Tag: {..}}:  Op::SetEntry{key,value} => {"SetEntry":{"key":..,"value":..}}
+///   - newtype struct    -> transparent:  ReplicaId(7)            => 7
+///
+/// This file is HAND-WRITTEN (the fixed wire types). The per-domain aggregate
+/// and directive-payload types under `generated/` are CODE-GENERATED from the
+/// TS domain definitions by `nomos2/dsl/src/codegen_dart.ts`.
+library;
+
+/// `ReplicaId(pub u64)` serializes as a bare number. Modelled as `int` (Dart
+/// has no unsigned type; replica ids in practice fit a signed 64-bit int).
+typedef WireReplicaId = int;
+
+/// `Hlc { physical: u64, logical: u32, replica: ReplicaId }`.
+///
+/// Note: `replica` is a BARE number on the wire (newtype-struct transparency),
+/// not `{"ReplicaId": 7}`.
+class Hlc {
+  final int physical;
+  final int logical;
+  final WireReplicaId replica;
+
+  const Hlc({
+    required this.physical,
+    required this.logical,
+    required this.replica,
+  });
+
+  factory Hlc.fromJson(Map<String, dynamic> json) => Hlc(
+        physical: (json['physical'] as num).toInt(),
+        logical: (json['logical'] as num).toInt(),
+        replica: (json['replica'] as num).toInt(),
+      );
+
+  Map<String, dynamic> toJson() => {
+        'physical': physical,
+        'logical': logical,
+        'replica': replica,
+      };
+
+  @override
+  bool operator ==(Object other) =>
+      other is Hlc &&
+      other.physical == physical &&
+      other.logical == logical &&
+      other.replica == replica;
+
+  @override
+  int get hashCode => Object.hash(physical, logical, replica);
+
+  @override
+  String toString() => 'Hlc(physical: $physical, logical: $logical, replica: $replica)';
+}
+
+/// `Value = Str | Int | Set | Map`.
+///
+/// Externally tagged: `{"Str":"x"}` / `{"Int":10}` / `{"Set":["a","b"]}` /
+/// `{"Map":{"k":<Field>}}`. `Set` is a `BTreeSet<String>` in the kernel, so it
+/// serializes as a JSON array and is sorted/deduped on the kernel side.
+sealed class Value {
+  const Value();
+
+  factory Value.fromJson(Map<String, dynamic> json) {
+    if (json.containsKey('Str')) {
+      return ValueStr(json['Str'] as String);
+    }
+    if (json.containsKey('Int')) {
+      return ValueInt((json['Int'] as num).toInt());
+    }
+    if (json.containsKey('Set')) {
+      return ValueSet(
+        (json['Set'] as List<dynamic>).map((e) => e as String).toList(),
+      );
+    }
+    if (json.containsKey('Map')) {
+      final raw = json['Map'] as Map<String, dynamic>;
+      return ValueMap(raw.map(
+        (k, v) => MapEntry(k, WireField.fromJson(v as Map<String, dynamic>)),
+      ));
+    }
+    throw FormatException('Unknown Value variant: ${json.keys}');
+  }
+
+  Map<String, dynamic> toJson();
+}
+
+/// `Value::Str(String)` -> `{"Str":"x"}`.
+class ValueStr extends Value {
+  final String value;
+  const ValueStr(this.value);
+
+  @override
+  Map<String, dynamic> toJson() => {'Str': value};
+
+  @override
+  bool operator ==(Object other) => other is ValueStr && other.value == value;
+  @override
+  int get hashCode => Object.hash('Str', value);
+  @override
+  String toString() => 'ValueStr($value)';
+}
+
+/// `Value::Int(i64)` -> `{"Int":10}`.
+class ValueInt extends Value {
+  final int value;
+  const ValueInt(this.value);
+
+  @override
+  Map<String, dynamic> toJson() => {'Int': value};
+
+  @override
+  bool operator ==(Object other) => other is ValueInt && other.value == value;
+  @override
+  int get hashCode => Object.hash('Int', value);
+  @override
+  String toString() => 'ValueInt($value)';
+}
+
+/// `Value::Set(BTreeSet<String>)` -> `{"Set":["a","b"]}`.
+class ValueSet extends Value {
+  final List<String> value;
+  const ValueSet(this.value);
+
+  @override
+  Map<String, dynamic> toJson() => {'Set': value};
+
+  @override
+  bool operator ==(Object other) =>
+      other is ValueSet && _listEq(other.value, value);
+  @override
+  int get hashCode => Object.hashAll(['Set', ...value]);
+  @override
+  String toString() => 'ValueSet($value)';
+}
+
+/// `Value::Map(BTreeMap<String, Field>)` -> `{"Map":{"k":<Field>}}`.
+class ValueMap extends Value {
+  final Map<String, WireField> value;
+  const ValueMap(this.value);
+
+  @override
+  Map<String, dynamic> toJson() =>
+      {'Map': value.map((k, v) => MapEntry(k, v.toJson()))};
+
+  @override
+  bool operator ==(Object other) =>
+      other is ValueMap && _mapEq(other.value, value);
+  @override
+  int get hashCode => Object.hashAll(['Map', ...value.entries.map((e) => Object.hash(e.key, e.value))]);
+  @override
+  String toString() => 'ValueMap($value)';
+}
+
+/// `Field { value: Value, stamp: Hlc }` — only used when reading state back.
+///
+/// Named `WireField` to avoid clashing with the DSL field-builder concept and
+/// with Flutter/material `Field` widgets the frontend may import.
+class WireField {
+  final Value value;
+  final Hlc stamp;
+
+  const WireField({required this.value, required this.stamp});
+
+  factory WireField.fromJson(Map<String, dynamic> json) => WireField(
+        value: Value.fromJson(json['value'] as Map<String, dynamic>),
+        stamp: Hlc.fromJson(json['stamp'] as Map<String, dynamic>),
+      );
+
+  Map<String, dynamic> toJson() => {
+        'value': value.toJson(),
+        'stamp': stamp.toJson(),
+      };
+
+  @override
+  bool operator ==(Object other) =>
+      other is WireField && other.value == value && other.stamp == stamp;
+  @override
+  int get hashCode => Object.hash(value, stamp);
+  @override
+  String toString() => 'WireField(value: $value, stamp: $stamp)';
+}
+
+/// `Op = Set(Value) | AddToSet(BTreeSet<String>) | SetEntry { key, value }`.
+sealed class Op {
+  const Op();
+
+  factory Op.fromJson(Map<String, dynamic> json) {
+    if (json.containsKey('Set')) {
+      return OpSet(Value.fromJson(json['Set'] as Map<String, dynamic>));
+    }
+    if (json.containsKey('AddToSet')) {
+      return OpAddToSet(
+        (json['AddToSet'] as List<dynamic>).map((e) => e as String).toList(),
+      );
+    }
+    if (json.containsKey('SetEntry')) {
+      final entry = json['SetEntry'] as Map<String, dynamic>;
+      return OpSetEntry(
+        key: entry['key'] as String,
+        value: Value.fromJson(entry['value'] as Map<String, dynamic>),
+      );
+    }
+    throw FormatException('Unknown Op variant: ${json.keys}');
+  }
+
+  Map<String, dynamic> toJson();
+}
+
+/// `Op::Set(Value)` -> `{"Set":{"Int":10}}`.
+class OpSet extends Op {
+  final Value value;
+  const OpSet(this.value);
+
+  @override
+  Map<String, dynamic> toJson() => {'Set': value.toJson()};
+
+  @override
+  bool operator ==(Object other) => other is OpSet && other.value == value;
+  @override
+  int get hashCode => Object.hash('Set', value);
+  @override
+  String toString() => 'OpSet($value)';
+}
+
+/// `Op::AddToSet(BTreeSet<String>)` -> `{"AddToSet":["x","y"]}`.
+class OpAddToSet extends Op {
+  final List<String> items;
+  const OpAddToSet(this.items);
+
+  @override
+  Map<String, dynamic> toJson() => {'AddToSet': items};
+
+  @override
+  bool operator ==(Object other) =>
+      other is OpAddToSet && _listEq(other.items, items);
+  @override
+  int get hashCode => Object.hashAll(['AddToSet', ...items]);
+  @override
+  String toString() => 'OpAddToSet($items)';
+}
+
+/// `Op::SetEntry { key, value }` -> `{"SetEntry":{"key":"color","value":{"Str":"red"}}}`.
+class OpSetEntry extends Op {
+  final String key;
+  final Value value;
+  const OpSetEntry({required this.key, required this.value});
+
+  @override
+  Map<String, dynamic> toJson() => {
+        'SetEntry': {'key': key, 'value': value.toJson()},
+      };
+
+  @override
+  bool operator ==(Object other) =>
+      other is OpSetEntry && other.key == key && other.value == value;
+  @override
+  int get hashCode => Object.hash('SetEntry', key, value);
+  @override
+  String toString() => 'OpSetEntry(key: $key, value: $value)';
+}
+
+/// `FieldOp { field: FieldId, op: Op }`.
+class FieldOp {
+  final String field;
+  final Op op;
+
+  const FieldOp({required this.field, required this.op});
+
+  factory FieldOp.fromJson(Map<String, dynamic> json) => FieldOp(
+        field: json['field'] as String,
+        op: Op.fromJson(json['op'] as Map<String, dynamic>),
+      );
+
+  Map<String, dynamic> toJson() => {'field': field, 'op': op.toJson()};
+
+  @override
+  bool operator ==(Object other) =>
+      other is FieldOp && other.field == field && other.op == op;
+  @override
+  int get hashCode => Object.hash(field, op);
+  @override
+  String toString() => 'FieldOp(field: $field, op: $op)';
+}
+
+/// `RefMode = Create | Mutate | Ensure | Archive` — the referential intent of an
+/// event's touch on its aggregate. serde unit-variant: a BARE string on the wire
+/// (`"Create"` / `"Mutate"` / `"Ensure"` / `"Archive"`). The DSL's
+/// `.creates`/`.mutates`/`.ensures`/`.archives` markers lower to these; the
+/// kernel's referential guard enforces them at write time. `serde(default)` =
+/// `Ensure`, so a missing `marker` on older wire decodes as [RefMode.ensure].
+enum RefMode {
+  create('Create'),
+  mutate('Mutate'),
+  ensure('Ensure'),
+  archive('Archive');
+
+  final String wire;
+  const RefMode(this.wire);
+
+  static RefMode fromWire(String wire) => RefMode.values.firstWhere(
+        (e) => e.wire == wire,
+        orElse: () => throw FormatException('Unknown RefMode: $wire'),
+      );
+}
+
+/// `Event { aggregate: AggregateId, marker: RefMode, ops: Vec<FieldOp> }` — one
+/// aggregate's mutations (the *where* + the field-ops) plus its referential
+/// [marker], #56. A directive fanning out across N aggregates emits N events,
+/// all carried by one [Intent]. `marker` is `serde(default)` = [RefMode.ensure].
+class Event {
+  final String aggregate;
+  final RefMode marker;
+  final List<FieldOp> ops;
+
+  const Event({
+    required this.aggregate,
+    this.marker = RefMode.ensure,
+    required this.ops,
+  });
+
+  factory Event.fromJson(Map<String, dynamic> json) => Event(
+        aggregate: json['aggregate'] as String,
+        marker: json.containsKey('marker')
+            ? RefMode.fromWire(json['marker'] as String)
+            : RefMode.ensure,
+        ops: (json['ops'] as List<dynamic>)
+            .map((e) => FieldOp.fromJson(e as Map<String, dynamic>))
+            .toList(),
+      );
+
+  Map<String, dynamic> toJson() => {
+        'aggregate': aggregate,
+        'marker': marker.wire,
+        'ops': ops.map((o) => o.toJson()).toList(),
+      };
+
+  @override
+  bool operator ==(Object other) =>
+      other is Event &&
+      other.aggregate == aggregate &&
+      other.marker == marker &&
+      _listEq(other.ops, ops);
+  @override
+  int get hashCode => Object.hash(aggregate, marker, Object.hashAll(ops));
+  @override
+  String toString() =>
+      'Event(aggregate: $aggregate, marker: $marker, ops: $ops)';
+}
+
+/// `Intent { id: IntentId, hlc: Hlc, strikes: Vec<IntentId>, events: Vec<Event> }`
+/// — one intent = one commit = the atomic unit (#56). Carries the whole event set:
+/// many per-aggregate events, all sharing the intent's HLC, all-or-nothing.
+/// Written as `intent.json` in the kernel's commit tree.
+///
+/// [id] identifies the commit; [strikes] lists intent ids this intent retracts
+/// (the strike-out / revert hatch). Both are `serde(default)` on the kernel, so a
+/// missing `id`/`strikes` on older wire decodes as `''` / `[]`.
+class Intent {
+  final String id;
+  final Hlc hlc;
+  final List<String> strikes;
+  final List<Event> events;
+
+  const Intent({
+    this.id = '',
+    required this.hlc,
+    this.strikes = const [],
+    required this.events,
+  });
+
+  /// Derive the deterministic intent id from its HLC (physical.logical.replica)
+  /// — the same rule the TS `intentIdFromHlc` uses, so both sides emit the
+  /// byte-identical `id`.
+  static String idFromHlc(Hlc hlc) =>
+      '${hlc.physical}.${hlc.logical}.${hlc.replica}';
+
+  factory Intent.fromJson(Map<String, dynamic> json) => Intent(
+        id: (json['id'] as String?) ?? '',
+        hlc: Hlc.fromJson(json['hlc'] as Map<String, dynamic>),
+        strikes: (json['strikes'] as List<dynamic>?)
+                ?.map((e) => e as String)
+                .toList() ??
+            const [],
+        events: (json['events'] as List<dynamic>)
+            .map((e) => Event.fromJson(e as Map<String, dynamic>))
+            .toList(),
+      );
+
+  Map<String, dynamic> toJson() => {
+        'id': id,
+        'hlc': hlc.toJson(),
+        'strikes': strikes,
+        'events': events.map((e) => e.toJson()).toList(),
+      };
+
+  @override
+  bool operator ==(Object other) =>
+      other is Intent &&
+      other.id == id &&
+      other.hlc == hlc &&
+      _listEq(other.strikes, strikes) &&
+      _listEq(other.events, events);
+  @override
+  int get hashCode =>
+      Object.hash(id, hlc, Object.hashAll(strikes), Object.hashAll(events));
+  @override
+  String toString() =>
+      'Intent(id: $id, hlc: $hlc, strikes: $strikes, events: $events)';
+}
+
+bool _listEq<T>(List<T> a, List<T> b) {
+  if (a.length != b.length) return false;
+  for (var i = 0; i < a.length; i++) {
+    if (a[i] != b[i]) return false;
+  }
+  return true;
+}
+
+bool _mapEq<K, V>(Map<K, V> a, Map<K, V> b) {
+  if (a.length != b.length) return false;
+  for (final entry in a.entries) {
+    if (!b.containsKey(entry.key) || b[entry.key] != entry.value) return false;
+  }
+  return true;
+}