@githolon/dsl 0.1.0 → 0.1.2

package/dart/lib/nomos_dsl.dart

@@ -0,0 +1,43 @@
+// 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 types.
+///
+///  - The hand-written kernel WIRE types (`Value`, `Field`/`WireField`, `Hlc`,
+///    `Op`, `FieldOp`, `Event`, `Schema`/`WireDriver`) — byte-compatible with
+///    serde_json. See `src/wire.dart`, `src/driver.dart`.
+///  - The ONE write verb `dispatch(intent)` (`src/dispatch.dart`) + the typed
+///    reactive read engine `NomosReads` (`src/subscriptions.dart`).
+///  - The framework PRIMITIVES ONLY. The CODE-GENERATED per-domain types
+///    (aggregates + public intent payloads + enums + `watch…` read accessors) NO LONGER
+///    live here — they were extracted into the co-located TENANT package
+///    `co2_nomos_domains` (`ts_packages/co2-nomos-domains/dart/`), emitted there by
+///    `ts_packages/co2-nomos-domains/src/emit_dart.ts`. Tenant domains squatting in
+///    the framework package was the wrong topology; this barrel now exports ONLY the
+///    hand-written framework wire/dispatch/read/provider primitives. App code that
+///    wants the typed domain surface imports `package:co2_nomos_domains/co2_nomos_domains.dart`,
+///    which re-exports this framework barrel PLUS every generated domain.
+library;
+
+export 'src/wire.dart';
+export 'src/driver.dart';
+export 'src/dispatch.dart';
+export 'src/subscriptions.dart';
+export 'src/schema_validation.dart';
+// The PROVIDER boundary (server-side capability-provider SDK runtime: TaskOutcome /
+// TaskSuccess / TaskFailure / TaskResult / TaskProvider / HostClock). The symmetric twin
+// of `dispatch.dart`; the generated per-task provider classes build on it.
+export 'src/provider.dart';
+
+// ── NO generated domains here ──────────────────────────────────────────────
+// The per-domain generated types moved to the tenant `co2_nomos_domains` package
+// (`ts_packages/co2-nomos-domains/dart/lib/src/generated/`). The tenant barrel
+// (`package:co2_nomos_domains/co2_nomos_domains.dart`) re-exports THIS framework
+// barrel plus every generated domain — so importing it gives the whole typed
+// surface (framework primitives + tenant domains) through one import. The colliding
+// positional enums (`StatusEnum`/`KindEnum`/…) and their `hide` clauses now live on
+// the tenant barrel's exports, not here.

package/dart/lib/src/dispatch.dart

