@githolon/dsl 0.58.0 → 0.59.0

package/dart/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 0.38.0
+- SPLIT: the pure data core (wire types, offer codec, NomosReads, aggregate meta, schema validation, error info) moved to the new `nomos_types` package; `nomos_client` depends on and re-exports it, so existing imports are unchanged. Frontend/UI code can now depend on `nomos_types` alone.
+
+## 0.37.1
+
+- Doc fix: `NomosBridge.attestedRead` docs now match the runtime — the call answers `{ entry: {queryId, result, attestation: …} }`; pass `result['entry']` as one `offerDirective` `attestations` element.
+
 ## 0.32.0
 
 - SPATIAL READS: `NomosBbox` + `NomosBridge.spatialWithin(spatialId, bbox)` + `watchSpatial(...)` — the R*Tree probe surfaces on the bridge; generated clients (tooling ≥0.46) emit typed `sitesByBounds({required NomosBbox bbox})` + watch accessors.

package/dart/lib/nomos_client.dart

@@ -23,25 +23,17 @@
 ///    which re-exports this framework barrel PLUS every generated domain.
 library;
 
-export 'src/wire.dart';
-export 'src/driver.dart';
-export 'src/offer.dart';
-// THE TRI-STATE SLOT — NomosSlot<T> (Omitted / ExplicitNull / Present) for `nullable`/`clearable`
-// declared fields (architecture/null_semantics.md); generated code references it, never redefines it.
-export 'src/null_slot.dart';
+// THE PURE-DATA CORE — the hand-written kernel wire types, the `offer(intent)` codec,
+// the tri-state `NomosSlot<T>`, `NomosReads`, schema validation, runtime aggregate
+// metadata, the data-only error/trace types, and the typed diagnostics moved to the
+// standalone `nomos_types` package (so generated per-domain TYPES files resolve against
+// it alone). Re-exported here so this barrel's public API is unchanged for consumers.
+export 'package:nomos_types/nomos_types.dart';
 // homeNameOf(subject) — the canonical home-workspace name (parity with @githolon/client + the law side).
 export 'src/home.dart';
-export 'src/subscriptions.dart';
-export 'src/schema_validation.dart';
-// RUNTIME AGGREGATE METADATA — the generated per-domain registry's support types
-// (lookup by aggregateType for generic surfaces: history UIs, op renderers, agents).
-export 'src/aggregate_meta.dart';
 // THE WEBVIEW BRIDGE (app-binding boundary) — the async Dart runtime that drives the REAL githolon running
 // in a WebView, so the generated typed client never needs a `MemoryPersistence` fake.
 export 'src/webview_bridge.dart';
-// TYPED DIAGNOSTICS (co2 feedback req 7) — the fixed set of ways the home-birth ceremony can fail, each
-// extending NomosBridgeError so existing handlers still catch them, named so the app can branch on `is`.
-export 'src/errors.dart';
 // The PROVIDER boundary (server-side capability-provider SDK runtime: TaskOutcome /
 // TaskSuccess / TaskFailure / TaskResult / TaskProvider / HostClock). The symmetric twin
 // of `offer.dart`; the generated per-task provider classes build on it.

package/dart/lib/src/provider.dart

@@ -31,7 +31,7 @@ library;
 
 import 'dart:convert';
 
-import 'offer.dart' show NomosIntent;
+import 'package:nomos_types/nomos_types.dart' show NomosIntent;
 
 /// The typed OUTCOME a provider handler returns for one Obligation: success, failure, blocked,
 /// or dead-lettered.

package/dart/lib/src/webview_bridge.dart

@@ -18,7 +18,8 @@ import 'dart:async';
 import 'dart:convert';
 import 'dart:math';
 
-import 'errors.dart' show nomosErrorFromInfo;
+import 'package:nomos_types/nomos_types.dart'
+    show nomosErrorFromInfo, NomosTraceContext, NomosErrorInfo;
 
 /// The protocol version the runner and the bridge agree on (`webview-runner.mjs` `WEBVIEW_BRIDGE_VERSION`).
 const int kWebviewBridgeVersion = 1;
