@githolon/dsl 0.1.0 → 0.1.1

package/dart/.dart_tool/package_graph.json

@@ -0,0 +1,485 @@
+{
+  "roots": [
+    "nomos_dsl"
+  ],
+  "packages": [
+    {
+      "name": "nomos_dsl",
+      "version": "0.0.0",
+      "dependencies": [
+        "json_schema"
+      ],
+      "devDependencies": [
+        "test"
+      ]
+    },
+    {
+      "name": "test",
+      "version": "1.31.1",
+      "dependencies": [
+        "analyzer",
+        "async",
+        "boolean_selector",
+        "collection",
+        "coverage",
+        "http_multi_server",
+        "io",
+        "matcher",
+        "node_preamble",
+        "package_config",
+        "path",
+        "pool",
+        "shelf",
+        "shelf_packages_handler",
+        "shelf_static",
+        "shelf_web_socket",
+        "source_span",
+        "stack_trace",
+        "stream_channel",
+        "test_api",
+        "test_core",
+        "typed_data",
+        "web_socket_channel",
+        "webkit_inspection_protocol",
+        "yaml"
+      ]
+    },
+    {
+      "name": "json_schema",
+      "version": "5.2.2",
+      "dependencies": [
+        "collection",
+        "http",
+        "logging",
+        "rfc_6901",
+        "uri"
+      ]
+    },
+    {
+      "name": "yaml",
+      "version": "3.1.3",
+      "dependencies": [
+        "collection",
+        "source_span",
+        "string_scanner"
+      ]
+    },
+    {
+      "name": "webkit_inspection_protocol",
+      "version": "1.2.1",
+      "dependencies": [
+        "logging"
+      ]
+    },
+    {
+      "name": "web_socket_channel",
+      "version": "3.0.3",
+      "dependencies": [
+        "async",
+        "crypto",
+        "stream_channel",
+        "web",
+        "web_socket"
+      ]
+    },
+    {
+      "name": "typed_data",
+      "version": "1.4.0",
+      "dependencies": [
+        "collection"
+      ]
+    },
+    {
+      "name": "test_core",
+      "version": "0.6.18",
+      "dependencies": [
+        "analyzer",
+        "args",
+        "async",
+        "boolean_selector",
+        "collection",
+        "coverage",
+        "frontend_server_client",
+        "glob",
+        "io",
+        "meta",
+        "package_config",
+        "path",
+        "pool",
+        "source_map_stack_trace",
+        "source_maps",
+        "source_span",
+        "stack_trace",
+        "stream_channel",
+        "test_api",
+        "vm_service",
+        "yaml"
+      ]
+    },
+    {
+      "name": "test_api",
+      "version": "0.7.12",
+      "dependencies": [
+        "async",
+        "boolean_selector",
+        "collection",
+        "meta",
+        "source_span",
+        "stack_trace",
+        "stream_channel",
+        "string_scanner",
+        "term_glyph"
+      ]
+    },
+    {
+      "name": "stream_channel",
+      "version": "2.1.4",
+      "dependencies": [
+        "async"
+      ]
+    },
+    {
+      "name": "stack_trace",
+      "version": "1.12.1",
+      "dependencies": [
+        "path"
+      ]
+    },
+    {
+      "name": "source_span",
+      "version": "1.10.2",
+      "dependencies": [
+        "collection",
+        "path",
+        "term_glyph"
+      ]
+    },
+    {
+      "name": "shelf_web_socket",
+      "version": "3.0.0",
+      "dependencies": [
+        "shelf",
+        "stream_channel",
+        "web_socket_channel"
+      ]
+    },
+    {
+      "name": "shelf_static",
+      "version": "1.1.3",
+      "dependencies": [
+        "convert",
+        "http_parser",
+        "mime",
+        "path",
+        "shelf"
+      ]
+    },
+    {
+      "name": "shelf_packages_handler",
+      "version": "3.0.2",
+      "dependencies": [
+        "path",
+        "shelf",
+        "shelf_static"
+      ]
+    },
+    {
+      "name": "shelf",
+      "version": "1.4.2",
+      "dependencies": [
+        "async",
+        "collection",
+        "http_parser",
+        "path",
+        "stack_trace",
+        "stream_channel"
+      ]
+    },
+    {
+      "name": "pool",
+      "version": "1.5.2",
+      "dependencies": [
+        "async",
+        "stack_trace"
+      ]
+    },
+    {
+      "name": "path",
+      "version": "1.9.1",
+      "dependencies": []
+    },
+    {
+      "name": "package_config",
+      "version": "2.2.0",
+      "dependencies": [
+        "path"
+      ]
+    },
+    {
+      "name": "node_preamble",
+      "version": "2.0.2",
+      "dependencies": []
+    },
+    {
+      "name": "matcher",
+      "version": "0.12.20",
+      "dependencies": [
+        "async",
+        "meta",
+        "stack_trace",
+        "term_glyph",
+        "test_api"
+      ]
+    },
+    {
+      "name": "io",
+      "version": "1.0.5",
+      "dependencies": [
+        "meta",
+        "path",
+        "string_scanner"
+      ]
+    },
+    {
+      "name": "http_multi_server",
+      "version": "3.2.2",
+      "dependencies": [
+        "async"
+      ]
+    },
+    {
+      "name": "coverage",
+      "version": "1.15.0",
+      "dependencies": [
+        "args",
+        "cli_config",
+        "glob",
+        "logging",
+        "meta",
+        "package_config",
+        "path",
+        "source_maps",
+        "stack_trace",
+        "vm_service",
+        "yaml"
+      ]
+    },
+    {
+      "name": "collection",
+      "version": "1.19.1",
+      "dependencies": []
+    },
+    {
+      "name": "boolean_selector",
+      "version": "2.1.2",
+      "dependencies": [
+        "source_span",
+        "string_scanner"
+      ]
+    },
+    {
+      "name": "async",
+      "version": "2.13.1",
+      "dependencies": [
+        "collection",
+        "meta"
+      ]
+    },
+    {
+      "name": "analyzer",
+      "version": "13.0.0",
+      "dependencies": [
+        "_fe_analyzer_shared",
+        "collection",
+        "convert",
+        "crypto",
+        "glob",
+        "meta",
+        "package_config",
+        "path",
+        "pub_semver",
+        "source_span",
+        "watcher",
+        "yaml"
+      ]
+    },
+    {
+      "name": "uri",
+      "version": "1.0.0",
+      "dependencies": [
+        "matcher",
+        "quiver"
+      ]
+    },
+    {
+      "name": "rfc_6901",
+      "version": "0.2.1",
+      "dependencies": []
+    },
+    {
+      "name": "logging",
+      "version": "1.3.0",
+      "dependencies": []
+    },
+    {
+      "name": "http",
+      "version": "1.6.0",
+      "dependencies": [
+        "async",
+        "http_parser",
+        "meta",
+        "web"
+      ]
+    },
+    {
+      "name": "string_scanner",
+      "version": "1.4.1",
+      "dependencies": [
+        "source_span"
+      ]
+    },
+    {
+      "name": "web_socket",
+      "version": "1.0.1",
+      "dependencies": [
+        "web"
+      ]
+    },
+    {
+      "name": "web",
+      "version": "1.1.1",
+      "dependencies": []
+    },
+    {
+      "name": "crypto",
+      "version": "3.0.7",
+      "dependencies": [
+        "typed_data"
+      ]
+    },
+    {
+      "name": "vm_service",
+      "version": "15.2.0",
+      "dependencies": []
+    },
+    {
+      "name": "source_maps",
+      "version": "0.10.13",
+      "dependencies": [
+        "source_span"
+      ]
+    },
+    {
+      "name": "source_map_stack_trace",
+      "version": "2.1.2",
+      "dependencies": [
+        "path",
+        "source_maps",
+        "stack_trace"
+      ]
+    },
+    {
+      "name": "meta",
+      "version": "1.18.2",
+      "dependencies": []
+    },
+    {
+      "name": "glob",
+      "version": "2.1.3",
+      "dependencies": [
+        "async",
+        "collection",
+        "file",
+        "path",
+        "string_scanner"
+      ]
+    },
+    {
+      "name": "frontend_server_client",
+      "version": "4.0.0",
+      "dependencies": [
+        "async",
+        "path"
+      ]
+    },
+    {
+      "name": "args",
+      "version": "2.7.0",
+      "dependencies": []
+    },
+    {
+      "name": "term_glyph",
+      "version": "1.2.2",
+      "dependencies": []
+    },
+    {
+      "name": "mime",
+      "version": "2.0.0",
+      "dependencies": []
+    },
+    {
+      "name": "http_parser",
+      "version": "4.1.2",
+      "dependencies": [
+        "collection",
+        "source_span",
+        "string_scanner",
+        "typed_data"
+      ]
+    },
+    {
+      "name": "convert",
+      "version": "3.1.2",
+      "dependencies": [
+        "typed_data"
+      ]
+    },
+    {
+      "name": "cli_config",
+      "version": "0.2.0",
+      "dependencies": [
+        "args",
+        "yaml"
+      ]
+    },
+    {
+      "name": "watcher",
+      "version": "1.2.1",
+      "dependencies": [
+        "async",
+        "path"
+      ]
+    },
+    {
+      "name": "pub_semver",
+      "version": "2.2.0",
+      "dependencies": [
+        "collection"
+      ]
+    },
+    {
+      "name": "_fe_analyzer_shared",
+      "version": "100.0.0",
+      "dependencies": [
+        "meta",
+        "source_span"
+      ]
+    },
+    {
+      "name": "quiver",
+      "version": "3.2.2",
+      "dependencies": [
+        "matcher"
+      ]
+    },
+    {
+      "name": "file",
+      "version": "7.0.1",
+      "dependencies": [
+        "meta",
+        "path"
+      ]
+    }
+  ],
+  "configVersion": 1
+}

