@githolon/dsl 0.70.0 → 0.70.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.70.0",
+  "version": "0.70.2",
   "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/codegen_dart.ts

@@ -4275,61 +4275,10 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
       ]
     : [];
 
-  // ROLE SUGAR — per-(role × aggregate) `canEdit<Agg>`/`canView<Agg>` UI-HINT helpers, pure functions
-  // over the folded RelationTuple projection (the client-side MIRROR of engine.check). INFORMATIONAL
-  // only — THE KERNEL GATE REMAINS THE AUTHORITY. Emitted only when the domain declares roles (era-safe).
-  const roleBlock = (() => {
-    const editRels = new Map<string, Set<string>>();
-    const viewRels = new Map<string, Set<string>>();
-    for (const r of mod.roles ?? []) {
-      if (r.editRelation) for (const agg of r.editAggregates) (editRels.get(agg) ?? editRels.set(agg, new Set()).get(agg)!).add(r.editRelation);
-      if (r.viewRelation) for (const agg of r.viewAggregates) {
-        const s = viewRels.get(agg) ?? viewRels.set(agg, new Set()).get(agg)!;
-        s.add(r.viewRelation);
-        if (r.editRelation && r.editAggregates.includes(agg)) s.add(r.editRelation);
-      }
-    }
-    if (editRels.size === 0 && viewRels.size === 0) return "";
-    const lines: string[] = [
-      `/// True iff [principal] holds ANY of [relations] as an ACTIVE tuple in [rows] (or a \`user:*\` wildcard).`,
-      `bool _holdsAnyRelation(List<Map<String, dynamic>>? rows, Set<String> relations, String principal) {`,
-      `  for (final r in rows ?? const []) {`,
-      `    final data = r['data'];`,
-      `    if (data is! Map) continue;`,
-      `    final rel = data['relation'];`,
-      `    if (rel is! String || !relations.contains(rel)) continue;`,
-      `    final subjects = data['subjects'];`,
-      `    if (subjects is! Map) continue;`,
-      `    for (final entry in subjects.entries) {`,
-      `      final subj = entry.key.toString();`,
-      `      dynamic leaf = entry.value;`,
-      `      if (leaf is String) { try { leaf = jsonDecode(leaf); } catch (_) { leaf = const {}; } }`,
-      `      final status = leaf is Map ? leaf['status'] : null;`,
-      `      if (status != null && status != 'active') continue;`,
-      `      if (subj == 'user:\$principal' || subj == 'user:*') return true;`,
-      `    }`,
-      `  }`,
-      `  return false;`,
-      `}`,
-    ];
-    const dartSet = (s: Set<string>): string => `{${[...s].sort().map((x) => `'${x}'`).join(", ")}}`;
-    for (const [agg, rels] of [...editRels].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
-      lines.push(
-        `/// UI HINT — may [principal] EDIT a ${agg}? Mirrors the kernel's ReBAC check; INFORMATIONAL only`,
-        `/// (the one wasm gate is the authority and refuses regardless).`,
-        `bool canEdit${cap(agg)}(List<Map<String, dynamic>>? relations, String principal) =>`,
-        `    _holdsAnyRelation(relations, ${dartSet(rels)}, principal);`,
-      );
-    }
-    for (const [agg, rels] of [...viewRels].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
-      lines.push(
-        `/// UI HINT — may [principal] VIEW a ${agg}? Mirrors the kernel's ReBAC read gate; INFORMATIONAL only.`,
-        `bool canView${cap(agg)}(List<Map<String, dynamic>>? relations, String principal) =>`,
-        `    _holdsAnyRelation(relations, ${dartSet(rels)}, principal);`,
-      );
-    }
-    return lines.join("\n");
-  })();
+  // ROLE SUGAR — the per-(role × aggregate) `canEdit<Agg>`/`canView<Agg>` UI-HINT helpers are NOT emitted
+  // into this TYPES file: they walk the folded RelationTuple projection and need `dart:convert` (jsonDecode),
+  // which the layered types-package PURITY GATE forbids. They live in the CLIENT package (`<name>.client.dart`,
+  // which may import runtime) via {@link dartRoleHelpers}. Flat mode emits them there too.
 
   return [
     `// GENERATED by nomos2/dsl/src/codegen_dart.ts — DO NOT EDIT BY HAND.`,
@@ -4342,7 +4291,7 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
     `// ignore_for_file: unused_import`,
     ``,
     // A nullable plain-`t.json()` read-model slot decode re-stringifies via `jsonEncode`.
-    ...(needsJsonConvert || roleBlock !== "" ? [`import 'dart:convert';`] : []),
+    ...(needsJsonConvert ? [`import 'dart:convert';`] : []),
     // The generated tenant domains live in the `co2_nomos_domains` package and depend
     // on the framework `nomos_client` package by its PUBLIC package: URI — NOT a relative
     // `../wire.dart` path into the framework (which broke when the generated dir moved
@@ -4416,12 +4365,65 @@ export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOp
         ]
       : []),
     ...helperBlock,
