@githolon/dsl 0.32.0 → 0.33.0

package/dart/lib/src/errors.dart

@@ -14,7 +14,111 @@
 /// All extend [NomosBridgeError] so existing `catch (NomosBridgeError)` handlers still catch them.
 library;
 
-import 'webview_bridge.dart' show NomosBridgeError;
+import 'webview_bridge.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,
+/// recoverable, carrying the eviction/escalation decision fields); everything else stays the generic
+/// [NomosBridgeError]. Apps `switch` on the type / `code`, never scrape prose.
+NomosBridgeError nomosErrorFromInfo(NomosErrorInfo info) {
+  if (info.code.startsWith('nomos.custody.')) return CustodyError.fromInfo(info);
+  return NomosBridgeError(info.message, info: info);
+}
+
+/// The custody phase a [CustodyError] was raised in.
+enum CustodyPhase { fold, author, fetch, unknown }
+
+/// Where the incomplete custody came from — the axis of the recovery decision.
+enum CustodySource { localSnapshot, cloudPack, unknown }
+
+/// A TYPED, RECOVERABLE CUSTODY ERROR — local custody (the clone/snapshot this holon folds from) is
+/// missing history the operation needed (`nomos.custody.shallow_insufficient` /
+/// `nomos.custody.missing_object`), and the in-client gap-fill repair could not complete it.
+///
+/// This replaces pattern-matching `shallow-insufficient` out of a stringly [NomosBridgeError]: the app
+/// switches on [code] and decides from the structured fields whether to EVICT LOCAL CUSTODY
+/// ([recommendedAction] == `quarantineLocalSnapshotAndReclone` — quarantine the snapshot, `inspectSnapshot`
+/// / `recoverFrom`, reconnect fresh) or ESCALATE CLOUD CUSTODY (`refetchFullHistoryAndRetry` — the cloud
+/// must serve the full chain). Trace IDs ride [NomosBridgeError.info.trace] as on every bridge error.
+class CustodyError extends NomosBridgeError {
+  /// The stable machine code, e.g. `nomos.custody.shallow_insufficient`.
+  final String code;
+
+  /// The workspace whose custody is incomplete.
+  final String? workspace;
+
+  /// The ref being folded (e.g. `refs/heads/main`).
+  final String? ref;
+
+  /// The ref's head commit at the time of the fault, when resolvable.
+  final String? head;
+
+  /// The missing object id the fold stopped at, when the kernel named one.
+  final String? missingObject;
+
+  /// The operation phase that hit the gap: fold (read), author (offer), fetch (the repair itself).
+  final CustodyPhase phase;
+
+  /// Provenance of the incomplete custody: a restored local snapshot, or a cloud-served pack.
+  final CustodySource source;
+
+  /// True when a known recovery lane exists (it always does for custody gaps — see [recommendedAction]).
+  final bool recoverable;
+
+  /// The named remedy: `quarantineLocalSnapshotAndReclone` | `refetchFullHistoryAndRetry`.
+  final String recommendedAction;
+
+  CustodyError({
+    required this.code,
+    required String message,
+    this.workspace,
+    this.ref,
+    this.head,
+    this.missingObject,
+    this.phase = CustodyPhase.unknown,
+    this.source = CustodySource.unknown,
+    this.recoverable = true,
+    this.recommendedAction = 'refetchFullHistoryAndRetry',
+    NomosErrorInfo? info,
+  }) : super(message, info: info);
+
+  /// Decode the structured custody payload the client attaches (`nomos.custody.*` attributes).
+  factory CustodyError.fromInfo(NomosErrorInfo info) {
+    String? attr(String name) {
+      final v = info.attributes['nomos.custody.$name'] ?? info.attributes[name];
+      return v?.toString();
+    }
+
+    return CustodyError(
+      code: info.code,
+      message: info.message,
+      workspace: info.workspace,
+      ref: attr('ref'),
+      head: attr('head'),
+      missingObject: attr('missing_object') ?? attr('missingObject'),
+      phase: CustodyPhase.values.firstWhere(
+        (p) => p.name == attr('phase'),
+        orElse: () => CustodyPhase.unknown,
+      ),
+      source: CustodySource.values.firstWhere(
+        (s) => s.name == attr('source'),
+        orElse: () => CustodySource.unknown,
+      ),
+      recoverable: attr('recoverable') != 'false',
+      recommendedAction: attr('recommended_action') ?? attr('recommendedAction') ?? 'refetchFullHistoryAndRetry',
+      info: info,
+    );
+  }
+
+  /// True when the remedy is to quarantine the local snapshot and re-clone (evict local custody).
+  bool get shouldEvictLocalCustody => recommendedAction == 'quarantineLocalSnapshotAndReclone';
+
+  @override
+  String toString() =>
+      'CustodyError($code${workspace != null ? ', workspace: $workspace' : ''}'
+      '${ref != null ? ', ref: $ref' : ''}${missingObject != null ? ', missing: $missingObject' : ''}'
+      ', phase: ${phase.name}, source: ${source.name}, recommendedAction: $recommendedAction): $message';
+}
 
 /// The auth-provider access token the cloud was given was missing, malformed, expired, or rejected — the
 /// cloud answered 401 / "invalid token" on a lane that requires a verified principal (every birth does).

