@githolon/dsl 0.45.0 → 0.47.0

package/dart/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 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.
+- Analyzer-clean under strict lints (curly-braces rule) — the two remaining unbraced ifs in the bridge are gone.
+
 ## 0.31.0
 
 - `NomosFieldMeta.fromBirth` — the registry surfaces BIRTH-PRESENCE LAW (`.fromBirth()` fields, tooling ≥0.42): a gate invariant guarantees the field present on every row, and the generated read models type it non-nullable.

package/dart/lib/src/errors.dart

@@ -22,9 +22,259 @@ import 'webview_bridge.dart' show NomosBridgeError, NomosErrorInfo;
 /// [NomosBridgeError]. Apps `switch` on the type / `code`, never scrape prose.
 NomosBridgeError nomosErrorFromInfo(NomosErrorInfo info) {
   if (info.code.startsWith('nomos.custody.')) return CustodyError.fromInfo(info);
+  if (info.code.startsWith('nomos.law.')) return LawMismatchError.fromInfo(info);
+  if (info.code.startsWith('nomos.auth.')) return AuthError.fromInfo(info);
+  if (info.code.startsWith('nomos.load.')) return LoadError.fromInfo(info);
   return NomosBridgeError(info.message, info: info);
 }
 
+/// THE ONE recommendedAction vocabulary, shared across EVERY typed error (custody, law, auth, load). A repair
+/// button branches on these stable strings, so there is exactly one lane per failure and no parallel spelling.
+/// [CustodyError.recommendedAction] already uses these strings — this names them so the other families reuse
+/// the SAME set rather than inventing their own.
+class NomosRecommendedAction {
+  NomosRecommendedAction._();
+
+  /// Regenerate the typed client against the deployed law (`githolon compile` / `npx nomos-compile`).
+  static const recompileClient = 'recompileClient';
+
+  /// Redeploy the client's law package to the workspace (`POST /v2/workspaces/<ws>/domains`).
+  static const redeployLaw = 'redeployLaw';
+
+  /// Re-acquire a fresh auth-provider token and reconnect.
+  static const reauth = 'reauth';
+
+  /// Quarantine the local snapshot and re-clone fresh (evict local custody).
+  static const quarantineLocalSnapshotAndReclone = 'quarantineLocalSnapshotAndReclone';
+
+  /// Ask the cloud to serve the full chain and retry (escalate cloud custody).
+  static const refetchFullHistoryAndRetry = 'refetchFullHistoryAndRetry';
+
+  /// Transient — retry the operation.
+  static const retry = 'retry';
+
+  /// Re-open the holon / reconnect fresh (the loaded runtime is unusable).
+  static const reopen = 'reopen';
+
+  /// No automatic remedy — surface to a human.
+  static const none = 'none';
+
+  /// A one-line, human-first sentence for [action] — used in the typed messages so a log line reads as prose.
+  static String sentence(String action) {
+    switch (action) {
+      case recompileClient:
+        return 'recompile the client (githolon compile / npx nomos-compile) against the deployed law';
+      case redeployLaw:
+        return 'redeploy the package (POST /v2/workspaces/<ws>/domains) so the workspace runs the client\'s law';
+      case reauth:
+        return 're-authenticate (acquire a fresh auth-provider token) and reconnect';
+      case quarantineLocalSnapshotAndReclone:
+        return 'quarantine the local snapshot and re-clone fresh';
+      case refetchFullHistoryAndRetry:
+        return 'refetch the full history from the cloud and retry';
+      case retry:
+        return 'retry the operation';
+      case reopen:
+        return 'reopen the holon (reconnect fresh)';
+      case none:
+        return 'no automatic remedy — inspect the error';
+      default:
+        return action;
+    }
+  }
+}
+
+/// LAW DRIFT — the client was generated under one law and the workspace runs another (`nomos.law.*`): either a
+/// §5 connect-time compat check, or a dispatch-time refusal when a payload's baked hash names law the workspace
+/// no longer runs. When [structurallyCompatible] is true the operation can still proceed (structural subtyping);
+/// when false it names the [incompatibleMember] that broke. REMEDY: `recompileClient` or `redeployLaw`.
+class LawMismatchError extends NomosBridgeError {
+  /// The stable machine code, e.g. `nomos.law.mismatch`.
+  final String code;
+
+  /// The workspace whose installed law differs.
+  final String? workspace;
+
+  /// The law hash the CLIENT was generated for.
+  final String? generatedFor;
+
+  /// The law hash the WORKSPACE actually runs.
+  final String? workspaceRuns;
+
+  /// The failing lane: directive id / query id / `connect` / `sync`.
+  final String? operation;
+
+  /// True/false when a structural compat verdict is known; null when undecided (a bare hash mismatch).
+  final bool? structurallyCompatible;
+
+  /// The structural member that broke compat, when [structurallyCompatible] is false and one was named.
+  final String? incompatibleMember;
+
+  /// The named remedy from [NomosRecommendedAction] (`recompileClient` | `redeployLaw`).
+  final String recommendedAction;
+
+  LawMismatchError({
+    required this.code,
+    required String message,
+    this.workspace,
+    this.generatedFor,
+    this.workspaceRuns,
+    this.operation,
+    this.structurallyCompatible,
+    this.incompatibleMember,
+    this.recommendedAction = NomosRecommendedAction.recompileClient,
+    NomosErrorInfo? info,
+  }) : super(message, info: info);
+
+  factory LawMismatchError.fromInfo(NomosErrorInfo info) {
+    String? attr(String name) {
+      final v = info.attributes['nomos.law.$name'] ?? info.attributes[name];
+      return v?.toString();
+    }
+
+    bool? compat() {
+      final v = info.attributes['nomos.law.structurallyCompatible'] ??
+          info.attributes['structurallyCompatible'] ??
+          info.attributes['structurally_compatible'];
+      if (v is bool) return v;
+      if (v == null) return null;
+      final s = v.toString();
+      if (s == 'true') return true;
+      if (s == 'false') return false;
+      return null;
+    }
+
+    return LawMismatchError(
+      code: info.code,
+      message: info.message,
+      workspace: info.workspace,
+      generatedFor: attr('generatedFor') ?? attr('generated_for') ?? attr('clientHash'),
+      workspaceRuns: attr('workspaceRuns') ?? attr('workspace_runs') ?? attr('installed'),
+      operation: info.operation ?? attr('operation'),
+      structurallyCompatible: compat(),
+      incompatibleMember: attr('incompatibleMember') ?? attr('incompatible_member') ?? attr('member'),
+      recommendedAction: attr('recommendedAction') ?? attr('recommended_action') ?? NomosRecommendedAction.recompileClient,
+      info: info,
+    );
+  }
+
+  /// The exact asked-for mismatch sentence:
+  /// "client generated for law <X>, workspace runs law <Y>; <compat verdict> — <remedy sentence>".
+  String get mismatchMessage {
+    final x = generatedFor ?? 'unknown';
+    final y = workspaceRuns ?? 'unknown';
+    final verdict = structurallyCompatible == true
+        ? 'structurally compatible — proceeding'
+        : (incompatibleMember != null
+            ? 'structurally incompatible on $incompatibleMember'
+            : 'structurally incompatible');
+    return 'client generated for law $x, workspace runs law $y; $verdict — ${NomosRecommendedAction.sentence(recommendedAction)}';
+  }
+
+  @override
+  String toString() => 'LawMismatchError($code): $mismatchMessage';
+}
+
+/// AUTH — the auth-provider token was missing/malformed/expired/rejected, or its issuer does not match the
+/// workspace's law-declared key (`nomos.auth.*`, e.g. `nomos.auth.issuer_mismatch`, `nomos.auth.token_invalid`,
+/// `nomos.auth.token_expired`). REMEDY is always `reauth`: acquire a fresh token and reconnect.
+class AuthError extends NomosBridgeError {
+  /// The stable machine code, e.g. `nomos.auth.issuer_mismatch`.
+  final String code;
+
+  /// The workspace the auth was for.
+  final String? workspace;
+
+  /// The token issuer, when one was decodable (present on an issuer mismatch).
+  final String? issuer;
+
+  /// The failing lane (e.g. `connect` / a birth directive id).
+  final String? operation;
+
+  /// The named remedy — always `reauth`.
+  final String recommendedAction;
+
+  AuthError({
+    required this.code,
+    required String message,
+    this.workspace,
+    this.issuer,
+    this.operation,
+    this.recommendedAction = NomosRecommendedAction.reauth,
+    NomosErrorInfo? info,
+  }) : super(message, info: info);
+
+  factory AuthError.fromInfo(NomosErrorInfo info) {
+    String? attr(String name) {
+      final v = info.attributes['nomos.auth.$name'] ?? info.attributes[name];
+      return v?.toString();
+    }
+
+    return AuthError(
+      code: info.code,
+      message: info.message,
+      workspace: info.workspace,
+      issuer: attr('issuer'),
+      operation: info.operation ?? attr('operation'),
+      recommendedAction: attr('recommendedAction') ?? attr('recommended_action') ?? NomosRecommendedAction.reauth,
+      info: info,
+    );
+  }
+
+  @override
+  String toString() =>
+      'AuthError($code${workspace != null ? ', workspace: $workspace' : ''}'
+      '${issuer != null ? ', issuer: $issuer' : ''}, recommendedAction: $recommendedAction): $message';
+}
+
+/// LOAD — a runtime artifact (the holon wasm, a manifest, the runner) could not be fetched or instantiated
+/// (`nomos.load.*`, e.g. `nomos.load.wasm_fetch_failed`, `nomos.load.instantiate_failed`,
+/// `nomos.load.manifest_failed`). This is a transport/runtime fault, never a law refusal. REMEDY: `retry` for a
+/// transient fetch, `reopen` when the loaded runtime is unusable.
+class LoadError extends NomosBridgeError {
+  /// The stable machine code, e.g. `nomos.load.wasm_fetch_failed`.
+  final String code;
+
+  /// WHICH artifact failed to load (e.g. `holon.wasm`, `manifests`, the runner).
+  final String? artifact;
+
+  /// The URL the artifact was fetched from, when known.
+  final String? sourceUrl;
+
+  /// The named remedy from [NomosRecommendedAction] (`retry` | `reopen`).
+  final String recommendedAction;
+
+  LoadError({
+    required this.code,
+    required String message,
+    this.artifact,
+    this.sourceUrl,
+    this.recommendedAction = NomosRecommendedAction.retry,
+    NomosErrorInfo? info,
+  }) : super(message, info: info);
+
+  factory LoadError.fromInfo(NomosErrorInfo info) {
+    String? attr(String name) {
+      final v = info.attributes['nomos.load.$name'] ?? info.attributes[name];
+      return v?.toString();
+    }
+
+    return LoadError(
+      code: info.code,
+      message: info.message,
+      artifact: attr('artifact'),
+      sourceUrl: attr('sourceUrl') ?? attr('source_url') ?? attr('url'),
+      recommendedAction: attr('recommendedAction') ?? attr('recommended_action') ?? NomosRecommendedAction.retry,
+      info: info,
+    );
+  }
+
+  @override
+  String toString() =>
+      'LoadError($code${artifact != null ? ', artifact: $artifact' : ''}'
+      '${sourceUrl != null ? ', sourceUrl: $sourceUrl' : ''}, recommendedAction: $recommendedAction): $message';
+}
+
 /// The custody phase a [CustodyError] was raised in.
 enum CustodyPhase { fold, author, fetch, unknown }