@@ -31,180 +32,6 @@ abstract interface class BridgeTransport {
   Stream<Map<String, Object?>> get messages;
 }
 
-/// Trace/span context carried over the bridge as plain JSON. It is intentionally OpenTelemetry-shaped without
-/// importing an OTel SDK: apps can map it to spans later, while Nomos stays dependency-light at the runtime edge.
-class NomosTraceContext {
-  final String? traceId;
-  final String? spanId;
-  final String? parentSpanId;
-  final bool? sampled;
-
-  const NomosTraceContext({
-    this.traceId,
-    this.spanId,
-    this.parentSpanId,
-    this.sampled,
-  });
-
-  factory NomosTraceContext.fromJson(Object? value) {
-    if (value is! Map) return const NomosTraceContext();
-    final m = value.cast<String, Object?>();
-    return NomosTraceContext(
-      traceId: m['traceId']?.toString(),
-      spanId: m['spanId']?.toString(),
-      parentSpanId: m['parentSpanId']?.toString(),
-      sampled: m['sampled'] is bool ? m['sampled'] as bool : null,
-    );
-  }
-
-  Map<String, Object?> toJson() => {
-        if (traceId != null) 'traceId': traceId,
-        if (spanId != null) 'spanId': spanId,
-        if (parentSpanId != null) 'parentSpanId': parentSpanId,
-        if (sampled != null) 'sampled': sampled,
-      };
-
-  bool get isEmpty =>
-      traceId == null &&
-      spanId == null &&
-      parentSpanId == null &&
-      sampled == null;
-}
-
-/// Structured runtime error detail for the bridge boundary. Keep this data-only: it is safe to serialize, log,
-/// persist, or later attach to an OpenTelemetry span without importing tracing into the core client package.
-class NomosErrorInfo {
-  final String code;
-  final String message;
-  final String component;
-  final String? operation;
-  final String? workspace;
-  final String? domain;
-  final String? directiveId;
-  final NomosTraceContext trace;
-  final Map<String, Object?> attributes;
-  final NomosErrorInfo? cause;
-
-  const NomosErrorInfo({
-    required this.code,
-    required this.message,
-    this.component = 'nomos.client',
-    this.operation,
-    this.workspace,
-    this.domain,
-    this.directiveId,
-    this.trace = const NomosTraceContext(),
-    this.attributes = const {},
-    this.cause,
-  });
-
-  factory NomosErrorInfo.legacy(
-    Object? message, {
-    String code = 'nomos.bridge.error',
-    String component = 'nomos.client',
-    String? operation,
-    NomosTraceContext trace = const NomosTraceContext(),
-  }) {
-    return NomosErrorInfo(
-      code: code,
-      message: (message ?? 'the githolon refused the request').toString(),
-      component: component,
-      operation: operation,
-      trace: trace,
-    );
-  }
-
-  factory NomosErrorInfo.fromJson(
-    Object? value, {
-    Object? fallbackMessage,
-    String? fallbackOperation,
-    NomosTraceContext fallbackTrace = const NomosTraceContext(),
-  }) {
-    if (value is! Map) {
-      return NomosErrorInfo.legacy(
-        fallbackMessage,
-        operation: fallbackOperation,
-        trace: fallbackTrace,
-      );
-    }
-    final m = value.cast<String, Object?>();
-    final trace = NomosTraceContext.fromJson(m['trace']);
-    return NomosErrorInfo(
-      code: (m['code'] ?? 'nomos.bridge.error').toString(),
-      message: (m['message'] ??
-              fallbackMessage ??
-              'the githolon refused the request')
-          .toString(),
-      component: (m['component'] ?? 'nomos.client').toString(),
-      operation: m['operation']?.toString() ?? fallbackOperation,
-      workspace: m['workspace']?.toString(),
-      domain: m['domain']?.toString(),
-      directiveId: m['directiveId']?.toString(),
-      trace: trace.isEmpty ? fallbackTrace : trace,
-      attributes:
-          ((m['attributes'] as Map?)?.cast<String, Object?>()) ?? const {},
-      cause: m['cause'] == null
-          ? null
-          : NomosErrorInfo.fromJson(m['cause'],
-              fallbackOperation: fallbackOperation),
-    );
-  }
-
-  factory NomosErrorInfo.fromBridgeMessage(
-    Map<String, Object?> message, {
-    String? fallbackOperation,
-    NomosTraceContext fallbackTrace = const NomosTraceContext(),
-    Object? fallbackMessage,
-  }) {
-    return NomosErrorInfo.fromJson(
-      message['errorInfo'],
-      fallbackMessage: message['error'] ?? fallbackMessage,
-      fallbackOperation: fallbackOperation,
-      fallbackTrace: fallbackTrace,
-    );
-  }
-
-  Map<String, Object?> toJson() => {
-        'code': code,
-        'message': message,
-        'component': component,
-        if (operation != null) 'operation': operation,
-        if (workspace != null) 'workspace': workspace,
-        if (domain != null) 'domain': domain,
-        if (directiveId != null) 'directiveId': directiveId,
-        if (!trace.isEmpty) 'trace': trace.toJson(),
-        if (attributes.isNotEmpty) 'attributes': attributes,
-        if (cause != null) 'cause': cause!.toJson(),
-      };
-
-  /// Attribute map suitable for attaching to a future OTel span/event. The keys are stable and low-cardinality
-  /// where possible; high-cardinality values stay explicit (`workspace`, `domain`, directive) so apps can redact.
-  Map<String, Object?> toTelemetryAttributes() => {
-        'exception.type': code,
-        'exception.message': message,
-        'nomos.error.code': code,
-        'nomos.component': component,
-        if (operation != null) 'nomos.operation': operation,
-        if (workspace != null) 'nomos.workspace': workspace,
-        if (domain != null) 'nomos.domain': domain,
-        if (directiveId != null) 'nomos.directive_id': directiveId,
-        if (trace.traceId != null) 'trace_id': trace.traceId,
-        if (trace.spanId != null) 'span_id': trace.spanId,
-        ...attributes,
-      };
-}
-
-/// A typed refusal surfaced from the githolon's gate (a law refusal, a drift, a malformed op). Carries the
-/// human-first message verbatim plus structured detail for logging, UI mapping, and future OTel export.
-class NomosBridgeError implements Exception {
-  final String message;
-  final NomosErrorInfo info;
-  NomosBridgeError(this.message, {NomosErrorInfo? info})
-      : info = info ?? NomosErrorInfo.legacy(message);
-  @override
-  String toString() => 'NomosBridgeError: $message';
-}
-
 /// Live byte-progress of a custody pack transfer (the big initial clone / heavy resync over `/pack`).
 /// [total] is the host's REAL packed size from `Content-Length` (known before the first body byte — the
 /// warm host packs into memory then sends), so [fraction] is a truthful 0→1 bar, never an estimate.