package/dart/lib/src/webview_bridge.dart

@@ -17,6 +17,8 @@ library;
 import 'dart:async';
 import 'dart:math';
 
+import 'errors.dart' show nomosErrorFromInfo;
+
 /// The protocol version the runner and the bridge agree on (`webview-runner.mjs` `WEBVIEW_BRIDGE_VERSION`).
 const int kWebviewBridgeVersion = 1;
 
@@ -336,7 +338,7 @@ class NomosBridge {
           final info = NomosErrorInfo.fromBridgeMessage(m,
               fallbackMessage: 'the watch read failed',
               fallbackOperation: 'watch');
-          ctrl.addError(NomosBridgeError(info.message, info: info));
+          ctrl.addError(nomosErrorFromInfo(info));
         } else {
           ctrl.add((m['rows'] as List?) ?? const []);
         }
@@ -349,7 +351,7 @@ class NomosBridge {
           final info = NomosErrorInfo.fromBridgeMessage(m,
               fallbackMessage: 'the compat watch failed',
               fallbackOperation: 'watchCompatibility');
-          cctrl.addError(NomosBridgeError(info.message, info: info));
+          cctrl.addError(nomosErrorFromInfo(info));
         } else {
           cctrl.add(((m['rows'] as Map?)?.cast<String, Object?>()) ?? const {});
         }
@@ -410,7 +412,7 @@ class NomosBridge {
           fallbackOperation: op,
           fallbackTrace: trace,
           fallbackMessage: 'the githolon refused the request');
-      completer.completeError(NomosBridgeError(info.message, info: info));
+      completer.completeError(nomosErrorFromInfo(info));
     }
   }
 
@@ -931,7 +933,7 @@ class NomosBridge {
             code: 'nomos.bridge.disposed',
             operation: _pendingOps[entry.key],
             trace: trace);
-        c.completeError(NomosBridgeError(info.message, info: info));
+        c.completeError(nomosErrorFromInfo(info));
       }
     }
     _pending.clear();

package/dart/test/webview_bridge_test.dart

@@ -61,6 +61,36 @@ class FakeRunner implements BridgeTransport {
                 'attributes': {'test.case': 'refusal'}
               }
             });
+          } else if (intentJson.contains('"directiveId":"custodyGap"')) {
+            // The client's typed custody error: structured errorInfo, code=nomos.custody.*.
+            _incoming.add({
+              'v': kWebviewBridgeVersion,
+              'id': id,
+              'ok': false,
+              'error':
+                  'shallow-insufficient: fold refs/heads/main: find commit: NotFound',
+              'errorInfo': {
+                'code': 'nomos.custody.shallow_insufficient',
+                'message':
+                    'shallow-insufficient: fold refs/heads/main: find commit: NotFound',
+                'component': 'nomos.custody',
+                'operation': 'offer',
+                'workspace': 'ws-1',
+                'trace': message['trace'],
+                'attributes': {
+                  'nomos.custody.ref': 'refs/heads/main',
+                  'nomos.custody.head':
+                      'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+                  'nomos.custody.missing_object':
+                      'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
+                  'nomos.custody.phase': 'author',
+                  'nomos.custody.source': 'localSnapshot',
+                  'nomos.custody.recoverable': true,
+                  'nomos.custody.recommended_action':
+                      'quarantineLocalSnapshotAndReclone',
+                }
+              }
+            });
           } else {
             _incoming.add(reply({'head': 'HEAD-offer'}));
           }
@@ -420,6 +450,41 @@ void main() {
     expect(e.info.toTelemetryAttributes()['nomos.operation'], 'offer');
   });
 