@@ -0,0 +1,87 @@
+// 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 ONE write verb: `dispatch(intent)`.
+///
+/// END-STATE (the "dispatch(intent) purge", Jack 2026-06-01): app code's only
+/// write verb is `dispatch(intent)`. The frontend constructs ONLY a typed
+/// generated intent DTO (a [NomosIntent]) — it never hand-types an engine rule
+/// id, never builds an `Event`, never holds an `Hlc`. `dispatch` ships the
+/// intent payload as DATA to the kernel's FRB `author(domain, directiveId, payloadJson,
+/// actor)`; the sealed engine runs the REAL `.plan()` and is the SOLE lowering
+/// authority (HLC + intent id are kernel-allocated host-side).
+///
+/// This file is HAND-WRITTEN and domain-AGNOSTIC (declared ONCE, here): the
+/// generated per-domain intent classes `implements NomosIntent`, so a single
+/// generic `dispatch` covers every public intent of every domain — replacing the
+/// ~63-method write façade.
+library;
+
+import 'dart:convert';
+
+/// A typed, generated public intent. Every generated `…Payload` class implements
+/// this: it knows its [domain] + [intentType] and serialises ONLY its typed
+/// fields to DATA via [toPayloadJson]. It builds NO `Event` and NO `Hlc`.
+abstract interface class NomosIntent {
+  /// The policy domain (the kernel `author` `domain` — the engine registry key).
+  String get domain;
+
+  /// The public intent type within [domain].
+  String get intentType;
+
+  /// The intent payload as DATA: the exact JSON shape the domain Zod
+  /// schema validates inside the engine. Optional fields are omitted when null.
+  Map<String, Object?> toPayloadJson();
+}
+
+/// The kernel write seam: the FRB `NomosClient.author` signature, as a function
+/// type. `dispatch` takes this (rather than importing the FRB client) so the
+/// generated `nomos_dsl` package stays free of a `flutter_rust_bridge` dependency
+/// — the app threads `client.author` in. Returns the new HEAD commit oid (hex).
+typedef Authorer = String Function({
+  required String domain,
+  required String directiveId,
+  required String payloadJson,
+  required String actor,
+});
+
+/// THE ONE WRITE VERB. Ship a typed [intent] payload as DATA to the kernel
+/// [author] seam. The domain + intent type + payload all come from the GENERATED
+/// intent object — nothing is hand-typed. Builds NO `Event` and NO `Hlc`: the
+/// engine lowers. [actor] is the authenticated actor the caller threads from auth.
+/// Returns the new HEAD commit oid (hex).
+String dispatch(NomosIntent intent,
+        {required Authorer author, required String actor}) =>
+    author(
+      domain: intent.domain,
+      directiveId: intent.intentType,
+      payloadJson: jsonEncode(intent.toPayloadJson()),
+      actor: actor,
+    );
+
+// ── ID-MINT SEAM (the type-safety keystone) ───────────────────────────────────
+//
+// The frontend NEVER mints an aggregate id and NEVER passes a raw string, a seed, or a
+// nonce. A generated `createX(...)` factory (no raw id param) calls the KERNEL mint via
+// this seam to RESERVE a typed, type-tagged `<Type>_<uuidv7>` id, which it ships in the
+// create payload; the kernel's GATE verifies its shape + type-tag prefix on author. Like
+// [Authorer], this is a function type the app threads in (the FRB
+// `NomosClient.mintIdForWorkspace`), so the generated `nomos_dsl` package stays free of a
+// `flutter_rust_bridge` dependency.
+//
+// WHERE THE RANDOMNESS LIVES (the model — the dev touches NONE of it): the KERNEL mints
+// the UUIDv7-shaped body from a HOST-INJECTED random source (native `OsRng`; web
+// `crypto.getRandomValues`), CAPTURES it in the create event, and replay READS it (never
+// re-mints). The UUID body is opaque uniqueness only — NOT time/order; intent HLCs carry
+// ordering. So there is NO Dart-side nonce, NO `freshMintSeed`, NO seed at all — the dev
+// just calls `createX(...)` and gets a guaranteed-unique typed id.
+
+/// The kernel id-mint seam: the FRB `NomosClient.mintIdForWorkspace` signature, as a
+/// function type. Returns a kernel-minted `<Type>_<uuidv7>` id (the kernel mints it from
+/// the host-injected rng). The dev supplies ONLY the aggregate type — no workspace, no
+/// author, no seed.
+typedef Minter = String Function({required String aggregateType});

package/dart/lib/src/driver.dart

