@githolon/dsl 0.107.4 → 0.108.1

package/src/framework/signing_identity.ts

@@ -42,11 +42,12 @@
  *    only revokes keys of its OWN identity).
  */
 import { z } from "zod";
-import { aggregate, instance } from "../aggregate.js";
+import { birthCertificatePayload, type BirthCertificatePayload } from "./birth_certificate_law.js";
+import { aggregate, instance, type BoundAggregate } from "../aggregate.js";
 import { t } from "../fields.js";
 import { Lww } from "../drivers.js";
 import { directive } from "../directive.js";
-import { set, withMarker, type PlannedOp } from "../ops.js";
+import { set, withMarker, type FieldOp, type PlannedOp } from "../ops.js";
 import { query } from "../query.js";
 import { relationType, self, key } from "../relation_schema.js";
 import { readRef, readSet, workspaceInvariant, ref } from "./workspace_invariant.js";
@@ -57,6 +58,7 @@ import {
   RelationTuple,
   relationTupleInstanceId,
 } from "./relations.js";
+import { MODEL_LIFECYCLE_AUTHORITY } from "./domain_lifecycle.js";
 
 /**
  * The framework `identity` relation schema — the `signer` relation, LEAF-ONLY
@@ -83,6 +85,9 @@ export function signerObject(principal: string): string {
 /** The `signer` relation name — the relation a device key holds on its `identity:<principal>` object. */
 export const SIGNER_RELATION = "signer";
 
+/** Reserved workload principal for external admission receipts. It is never the business actor. */
+export const ADMISSION_CHECKPOINT_PRINCIPAL = "workspace:admission-peer";
+
 const sha256Hex = z.string().regex(/^[0-9a-f]{64}$/, "expected lowercase sha256 hex (the device pubkey hash)");
 
 // ─────────────────────────────── PHASE 0 — SignerEpoch ───────────────────────────────
@@ -239,6 +244,36 @@ export const enrollSigner = directive("enrollSigner")
     });
   });
 
+/**
+ * Enrol the runtime workload key which signs causal admission checkpoints. This is ordinary law:
+ * lifecycle authority chooses the public key, the relation is visible/revocable, and possession of
+ * the secret alone grants nothing. The key certifies that this workspace admitted an exact causal
+ * transition; the target directive's independent Zanzibar requirement remains business authority.
+ */
+export const enrollAdmissionCheckpointSigner = directive(
+  "_nmsEffectEnrollAdmissionCheckpointSigner",
+)
+  .ensures(RelationTuple)
+  .payload(
+    z.object({
+      keyHash: sha256Hex,
+      validFromEpoch: z.number().int().nonnegative(),
+      grantedAt: z.string().min(1),
+    }).strict(),
+  )
+  .plan((p, ctx) =>
+    writeTuple({
+      object: signerObject(ADMISSION_CHECKPOINT_PRINCIPAL),
+      relation: SIGNER_RELATION,
+      subject: `key:${p.keyHash}`,
+      grantedBy: ctx.principal().asAttribution(),
+      grantedAt: p.grantedAt,
+      validFromEpoch: p.validFromEpoch,
+      verifiedVia: "workspace-law",
+    }),
+  )
+  .requires(MODEL_LIFECYCLE_AUTHORITY, { object: "workspace:self" });
+
 /**
  * THE SELF-BIND ENROLL (VA-1 / B2). A device enrolls a key for ITS OWN verified identity — the bound
  * principal is `ctx.principal()` (the captured authoring principal), NOT a payload field, so a device can
@@ -305,8 +340,8 @@ export const enrollSignerSelfRequiresVerified = workspaceInvariant("EnrollSigner
  * DELEGATION CERT binding U's device key `P_U` to the tenant's lineage: a `BirthCert {founder: U,
  * parent_key: P_U, …}` signed by `S_P`. This singleton (keyed by U) records it in the PLATFORM's folded
  * state, so the kernel's birth offer-effect reads U's delegation by-user (trusted, not from the payload) when
- * it assembles U's home cert chain. The cert is OPAQUE on-chain (a JSON `BirthCert`); the kernel parses +
- * verifies it as one chain link (signed by S_P, whose pubkey is attested by the platform's own chain).
+ * it assembles U's home cert chain. Every certificate member is stored as typed USDA fields; the kernel
+ * reconstructs and verifies the nominal link signed by S_P, whose key is attested by the platform chain.
  *
  * SELF-BOUND / control-plane: enrolled by the tenant onboarding lane (composed into the tenant's governance
  * law, off the open session lane), so a tenant cannot forge a delegation for a user another tenant verified.
@@ -322,9 +357,21 @@ export const SignerDelegation = aggregate("SignerDelegation", {
   user: t.string().merge(Lww),
   /** The user's device PUBLIC KEY (base64) the delegation binds — `P_U`, the home_cert's signer. */
   deviceKey: t.string().merge(Lww),