+  test(
+      'a custody fault surfaces as the TYPED CustodyError (switch on code, never scrape prose)',
+      () async {
+    await bridge.ready;
+    Object? err;
+    try {
+      await bridge.offer(
+          intentBytes: base64Encode(utf8.encode(jsonEncode({
+        'v': 2,
+        'intent': {
+          'domain': 'x',
+          'directiveId': 'custodyGap',
+          'payload': {},
+          'domainHash': 'h'
+        }
+      }))));
+    } on NomosBridgeError catch (e) {
+      err = e; // still catchable as the generic bridge error
+    }
+    expect(err, isA<CustodyError>());
+    final e = err as CustodyError;
+    expect(e.code, 'nomos.custody.shallow_insufficient');
+    expect(e.workspace, 'ws-1');
+    expect(e.ref, 'refs/heads/main');
+    expect(e.head, 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa');
+    expect(e.missingObject, 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb');
+    expect(e.phase, CustodyPhase.author);
+    expect(e.source, CustodySource.localSnapshot);
+    expect(e.recoverable, isTrue);
+    expect(e.recommendedAction, 'quarantineLocalSnapshotAndReclone');
+    expect(e.shouldEvictLocalCustody, isTrue);
+    expect(e.info.trace.traceId, isNotEmpty); // trace IDs ride as on every bridge error
+    expect(e.message, contains('shallow-insufficient'));
+  });
+
   test(
       'legacy string-only runner errors still get operation and trace metadata',
       () async {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/build_package.ts

@@ -56,6 +56,7 @@ import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js"
 import { synthesizePreconditionInvariants } from "./precondition.js";
 import type { RelationTypeDecl } from "./relation_schema.js";
 import { domainHash, emitManifestBytes } from "./manifest.js";
+import { collectValueObjectDescriptors } from "./value_object.js";
 import { emitUsd } from "./usd.js";
 import { expandCapabilityExports } from "./capability_exports.js";
 import { RelationTuple } from "./framework/relations.js";
@@ -188,6 +189,27 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
   // a directive with no precondition synthesizes nothing (byte-identical manifest).
   for (const d of directives) workspaceInvariants.push(...synthesizePreconditionInvariants(d));
   const relationTypes = [...(spec.relationTypes ?? [])];
+  // FIRST-CLASS VALUE OBJECTS (value_object.ts): the deduped, sorted descriptors of every
+  // named VO the domain's aggregates carry (transitive nested VOs included) — the input to
+  // the additive `nomosValueObjects` USD key. Omit-when-empty (era rule): a VO-free domain's
+  // module — and thus its USD/package bytes — is byte-identical to before VOs existed.
+  const valueObjects = collectValueObjectDescriptors(aggregates);
+  // SPATIAL × VO PAIRING (fail at build, not at fold): a spatial index over a VO-typed field
+  // must index a GEO value object (an RFC 7946 geometry — the R*Tree's bbox source). A
+  // structural VO (e.g. a PostalAddress) has no geometry to index. Non-VO fields (a
+  // hand-rolled `t.jsonObject()` GeoJSON leaf) pass through unchecked, exactly as before.
+  for (const s of spatials) {
+    const agg = byId.get(s.of);
+    const field = agg?.fields[s.on];
+    const vo = field?.valueObject;
+    if (vo !== undefined && vo.geometry === undefined) {
+      throw new Error(
+        `build-package: spatial '${s.id}' indexes '${s.of}.${s.on}', a '${vo.name}' value object with NO ` +
+          `geometry — the R*Tree needs an RFC 7946 geometry leaf. Give the geometry its OWN field ` +
+          `(e.g. \`point: geo.point().field()\`) and index that (v1: no sub-path indexing).`,
+      );
+    }
+  }
   const dartImports = [...(spec.dartImports ?? [])];
   // THE PEER-SOVEREIGN ROOT-OF-TRUST: a home/child law that exports `requireParentAttestedBirth` declares
   // it requires a parent-attested-birth cert chain. Discovered by shape across the module list (the SAME
@@ -233,6 +255,9 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
     // Omit-when-empty — the relation schema is hashed law (P1); a relation-free domain's
     // canonical manifest/USD stays byte-identical (the nomosRelations era rule).
     ...(relationTypes.length > 0 ? { relationTypes } : {}),
+    // Omit-when-empty — the `nomosValueObjects` era rule: a VO-free domain's USD/package
+    // bytes are byte-identical to before value objects existed.
+    ...(valueObjects.length > 0 ? { valueObjects } : {}),
     // THE PEER-SOVEREIGN ROOT-OF-TRUST: omit-when-false — a law that doesn't require parent-attested
     // birth is byte-identical in the canonical manifest/USD (the nomosParentAttestedBirth era rule).
     ...(parentAttestedBirth ? { parentAttestedBirth } : {}),