@githolon/dsl 0.80.2 → 0.81.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.80.2",
+  "version": "0.81.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/births.ts

@@ -79,6 +79,81 @@ export function birth(recipe: BirthRecipe): void {
   footprint.push(recipe);
 }
 
+// `nomos.sha256` — the trustless pure hash bound in the sealed engine (like `nomos.mint`), used to derive a
+// singleton child's DETERMINISTIC name in-law so every peer re-derives the same name.
+declare const nomos: { sha256(input: string): string };
+
+/** A genesis chain, or a builder that receives the resolved child workspace name (so a seed step can embed
+ *  it — e.g. `seedEstate` needs to write its own `estateName`). Passing a builder is the common case. */
+export type GenesisChainOrBuilder = unknown | ((childWorkspace: string) => unknown);
+function resolveChain(child: string, c: GenesisChainOrBuilder): unknown {
+  return typeof c === "function" ? (c as (w: string) => unknown)(child) : c;
+}
+
+/** A `create()`d aggregate reference — the birth's audit record, whose MINTED (captured, replay-stable) id
+ *  becomes the instance child's workspace name. Only its `__id` is read. */
+interface MintedRef {
+  readonly __id: string;
+}
+
+/**
+ * THE BIRTH CARDINALITY DECISION — stated at the call site so an agent models it right by default.
+ *
+ * A born child's workspace name is its IDENTITY. The wrong instinct (births are deterministic, so derive the
+ * name from a stable field like the owner) silently caps the parent at ONE child per owner. So the choice is
+ * explicit and NAMED, exactly like a merge driver states convergence:
+ *
+ *   • `birth.instance(...)` — MANY children per parent. The child's workspace id is MINTED from `from` (an
+ *     aggregate you `create()` for the birth) — its id already rides the committed intent (captured), so the
+ *     child name reproduces byte-identically at replay. Nomos mints the identity; you never hand-roll it.
+ *
+ *   • `birth.singleton(...)` — EXACTLY ONE child per `keyedBy`. The name is DERIVED deterministically in-law,
+ *     so a re-birth is idempotent (same name → the child self-validates to the same identity). This is the
+ *     RIGHT tool for a home (one home per user), and the ONLY case where a name-from-a-field is correct.
+ *
+ * Raw {@link birth} stays the low-level escape hatch for an externally-determined name.
+ */
+export const birthInstance = ({
+  from,
+  prefix = "",
+  genesisChain,
+}: {
+  /** The `create()`d audit record whose minted, captured id names the child (replay-stable uniqueness). */
+  from: MintedRef;
+  /** Optional human-legible workspace-name prefix (e.g. `"estate-"`). */
+  prefix?: string;
+  genesisChain: GenesisChainOrBuilder;
+}): string => {
+  const child = prefix + from.__id;
+  footprint.push({ workspace: child, genesisChain: resolveChain(child, genesisChain) });
+  return child;
+};
+
+export const birthSingleton = ({
+  keyedBy,
+  namespace,
+  genesisChain,
+}: {
+  /** The key the child is a singleton OF (e.g. the owner). One child per distinct key; re-birth idempotent. */
+  keyedBy: string | readonly string[];
+  /** Optional name namespace/prefix (e.g. `"home"` → `home-<hash>`). */
+  namespace?: string;
+  genesisChain: GenesisChainOrBuilder;
+}): string => {
+  const parts = (Array.isArray(keyedBy) ? keyedBy : [keyedBy]).map(String);
+  const child = (namespace ? namespace + "-" : "") + nomos.sha256(JSON.stringify(parts)).slice(0, 40);
+  footprint.push({ workspace: child, genesisChain: resolveChain(child, genesisChain) });
+  return child;
+};
+
+// Function/namespace declaration merging: attach the two cardinality verbs to `birth` so the call site reads
+// `birth.instance(...)` / `birth.singleton(...)` — with full types AND the runtime assignment in one place.
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export namespace birth {
+  export const instance = birthInstance;
+  export const singleton = birthSingleton;
+}
+
 /**
  * THE PEER-SOVEREIGN ROOT-OF-TRUST SENTINEL (the BirthAttestation cert chain). A home/child law EXPORTS
  * this marker to declare it REQUIRES a parent-attested-birth: a warranted workspace running this law must

package/src/directive.ts

@@ -169,6 +169,28 @@ export interface Directive<P = unknown> {
       readonly signature: string;
     };
   };
+  /**
+   * DELEGATED-AUTHORITY DELIVERY (`delegatedRole`/`.delegatedFrom(parent)`,
+   * architecture/delegated_authority_births.md). When set, this directive folds a DELEGATED relation tuple
+   * ONLY if its payload carries a valid `DelegationCert` — a platform P's SIGNED grant, rooting at `K_root`,
+   * binding the SAME (relation, subject) the tuple writes, and (`.delegatedFrom(parent)`) whose grantor key
+   * is THIS workspace's declared parent key. Lowered into the `nomosDelegationGate` era key so the one gate
+   * (author / admission / verify_chain) re-verifies the grant OFFLINE — the delivered fact H's own
+   * `.requires(relation)` birth gate then reads locally. The kernel hardcodes no id/field — all law-declared.
+   */
+  readonly delegatedRoleGate?: {
+    /** The delegated relation the folded tuple writes (`co2EstateCreator`) — the cert must grant exactly it. */
+    readonly relation: string;
+    /** The payload field carrying the delegated subject (a `user:`/`key:` string). */
+    readonly subjectField: string;
+    /** The payload field carrying the `DelegationCert` (JSON string). */
+    readonly certField: string;
+    /** `.delegatedFrom(parent)`: the singleton INSTANCE id whose field holds this workspace's parent key
+     *  (e.g. `birth-attestation:self` / a seeded `platform-key:self`). "" ⇒ from-parent binding inert. */
+    readonly parentKeyObject: string;
+    /** The field on that singleton holding the parent's base64 ed25519 public key (e.g. `parentKey`). */
+    readonly parentKeyField: string;
+  };
   /**
    * THE KEYLESS VERIFIED-FIRST-DEVICE GATE (architecture/keyless_verified_onboard.md). When set, this
    * directive bootstraps a principal's FIRST device-signer from an ON-CHAIN, device-bound IdP attestation:
@@ -365,6 +387,21 @@ export interface RequirableDirective<P> extends Directive<P> {
    * host-free. Framework-only (the home law's `recordShare`). Returns a NEW requirable directive.
    */
   attestationAuthorized(owner: { ownerObject: string; ownerField: string }): RequirableDirective<P>;