-    ...(roleBlock !== ""
-      ? [
-          ``,
-          `// ---- role policy (UI hints — the KERNEL GATE is the authority) ----`,
-          roleBlock,
-        ]
-      : []),
+    // NOTE: role UI-hint helpers (canEdit/canView) are emitted into the CLIENT package by dartRoleHelpers,
+    // NOT here — they need dart:convert, which the types-package purity gate forbids.
   ].join("\n");
 }
+
+/** The role UI-hint helpers (`canEdit<Agg>`/`canView<Agg>` + `_holdsAnyRelation`) for the CLIENT package — a
+ *  pure client-side MIRROR of the kernel ReBAC check over the folded RelationTuple projection. INFORMATIONAL
+ *  only (the one wasm gate is the authority and refuses regardless). Uses `dart:convert` (jsonDecode of the
+ *  per-subject leaf), so it may NOT live in the pure types file — the caller emits it into `<name>.client.dart`
+ *  and ensures a `dart:convert` import. Returns "" when the domain declares no roles (era-safe, no import). */
+export function dartRoleHelpers(mod: DomainModule): string {
+  const editRels = new Map<string, Set<string>>();
+  const viewRels = new Map<string, Set<string>>();
+  for (const r of mod.roles ?? []) {
+    if (r.editRelation) for (const agg of r.editAggregates) (editRels.get(agg) ?? editRels.set(agg, new Set()).get(agg)!).add(r.editRelation);
+    if (r.viewRelation) for (const agg of r.viewAggregates) {
+      const s = viewRels.get(agg) ?? viewRels.set(agg, new Set()).get(agg)!;
+      s.add(r.viewRelation);
+      if (r.editRelation && r.editAggregates.includes(agg)) s.add(r.editRelation);
+    }
+  }
+  if (editRels.size === 0 && viewRels.size === 0) return "";
+  const lines: string[] = [
+    `/// True iff [principal] holds ANY of [relations] as an ACTIVE tuple in [rows] (or a \`user:*\` wildcard).`,
+    `bool _holdsAnyRelation(List<Map<String, dynamic>>? rows, Set<String> relations, String principal) {`,
+    `  for (final r in rows ?? const []) {`,
+    `    final data = r['data'];`,
+    `    if (data is! Map) continue;`,
+    `    final rel = data['relation'];`,
+    `    if (rel is! String || !relations.contains(rel)) continue;`,
+    `    final subjects = data['subjects'];`,
+    `    if (subjects is! Map) continue;`,
+    `    for (final entry in subjects.entries) {`,
+    `      final subj = entry.key.toString();`,
+    `      dynamic leaf = entry.value;`,
+    `      if (leaf is String) { try { leaf = jsonDecode(leaf); } catch (_) { leaf = const {}; } }`,
+    `      final status = leaf is Map ? leaf['status'] : null;`,
+    `      if (status != null && status != 'active') continue;`,
+    `      if (subj == 'user:\$principal' || subj == 'user:*') return true;`,
+    `    }`,
+    `  }`,
+    `  return false;`,
+    `}`,
+  ];
+  const dartSet = (s: Set<string>): string => `{${[...s].sort().map((x) => `'${x}'`).join(", ")}}`;
+  for (const [agg, rels] of [...editRels].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+    lines.push(
+      `/// UI HINT — may [principal] EDIT a ${agg}? Mirrors the kernel's ReBAC check; INFORMATIONAL only`,
+      `/// (the one wasm gate is the authority and refuses regardless).`,
+      `bool canEdit${cap(agg)}(List<Map<String, dynamic>>? relations, String principal) =>`,
+      `    _holdsAnyRelation(relations, ${dartSet(rels)}, principal);`,
+    );
+  }
+  for (const [agg, rels] of [...viewRels].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+    lines.push(
+      `/// UI HINT — may [principal] VIEW a ${agg}? Mirrors the kernel's ReBAC read gate; INFORMATIONAL only.`,
+      `bool canView${cap(agg)}(List<Map<String, dynamic>>? relations, String principal) =>`,
+      `    _holdsAnyRelation(relations, ${dartSet(rels)}, principal);`,
+    );
+  }
+  return lines.join("\n");
+}