@@ -0,0 +1,122 @@
+// 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.
+
+/// `Driver` + `Schema` wire shapes, mirroring `nomos2/kernel/src/lib.rs`.
+///
+/// `Driver = Lww | AddWins | MapOf(Box<Driver>) | Conflict`.
+///   - unit variants are BARE strings:        "Lww" / "AddWins" / "Conflict"
+///   - the MapOf newtype variant nests:        {"MapOf":"Lww"}
+///
+/// `Schema = BTreeMap<FieldId, Driver>` — a plain JSON object: field -> Driver.
+library;
+
+/// One field's merge driver. Hand-written wire type (the frontend reads a
+/// schema to know how each field merges / renders).
+sealed class WireDriver {
+  const WireDriver();
+
+  factory WireDriver.fromJson(dynamic json) {
+    if (json is String) {
+      switch (json) {
+        case 'Lww':
+          return const DriverLww();
+        case 'AddWins':
+          return const DriverAddWins();
+        case 'Conflict':
+          return const DriverConflict();
+        default:
+          throw FormatException('Unknown Driver unit variant: $json');
+      }
+    }
+    if (json is Map<String, dynamic> && json.containsKey('MapOf')) {
+      return DriverMapOf(WireDriver.fromJson(json['MapOf']));
+    }
+    throw FormatException('Unknown Driver shape: $json');
+  }
+
+  /// Returns either a `String` (unit variants) or a `Map` (MapOf).
+  dynamic toJson();
+}
+
+class DriverLww extends WireDriver {
+  const DriverLww();
+  @override
+  dynamic toJson() => 'Lww';
+  @override
+  bool operator ==(Object other) => other is DriverLww;
+  @override
+  int get hashCode => 'Lww'.hashCode;
+  @override
+  String toString() => 'DriverLww';
+}
+
+class DriverAddWins extends WireDriver {
+  const DriverAddWins();
+  @override
+  dynamic toJson() => 'AddWins';
+  @override
+  bool operator ==(Object other) => other is DriverAddWins;
+  @override
+  int get hashCode => 'AddWins'.hashCode;
+  @override
+  String toString() => 'DriverAddWins';
+}
+
+class DriverConflict extends WireDriver {
+  const DriverConflict();
+  @override
+  dynamic toJson() => 'Conflict';
+  @override
+  bool operator ==(Object other) => other is DriverConflict;
+  @override
+  int get hashCode => 'Conflict'.hashCode;
+  @override
+  String toString() => 'DriverConflict';
+}
+
+class DriverMapOf extends WireDriver {
+  final WireDriver inner;
+  const DriverMapOf(this.inner);
+  @override
+  dynamic toJson() => {'MapOf': inner.toJson()};
+  @override
+  bool operator ==(Object other) => other is DriverMapOf && other.inner == inner;
+  @override
+  int get hashCode => Object.hash('MapOf', inner);
+  @override
+  String toString() => 'DriverMapOf($inner)';
+}
+
+/// `Schema = BTreeMap<FieldId, Driver>` — field id -> Driver.
+class Schema {
+  final Map<String, WireDriver> drivers;
+  const Schema(this.drivers);
+
+  factory Schema.fromJson(Map<String, dynamic> json) => Schema(
+        json.map((k, v) => MapEntry(k, WireDriver.fromJson(v))),
+      );
+
+  Map<String, dynamic> toJson() =>
+      drivers.map((k, v) => MapEntry(k, v.toJson()));
+
+  @override
+  bool operator ==(Object other) {
+    if (other is! Schema) return false;
+    if (other.drivers.length != drivers.length) return false;
+    for (final e in drivers.entries) {
+      if (other.drivers[e.key] != e.value) return false;
+    }
+    return true;
+  }
+
+  @override
+  int get hashCode =>
+      Object.hashAll(drivers.entries.map((e) => Object.hash(e.key, e.value)));
+
+  @override
+  String toString() => 'Schema($drivers)';
+}

package/dart/lib/src/provider.dart