-  /** THE DELEGATION CERT (JSON `executor::birth_cert::BirthCert`), signed by the tenant's `S_P`. Opaque
-   *  on-chain; the kernel parses + verifies it as the `links[1]` delegation in U's travelling chain. */
-  certJson: t.string().merge(Lww),
+  /** Legacy replay slot for histories authored before the typed certificate fields below. */
+  certJson: t.string().merge(Lww).optional(),
+  certificateChild: t.string().merge(Lww).optional(),
+  certificateFounder: t.string().merge(Lww).optional(),
+  certificateVerified: t.bool().merge(Lww).optional(),
+  certificateParentKey: t.string().merge(Lww).optional(),
+  certificateParentId: t.string().merge(Lww).optional(),
+  certificateEpoch: t.int().merge(Lww).optional(),
+  certificateSignature: t.string().merge(Lww).optional(),
+  certificateVerifiedVia: t.string().merge(Lww).optional(),
+  certificateIdpToken: t.string().merge(Lww).optional(),
+  certificateCapturedClock: t.int().merge(Lww).optional(),
+  certificateAuthProviderIssuer: t.string().merge(Lww).optional(),
+  certificateAuthProviderJwks: t.string().merge(Lww).optional(),
+  certificateAuthProviderAudience: t.string().merge(Lww).optional(),
   /** ISO-8601, caller-stamped (determinism — no clock in the plan). */
   enrolledAt: t.string().merge(Lww),
 }).public();
@@ -335,6 +382,29 @@ export function signerDelegationInstanceId(user: string): string {
   return SIGNER_DELEGATION_PREFIX + user;
 }
 
+function writeDelegationCertificate(
+  delegation: BoundAggregate<typeof SignerDelegation.id, typeof SignerDelegation.fields>,
+  certificate: BirthCertificatePayload,
+  marker?: "ensures",
+): PlannedOp[] {
+  const marked = (operation: FieldOp) => marker ? withMarker(operation, marker) : operation;
+  return [
+    marked(set(delegation, "certificateChild", certificate.child)),
+    marked(set(delegation, "certificateFounder", certificate.founder)),
+    marked(set(delegation, "certificateVerified", certificate.verified)),
+    marked(set(delegation, "certificateParentKey", certificate.parentKey)),
+    marked(set(delegation, "certificateParentId", certificate.parentId)),
+    marked(set(delegation, "certificateEpoch", certificate.epoch)),
+    marked(set(delegation, "certificateSignature", certificate.signature)),
+    ...(certificate.verifiedVia ? [marked(set(delegation, "certificateVerifiedVia", certificate.verifiedVia))] : []),
+    ...(certificate.idpToken ? [marked(set(delegation, "certificateIdpToken", certificate.idpToken))] : []),
+    ...(certificate.capturedClock === undefined ? [] : [marked(set(delegation, "certificateCapturedClock", certificate.capturedClock))]),
+    ...(certificate.authProviderIssuer ? [marked(set(delegation, "certificateAuthProviderIssuer", certificate.authProviderIssuer))] : []),
+    ...(certificate.authProviderJwks ? [marked(set(delegation, "certificateAuthProviderJwks", certificate.authProviderJwks))] : []),
+    ...(certificate.authProviderAudience ? [marked(set(delegation, "certificateAuthProviderAudience", certificate.authProviderAudience))] : []),
+  ];
+}
+
 /**
  * `enrollFirstDevice` (architecture/keyless_verified_onboard.md) — THE KEYLESS VERIFIED FIRST-DEVICE
  * self-onboard. A brand-new principal (an IdP-verified user with NO enrolled signer key) bootstraps its
@@ -369,8 +439,11 @@ export const enrollFirstDevice = directive("enrollFirstDevice")
       /** THE CAPTURED PREMISE: the IdP's signed identity assertion (JWT), re-verified on every lane against
        *  the on-chain AuthProvider keys. */
       idpToken: z.string().min(1),