package/src/codegen_dart_client.ts

@@ -33,7 +33,7 @@ import type { Field } from "./fields.js";
 import type { Directive } from "./directive.js";
 import type { QueryDecl } from "./query.js";
 import type { DomainModule } from "./codegen_dart.js";
-import { cap, readModelClassName } from "./codegen_dart.js";
+import { cap, readModelClassName, dartRoleHelpers } from "./codegen_dart.js";
 import { finishCount } from "./count.js";
 import { finishSum } from "./sum.js";
 import { autoStampFields, domainEncryptionMap, type EncDomainMap, type InterfaceAggShape } from "./codegen_ts.js";
@@ -149,6 +149,11 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
   const aggById = new Map<string, AggregateHandle>();
   for (const a of mod.aggregates) aggById.set(a.id, a);
 
+  // ROLE SUGAR — the `canEdit<Agg>`/`canView<Agg>` UI-hint helpers live HERE (the client package, which may
+  // import runtime), NOT in the pure types file: they `jsonDecode` the folded RelationTuple leaf, and the
+  // layered types-package purity gate forbids `dart:convert`. Empty ⇒ no roles (era-safe; no extra import).
+  const roleHelpers = dartRoleHelpers(mod);
+
   // THE E2E-SEALING MAP (the sealing client) — non-null iff a field is `.encrypted()`. When null NOTHING
   // below emits (the generated Dart client is byte-identical to a pre-sealing compile). Same map + sids as
   // the TS client (one source of truth: `domainEncryptionMap`); requires the baked interface for the sids.
@@ -407,7 +412,7 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     ``,
     // `dart:convert` is needed ONLY for the interface block's `jsonDecode` — the offer lane no longer encodes
     // any envelope (it routes through `bridge.offerDirective` → THE ONE ENCODER). Omit it when no interface.
-    ...(opts.interface !== undefined ? [`import 'dart:convert';`, ``] : []),
+    ...(opts.interface !== undefined || roleHelpers !== "" ? [`import 'dart:convert';`, ``] : []),
     `import '${supportImport}';`,
     // Layered-packages mode: the sibling types live in their OWN package — one barrel import
     // replaces both the relative types import and the relative framework import.
@@ -531,6 +536,13 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     ...methods,
     `}`,
     ``,
+    ...(roleHelpers !== ""
+      ? [
+          `// ---- role policy (UI hints — the KERNEL GATE is the authority) ----`,
+          roleHelpers,
+          ``,
+        ]
+      : []),
   ].join("\n");
 }
 

package/src/codegen_proof.ts

@@ -508,19 +508,25 @@ function relationSeedLegLines(
     ];
   }
   const ACTOR = `"user:proof-conformance"`;
+  const BARE_ACTOR = `"proof-conformance"`; // the uid without the `user:` prefix — for WRAPPED subject fields
   const speculative = leg.seedSpeculative === true;
   // A payload literal with subject/founder-conventional fields (+ the routed set) overwritten to the actor —