@@ -0,0 +1,139 @@
+// 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 PROVIDER boundary: the typed server-side capability-provider SDK runtime.
+///
+/// This is the SYMMETRIC TWIN of `dispatch.dart` (the peer write boundary). Where
+/// the peer authors an Order (`createTranscribeVoiceNote(...)` -> `dispatch`), a
+/// PROVIDER (Whisper, a renderer, a multi-target PR transporter) is the
+/// other end of the framework `impureCapability` Order→Receipt pair: it WATCHES `requested`
+/// task rows, performs the impure side-effect OUTSIDE the fold, and authors the RECEIPT
+/// (`complete…`/`fail…`/`block…`/`deadLetter…`) back through the SAME write path. The receipt is an ordinary
+/// intent — the provider is a Nomos author, NOT a bypass (ONE-WRITE-PATH).
+/// Order and Receipt are intent roles, not provider-owned jobs or privileged server
+/// mutation channels.
+///
+/// PRINCIPLE (Jack 2026-06-04): code is ~free; INTEGRATION POINTS are expensive +
+/// fuckup-guaranteed. So the generated provider SDK is fully TYPED to the boundary —
+/// the dev writes a typed `handler(Order) -> Result | Failure | Blocked | DeadLetter`; the generated
+/// dispatcher DECODES the incoming Order JSON into the typed Order and ENCODES the typed
+/// outcome into the ordinary Receipt intent. NO dynamic / `Map<String, dynamic>` / raw-JSON leaks
+/// into the dev-facing API; the types stop ONLY at the actual JSON serde (`handleOrder`).
+///
+/// This file is HAND-WRITTEN and domain-AGNOSTIC (declared ONCE, here): the generated
+/// per-task provider classes build on these interfaces, so the round-trip mechanism is
+/// proven once and reused for every capability.
+library;
+
+import 'dart:convert';
+
+import 'dispatch.dart' show NomosIntent;
+
+/// The typed OUTCOME a provider handler returns for one Order: success, failure, blocked,
+/// or dead-lettered.
+/// SEALED so a generated dispatcher's `switch` is EXHAUSTIVE — a new outcome variant is
+/// a compile error at every dispatcher, never a silent fall-through. The mirror of the
+/// framework `TaskOutcome` union (`impure_capability.ts`), but TYPED in the Result.
+sealed class TaskOutcome<R> {
+  const TaskOutcome();
+}
+
+/// The SUCCESS outcome: the typed [result] the handler produced. The generated
+/// dispatcher maps this → the `complete…` Receipt directive (status:completed +
+/// resultRef + closesOrder).
+final class TaskSuccess<R> extends TaskOutcome<R> {
+  /// The typed result the handler produced (e.g. a transcription's `resultRef`).
+  final R result;
+  const TaskSuccess(this.result);
+}
+
+/// The FAILURE outcome: the [failureReason] the handler recorded. The generated
+/// dispatcher maps this → the `fail…` Receipt directive (status:failed + failureReason +
+/// closesOrder). A recorded failure is the terminal state — NOT a retry storm
+/// (conformance X1's "declined is recorded" discipline at the task scale).
+final class TaskFailure<R> extends TaskOutcome<R> {
+  /// Why the side-effect failed (recorded onto the task, never re-thrown into the fold).
+  final String failureReason;
+  const TaskFailure(this.failureReason);
+}
+
+/// The BLOCKED outcome: the provider cannot proceed until an external condition changes.
+/// The generated dispatcher maps this -> the `block...` Receipt directive
+/// (status:blocked + blockedReason + nextAction + closesOrder). This is terminal for this
+/// order; recovery is a fresh explicit Order after the next action is satisfied.
+final class TaskBlocked<R> extends TaskOutcome<R> {
+  /// Why the provider cannot proceed.
+  final String blockedReason;
+
+  /// What the host/human must do before a fresh order can proceed.
+  final String nextAction;
+
+  const TaskBlocked({
+    required this.blockedReason,
+    required this.nextAction,
+  });
+}
+
+/// The DEAD-LETTER outcome: stop retrying this order and park it in the DLQ. The generated
+/// dispatcher maps this -> the `deadLetter...` Receipt directive
+/// (status:deadLettered + deadLetterReason + closesOrder).
+final class TaskDeadLetter<R> extends TaskOutcome<R> {
+  /// Why this order was moved to the DLQ.
+  final String deadLetterReason;
+  const TaskDeadLetter(this.deadLetterReason);
+}
+
+/// A typed RESULT a provider handler can encode into a Receipt's content-addressed
+/// `resultRef`. Every generated `…Result` class implements this: it serialises to the
+/// single JSON string the framework `complete…` Receipt records as its `resultRef` (the
+/// authoritative artifact). The framework's `resultRef` is a JSON STRING leaf
+/// (`impure_capability.ts` `completeSchema.resultRef`), so a structured result is JSON-encoded
+/// into it and decodes losslessly on the read side.
+abstract interface class TaskResult {
+  /// Encode this result to the Receipt's `resultRef` JSON string.
+  String toResultRef();
+}
+
+/// The HOST CLOCK seam: the provider stamps the Receipt's terminal time (epoch-ms) from
+/// the host clock — the reactor is a client, so its authoring time comes from a host
+/// port, passed in so the dispatcher stays PURE + unit-testable (the same shape as the
+/// framework `impureCapabilityReceipt(now)`). The app threads its real clock; a test threads a
+/// fixed `now` so the emitted Receipt JSON is deterministic.
+typedef HostClock = int Function();
+
+/// The minimal contract a generated per-task provider exposes. Generic in the typed
+/// Order/Result; the generated subtype binds them. `handleOrder` is the ONE seam a host
+/// loop calls per `requested` row.
+abstract interface class TaskProvider<O, R> {
+  /// The framework `impureCapability` ids this provider is bound to (provenance — the host
+  /// can assert it is draining the right capability). Carried as DATA, never hand-typed.
+  String get orderDirectiveId;
+  String get completeDirectiveId;
+  String get failDirectiveId;
+  String get blockDirectiveId;
+  String get deadLetterDirectiveId;
+
+  /// DECODE an incoming Order intent's payload JSON into the typed [O], run the
+  /// registered typed handler, and ENCODE the outcome into the ordinary Receipt intent — a
+  /// [NomosIntent] ready for the ONE write path (`dispatch`). `now` stamps the
+  /// terminal time. Decoding raw JSON happens HERE and only here; the handler the dev
+  /// writes sees ONLY the typed [O] and returns ONLY a typed [TaskOutcome].
+  NomosIntent handleOrder(String orderPayloadJson, {required HostClock now});
+
+  /// Convenience: decode an Order payload from an already-parsed map (the host may have
+  /// the row's `data` map in hand from a read). Same path as [handleOrder].
+  NomosIntent handleOrderMap(
+    Map<String, Object?> orderPayload, {
+    required HostClock now,
+  });
+}
+
+/// Decode an Order payload JSON string to a map for a generated `…Order.fromJson`.
+/// Shared so every generated provider decodes Orders identically (the symmetry of the
+/// client's `jsonEncode(toPayloadJson())`).
+Map<String, Object?> decodeOrderPayload(String orderPayloadJson) =>
+    (jsonDecode(orderPayloadJson) as Map<String, Object?>);