+  /**
+   * Declare this directive a DELEGATED-AUTHORITY delivery (`delegated_authority_births.md`): its write folds
+   * the delegated `relation` tuple ONLY behind a carried `DelegationCert` P signed — lowered into the
+   * `nomosDelegationGate` era key so the one gate re-verifies the grant to `K_root` OFFLINE on every peer.
+   * `subjectField`/`certField` default to `"subject"`/`"delegationCert"`. Chain `.delegatedFrom(parent)` to
+   * bind the grantor to this workspace's parent key. Returns a NEW requirable directive.
+   */
+  delegatedRole(relation: string, opts?: { subjectField?: string; certField?: string }): RequirableDirective<P>;
+  /**
+   * `.delegatedFrom(parent)` — bind the delegating grantor to THIS workspace's parent key (the platform P
+   * that bore this home): the `DelegationCert`'s grantor key MUST equal the base64 key at
+   * `parentKeyObject.parentKeyField` (e.g. the birth-cert `birth-attestation:self`.`parentKey`, or a seeded
+   * `platform-key:self`.`grantorKey`). Refines the `.delegatedRole()` gate. Returns a NEW requirable directive.
+   */
+  delegatedFrom(parent: { parentKeyObject: string; parentKeyField: string }): RequirableDirective<P>;
   /**
    * Declare this directive a KEYLESS VERIFIED-FIRST-DEVICE bootstrap (keyless_verified_onboard.md): its
    * authorization is a carried, device-bound IdP `idpToken` re-verified against the workspace AuthProvider —
@@ -762,6 +799,44 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
         },
       });
     },
+    delegatedRole(relation: string, opts?: { subjectField?: string; certField?: string }): RequirableDirective<P> {
+      // DELEGATED-AUTHORITY DELIVERY (delegated_authority_births.md): this directive's write folds the
+      // delegated `relation` tuple ONLY behind a carried DelegationCert — lowered into the `nomosDelegationGate`
+      // era key, so the one gate re-verifies P's grant to K_root OFFLINE on every peer. Field names default to
+      // the framework convention here (the kernel reads them from the law's declaration, hardcoding nothing).
+      const prior = (base as { delegatedRoleGate?: { parentKeyObject?: string; parentKeyField?: string } })
+        .delegatedRoleGate;
+      return makeRequirable({
+        ...base,
+        delegatedRoleGate: {
+          relation,
+          subjectField: opts?.subjectField ?? "subject",
+          certField: opts?.certField ?? "delegationCert",
+          parentKeyObject: prior?.parentKeyObject ?? "",
+          parentKeyField: prior?.parentKeyField ?? "",
+        },
+      });
+    },
+    delegatedFrom(parent: { parentKeyObject: string; parentKeyField: string }): RequirableDirective<P> {
+      // .delegatedFrom(parent): bind the grantor to this workspace's parent key (the platform P). Refines the
+      // .delegatedRole() gate (a preceding .delegatedRole() supplies relation/fields; this adds the binding).
+      const g = (base as { delegatedRoleGate?: {
+        relation: string; subjectField: string; certField: string;
+      } }).delegatedRoleGate;
+      if (g === undefined) {
+        throw new Error("directive.delegatedFrom(): call .delegatedRole(relation) before .delegatedFrom(parent)");
+      }
+      return makeRequirable({
+        ...base,
+        delegatedRoleGate: {
+          relation: g.relation,
+          subjectField: g.subjectField,
+          certField: g.certField,
+          parentKeyObject: parent.parentKeyObject,
+          parentKeyField: parent.parentKeyField,
+        },
+      });
+    },
     verifiedFirstDevice(opts?: {
       tokenField?: string;
       keyHashField?: string;

package/src/usd.ts

@@ -347,6 +347,25 @@ export interface UsdLayer {
       }
     >;
   };
+  /**
+   * THE DELEGATED-AUTHORITY GATE (delegated_authority_births.md). Present IFF ≥1 directive declares
+   * `.delegatedRole()`: directiveId → {relation, subjectField, certField, parentKeyObject, parentKeyField}.
+   * The one gate folds the delegated tuple ONLY behind a DelegationCert P signed (rooting at K_root, binding
+   * the same relation+subject, `.delegatedFrom(parent)`). OMITTED for law with no such directive (era rule).
+   */
+  readonly nomosDelegationGate?: {
+    readonly v: 1;
+    readonly directives: Record<
+      string,
+      {
+        readonly relation: string;
+        readonly subjectField: string;
+        readonly certField: string;
+        readonly parentKeyObject: string;
+        readonly parentKeyField: string;
+      }
+    >;
+  };
   /**
    * THE KEYLESS VERIFIED-FIRST-DEVICE GATE (architecture/keyless_verified_onboard.md). Present IFF ≥1
    * directive declares `.verifiedFirstDevice()`: a per-directive payload FIELD MAPPING. A principal's FIRST
@@ -1136,6 +1155,30 @@ export function emitUsd(
       }
       const nomosAttestationGate =
         Object.keys(attestationReq).length > 0 ? { v: 1 as const, directives: attestationReq } : undefined;
+      // THE DELEGATED-AUTHORITY GATE (delegated_authority_births.md): directives declaring `.delegatedRole()`
+      // → directiveId → its {relation, subjectField, certField, parentKeyObject, parentKeyField}. SORTED keys
+      // (byte-determinism). Omit-when-empty (era rule) — a law with no delegation is byte-identical. The one
+      // gate verifies the carried DelegationCert to K_root + binds (relation, subject) + `.delegatedFrom(parent)`.
+      const delegationReq: Record<
+        string,
+        { relation: string; subjectField: string; certField: string; parentKeyObject: string; parentKeyField: string }
+      > = {};
+      for (const d of [...l.module.directives].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))) {
+        const g = (d as { delegatedRoleGate?: {
+          relation: string; subjectField: string; certField: string; parentKeyObject: string; parentKeyField: string;
+        } }).delegatedRoleGate;
+        if (g !== undefined) {
+          delegationReq[d.id] = {
+            relation: g.relation,
+            subjectField: g.subjectField,
+            certField: g.certField,
+            parentKeyObject: g.parentKeyObject,
+            parentKeyField: g.parentKeyField,
+          };
+        }
+      }
+      const nomosDelegationGate =
+        Object.keys(delegationReq).length > 0 ? { v: 1 as const, directives: delegationReq } : undefined;
       // THE ATTESTED-READ GATE (slice B): per-directive `(queryId, from)` edges + the module's
       // trustSource declarations. Emitted iff ≥1 directive declares a foreign read (the era
       // rule). A declared `from` with NO matching trustSource is a NAMED COMPILE ERROR — the
@@ -1492,6 +1535,7 @@ export function emitUsd(
         ...(nomosReadProjectionNamespace !== undefined ? { nomosReadProjectionNamespace } : {}),
         ...(nomosRelationGate !== undefined ? { nomosRelationGate } : {}),
         ...(nomosAttestationGate !== undefined ? { nomosAttestationGate } : {}),
+        ...(nomosDelegationGate !== undefined ? { nomosDelegationGate } : {}),
         ...(nomosAttestedReadGate !== undefined ? { nomosAttestedReadGate } : {}),
         ...(nomosBirthGate !== undefined ? { nomosBirthGate } : {}),
         ...(nomosBirthRecordGate !== undefined ? { nomosBirthRecordGate } : {}),

package/src/usd_layers.ts

@@ -198,6 +198,9 @@ function domainLayerAttrLines(domain: string, layer: UsdLayer, indent: string):
     ...(layer.nomosAttestationGate !== undefined
       ? [`${indent}custom string nomos:attestationGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosAttestationGate)))}`]
       : []),
+    ...(layer.nomosDelegationGate !== undefined
+      ? [`${indent}custom string nomos:delegationGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosDelegationGate)))}`]
+      : []),
     ...(layer.nomosAttestedReadGate !== undefined
       ? [`${indent}custom string nomos:attestedReadGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosAttestedReadGate)))}`]
       : []),
@@ -875,6 +878,22 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
         attestationGate = { v: 1, directives: rec };
       }
     }
+    // THE DELEGATED-AUTHORITY GATE (delegated_authority_births.md): directiveId → delegation spec merged
+    // later-wins across layers, SORTED keys. Omit-when-empty (era rule).
+    let delegationGate: UsdLayer["nomosDelegationGate"];
+    {
+      type DelSrc = NonNullable<UsdLayer["nomosDelegationGate"]>["directives"][string];
+      const a = new Map<string, DelSrc>();
+      for (const l of stack) {
+        if (l.nomosDelegationGate === undefined) continue;
+        for (const [id, src] of Object.entries(l.nomosDelegationGate.directives)) a.set(id, src);
+      }
+      if (a.size > 0) {
+        const rec: Record<string, DelSrc> = {};
+        for (const k of [...a.keys()].sort()) rec[k] = a.get(k)!;
+        delegationGate = { v: 1, directives: rec };
+      }
+    }
     // THE ATTESTED-READ GATE (slice B): sources + per-directive edges merged later-wins across
     // layers, SORTED keys (matching the composed emission). Omit-when-empty (era rule).
     let attestedReadGate: UsdLayer["nomosAttestedReadGate"];
@@ -1031,6 +1050,7 @@ return {
       ...(readProjectionNamespace !== undefined ? { nomosReadProjectionNamespace: readProjectionNamespace } : {}),
       ...(relationGate !== undefined ? { nomosRelationGate: relationGate } : {}),
       ...(attestationGate !== undefined ? { nomosAttestationGate: attestationGate } : {}),
+      ...(delegationGate !== undefined ? { nomosDelegationGate: delegationGate } : {}),
       ...(attestedReadGate !== undefined ? { nomosAttestedReadGate: attestedReadGate } : {}),
       ...(birthGate !== undefined ? { nomosBirthGate: birthGate } : {}),
       ...(birthRecordGate !== undefined ? { nomosBirthRecordGate: birthRecordGate } : {}),
@@ -1173,6 +1193,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
   const relationNamespaceByDomain = new Map<string, UsdLayer["nomosRelationNamespace"]>();
   const readProjectionNamespaceByDomain = new Map<string, UsdLayer["nomosReadProjectionNamespace"]>();
   const attestationGateByDomain = new Map<string, UsdLayer["nomosAttestationGate"]>();
+  const delegationGateByDomain = new Map<string, UsdLayer["nomosDelegationGate"]>();
   const attestedReadGateByDomain = new Map<string, UsdLayer["nomosAttestedReadGate"]>();
   const birthGateByDomain = new Map<string, UsdLayer["nomosBirthGate"]>();
   const birthRecordGateByDomain = new Map<string, UsdLayer["nomosBirthRecordGate"]>();
@@ -1248,6 +1269,11 @@ export function parseUsdaDocument(text: string): UsdDocument {
       if (typeof attGateHex === "string") {
         attestationGateByDomain.set(domain, JSON.parse(unhexUtf8(attGateHex)) as UsdLayer["nomosAttestationGate"]);
       }
+      // THE DELEGATED-AUTHORITY GATE (delegated_authority_births.md): the hex-carried delegation spec.
+      const delGateHex = p.attrs.get("nomos:delegationGateHex");
+      if (typeof delGateHex === "string") {
+        delegationGateByDomain.set(domain, JSON.parse(unhexUtf8(delGateHex)) as UsdLayer["nomosDelegationGate"]);
+      }
       // THE ATTESTED-READ GATE (slice B): the hex-carried trust-edge declaration.
       const attReadGateHex = p.attrs.get("nomos:attestedReadGateHex");
       if (typeof attReadGateHex === "string") {
@@ -1395,6 +1421,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
       const relNs = relationNamespaceByDomain.get(domain);
       const rpNs = readProjectionNamespaceByDomain.get(domain);
       const attGate = attestationGateByDomain.get(domain);
+      const delGate = delegationGateByDomain.get(domain);
       const attReadGate = attestedReadGateByDomain.get(domain);
       const birthGate = birthGateByDomain.get(domain);
       const birthRecordGate = birthRecordGateByDomain.get(domain);
@@ -1423,6 +1450,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
         ...(rpNs !== undefined ? { nomosReadProjectionNamespace: rpNs } : {}),
         ...(relGate !== undefined ? { nomosRelationGate: relGate } : {}),
         ...(attGate !== undefined ? { nomosAttestationGate: attGate } : {}),
+        ...(delGate !== undefined ? { nomosDelegationGate: delGate } : {}),
         ...(attReadGate !== undefined ? { nomosAttestedReadGate: attReadGate } : {}),
         ...(birthGate !== undefined ? { nomosBirthGate: birthGate } : {}),
         ...(birthRecordGate !== undefined ? { nomosBirthRecordGate: birthRecordGate } : {}),