-      /** THE KEYLESS DELEGATION CERT (JSON `executor::birth_cert::BirthCert`) — the self-serve sibling of
-       *  `enrollDelegation.certJson`. Built CLIENT-SIDE via the `cert_sign` op: DEVICE-self-signed by this
+      /** Legacy replay input for callers predating `delegationCertificate`. New callers must provide the
+       *  typed certificate below. */
+      delegationCert: z.string().min(1).optional(),
+      /** THE KEYLESS DELEGATION CERT — the self-serve sibling of `enrollDelegation.certificate`. Built
+       *  CLIENT-SIDE via the typed kernel sign operation: DEVICE-self-signed by this
        *  same device key `P_U` (parent_key == P_U), founder == `user:<uid>`, carrying `verifiedVia` +
        *  `idpToken` + `capturedClock`. There is NO tenant `S_P` in the loop — the kernel's home-birth chain
        *  walk (`verify_to_root`, keyless branch) RE-VERIFIES the token against the platform-attested
@@ -380,7 +453,7 @@ export const enrollFirstDevice = directive("enrollFirstDevice")
        *  OPTIONAL — an enroll-only flow (seat the signer, no imminent home birth) omits it and seeds no
        *  delegation (backward-compatible with every pre-B `enrollFirstDevice` caller). The keyless home-birth
        *  ceremony ALWAYS supplies it (that is what seeds the delegation the chain needs). */
-      delegationCert: z.string().min(1).optional(),
+      delegationCertificate: birthCertificatePayload.optional(),
     }),
   )
   .plan((p, ctx) => {
@@ -404,14 +477,24 @@ export const enrollFirstDevice = directive("enrollFirstDevice")
     // The delegation is keyed by the AUTHENTICATED principal — EXACTLY the `founder` the kernel's birth
     // offer-effect reads it back by (`read_signer_delegation(state, &founder)`, founder == captured principal
     // == this `rawPrincipal`, already in `user:<uid>` form). Do NOT re-prefix.
-    // Absent delegationCert ⇒ enroll-only (no delegation seeded), byte-identical to a pre-B enroll.
-    if (!p.delegationCert) return tupleOps;
+    // Absent certificate ⇒ enroll-only (no delegation seeded), byte-identical to a pre-B enroll.
+    if (!p.delegationCert && !p.delegationCertificate) return tupleOps;
     const d = instance(SignerDelegation, signerDelegationInstanceId(rawPrincipal));
     const delegationOps: PlannedOp[] = [
       withMarker(set(d, "user", rawPrincipal), "ensures"),
       withMarker(set(d, "deviceKey", "key:" + p.keyHash), "ensures"),
-      withMarker(set(d, "certJson", p.delegationCert), "ensures"),
-      withMarker(set(d, "enrolledAt", p.grantedAt), "ensures"),
+      ...(p.delegationCertificate
+        ? [
+            withMarker(set(d, "enrolledAt", p.grantedAt), "ensures"),
+            ...writeDelegationCertificate(d, p.delegationCertificate, "ensures"),
+          ]
+        : [
+            // Exact legacy event order is replay identity, even though Lww folding would commute these
+            // two writes. Historical enrollFirstDevice intents wrote certJson before enrolledAt; retain
+            // that byte-level outcome when re-authoring an old payload under a candidate law.
+            withMarker(set(d, "certJson", p.delegationCert!), "ensures"),
+            withMarker(set(d, "enrolledAt", p.grantedAt), "ensures"),
+          ]),
     ];
     return [...tupleOps, ...delegationOps];
   })