package/dart/lib/src/schema_validation.dart

@@ -0,0 +1,44 @@
+// 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.
+
+library;
+
+import 'package:json_schema/json_schema.dart';
+
+/// Thrown when a decoded JSON value fails a compiler-emitted Nomos JSON Schema.
+final class NomosJsonSchemaException implements Exception {
+  final String context;
+  final ValidationResults results;
+
+  const NomosJsonSchemaException(this.context, this.results);
+
+  @override
+  String toString() {
+    final errors = results.errors.map((e) => e.toString()).join('; ');
+    return 'NomosJsonSchemaException($context): $errors';
+  }
+}
+
+/// Validate [value] against a compiler-emitted JSON Schema map.
+ValidationResults validateNomosJsonSchema(
+  Map<String, Object?> schema,
+  Object? value, {
+  bool? validateFormats,
+}) =>
+    JsonSchema.create(schema).validate(value, validateFormats: validateFormats);
+
+/// Validate [value] and throw [NomosJsonSchemaException] if it does not conform.
+void requireNomosJsonSchema(
+  Map<String, Object?> schema,
+  Object? value, {
+  String context = 'nomos payload',
+  bool? validateFormats,
+}) {
+  final results =
+      validateNomosJsonSchema(schema, value, validateFormats: validateFormats);
+  if (!results.isValid) throw NomosJsonSchemaException(context, results);
+}