@@ -1191,14 +1018,13 @@ class NomosBridge {
   /// ATTESTED READ — serve + SIGN a declared query over a COLOCATED source session's certified fold (the
   /// dynamic-source trust lane; architecture/dynamic_source_attested_reads.md). In a [NomosTestHarness.cluster]
   /// (one engine plane, many sessions) this fulfils the read IN-PROCESS from the [from] session and returns
-  /// the signed envelope `{ ok, rows, attestation:{ source_genesis, … } }` — hand it back as an
-  /// [offerDirective] `attestations` element, or read `attestation.source_genesis` to enrol the source in a
-  /// reader's allow-list. [args] are the query params. [session] is the caller/reader session (defaults to
-  /// this view's bound session).
+  /// `{ entry: {queryId, result, attestation:{source_genesis, public_key, …}} }` — pass `result['entry']`
+  /// (the whole entry map) as one [offerDirective] `attestations` element, or read
+  /// `entry['attestation']['source_genesis']` to enrol the source in a reader's allow-list. [args] are the
+  /// query params. [session] is the caller/reader session (defaults to this view's bound session).
   /// [attestorSecret] is the source's base64 read-attestor secret (from [authorKeygen]); when omitted the
   /// source session's connect-time `authorSecret` signs. [nowMs] stamps the freshness clock (defaults to the
-  /// source's own clock). The returned `entry` is `{queryId, result, attestation:{source_genesis, public_key,
-  /// …}}` — pass the whole `entry` as one [offerDirective] `attestations` element.
+  /// source's own clock).
   Future<Map<String, Object?>> attestedRead({
     required String from,
     required String queryId,

package/dart/lib/testing.dart

@@ -0,0 +1,13 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.
+//
+/// The TEST-ONLY entrypoint (`package:nomos_client/testing.dart`) — the headless harness
+/// (NomosTestHarness drives the REAL githolon under `dart test`, no WebView) and the
+/// node-runner transport it rides. Depend on this ONLY from `dev_dependencies`-scoped
+/// packages: it pulls `dart:io` and process management, which never belong in app code.
+/// The layered-packages emit (`dart.packages.test`) re-exports this as the generated
+/// test package's harness surface.
+library;
+
+export 'src/node_runner_transport.dart';
+export 'src/test_harness.dart';

package/dart/pubspec.lock

@@ -185,6 +185,13 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "2.0.2"
+  nomos_types:
+    dependency: "direct main"
+    description:
+      path: "../dart_types"
+      relative: true
+    source: path
+    version: "0.1.0"
   package_config:
     dependency: transitive
     description:

package/dart/pubspec.yaml

@@ -11,12 +11,16 @@ description: >-
   Nomos 2 Dart frontend types — the hand-written kernel wire types plus the
   code-generated per-domain aggregate + directive-payload types. (De)serializes
   the EXACT serde JSON the Rust kernel + projection produce/consume.
-version: 0.37.0
+version: 0.38.0
 
 environment:
   sdk: ^3.5.0
 
 dependencies:
+  # The pure-data core (wire types, offer codec, NomosReads, schema validation, error
+  # info). nomos_client depends on and re-exports it, so existing imports are unchanged.
+  # For local monorepo dev, pubspec_overrides.yaml points this at ../dart_types.
+  nomos_types: ^0.1.0
   json_schema: ^5.2.2
   crypto: ^3.0.0
 

package/dart/pubspec_overrides.yaml

@@ -0,0 +1,7 @@
+# IN-REPO RESOLUTION: nomos_types lives in this monorepo (dsl/dart_types) and is not yet on
+# pub.dev — this override makes `dart pub get` resolve it from source for everyone cloning the
+# repo. Once nomos_types is published, consumers outside the repo resolve the hosted ^0.1.0;
+# this file only affects in-repo development.
+dependency_overrides:
+  nomos_types:
+    path: ../dart_types

package/dart_types/CHANGELOG.md

@@ -0,0 +1,6 @@
+## 0.1.0
+- Initial release. The pure-data core split out of `nomos_client`: kernel wire types,
+  the offer codec, `NomosReads`, the tri-state `NomosSlot`, aggregate metadata, schema
+  validation, and the data-only error/trace types (`NomosBridgeError`, `NomosErrorInfo`,
+  `NomosTraceContext`) plus the typed diagnostics. No transport, no bridge, no runtime —
+  generated per-domain TYPES files depend on only this.

package/dart_types/lib/nomos_types.dart

@@ -0,0 +1,29 @@
+// 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}.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/// Nomos 2 pure-data core — the hand-written kernel WIRE/data types with NO transport,
+/// NO bridge, NO runtime, NO Flutter. Generated per-domain TYPES files depend on ONLY
+/// this, so they resolve without pulling in sessions/workspace lifecycle. The
+/// `nomos_client` package depends on and re-exports this barrel, so existing
+/// `package:nomos_client/nomos_client.dart` imports are unchanged.
+///
+///  - The kernel WIRE types (`Value`, `Field`/`WireField`, `Hlc`, `Op`, `FieldOp`,
+///    `Event`, `Schema`/`WireDriver`) — byte-compatible with serde_json.
+///  - The ONE effectful write verb `offer(intent)` + the typed reactive read engine
+///    `NomosReads`.
+///  - The tri-state `NomosSlot<T>`, runtime aggregate metadata, schema validation, and
+///    the data-only error/trace types (`NomosBridgeError`, `NomosErrorInfo`,
+///    `NomosTraceContext`) plus the typed diagnostics.
+library;
+
+export 'src/wire.dart';
+export 'src/driver.dart';
+export 'src/offer.dart';
+export 'src/null_slot.dart';
+export 'src/subscriptions.dart';
+export 'src/schema_validation.dart';
+export 'src/aggregate_meta.dart';
+export 'src/error_info.dart';
+export 'src/errors.dart';

package/dart_types/lib/src/error_info.dart

@@ -0,0 +1,184 @@
+// 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}.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/// Data-only error/trace types for the bridge boundary. These carry NO transport, NO
+/// bridge, NO runtime — they are pure serializable value types, so they live in
+/// `nomos_types` and are safe to depend on from generated types files + UI code. The
+/// async [NomosBridge] runtime (in `nomos_client`'s `webview_bridge.dart`) builds on them.
+library;
+
+/// Trace/span context carried over the bridge as plain JSON. It is intentionally OpenTelemetry-shaped without
+/// importing an OTel SDK: apps can map it to spans later, while Nomos stays dependency-light at the runtime edge.
+class NomosTraceContext {
+  final String? traceId;
+  final String? spanId;
+  final String? parentSpanId;
+  final bool? sampled;
+
+  const NomosTraceContext({
+    this.traceId,
+    this.spanId,
+    this.parentSpanId,
+    this.sampled,
+  });
+
+  factory NomosTraceContext.fromJson(Object? value) {
+    if (value is! Map) return const NomosTraceContext();
+    final m = value.cast<String, Object?>();
+    return NomosTraceContext(
+      traceId: m['traceId']?.toString(),
+      spanId: m['spanId']?.toString(),
+      parentSpanId: m['parentSpanId']?.toString(),
+      sampled: m['sampled'] is bool ? m['sampled'] as bool : null,
+    );
+  }
+
+  Map<String, Object?> toJson() => {
+        if (traceId != null) 'traceId': traceId,
+        if (spanId != null) 'spanId': spanId,
+        if (parentSpanId != null) 'parentSpanId': parentSpanId,
+        if (sampled != null) 'sampled': sampled,
+      };
+
+  bool get isEmpty =>
+      traceId == null &&
+      spanId == null &&
+      parentSpanId == null &&
+      sampled == null;
+}
+
+/// Structured runtime error detail for the bridge boundary. Keep this data-only: it is safe to serialize, log,
+/// persist, or later attach to an OpenTelemetry span without importing tracing into the core client package.
+class NomosErrorInfo {
+  final String code;
+  final String message;
+  final String component;
+  final String? operation;
+  final String? workspace;
+  final String? domain;
+  final String? directiveId;
+  final NomosTraceContext trace;
+  final Map<String, Object?> attributes;
+  final NomosErrorInfo? cause;
+
+  const NomosErrorInfo({
+    required this.code,
+    required this.message,
+    this.component = 'nomos.client',
+    this.operation,
+    this.workspace,
+    this.domain,
+    this.directiveId,
+    this.trace = const NomosTraceContext(),
+    this.attributes = const {},
+    this.cause,
+  });
+
+  factory NomosErrorInfo.legacy(
+    Object? message, {
+    String code = 'nomos.bridge.error',
+    String component = 'nomos.client',
+    String? operation,
+    NomosTraceContext trace = const NomosTraceContext(),
+  }) {
+    return NomosErrorInfo(
+      code: code,
+      message: (message ?? 'the githolon refused the request').toString(),
+      component: component,
+      operation: operation,
+      trace: trace,
+    );
+  }
+
+  factory NomosErrorInfo.fromJson(
+    Object? value, {
+    Object? fallbackMessage,
+    String? fallbackOperation,
+    NomosTraceContext fallbackTrace = const NomosTraceContext(),
+  }) {
+    if (value is! Map) {
+      return NomosErrorInfo.legacy(
+        fallbackMessage,
+        operation: fallbackOperation,
+        trace: fallbackTrace,
+      );
+    }
+    final m = value.cast<String, Object?>();
+    final trace = NomosTraceContext.fromJson(m['trace']);
+    return NomosErrorInfo(
+      code: (m['code'] ?? 'nomos.bridge.error').toString(),
+      message: (m['message'] ??
+              fallbackMessage ??
+              'the githolon refused the request')
+          .toString(),
+      component: (m['component'] ?? 'nomos.client').toString(),
+      operation: m['operation']?.toString() ?? fallbackOperation,
+      workspace: m['workspace']?.toString(),
+      domain: m['domain']?.toString(),
+      directiveId: m['directiveId']?.toString(),
+      trace: trace.isEmpty ? fallbackTrace : trace,
+      attributes:
+          ((m['attributes'] as Map?)?.cast<String, Object?>()) ?? const {},
+      cause: m['cause'] == null
+          ? null
+          : NomosErrorInfo.fromJson(m['cause'],
+              fallbackOperation: fallbackOperation),
+    );
+  }
+
+  factory NomosErrorInfo.fromBridgeMessage(
+    Map<String, Object?> message, {
+    String? fallbackOperation,
+    NomosTraceContext fallbackTrace = const NomosTraceContext(),
+    Object? fallbackMessage,
+  }) {
+    return NomosErrorInfo.fromJson(
+      message['errorInfo'],
+      fallbackMessage: message['error'] ?? fallbackMessage,
+      fallbackOperation: fallbackOperation,
+      fallbackTrace: fallbackTrace,
+    );
+  }
+
+  Map<String, Object?> toJson() => {
+        'code': code,
+        'message': message,
+        'component': component,
+        if (operation != null) 'operation': operation,
+        if (workspace != null) 'workspace': workspace,
+        if (domain != null) 'domain': domain,
+        if (directiveId != null) 'directiveId': directiveId,
+        if (!trace.isEmpty) 'trace': trace.toJson(),
+        if (attributes.isNotEmpty) 'attributes': attributes,
+        if (cause != null) 'cause': cause!.toJson(),
+      };
+
+  /// Attribute map suitable for attaching to a future OTel span/event. The keys are stable and low-cardinality
+  /// where possible; high-cardinality values stay explicit (`workspace`, `domain`, directive) so apps can redact.
+  Map<String, Object?> toTelemetryAttributes() => {
+        'exception.type': code,
+        'exception.message': message,
+        'nomos.error.code': code,
+        'nomos.component': component,
+        if (operation != null) 'nomos.operation': operation,
+        if (workspace != null) 'nomos.workspace': workspace,
+        if (domain != null) 'nomos.domain': domain,
+        if (directiveId != null) 'nomos.directive_id': directiveId,
+        if (trace.traceId != null) 'trace_id': trace.traceId,
+        if (trace.spanId != null) 'span_id': trace.spanId,
+        ...attributes,
+      };
+}
+
+/// A typed refusal surfaced from the githolon's gate (a law refusal, a drift, a malformed op). Carries the
+/// human-first message verbatim plus structured detail for logging, UI mapping, and future OTel export.
+class NomosBridgeError implements Exception {
+  final String message;
+  final NomosErrorInfo info;
+  NomosBridgeError(this.message, {NomosErrorInfo? info})
+      : info = info ?? NomosErrorInfo.legacy(message);
+  @override
+  String toString() => 'NomosBridgeError: $message';
+}

package/{dart → dart_types}/lib/src/errors.dart

@@ -14,7 +14,7 @@
 /// All extend [NomosBridgeError] so existing `catch (NomosBridgeError)` handlers still catch them.
 library;
 
-import 'webview_bridge.dart' show NomosBridgeError, NomosErrorInfo;
+import 'error_info.dart' show NomosBridgeError, NomosErrorInfo;
 
 /// Mint the MOST SPECIFIC typed error for a structured refusal — the one construction point the bridge
 /// uses everywhere it surfaces an `errorInfo`. A `nomos.custody.*` code becomes a [CustodyError] (typed,