@@ -466,7 +549,7 @@ export const revokeSigner = directive("revokeSigner")
  * offer-effect can read U's delegation when it assembles U's home chain. `.ensures` (a deterministic-keyed
  * singleton — upsert-by-user). A CONTROL-PLANE write composed into the tenant's onboarding governance law
  * (off the open session lane) — only the tenant (whose `S_P` the platform chain attests) may enroll a
- * delegation. The `certJson` is verified by the kernel at home birth (signed by S_P, founder == U); a forged
+ * delegation. The typed certificate is verified by the kernel at home birth (signed by S_P, founder == U); a forged
  * delegation simply fails the chain walk / founder-binding at the child's gate.
  */
 export const enrollDelegation = directive("enrollDelegation")
@@ -475,7 +558,7 @@ export const enrollDelegation = directive("enrollDelegation")
     z.object({
       user: z.string().min(1), // the user:<uid> the delegation enrolls
       deviceKey: z.string().min(1), // base64 P_U — the user's device public key
-      certJson: z.string().min(1), // JSON BirthCert, signed by the tenant's S_P
+      certificate: birthCertificatePayload,
       enrolledAt: z.string().min(1), // ISO-8601, caller-stamped
     }),
   )
@@ -484,8 +567,8 @@ export const enrollDelegation = directive("enrollDelegation")
     return [
       set(d, "user", p.user),
       set(d, "deviceKey", p.deviceKey),
-      set(d, "certJson", p.certJson),
       set(d, "enrolledAt", p.enrolledAt),
+      ...writeDelegationCertificate(d, p.certificate),
     ];
   });
 

package/src/framework/workspaces.ts

@@ -106,7 +106,14 @@ export { enrollFirstDevice, revokeSigner } from "./signing_identity.js";
 // `[platform_cert]` chain would fail `verify_to_root` (>=2 links), so its own verify doors must stay inert
 // while it still carries the cert for its children. Fully additive (new aggregate + directive, no era key ⇒
 // pre-existing chains replay byte-identical). See architecture/verified_auth_from_genesis.md.
-export { BIRTH_ATTESTATION_ID, BirthAttestation, birthAttestation, seedBirthAttestation } from "./home.js";
+export {
+  BIRTH_ATTESTATION_ID,
+  BIRTH_ATTESTATION_LINK_PREFIX,
+  BirthAttestation,
+  BirthAttestationLink,
+  birthAttestation,
+  seedBirthAttestation,
+} from "./home.js";
 // THE ENROLL-ONCE DELEGATION LANE — a platform records each tenant's device-key delegation (signed by its
 // onboarding signer S_P) so the kernel reads it at `signer-delegation:<user>` when assembling a home's chain.
 export { SignerDelegation, enrollDelegation, signerDelegationByUser } from "./signing_identity.js";
@@ -1390,16 +1397,37 @@ export const setPlatformPool = directive("setPlatformPool")
 // here verbatim — the public surface and the law bytes are unchanged.
 export {
   AUTH_PROVIDER_ID,
+  AUTH_PROVIDER_KEY_ID_PREFIX,
+  AUTH_PROVIDER_CERTIFICATE_ID_PREFIX,
   AuthProvider,
+  AuthProviderKey,
+  AuthProviderCertificate,
+  authProviderPublicKey,
+  authProviderKeySet,
+  authProviderConfiguration,
+  type AuthProviderConfiguration,
+  writeAuthProviderConfiguration,
+  writeAuthProviderKeySet,
   seedAuthProvider,
   authProviderSeedBeforeWarrant,
   setAuthProvider,
   authProvider,
+  authProviderKeys,
+  authProviderCertificates,
+} from "./auth_provider_law.js";
+import {
+  AUTH_PROVIDER_ID,
+  AuthProvider,
+  AuthProviderCertificate,
+  AuthProviderKey,
+  authProvider,
+  authProviderKeySet,
+  setAuthProvider,
+  writeAuthProviderKeySet,
 } from "./auth_provider_law.js";