-  // so a seat lands ON the actor AND every write-once/author-binding/founder-binding invariant holds.
-  const actorSeatLit = (payload: Record<string, unknown>, routed: readonly string[]): string => {
+  // so a seat lands ON the actor AND every write-once/author-binding/founder-binding invariant holds. A WRAPPED
+  // subject field (the plan lifts a bare uid into `user:${field}`) gets the BARE uid — else the re-wrap yields
+  // a double-prefixed `user:user:<uid>` the gate never stamped.
+  const actorSeatLit = (payload: Record<string, unknown>, routed: readonly string[], wrapped: readonly string[] = []): string => {
     const overwrite = new Set<string>(routed);
+    const wrappedSet = new Set<string>(wrapped);
     const entries = Object.entries(payload).map(([k, v]) =>
-      overwrite.has(k) || /^(subject|principal|grantedBy|grantee|member|user|owner|founder)$/i.test(k)
-        ? `${JSON.stringify(k)}: ${ACTOR}`
-        : `${JSON.stringify(k)}: ${JSON.stringify(v)}`,
+      wrappedSet.has(k)
+        ? `${JSON.stringify(k)}: ${BARE_ACTOR}`
+        : overwrite.has(k) || /^(subject|principal|grantedBy|grantee|member|user|owner|founder)$/i.test(k)
+          ? `${JSON.stringify(k)}: ${ACTOR}`
+          : `${JSON.stringify(k)}: ${JSON.stringify(v)}`,
     );
     return `{ ${entries.join(", ")} }`;
   };
-  const grantPayloadLit = actorSeatLit(leg.grantPayload, [...leg.grantSubjectFields, ...leg.grantGrantedByFields]);
+  const grantPayloadLit = actorSeatLit(leg.grantPayload, [...leg.grantSubjectFields, ...leg.grantGrantedByFields], leg.grantSubjectWrappedFields ?? []);
   // The PREREQUISITE-SEED CHAIN dispatches (each as the actor = founder) BEFORE the grant.
   const prereqLines = (leg.prerequisiteSeeds ?? []).flatMap((seed) => [
     `    // prerequisite: ${leg.domain}/${seed.directiveId} establishes the state the grant's invariant reads (as founder = ACTOR).`,
@@ -665,6 +671,10 @@ export interface RelationBootstrapLeg {
   readonly grantSubjectFields: readonly string[];
   /** Grant-payload field(s) routed into the tuple `grantedBy` — set to the proof actor (free attribution). */
   readonly grantGrantedByFields: readonly string[];
+  /** Grant-payload field(s) the plan WRAPPED into a `<prefix>:<uid>` subject (`user:${principal}`) — the
+   *  runner seats the BARE actor uid here (else the re-wrap double-prefixes to `user:user:<uid>` and the seat
+   *  lands on nobody the gate stamped). The role-sugar + framework grant/seed shape. */
+  readonly grantSubjectWrappedFields?: readonly string[];
   /** How the granter was resolved — `"marker"` (`.grants(R)` on R directly), `"inferred"` (a plan-probed
    *  `writeTuple(R)`), `"computed-base"` (R is computed; the grant seats a rewrite BASE relation the granter
    *  was found for), or `"seed-path"` (LAYER 3: R is reachable only through ttu/intersection/exclusion — no
@@ -887,7 +897,7 @@ function probeRelationsWritten(dir: Directive<unknown>, where: string): string[]
  *  values. Best-effort: an unmatched routing just leaves the field list empty (runtime falls back). */
 function resolveGrantSubjectFields(
   probed: { ops: FieldOp[]; synth: SynthesizedPayload },
-): { subjectFields: string[]; grantedByFields: string[] } {
+): { subjectFields: string[]; grantedByFields: string[]; wrappedSubjectFields: string[] } {
   const { ops, synth } = probed;
   const fieldForValue = (v: unknown): string | undefined =>
     typeof v === "string" && v.length > 0
@@ -895,11 +905,23 @@ function resolveGrantSubjectFields(
       : undefined;
   const subjectFields = new Set<string>();
   const grantedByFields = new Set<string>();
+  // WRAPPED subject fields: the plan lifted a BARE payload uid into a `<prefix>:<uid>` subject wire form
+  // (`writeTuple({ subject: `user:${p.principal}` })` — the role-sugar + framework grant shape). The runner
+  // must seat the BARE actor uid into these (not the full `user:` subject), else the plan re-wraps it into a
+  // double-prefixed `user:user:<uid>` that never matches the actor the gate stamped. Distinct from a DIRECT
+  // subject field (entryKey === the payload value verbatim — a full `user:<uid>` payload), which stays full.
+  const wrappedSubjectFields = new Set<string>();
   for (const o of ops) {
     // The subject rides the tuple map entry KEY (`setEntry(rt, "subjects", <subjectRaw>, leaf)`).
     if (o.kind === "setEntry" && o.field === "subjects" && typeof o.entryKey === "string") {
       const f = fieldForValue(o.entryKey);
       if (f !== undefined) subjectFields.add(f);
+      else {
+        // entryKey `<prefix>:<uid>` (e.g. `user:sample-principal`) where <uid> is a payload value ⇒ wrapped.
+        const m = /^[a-z]+:(.+)$/.exec(o.entryKey);
+        const inner = m !== null ? fieldForValue(m[1]) : undefined;
+        if (inner !== undefined) wrappedSubjectFields.add(inner);
+      }
       // grantedBy rides the JSON leaf value — scan the serialized leaf for any synthesized payload value.
       if (typeof o.value === "string") {
         for (const [name, sv] of Object.entries(synth.value)) {
@@ -910,7 +932,7 @@ function resolveGrantSubjectFields(
       }
     }
   }
-  return { subjectFields: [...subjectFields], grantedByFields: [...grantedByFields] };
+  return { subjectFields: [...subjectFields], grantedByFields: [...grantedByFields], wrappedSubjectFields: [...wrappedSubjectFields] };
 }
 
 // ── rewrite-aware base-relation resolution (the COMPUTED-authority lane) ──────────────────────────────
@@ -1382,7 +1404,7 @@ export function discoverRelationBootstrapLeg(mod: DomainModule, gatedOverride?:
   }
   const grantPayload: Record<string, unknown> = { ...grantSynth.value };
   const probed = probePlanOps(granter, `${domain}/${granter.id}`);
-  const routed = probed !== undefined ? resolveGrantSubjectFields(probed) : { subjectFields: [], grantedByFields: [] };
+  const routed = probed !== undefined ? resolveGrantSubjectFields(probed) : { subjectFields: [], grantedByFields: [], wrappedSubjectFields: [] };
 
   return {
     domain,
@@ -1397,6 +1419,7 @@ export function discoverRelationBootstrapLeg(mod: DomainModule, gatedOverride?:
     grantAutoStamped: grantSynth.autoStamped,
     grantSubjectFields: routed.subjectFields,
     grantGrantedByFields: routed.grantedByFields,
+    ...(routed.wrappedSubjectFields.length > 0 ? { grantSubjectWrappedFields: routed.wrappedSubjectFields } : {}),
     via,
     ...(seedSpeculative ? { seedSpeculative: true } : {}),
     ...(seedWritesRelations !== undefined ? { seedWritesRelations } : {}),

package/src/codegen_ts.ts

@@ -950,7 +950,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `  /** THE ONE ENCODER offer (the single v2-envelope codec lives in @githolon/client \`encodeIntentOfferBytes\`):`,
     `   *  hand the holon a PLANNED directive + the verified \`actor\`; the holon encodes + offers. The generated`,
     `   *  client calls THIS, never building offer bytes itself — so there is exactly ONE copy of the wire format. */`,
-    `  offerDirective(domain: string, directiveId: string, payload: unknown, opts?: { domainHash?: string; actor?: string; returnCreated?: boolean }): Promise<string>;`,
+    `  offerDirective(domain: string, directiveId: string, payload: unknown, opts?: { domainHash?: string; actor?: string; returnCreated?: boolean }): Promise<string | { head: string; created?: { type: string; id: string }[]; workspace?: string }>;`,
     `  /** Opaque-bytes offer — retained for carriers that already hold an encoded envelope (back-compat). */`,
     `  offer(intentBytes: string | Uint8Array): Promise<string>;`,
     `  /** The workspace this holon is bound to — the \`workspace\` of every [NomosRef] this client composes. */`,

package/src/compile_package_main.ts

@@ -865,11 +865,13 @@ function emitDart(
 
 /** The pure-core support import generated TYPES files carry in layered-packages mode. */
 const DART_TYPES_IMPORT = `import 'package:nomos_types/nomos_types.dart';`;
-/** Version constraints the scaffolded pubspecs pin — move together with the Dart packages' releases. */
-// FLOOR = the release carrying every symbol generated code may reference (0.1.3: NomosRef).
-const NOMOS_TYPES_DEP = "^0.1.3";
-// FLOOR = the release carrying the bridge methods generated clients call (0.45.0: offerOutcome/NomosCreated.ref).
-const NOMOS_CLIENT_DEP = "^0.45.0";
+/** Version constraints the scaffolded pubspecs pin — move together with the Dart packages' releases.
+ *  Caret on 0.x is EXACT-MINOR (`^0.45.0` = `<0.46.0`), so these must track the CURRENT release, not
+ *  just the floor generated code needs — a lagging pin forces tenants into dependency_overrides. */
+// 0.1.4: custody-lifecycle types (CustodyBreakPolicy et al).
+const NOMOS_TYPES_DEP = "^0.1.4";
+// 0.46.0: custody lifecycle on NomosBridge/NomosSession (onCustodyBreak/custodyStatus/salvage lanes).
+const NOMOS_CLIENT_DEP = "^0.46.0";
 
 const isPubPackageName = (s: string): boolean => /^[a-z][a-z0-9_]*$/.test(s);