package/dart/.dart_tool/version

@@ -0,0 +1 @@
+3.41.9

package/dart/FINDINGS.md

@@ -0,0 +1,147 @@
+<!--
+  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.
+-->
+
+# Nomos 2 Dart frontend codegen — findings
+
+The Dart types the Flutter frontend needs, (de)serializing the **exact** serde
+JSON the Rust kernel + projection produce/consume. This is decision-6 of the DSL
+design: the schema is the single source of truth → TS (done), proto (later),
+**Dart frontend types (this slice)**.
+
+## What was built
+
+`nomos2/dsl/dart/` — a Dart package (`nomos_dsl`):
+
+| Path | Role | Hand-written / generated |
+|---|---|---|
+| `lib/src/wire.dart` | Fixed kernel wire types: `Hlc`, `Value` (sealed: `ValueStr`/`ValueInt`/`ValueSet`/`ValueMap`), `WireField`, `Op` (sealed: `OpSet`/`OpAddToSet`/`OpSetEntry`), `FieldOp`, `Event` (`{aggregate, ops}`, #56), `Intent` (`{hlc, events}`, #56). | hand-written |
+| `lib/src/driver.dart` | `WireDriver` (sealed: `DriverLww`/`DriverAddWins`/`DriverConflict`/`DriverMapOf`) + `Schema`. | hand-written |
+| `lib/src/generated/trackable_asset.dart` | The `trackable_asset` domain: `TrackableAsset` aggregate, `StatusEnum`, and `CreateAssetPayload`/`MoveAssetPayload`/`TagAssetPayload`/`SetCustomFieldPayload`. | **generated** |
+| `lib/nomos_dsl.dart` | Public barrel (exports the three above). | hand-written |
+| `test/wire_test.dart` | Round-trip tests for every wire type + Driver/Schema. | — |
+| `test/trackable_asset_test.dart` | Read-model aggregate deserialization + directive-payload → Event JSON. | — |
+
+The **codegen** lives in `nomos2/dsl/` (TS, alongside the existing TS DSL):
+
+| Path | Role |
+|---|---|
+| `src/codegen_dart.ts` | The generator: introspects aggregates + directives, emits the Dart per-domain source. |
+| `src/emit_dart.ts` | The driver: wires the `trackable_asset` domain into the generator, writes `dart/lib/src/generated/`. Run `npx tsx src/emit_dart.ts` (or `npm run emit:dart`). |
+
+Per the brief: #1 (fixed wire types) is hand-written; **#2 (per-domain types) is
+generated**, so it stays reproducible from the domain definitions, not drifting.
+
+## The exact serde JSON shape matched
+
+Verified against `nomos2/kernel/src/lib.rs` and the existing emitted fixtures
+(`nomos2/dsl/fixtures/*.json`, the TS side's real-kernel round-trip output):
+
+```
+Hlc          {"physical":1,"logical":0,"replica":7}     replica is a BARE int (newtype-struct transparency), NOT {"ReplicaId":7}
+Value::Str   {"Str":"red"}
+Value::Int   {"Int":10}                                  i64 in Rust -> Dart int
+Value::Set   {"Set":["a","b"]}                           BTreeSet<String> -> JSON array
+Value::Map   {"Map":{"k":{"value":<Value>,"stamp":<Hlc>}}}
+Op::Set      {"Set":{"Int":10}} / {"Set":{"Str":"A"}}
+Op::AddToSet {"AddToSet":["x","y"]}
+Op::SetEntry {"SetEntry":{"key":"color","value":{"Str":"red"}}}
+FieldOp      {"field":"pos","op":<Op>}
+Event        {"aggregate":"asset-1","ops":[<FieldOp>...]}    (#56: per-aggregate, the *where*)
+Intent       {"hlc":<Hlc>,"events":[<Event>...]}             (#56: one commit = intent.json)
+Driver unit  "Lww" / "AddWins" / "Conflict"              bare strings
+Driver::MapOf {"MapOf":"Lww"}                            nests
+Schema       {"label":"Lww",...,"customFields":{"MapOf":"Lww"}}   plain object (BTreeMap)
+```
+
+Read-model aggregate shape (what `TrackableAsset.fromJson` consumes — REALIGNED
+2026-06-01 to the dispatch(intent) read half): the FLAT, already-decoded `data`
+map of a `{type,id,data}` row that the FRB `query()`/`query_by_id()`/`view()`
+emit — e.g. `{ "label":"Pump 2", "pos":10, "status":"active", "tags":["x","y"],
+"customFields":{"size":"L"} }`. NOT the projection-internal `{field:{value,stamp}}`
+`WireField` shape (the Rust `decode_field` has already peeled the kernel `Value`
+back to bare JSON). The generated `fromJson` reads each field via a tolerant
+flat-projection reader in `src/subscriptions.dart` (`readStr`/`readInt`/`readSet`/
+`readStrMap`/`readEnum`/`readJsonStr`).
+
+The generated `TrackableAsset` maps each field to a frontend-pleasant Dart type:
+`label: String`, `pos: int`, `status: StatusEnum`, `tags: Set<String>`,
+`customFields: Map<String, String>`. The app subscribes through the generated
+typed read accessors (`watch…`/`read…` over `query()`/`query_by_id()`, threading a
+`NomosReads`) — the READ half of the peer boundary, symmetric with `dispatch`.
+
+## How the codegen derives directive ops (no second source of truth)
+
+A directive's `plan(payload, ctx)` is arbitrary TS, so the op structure can't be
+read off statically. Instead the generator runs the **same** `plan` with a Proxy
+payload whose property reads return tracking tokens (`{__payloadKey}`). The
+resulting `PlannedOp[]` then tells us, per op, which payload key feeds the value
+/ items / entry-key. That op template is emitted into the Dart payload's
+`toEvent()` — which lowers exactly as the TS `runDirective`/`lowerValue` does
+(int→`ValueInt`, string/enum→`ValueStr`, string[]→`ValueSet`) and threads the
+directive's target aggregate id into the `Event{aggregate, ops}` (#56);
+`toIntent(hlc)` wraps it in a one-event `Intent{hlc, events}`. So the Dart wire
+output is driven by the identical authored plan, not a re-typed copy.
+
+## The proof (green via `dart test`)
+
+`cd nomos2/dsl/dart && dart test` — **28 tests pass**, `dart analyze` clean:
+
+- **Round-trip** (`wire_test.dart`): kernel JSON for `Hlc`, all four `Value`
+  variants, all three `Op` variants, an `Event{aggregate, ops}` (Set/AddToSet/
+  SetEntry), a multi-aggregate `Intent{hlc, events}` (#56), all `Driver` variants,
+  and the lowered `Schema` → `fromJson` → `toJson` structurally equals the input.
+  Explicit assertions that `replica` is a bare int and `MapOf` nests.
+- **Read-model aggregate** (`trackable_asset_test.dart`): a `{field:{value,stamp}}`
+  JSON (incl. a `Value::Map` for `customFields`) deserializes into the generated
+  `TrackableAsset`; enum string → `StatusEnum`; missing field throws.
+- **Directive payload → kernel Intent**: `CreateAssetPayload(...).toIntent(hlc)`
+  emits a one-event `Intent` whose event threads `aggregate: 'TrackableAsset'`
+  (#56); `toEvent()` exposes the per-aggregate `Event`; `moveAsset`/`tagAsset`/
+  `setCustomField` each lower the expected `Set`/`AddToSet`/`SetEntry`; the produced
+  `Intent` round-trips back through `Intent.fromJson`.
+
+The codegen is **reproducible**: re-running `npx tsx src/emit_dart.ts` produces a
+byte-identical `trackable_asset.dart` (verified). The TS side is unaffected:
+`npx tsc --noEmit` is clean and the existing 13 vitest tests stay green.
+
+## Friction / notes (not fixed, by instruction)
+
+1. **Aggregate identity (#56) — DONE.** The kernel `Event` is now
+   `{aggregate, ops}` and a commit is an `Intent{hlc, events}` (`intent.json`).
+   `Event`/`Intent` in `wire.dart` match; each generated payload threads its
+   `aggregateId` into `toEvent()` and `toIntent(hlc)` wraps a one-event `Intent`.
+   (The generated domain directives are single-aggregate, so each payload's intent
+   carries exactly one event; a future multi-aggregate generated directive would
+   emit several — same grouping the TS `runDirective` already does.)
+2. **`replica` unsigned.** Rust `ReplicaId(u64)`; Dart has no unsigned int, so
+   `WireReplicaId = int`. Fine for realistic replica ids; a far-future >2^63 id
+   would need `BigInt` (noted, not handled — out of scope).
+3. **`Value::Set` ordering.** Kernel `BTreeSet` is sorted; Dart `List<String>`
+   preserves wire order on round-trip (we don't re-sort), so `toJson` is
+   byte-stable against the kernel's already-sorted input. The aggregate field is
+   surfaced as a `Set<String>` (order-insensitive) for the frontend.
+4. **Generator scope.** `codegen_dart.ts` handles the field/payload kinds the
+   `trackable_asset` domain uses (string/int/enum/set/map, and `json`/`ref` →
+   `String` on the aggregate side). Unsupported Zod payload kinds throw loudly
+   rather than mis-emit — same fail-closed posture as the TS `lowerDriver`.
+
+## How to run
+
+```
+cd nomos2/dsl
+npm install
+npx tsx src/emit_dart.ts        # (re)generate dart/lib/src/generated/
+npx tsc --noEmit                # TS still typechecks
+npx vitest run                  # existing 13 TS tests
+
+cd dart
+dart pub get
+dart analyze                    # clean
+dart test                       # 28 tests green
+```

package/dart/build/native_assets/macos/native_assets.json

@@ -0,0 +1 @@
+{"format-version":[1,0,0],"native-assets":{}}

package/dart/build/unit_test_assets/FontManifest.json

@@ -0,0 +1 @@
+[]

package/dart/build/unit_test_assets/NativeAssetsManifest.json

@@ -0,0 +1 @@
+{"format-version":[1,0,0],"native-assets":{}}