-import { AUTH_PROVIDER_ID, AuthProvider, setAuthProvider, authProvider } from "./auth_provider_law.js";
 
 /**
- * rotateKeys — TRUSTLESS key rotation. Replace {@link AuthProvider.keys} with a new JWKS whose every key
+ * rotateKeys — TRUSTLESS key rotation. Replace the typed key epoch with public keys whose every key
  * carries an `x5c` cert chain. DELIBERATELY UNGATED at the relation level — the KERNEL is the authority: it
  * admits this ONLY if each key's x5c chain validates (RFC 5280) to the law-pinned {@link AuthProvider.rootCert}
  * and each key matches its CA-vouched leaf cert (the bind). So a bailiff (host on a cron, or anyone) may
@@ -1410,17 +1438,18 @@ export const rotateKeys = directive("rotateKeys")
   .ensures(AuthProvider)
   .payload(
     z.object({
-      /** The new JWKS JSON; EACH key MUST carry an `x5c` the kernel validates to {@link AuthProvider.rootCert}. */
-      keys: z.string().min(1),
+      /** The new typed keys; EACH key MUST carry an `x5c` the kernel validates to the pinned root. */
+      keySet: authProviderKeySet,
       rotatedAt: epochMs,
-    }),
+    }).strict(),
   )
   .plan((p) => {
     const ap = instance(AuthProvider, AUTH_PROVIDER_ID);
-    // The kernel's x5c admission gate authorizes this (validate_rotate_keys); the plan just stores the
-    // CA-vouched JWKS. The `ensures` marker upserts onto the existing AuthProvider singleton.
-    return [withMarker(set(ap, "keys", p.keys), "ensures"), set(ap, "setAt", p.rotatedAt)];
-  });
+    // The kernel's x5c admission gate authorizes this; the plan stores the CA-vouched typed key epoch.
+    return [withMarker(set(ap, "keyEpoch", p.keySet.epoch), "ensures"), ...writeAuthProviderKeySet(p.keySet), set(ap, "setAt", p.rotatedAt)];
+  })
+  .alsoEnsuresMany(AuthProviderKey)
+  .alsoEnsuresMany(AuthProviderCertificate);
 
 /**
  * HostnameClaim — a CUSTOM HOSTNAME bound to a platform: `api.acme.com` serving

package/src/framework_call_definitions.ts

@@ -0,0 +1,53 @@
+// Stable framework operation names, bound to their authored directive schemas.
+//
+// This is deliberately metadata, not a second schema language. Every payload
+// type and encoder is derived from the Directive object carried here. Both the
+// TypeScript and Dart compilers consume this same list, so adding or changing a
+// framework field cannot leave a handwritten host mirror behind.
+
+import type { Directive } from "./directive.js";
+import { APPLICATION_HOME_DOMAIN } from "./framework/application_home_domain.js";
+import { setAuthProvider } from "./framework/auth_provider_law.js";
+import { seedBirthPolicy } from "./framework/birth_meter.js";
+import { installDomain, promoteDomain, rollbackDomain, stageDomain } from "./framework/domain_lifecycle.js";
+import { seedGenesis } from "./framework/genesis.js";
+import {
+  birthReceivingGroupForDomain,
+  seedBirthAttestation,
+  seedReceivingGroup,
+  seedReceivingGroupPolicy,
+} from "./framework/home.js";
+import { enrollDelegation, enrollFirstDevice, enrollSigner } from "./framework/signing_identity.js";
+
+export interface FixedFrameworkCallDefinition {
+  readonly group: "identity" | "lifecycle" | "birth";
+  readonly kind: string;
+  readonly directive: Directive<any>;
+  /** Needed by the pre-bind Dart birth ceremony before an application exists. */
+  readonly dartBirth?: true;
+  /** A composed application-home law must contain this operation. */
+  readonly requiredApplicationHome?: true;
+}
+
+const receivingGroupBirth = birthReceivingGroupForDomain(
+  APPLICATION_HOME_DOMAIN,
+  0,
+  [APPLICATION_HOME_DOMAIN],
+);
+
+export const fixedFrameworkCallDefinitions: readonly FixedFrameworkCallDefinition[] = [
+  { group: "identity", kind: "enrollFirstDevice", directive: enrollFirstDevice, dartBirth: true, requiredApplicationHome: true },
+  { group: "identity", kind: "enrollSigner", directive: enrollSigner, dartBirth: true, requiredApplicationHome: true },
+  { group: "identity", kind: "setAuthProvider", directive: setAuthProvider, requiredApplicationHome: true },
+  { group: "identity", kind: "birthReceivingGroup", directive: receivingGroupBirth, dartBirth: true, requiredApplicationHome: true },
+  { group: "lifecycle", kind: "installDomain", directive: installDomain },
+  { group: "lifecycle", kind: "stageDomain", directive: stageDomain },
+  { group: "lifecycle", kind: "promoteDomain", directive: promoteDomain },
+  { group: "lifecycle", kind: "rollbackDomain", directive: rollbackDomain },
+  { group: "birth", kind: "seedBirthPolicy", directive: seedBirthPolicy, dartBirth: true },
+  { group: "birth", kind: "enrollDelegation", directive: enrollDelegation, dartBirth: true },
+  { group: "birth", kind: "seedBirthAttestation", directive: seedBirthAttestation, dartBirth: true },
+  { group: "birth", kind: "seedGenesis", directive: seedGenesis, dartBirth: true },
+  { group: "birth", kind: "seedReceivingGroupPolicy", directive: seedReceivingGroupPolicy, dartBirth: true },
+  { group: "birth", kind: "seedReceivingGroup", directive: seedReceivingGroup, dartBirth: true },
+];

