@githolon/dsl 0.102.5 → 0.103.0

package/src/wire.ts

@@ -36,9 +36,28 @@ export interface WireHlc {
  * unit-variant bare string `"Git" | "External"`. */
 export type WireValue =
   | { Str: string }
+  | { NomosRef: { workspace: string; type: string; id: string } }
+  | {
+      VersionedNomosRef: {
+        pinned: { workspace: string; type: string; id: string };
+        series: { workspace: string; type: string; id: string };
+      };
+    }
   | { Int: number }
   | { Set: string[] }
   | { Map: Record<string, WireField> }
+  | {
+      RelationshipSubject: {
+        status: "active" | "revoked";
+        grantedBy: string;
+        grantedAt: string;
+        revokedBy?: string;
+        revokedAt?: string;
+        validFromEpoch?: number;
+        verifiedVia?: string;
+        ownedCustody?: string;
+      };
+    }
   | { Evidence: WireEvidenceRef }
   // First-class canonical JSON (RFC 8785 / JCS) — the committed form of a `t.json()` leaf. The
   // value rides INLINE (`{Json: <any json>}`), not as a string-of-JSON; the kernel canonicalises

package/src/wire_encode.ts

@@ -114,6 +114,17 @@ function describeShape(value: unknown): string {
  *  `op` is passed purely for a NAMED diagnostic (aggregate + field + expected VO type) when a value
  *  can't be lowered — never `field '?'`. */
 function encodeKernelValue(field: Field | undefined, value: unknown, op?: FieldOp): WireValue {
+  if (op?.kernelValue !== undefined) {
+    if (
+      "RelationshipSubject" in op.kernelValue &&
+      (op.aggregateType !== "RelationTuple" || op.field !== "subjects" || op.kind !== "setEntry")
+    ) {
+      throw new Error(
+        "RelationshipSubject is a framework kernel value restricted to RelationTuple.subjects setEntry operations",
+      );
+    }
+    return op.kernelValue;
+  }
   if (value === undefined) {
     const aggName = op?.aggregateType ?? op?.aggregateId ?? "?";
     const fieldName = op?.field ?? field?.kind ?? "?";
@@ -141,6 +152,17 @@ function encodeKernelValue(field: Field | undefined, value: unknown, op?: FieldO
         `t.json({ null: "explicit-empty", reason }) for a real empty value.`,
     );
   }
+  if (field?.nomosRef !== undefined) {
+    const parsed = field.zod.parse(value) as { workspace: string; type: string; id: string };
+    return { NomosRef: parsed };
+  }
+  if (field?.versionedForeignRef !== undefined) {
+    const parsed = field.zod.parse(value) as {
+      pinned: { workspace: string; type: string; id: string };
+      series: { workspace: string; type: string; id: string };
+    };
+    return { VersionedNomosRef: parsed };
+  }
   if (field?.kind === "evidence") {
     const v = value as EvidenceRefValue;
     return {

package/src/workspace_sharding.ts

@@ -79,7 +79,15 @@ import { query } from "./query.js";
 import { read } from "./read.js";
 import { sum } from "./sum.js";
 import { min, max } from "./extremum.js";
-import { refAs, workspaceInvariant } from "./framework/workspace_invariant.js";
+import {
+  idItem,
+  idPayload,
+  idTemplate,
+  readRef,
+  readSet,
+  refAs,
+  workspaceInvariant,
+} from "./framework/workspace_invariant.js";
 
 /** One packed axis the factory derives a placement lane for. */
 export interface ShardingAxisSpec {
@@ -1152,16 +1160,20 @@ export function shardingLawModule(spec: ShardingLawSpec): Record<string, unknown
   //     (`summary-mismatch:…`): held + carried events ⇒ claimed, byte-compared.
   mod["nomosSummaryGate_nomosPropagateSummary"] = workspaceInvariant("nomosSummaryGate:nomosPropagateSummary")
     .on("nomosPropagateSummary")
-    .reads(({ intent }) => {
-      const shard = String(intent["shard"] ?? "");
-      const subtotals = Array.isArray(intent["subtotals"]) ? (intent["subtotals"] as { readId?: unknown; group?: unknown }[]) : [];
-      return [
-        refAs("frontier", "NomosSummaryFrontier", `pre:${summaryFrontierRowId(shard)}`),
-        ...subtotals.map((s, i) =>
-          refAs(`prev${i}`, "NomosSummarySubtotal", `pre:${summarySubtotalRowId(shard, String(s.readId ?? ""), String(s.group ?? ""))}`),
-        ),
-      ];
-    })
+    .reads(readSet(
+      readRef("frontier", NomosSummaryFrontier).pre().fromTemplate(idTemplate(
+        "nomos-summary-frontier:",
+        idPayload("shard"),
+      )),
+      readRef("prev", NomosSummarySubtotal).pre().forEach("subtotals", idTemplate(
+        "nomos-subtotal:",
+        idPayload("shard"),
+        "|",
+        idItem("readId", "row-key"),
+        "|",
+        idItem("group", "row-key"),
+      )),
+    ))
     .assert((snapshots, ctx) => {
       const intent = ctx?.intent ?? {};
       const held = snapshots["frontier"]?.["frontier"];
@@ -1212,17 +1224,17 @@ export function shardingLawModule(spec: ShardingLawSpec): Record<string, unknown
   //        no skipped or replayed sequence points. ──
   mod["nomosCheckpointGate_nomosCheckpointSeal"] = workspaceInvariant("nomosCheckpointGate:nomosCheckpointSeal")
     .on("nomosCheckpointSeal")
-    .reads(({ intent }) => {
-      const frontiers = Array.isArray(intent["frontiers"]) ? (intent["frontiers"] as { shard?: unknown }[]) : [];
-      const seq = typeof intent["seq"] === "number" ? (intent["seq"] as number) : "?";
-      return [
-        refAs("head", "NomosCheckpointSeal", `pre:${NOMOS_CHECKPOINT_HEAD_ID}`),
-        refAs("own", "NomosCheckpointSeal", `pre:${checkpointSealRowId(seq)}`),
-        ...frontiers.map((f, i) =>
-          refAs(`front${i}`, "NomosSummaryFrontier", `pre:${summaryFrontierRowId(String(f?.shard ?? ""))}`),
-        ),
-      ];
-    })
+    .reads(readSet(
+      readRef("head", NomosCheckpointSeal).pre().at(NOMOS_CHECKPOINT_HEAD_ID),
+      readRef("own", NomosCheckpointSeal).pre().fromTemplate(idTemplate(
+        "nomos-checkpoint-seal:",
+        idPayload("seq"),
+      )),
+      readRef("front", NomosSummaryFrontier).pre().forEach("frontiers", idTemplate(
+        "nomos-summary-frontier:",
+        idItem("shard"),
+      )),
+    ))
     .assert((snapshots, ctx) => {
       const intent = ctx?.intent ?? {};
       const claimedSeq = typeof intent["seq"] === "number" ? (intent["seq"] as number) : NaN;
@@ -1259,12 +1271,12 @@ export function shardingLawModule(spec: ShardingLawSpec): Record<string, unknown
   //    homes it actually holds on the named source; a handoff seal may only land on
   //    rows mid-move to exactly its target, with the map version bumped exactly once.
   //    Every refusal is typed with the held state — the named remedy. ──
-  const moveReads = ({ intent }: { intent: Record<string, unknown> }) => {
-    const homeKeys = Array.isArray(intent["homeKeys"]) ? (intent["homeKeys"] as unknown[]) : [];
-    return homeKeys.map((k, i) =>
-      refAs(`held${i}`, "NomosShardAssignment", `pre:${shardAssignmentRowId(String(k ?? ""))}`),
-    );
-  };
+  const moveReads = readSet(
+    readRef("held", NomosShardAssignment).pre().forEach("homeKeys", idTemplate(
+      "nomos-shard-assignment:",
+      idItem([], "row-key"),
+    )),
+  );
   mod["nomosMoveGate_nomosSplitShard"] = workspaceInvariant("nomosMoveGate:nomosSplitShard")
     .on("nomosSplitShard")
     .reads(moveReads)
@@ -1326,10 +1338,13 @@ export function shardingLawModule(spec: ShardingLawSpec): Record<string, unknown
     const keyField = route.key;
     mod[`nomosWrongHome_${route.directive}`] = workspaceInvariant(`nomosWrongHome:${route.directive}`)
       .on(route.directive)
-      .reads(({ intent }) => [
-        refAs("shardIdentity", "NomosShardIdentity", NOMOS_SHARD_IDENTITY_ID),
-        refAs("receipt", "NomosHomeReceipt", homeReceiptRowId(String(intent[keyField] ?? ""))),
-      ])
+      .reads(readSet(
+        readRef("shardIdentity", NomosShardIdentity).at(NOMOS_SHARD_IDENTITY_ID),
+        readRef("receipt", NomosHomeReceipt).fromTemplate(idTemplate(
+          "nomos-home-receipt:",
+          idPayload(keyField, "row-key"),
+        )),
+      ))
       .assert((snapshots, ctx) => {
         const identity = snapshots["shardIdentity"] ?? {};
         const label = identity["label"];
@@ -1359,7 +1374,7 @@ export function shardingLawModule(spec: ShardingLawSpec): Record<string, unknown
   // ── THE RECEIPT'S OWN HOMING (a receipt claiming a foreign shard never folds) ──
   mod["nomosReceiptHome_nomosReceiveAssignment"] = workspaceInvariant("nomosReceiptHome:nomosReceiveAssignment")
     .on("nomosReceiveAssignment")
-    .reads(() => [refAs("shardIdentity", "NomosShardIdentity", NOMOS_SHARD_IDENTITY_ID)])
+    .reads(readSet(readRef("shardIdentity", NomosShardIdentity).at(NOMOS_SHARD_IDENTITY_ID)))
     .assert((snapshots, ctx) => {
       const label = snapshots["shardIdentity"]?.["label"];
       if (typeof label !== "string" || label.length === 0) return { accept: true };
@@ -1437,9 +1452,10 @@ export function shardingLawModule(spec: ShardingLawSpec): Record<string, unknown
     // row WITHOUT authoring).
     mod[`nomosPlacementUnique_${dirId}`] = workspaceInvariant(`nomosPlacementUnique:${dirId}`)
       .on(dirId)
-      .reads(({ intent }) => [
-        refAs("held", "NomosShardAssignment", `pre:${shardAssignmentRowId(String(intent[keyField] ?? ""))}`),
-      ])
+      .reads(readSet(readRef("held", NomosShardAssignment).pre().fromTemplate(idTemplate(
+        "nomos-shard-assignment:",
+        idPayload(keyField, "row-key"),
+      ))))
       .assert((snapshots) => {
         const held = snapshots["held"] ?? {};
         const heldShard = held["shard"];

package/src/workspace_sharing.ts

@@ -16,6 +16,8 @@ import { Lww } from "./drivers.js";
 import { endorsementOf } from "./principal_evidence.js";
 import { RelationTuple, writeTuple } from "./framework/relations.js";
 import {
+  readRef,
+  readSet,
   refAs,
   workspaceInvariant,
   type WorkspaceInvariantDecl,
@@ -58,6 +60,28 @@ export interface WorkspaceSharingInvitationLaw {
   readonly pendingByRecipient: QueryDecl;
 }
 
+/**
+ * Fold the generated invitation law into the same export bag consumed by both
+ * package composition and the executable engine registry. Keeping one seam is
+ * essential: if the compiler alone injects the redeem directive, custody can
+ * advertise a route which the selected runtime plan can never register.
+ */
+export function withWorkspaceSharingInvitationExports(
+  moduleExports: Record<string, unknown>,
+  policies: readonly WorkspaceSharingPolicy[],
+): Record<string, unknown> {
+  if (policies.length === 0) return moduleExports;
+  const out = { ...moduleExports };
+  for (const policy of policies) {
+    const law = policy.invitationLaw;
+    out[`__nomosWorkspaceSharingAggregate:${law.claim.id}`] = law.claim;
+    out[`__nomosWorkspaceSharingDirective:${law.redeem.id}`] = law.redeem;
+    out[`__nomosWorkspaceSharingInvariant:${law.gate.id}`] = law.gate;
+    out[`__nomosWorkspaceSharingQuery:${law.pendingByRecipient.id}`] = law.pendingByRecipient;
+  }
+  return out;
+}
+
 /** One workspace-wide consumption record makes a bearer invitation single-use across every policy. */
 const NomosInvitationClaim = {
   ...aggregate("NomosInternalInvitationClaim7c1f5e", {
@@ -204,10 +228,10 @@ export function workspaceSharing(options: WorkspaceSharingOptions): WorkspaceSha
   });
   const gate = workspaceInvariant(`NomosInvitationGate:${options.orders.id}`)
     .on(redeemId)
-    .reads(({ intent }) => [
-      refAs("order", options.orders.id, `pre:${String(intent.orderId ?? "")}`),
-      refAs("claim", NomosInvitationClaim.id, `pre:${String(intent.invitationId ?? "")}`),
-    ])
+    .reads(readSet(
+      readRef("order", options.orders).pre().fromPayload("orderId"),
+      readRef("claim", NomosInvitationClaim).pre().fromPayload("invitationId"),
+    ))
     .assert((snapshots, ctx) => {
       const intent = ctx?.intent ?? {};
       const order = snapshots.order ?? {};

package/src/zod_introspection.ts

@@ -63,7 +63,7 @@ const SUBJECT_SAMPLES: readonly string[] = [
   "0".repeat(64),
 ];
 const STRING_SAMPLES: readonly string[] = [
-  "sample", "{}", "en", "en-GB", "AA", "A1", "a", "1", "2026-01-01",
+  "sample", "{}", "en", "en-GB", "AA", "A1", "a", "1", "2026-01", "2026-01-01",
   "000001", "2026-01-01T00:00:00Z", "a@example.com", "https://example.com", "#000000",
   "00000000-0000-0000-0000-000000000000", "example.com", "0".repeat(40), "0".repeat(64),
   `nomos-invitation-${"0".repeat(64)}`,

package/dart/test/cluster_attested_test.dart

@@ -1,201 +0,0 @@
-// THE CLUSTER / ATTESTED-READ ACCEPTANCE — DART LEG (co2's test-cluster ask). Prove the exact
-// dynamic-source attested-read scenario (architecture/dynamic_source_attested_reads.md) end-to-end from
-// Dart, ONE engine plane, TWO colocated workspaces, ZERO network:
-//
-//   • NomosTestHarness.cluster boots ONE runner holding a `catalogue` session (the source) and an `estate`
-//     session (the reader), each with its own law installed offline.
-//   • the catalogue session seeds a listing; the estate session serves + SIGNS it via the in-process
-//     `attestedRead` op (the colocated source lane) and reads the source's GENESIS off the envelope.
-//   • NEGATIVE arm: offering `importListing` with that envelope BEFORE enrolling the catalogue refuses
-//     `AttestedReadUntrustedSource` — surfaced to Dart as a NomosBridgeError carrying that name.
-//   • HAPPY arm: enrol the source genesis + attestor key, offer `importListing` carrying the signed
-//     envelope, and read the imported row back through the generated EstateApplication bound to
-//     `harness.session('estate')`.
-@TestOn('vm')
-library;
-
-import 'dart:convert';
-import 'dart:io';
-
-import 'package:crypto/crypto.dart';
-import 'package:nomos_client/src/nms_conformance_runtime.dart';
-import 'package:nomos_client/src/nms_generated_runtime.dart';
-import 'package:test/test.dart';
-
-// Framework acceptance tests may bind a generated application to an already-mounted harness session. The
-// raw client is a private `part` and is deliberately not importable, even here.
-import '../../../bench/scale/fixtures/catalogue-reader/build/dart/src/generated/estate.application.dart';
-
-String get _root => '${Directory.current.path}/../..';
-String get _repoEntry => '$_root/cloud/web-client/runner/node-entry.ts';
-String get _catDeploy =>
-    '$_root/bench/scale/fixtures/catalogue-src/build/cat.deploy.json';
-String get _estateDeploy =>
-    '$_root/bench/scale/fixtures/catalogue-reader/build/estate.deploy.json';
-String get _estateClientDart =>
-    '$_root/bench/scale/fixtures/catalogue-reader/build/dart/src/generated/estate.application.dart';
-String get _runtimeDir =>
-    Platform.environment['NOMOS_DART_RUNTIME'] ??
-    Platform.environment['NOMOS_OFFLINE_RUNTIME'] ??
-    '${Platform.environment['HOME'] ?? ''}/.holon/runtime';
-
-String? _missingPrereq() {
-  if (!File(_repoEntry).existsSync())
-    return 'in-repo runner not found at $_repoEntry';
-  for (final p in [_catDeploy, _estateDeploy, _estateClientDart]) {
-    if (!File(p).existsSync()) {
-      return 'compile the catalogue fixtures with dart output: '
-          'cd bench/scale/fixtures/<catalogue-src|catalogue-reader> && node ../../../../dsl/compile_package.mjs '
-          '(needs `dart: { support: "package" }` in nomos.package.mjs) — missing $p';
-    }
-  }
-  if (!File('$_runtimeDir/holon-testmint.wasm').existsSync() ||
-      !File('$_runtimeDir/packages.json').existsSync()) {
-    return 'warm ~/.holon/runtime first (run any `githolon` command once)';
-  }
-  return null;
-}
-
-/// sha256hex of the attestor's raw public bytes — the `keyHash` the reader enrolls (parity with the
-/// smoke's `sha256hexBytes(base64decode(public))`).
-String _keyHashOf(String base64Public) =>
-    sha256.convert(base64Decode(base64Public)).toString();
-
-void main() {
-  test(
-      'cluster attested reads: colocated source served + signed → enrolled → typed import read back',
-      () async {
-    final skip = _missingPrereq();
-    if (skip != null) {
-      markTestSkipped(skip);
-      return;
-    }
-
-    final harness = await NomosTestHarness.cluster(
-      workspaces: {
-        'catalogue': [_catDeploy],
-        'estate': [_estateDeploy],
-      },
-      // The catalogue SOURCE signs its attested reads with its device key — the colocation resolver uses it,
-      // and the reader enrols sha256(that public key). (The reader needs no device key: it authors as an actor.)
-      deviceKeyed: {'catalogue'},
-      nodeEntry: _repoEntry,
-      runtimeDir: _runtimeDir,
-    );
-    try {
-      expect(harness.sessions.toSet(), {'catalogue', 'estate'});
-
-      // THE PRODUCTION MULTI-WORKSPACE SURFACE: one bridge = this device's local plane; `bridge.session(ws)`
-      // is the first-class handle. Enumerate the plane — both workspaces are LOCAL-ONLY (no cloud posture).
-      final plane = await harness.bridge.listWorkspaces();
-      expect(plane.map((w) => w['workspace']).toSet(), {'catalogue', 'estate'});
-      expect(plane.every((w) => w['syncPosture'] == 'local-only'), isTrue,
-          reason: 'the cluster opens local githolons, not cloud connections');
-
-      // Get the session handles through the production entry (the harness delegates to bridge.session).
-      final catalogue = harness.bridge.session('catalogue');
-      final estate = harness.bridge.session('estate');
-      expect(identical(estate, harness.session('estate')), isTrue,
-          reason: 'session handles are stable + cached on the plane');
-
-      // 1. seed a listing in the CATALOGUE source (raw offer — the source's own law).
-      final seeded = await catalogue.offerCreates(
-        domain: 'cat',
-        directiveId: 'listCatalogue',
-        payload: {
-          'listingId': 'L-100',
-          'title': 'Oak dresser',
-          'priceGbp': '420',
-          'listedAt': '2026-07-03T00:00:00Z',
-        },
-        actor: 'user:seller',
-      );
-      expect(seeded.head, isNotEmpty);
-
-      // 2. Read the source's GENESIS (its true identity) + its signing key off ONE attested read. No attestor
-      //    secret: the source session signs with its DEVICE key (its connect authorSecret), which the
-      //    colocation resolver also uses — so the enrolled keyHash matches what the zero-injection lane signs.
-      final served = await estate.attestedRead(
-        from: 'catalogue',
-        queryId: 'listingById',
-        args: {'listingId': 'L-100'},
-      );
-      final entry = (served['entry'] as Map).cast<String, Object?>();
-      final attestation = (entry['attestation'] as Map).cast<String, Object?>();
-      final sourceGenesis = (attestation['source_genesis'] ?? '').toString();
-      final signingKey = (attestation['public_key'] ?? '').toString();
-      final keyHash = _keyHashOf(signingKey);
-      expect(sourceGenesis.length, greaterThanOrEqualTo(40),
-          reason: 'the source genesis oid resolves off the signed envelope');
-      expect(signingKey, harness.devicePublicKey('catalogue'),
-          reason:
-              'the read is signed by the source session device key the resolver will use');
-
-      // The one importListing offer, offered TWICE (unenrolled then enrolled). ZERO injection: the payload
-      // names `catalogueWs`, and the runner's colocation resolver serves+signs the foreign read IN-PROCESS —
-      // NO `attestations` param. The gate judges the served envelope's genesis against the reader's allow-list.
-      Future<NomosOfferOutcome> importRawForFrameworkTest(String importedAt) =>
-          estate.offerCreates(
-            domain: 'estate',
-            directiveId: 'importListing',
-            payload: {
-              'listingId': 'L-100',
-              'catalogueWs': 'catalogue',
-              'importedAt': importedAt,
-            },
-            actor: 'user:estate-owner',
-          );
-
-      // 3. NEGATIVE — BEFORE enrolment the source genesis is not in the allow-list → UntrustedSource
-      //    (the resolver still serves+signs; the gate refuses on the untrusted genesis).
-      Object? negError;
-      try {
-        // Deliberately raw: this framework test needs the refused kernel outcome itself. This is framework
-        // test instrumentation, not public API; tenant code gets only the generated application.
-        await importRawForFrameworkTest('2026-07-03T12:00:00Z');
-      } catch (e) {
-        negError = e;
-      }
-      expect(negError, isA<NomosBridgeError>(),
-          reason: 'an unenrolled source must refuse the import');
-      expect(negError.toString(), contains('AttestedReadUntrustedSource'),
-          reason: 'the typed refusal name must surface to Dart');
-
-      // 4. ENROL the catalogue: its genesis + the source device keyHash become folded law-state in the
-      //    reader's own chain (typed write — the reader's own directive, no attestation).
-      final app =
-          await nomosInternalBindEstateApplication(estate, 'user:estate-owner');
-      final enrolled =
-          await app.trustedCatalogues.enrollCatalogue(EnrollCataloguePayload(
-        sourceGenesis: sourceGenesis,
-        keyHashes: [keyHash],
-        label: 'Acme Catalogue',
-        enrolledAt: '2026-07-03T10:00:00Z',
-      ));
-      expect(NmsInternalNomosRefs.workspace(enrolled.trustedCatalogue), 'estate');
-
-      // 5. HAPPY — the SAME zero-injection offer now admits: the resolver serves+signs, the gate judges the
-      //    genesis against the folded allow-list, and the catalogue title lands on EstateListing.
-      final imported = await app.estateListings.importListing(
-        const ImportListingPayload(
-          listingId: 'L-100',
-          catalogueWs: 'catalogue',
-          importedAt: '2026-07-03T12:05:00Z',
-        ),
-      );
-      expect(NmsInternalNomosRefs.workspace(imported.estateListing), 'estate');
-
-      // 6. TYPED read-back through the generated application bound to the estate session.
-      final row = await app.estateListings.find(imported.estateListing);
-      expect(row, isNotNull,
-          reason:
-              'the imported EstateListing reads back on the estate session');
-      expect(row!.title, 'Oak dresser',
-          reason: 'the imported title was read through the policy edge, typed');
-      expect(row.catalogue, 'catalogue');
-      expect(row.listingRef, 'L-100');
-    } finally {
-      await harness.dispose();
-    }
-  }, timeout: const Timeout(Duration(minutes: 3)));
-}