package/src/framework_read_definitions.ts

@@ -0,0 +1,45 @@
+// Stable framework reads bound to their authored aggregate/query declarations.
+//
+// This is metadata, not another schema language. The compiler consumes the
+// AggregateHandle/QueryDecl objects directly, so the public host contract,
+// canonical query USDA and result decoder all change together with the DSL.
+
+import type { AggregateHandle } from "./aggregate.js";
+import type { QueryDecl } from "./query.js";
+import { EncKey, encKeyByPrincipal } from "./framework/encryption_identity.js";
+import {
+  KeyScope,
+  WrappedKey,
+  keyScopeByScope,
+  wrappedKeysByRecipient,
+} from "./framework/encryption_scope.js";
+import {
+  OwnedRecoveryOrder,
+  OwnedRecoveryPolicy,
+  ownedRecoveryOrdersByRecoveryPrincipal,
+} from "./framework/owned_custody.js";
+import { RelationTuple, relationTuplesByObject } from "./framework/relations.js";
+import { SignerEpoch } from "./framework/signing_identity.js";
+
+export interface FixedFrameworkReadDefinition {
+  readonly kind:
+    | "encKey"
+    | "keyScope"
+    | "ownedRecoveryOrder"
+    | "ownedRecoveryPolicy"
+    | "relationTuple"
+    | "signerEpoch"
+    | "wrappedKey";
+  readonly aggregate: AggregateHandle;
+  readonly query?: QueryDecl;
+}
+
+export const fixedFrameworkReadDefinitions: readonly FixedFrameworkReadDefinition[] = [
+  { kind: "encKey", aggregate: EncKey, query: encKeyByPrincipal },
+  { kind: "keyScope", aggregate: KeyScope, query: keyScopeByScope },
+  { kind: "ownedRecoveryOrder", aggregate: OwnedRecoveryOrder, query: ownedRecoveryOrdersByRecoveryPrincipal },
+  { kind: "ownedRecoveryPolicy", aggregate: OwnedRecoveryPolicy },
+  { kind: "relationTuple", aggregate: RelationTuple, query: relationTuplesByObject },
+  { kind: "signerEpoch", aggregate: SignerEpoch },
+  { kind: "wrappedKey", aggregate: WrappedKey, query: wrappedKeysByRecipient },
+];

package/src/identity_frontier.ts

@@ -0,0 +1,58 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+
+export type IdentityFrontierSource = Readonly<{
+  source: string;
+  custody: "git-head" | "working-file";
+}>;
+
+/**
+ * Read the identity frontier which is already part of custody.
+ *
+ * The working identity layer is candidate output: it may contain identities minted
+ * by an earlier successful local compile which have never been committed or shipped.
+ * Git HEAD is therefore the historical evolution frontier whenever the package is in
+ * Git custody. Outside Git, the checked-in/working file remains the portable fallback.
+ */
+export function readHistoricalIdentityFrontier(
+  lockPath: string,
+): IdentityFrontierSource | undefined {
+  const directory = path.dirname(lockPath);
+  let repositoryRoot: string;
+  try {
+    repositoryRoot = realpathSync(execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd: directory,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim());
+  } catch {
+    return existsSync(lockPath)
+      ? { source: readFileSync(lockPath, "utf8"), custody: "working-file" }
+      : undefined;
+  }
+
+  const canonicalLockPath = path.join(realpathSync(directory), path.basename(lockPath));
+  const relative = path.relative(repositoryRoot, canonicalLockPath);
+  if (relative === "" || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    return existsSync(lockPath)
+      ? { source: readFileSync(lockPath, "utf8"), custody: "working-file" }
+      : undefined;
+  }
+
+  try {
+    return {
+      source: execFileSync("git", ["show", `HEAD:${relative.split(path.sep).join("/")}`], {
+        cwd: repositoryRoot,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      }),
+      custody: "git-head",
+    };
+  } catch {
+    // A repository with no committed identity has no historical frontier. Treating
+    // an untracked or candidate-only file as history would make local experimentation
+    // irreversible before it ever entered custody.
+    return undefined;
+  }
+}

package/src/index.ts

@@ -254,7 +254,7 @@ export { repair, repairsOf, isRepairDecl, type RepairDecl, type RepairMatcher, t
 // NOT YET DEPLOYABLE (#57): the sealed wasm engine does not provide `nomos.read` yet, so
 // `nomos-compile` REFUSES law that references read() (a named compile error, never a runtime halt).
 // The captured-reads wave (task #58) wires the capability in and lifts the refusal.
-export { read } from "./read.js";
+export { read, readFrameworkDeclaredRows } from "./read.js";
 // RELEASE COHERENCE — standard OSGi Contract Namespace requirements derived from law shape.
 export {
   requiredKernelContracts,
@@ -319,12 +319,14 @@ export {
 // `nomosBirthGate` era key, never domain state) — spawns + self-validates the child after the offer admits.
 export {
   birth,
+  workspaceRole,
   workspaceNameForKey,
   WORKSPACE_NAME_SEP,
   birthKeyed,
   birthSingleton,
   birthInstance,
   type BirthRecipe,
+  type WorkspaceRole,
   type GenesisChainOrBuilder,
   type BusinessBirthDecl,
   type BusinessBirthSpec,
@@ -505,6 +507,8 @@ export {
   identityRelations,
   signerObject,
   SIGNER_RELATION,
+  ADMISSION_CHECKPOINT_PRINCIPAL,
+  enrollAdmissionCheckpointSigner,
   enrollSigner,
   // VA-core — SignerEpoch + self-bind enroll/revoke + the strict-increment & verified-enroll gates.
   SignerEpoch,
@@ -535,11 +539,26 @@ export {
 // the provider explicitly, without re-declaring the kernel's security schema in tenant code.
 export {
   AUTH_PROVIDER_ID,
+  AUTH_PROVIDER_KEY_ID_PREFIX,
+  AUTH_PROVIDER_CERTIFICATE_ID_PREFIX,
   AuthProvider,
+  AuthProviderKey,
+  AuthProviderCertificate,
+  authProviderPublicKey,
+  authProviderKeySet,
+  authProviderConfiguration,
+  type AuthProviderConfiguration,
+  type AuthProviderVerifyingConfiguration,
+  readAuthProviderConfiguration,
+  readAuthProviderVerifyingConfiguration,
+  writeAuthProviderConfiguration,
+  writeAuthProviderKeySet,
   seedAuthProvider,
   authProviderSeedBeforeWarrant,
   setAuthProvider,
   authProvider,
+  authProviderKeys,
+  authProviderCertificates,
 } from "./framework/auth_provider_law.js";
 // THE RECEIVING-GROUP HOLON — the framework-private shared signer roster + access manifest.
 export {
@@ -566,7 +585,9 @@ export {
   birthReceivingGroup,
   // THE PEER-SOVEREIGN ROOT-OF-TRUST (the BirthAttestation cert chain).
   BirthAttestation,
+  BirthAttestationLink,
   BIRTH_ATTESTATION_ID,
+  BIRTH_ATTESTATION_LINK_PREFIX,
   seedBirthAttestation,
   birthAttestation,
   parentAttestedBirth,