@githolon/dsl 0.108.6 → 0.110.0

package/src/framework/auth_provider_law.ts

@@ -12,9 +12,15 @@ import { t } from "../fields.js";
 import { Lww } from "../drivers.js";
 import { addToSet, set, withMarker, type PlannedOp } from "../ops.js";
 import { query } from "../query.js";
-import { readFrameworkDeclaredRows } from "../read.js";
+import {
+  readFrameworkAttestedRows,
+  readFrameworkDeclaredRows,
+} from "../read.js";
+import { attestedReadSubject, fromPayload, trustAuthorizedSource } from "../attested_core.js";
 import { GENESIS_WARRANT_ID } from "./genesis.js";
 import { readRef, readSet, refAs, workspaceInvariant } from "./workspace_invariant.js";
+import { object, relationType, self } from "../relation_schema.js";
+import { AUTH_PROVIDER_AUTHORITY, AUTH_PROVIDER_EPOCH_CONSUMER } from "../births.js";
 
 const epochMs = z.number().int().nonnegative();
 
@@ -29,9 +35,40 @@ export const AUTH_PROVIDER_KEY_ID_PREFIX = "auth-provider-key:";
 /** Stable prefix for ordered x5c certificate entries belonging to one typed public key. */
 export const AUTH_PROVIDER_CERTIFICATE_ID_PREFIX = "auth-provider-certificate:";
 
+/**
+ * The ordinary workspace relation which names the sovereign source allowed to
+ * publish replacement provider material into this workspace.
+ *
+ * It is neither ancestry nor placement. A birth may deliberately seat its
+ * immediate parent, copy an already chosen provider root, or choose another
+ * workspace; the adoption directive only asks this relation what current law
+ * authorises.
+ */
+export { AUTH_PROVIDER_AUTHORITY, AUTH_PROVIDER_EPOCH_CONSUMER };
+export const authProviderSourceRelations = relationType("workspace")
+  .asGlobal()
+  .relation(AUTH_PROVIDER_AUTHORITY, {
+    rewrite: self(),
+    allow: [object("workspace")],
+  });
+/**
+ * The inverse edge: the parent's own permission for one immediate child to ask for its current
+ * verifier epoch (`nomosInternalServeAuthProviderEpoch7c1f5e` gates on it). Seated by every
+ * framework birth for the child it births; declared here once so no tenant re-declares it.
+ */
+export const authProviderEpochConsumerRelations = relationType("workspace")
+  .asGlobal()
+  .relation(AUTH_PROVIDER_EPOCH_CONSUMER, {
+    rewrite: self(),
+    allow: [object("workspace")],
+  });
+
 export const AuthProvider = aggregate("AuthProvider", {
-  /** The singleton key — always `"platform"`. */
+  /** Workspace-local lookup key. Historical default-provider state uses `"platform"`. */
   scope: t.string().merge(Lww),
+  /** Stable provider namespace selected by new member law. It survives issuer and key rotation;
+   * historical default-provider rows omit it to preserve their original interpretation. */
+  identitySha256: t.string().merge(Lww).optional(),
   /** The token issuer (the `iss` claim tokens must carry). */
   issuer: t.string().merge(Lww),
   /** The provider's public JWKS endpoint (asymmetric verification keys). The KERNEL never fetches — it's a
@@ -117,6 +154,14 @@ export const authProviderCertificates = query("authProviderCertificates")
   .key("providerEpoch")
   .returns(AuthProviderCertificate);
 
+/** The declared read serving a workspace's own AuthProvider singleton. */
+export const authProvider = query("authProvider").key("scope").returns(AuthProvider);
+
+/** The workspace-local source binding authorises the named workspace's signed publication.
+ * It is independent of lineage and placement. Source custody, when present, reconciles the
+ * signer and exact read immediately; otherwise the attributable statement remains replayable. */
+export const identityProviderSourceTrust = trustAuthorizedSource("identityProviderSource");
+
 const authProviderAttestation = z.object({
   child: z.string().min(1),
   founder: z.string().min(1),
@@ -212,6 +257,13 @@ function readCurrentAuthProviderValue(): {
   if (provider?.issuer === undefined || provider.issuer.length === 0) return undefined;
   const keyEpoch = provider.keyEpoch;
   const providerEpoch = keyEpoch === undefined ? undefined : `platform:${keyEpoch}`;
+  // Keep execution in the exact order declared on every directive which calls
+  // this helper: provider, keys, certificates. Captured reads are an ordered
+  // replay transcript, so moving the convenient certificate join ahead of the
+  // key read would make the authored plan disagree with its own law contract.
+  const keyRows = providerEpoch === undefined
+    ? []
+    : readFrameworkDeclaredRows(authProviderKeys, AuthProviderKey, { providerEpoch });
   const certificates = providerEpoch === undefined
     ? []
     : readFrameworkDeclaredRows(
@@ -219,9 +271,7 @@ function readCurrentAuthProviderValue(): {
         AuthProviderCertificate,
         { providerEpoch },
       );
-  const keys = providerEpoch === undefined
-    ? []
-    : readFrameworkDeclaredRows(authProviderKeys, AuthProviderKey, { providerEpoch })
+  const keys = keyRows
         .sort((a, b) => (a.ordinal ?? Number.MAX_SAFE_INTEGER) - (b.ordinal ?? Number.MAX_SAFE_INTEGER))
         .map((key) => authProviderPublicKey.parse({
           kty: key.kty,
@@ -398,7 +448,120 @@ export const setAuthProvider = directive("setAuthProvider")
   .plan(updateAuthProviderConfiguration)
   .alsoEnsuresMany(AuthProviderKey)
   .alsoEnsuresMany(AuthProviderCertificate)
-  .requires("admin");
+  .requires("admin")
+  // Updating the provider verifier cannot require a token verified by that
+  // same (possibly stale) verifier. The active enrolled device authenticates
+  // the author; the independent admin relation still authorizes the change.
+  .authenticatesWithEnrolledDevice();
+
+/**
+ * One lazy provider repair, expressed as ordinary law.
+ *
+ * The payload carries only the routable source workspace. The verifier
+ * material is read from that sovereign workspace through Nomos's existing
+ * attested-read machinery, captured on this ordinary intent, and folded into
+ * this workspace's normal AuthProvider aggregates. The peer runtime may reuse
+ * the same attestation across many local workspaces, but after this offer is
+ * admitted it is absent from every subsequent authentication operation.
+ */
+export const adoptIdentityProviderWitness = directive("adoptIdentityProviderWitness")
+  .mutates(AuthProvider)
+  .payload(z.object({ sourceWorkspace: z.string().min(1) }).strict())
+  .plan(({ sourceWorkspace }) => {
+    const providers = readFrameworkAttestedRows(
+      authProvider,
+      AuthProvider,
+      { scope: "platform" },
+      sourceWorkspace,
+    );
+    const provider = providers.find((row) => row.issuer !== undefined);
+    if (provider?.issuer === undefined || provider.issuer.length === 0) {
+      throw new Error("identity-provider source has no current provider publication");
+    }
+    if (provider.keyEpoch === undefined) {
+      throw new Error("identity-provider source has no typed key epoch");
+    }
+    const providerEpoch = `platform:${provider.keyEpoch}`;
+    const keyRows = readFrameworkAttestedRows(
+      authProviderKeys,
+      AuthProviderKey,
+      { providerEpoch },
+      sourceWorkspace,
+    );
+    const certificateRows = readFrameworkAttestedRows(
+      authProviderCertificates,
+      AuthProviderCertificate,
+      { providerEpoch },
+      sourceWorkspace,
+    );
+    const keys = keyRows
+      .sort((left, right) =>
+        (left.ordinal ?? Number.MAX_SAFE_INTEGER) -
+        (right.ordinal ?? Number.MAX_SAFE_INTEGER)
+      )
+      .map((key) => authProviderPublicKey.parse({
+        kty: key.kty,
+        kid: key.kid,
+        alg: key.alg,
+        use: key.use,
+        crv: key.crv,
+        x: key.x,
+        y: key.y,
+        n: key.n,
+        e: key.e,
+        keyOps: key.keyOps,
+        x5c: certificateRows
+          .filter((certificate) => certificate.keyOrdinal === key.ordinal)
+          .sort((left, right) =>
+            (left.certificateOrdinal ?? Number.MAX_SAFE_INTEGER) -
+            (right.certificateOrdinal ?? Number.MAX_SAFE_INTEGER)
+          )
+          .map((certificate) => certificate.derBase64),
+      }));
+    if (keys.length === 0) {
+      throw new Error("identity-provider source published an empty typed key epoch");
+    }
+    return updateAuthProviderConfiguration(authProviderConfiguration.parse({
+      issuer: provider.issuer,
+      jwksUrl: provider.jwksUrl && provider.jwksUrl.length > 0
+        ? provider.jwksUrl
+        : provider.issuer,
+      ...(provider.audience && provider.audience.length > 0
+        ? { audience: provider.audience }
+        : {}),
+      keySet: { epoch: provider.keyEpoch, keys },
+      ...(provider.principalClaim && provider.principalClaim.length > 0
+        ? { principalClaim: provider.principalClaim }
+        : {}),
+      ...(provider.rootCert && provider.rootCert.length > 0
+        ? { rootCert: provider.rootCert }
+        : {}),
+      ...(provider.deviceBindingClaim && provider.deviceBindingClaim.length > 0
+        ? { deviceBindingClaim: provider.deviceBindingClaim }
+        : {}),
+      ...(provider.requireDeviceBinding === "true" || provider.requireDeviceBinding === "false"
+        ? { requireDeviceBinding: provider.requireDeviceBinding }
+        : {}),
+      label: `adopted from ${sourceWorkspace}`,
+      setBy: `workspace:${sourceWorkspace}`,
+      setAt: Date.now(),
+    }));
+  })
+  .alsoEnsuresMany(AuthProviderKey)
+  .alsoEnsuresMany(AuthProviderCertificate)
+  .readsFrom(fromPayload("sourceWorkspace"), authProvider, {
+    policy: identityProviderSourceTrust,
+  })
+  .readsFrom(fromPayload("sourceWorkspace"), authProviderKeys, {
+    policy: identityProviderSourceTrust,
+  })
+  .readsFrom(fromPayload("sourceWorkspace"), authProviderCertificates, {
+    policy: identityProviderSourceTrust,
+  })
+  .requires("authProviderAuthority", {
+    object: "workspace:self",
+    subjectFrom: attestedReadSubject(authProvider),
+  });
 
 /**
  * Private child-genesis twin of {@link setAuthProvider}. It deliberately has no role requirement because
@@ -423,6 +586,3 @@ export const authProviderSeedBeforeWarrant = workspaceInvariant("AuthProviderSee
       ? { accept: true }
       : { reject: "seedAuthProvider is a child-genesis primitive; use the role-gated setAuthProvider after birth" };
   });
-
-/** The declared read serving a workspace's OWN AuthProvider row (and birthHome's inheritance capture). */
-export const authProvider = query("authProvider").key("scope").returns(AuthProvider);

package/src/framework/birth_certificate_law.ts

@@ -4,6 +4,7 @@
 // It is never lowered to a JSON string. The JWKS member is the external standardized JWKS document itself;
 // the certificate envelope and chain structure remain typed Nomos data.
 import { z } from "zod";
+import { valueObject } from "../value_object.js";
 
 export const birthCertificatePayload = z.object({
   child: z.string().min(1),
@@ -22,3 +23,6 @@ export const birthCertificatePayload = z.object({
 });
 
 export type BirthCertificatePayload = z.infer<typeof birthCertificatePayload>;
+
+/** One signed value. Merge operations must never combine members from different certificates. */
+export const BirthDelegationCertificate = valueObject("BirthDelegationCertificate", birthCertificatePayload.shape);

package/src/framework/capability.ts

@@ -157,6 +157,18 @@ export interface CapabilityDecl<
    * rest at `requested` with nowhere to go (the deploy notice says so).
    */
   readonly endpoint?: string;
+  /**
+   * Where the obligation's impure execution is allowed to happen. This is law,
+   * not host configuration: the kernel resolves it with the rest of the
+   * capability declaration and seals the resolved value into each admitted
+   * outbox offer. The policy exists even before a provider endpoint is bound:
+   * capability addressing is mutable law-state, while execution placement is
+   * part of the capability's semantic declaration. `custodian/singleton` is
+   * deliberately the only executable policy today. It means one live custodian
+   * for the source workspace; replicas and retained archives may carry the offer
+   * but must not perform it.
+   */
+  readonly execution?: CapabilityExecutionPolicy;
   /**
    * THE DECLASSIFY WAIVER (nomosFlowGate rule 5 — no private bytes in an outbound offer): present
    * iff the author acknowledged that this capability POSTs data derived from a private/encrypted
@@ -186,6 +198,11 @@ export interface CapabilityDecl<
   };
 }
 
+export interface CapabilityExecutionPolicy {
+  readonly placement: "custodian";
+  readonly cardinality: "singleton";
+}
+
 /**
  * Declare a typed marketplace capability. Sugar over {@link impureCapability} —
  * nothing new on the wire; the one piece of REAL work it adds is the
@@ -203,6 +220,11 @@ export function capability<
   request: Req;
   receipt?: Rec;
   endpoint?: string;
+  /** Defaults to `{ placement: "custodian", cardinality: "singleton" }`. */
+  execution?: {
+    placement: "custodian";
+    cardinality?: "singleton";
+  };
   declassify?: string;
   /** Authorization required to request the capability. Declare it here so the
    * capability's one obligation object remains identical everywhere it is composed. */
@@ -239,6 +261,10 @@ export function capability<
    * `declassify`, replayable and auditable, never a silent default.
    */
   openReceipts?: string;
+  /** The workspace relation that may grant and revoke provider authority. Defaults to `admin`; a
+   *  capability whose provider is operated infrastructure names `operator`, so an admin who is not an
+   *  operator cannot seat itself as the provider and close its own obligations. */
+  providerGrantedBy?: "admin" | "operator";
 }): CapabilityDecl<Req, Rec> {
   if (!CAPABILITY_NAME_RE.test(name)) {
     throw new Error(
@@ -352,7 +378,8 @@ export function capability<
   // the hard way (re-exporting them registered an ungated `workspace:self#admin@…` writer — a
   // self-grant-admin hole). A law that exported them alongside this fence would let anyone
   // self-grant provider authority and close their own obligations. So provider authority is
-  // seated ONLY through these admin-gated wrappers, scoped to THIS capability's object.
+  // seated ONLY through these gated wrappers (admin, or the operator by `providerGrantedBy`), scoped to
+  // THIS capability's object.
   const grantPayload = z.object({
     subject: z.string().min(1),
     grantedBy: z.string().min(1),
@@ -370,7 +397,7 @@ export function capability<
         grantedAt: p.grantedAt,
       }),
     )
-    .requires("admin");
+    .requires(spec.providerGrantedBy ?? "admin");
   const revokeProvider = directive(`revoke${pascal}Provider`)
     .ensures(RelationTuple)
     .payload(grantPayload.extend({ revokedBy: z.string().min(1), revokedAt: z.string().min(1) }))
@@ -385,7 +412,7 @@ export function capability<
         revokedAt: p.revokedAt,
       }),
     )
-    .requires("admin");
+    .requires(spec.providerGrantedBy ?? "admin");
 
   // THE FENCE, APPLIED. Every Receipt verb is gated on provider authority for THIS capability
   // unless the law carries an explicit `openReceipts` waiver. The gate is the shipped native
@@ -437,6 +464,10 @@ export function capability<
     instanceId: impureCapabilityInstanceId,
     name,
     ...(spec.endpoint !== undefined ? { endpoint: spec.endpoint } : {}),
+    execution: Object.freeze({
+      placement: spec.execution?.placement ?? "custodian",
+      cardinality: spec.execution?.cardinality ?? "singleton",
+    }),
     ...(spec.declassify !== undefined ? { declassify: spec.declassify } : {}),
     requestSchema: z.object(requestShape),
     receiptSchema: z.object(receiptShape),

package/src/framework/child_authentication.ts

@@ -0,0 +1,346 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded QuickJS engine}.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * CHILD AUTHENTICATION — framework law for every workspace that births business children.
+ *
+ * A child workspace verifies tokens against ITS OWN copied verifier and seats only the device keys it has
+ * been told about. Both go stale on their own: the identity provider rotates keys, or the person enrols a
+ * new device on the parent AFTER the child was born. The parent is the child's provider authority (the
+ * child seated {@link AUTH_PROVIDER_AUTHORITY} for it at genesis), so the parent repairs the child. Three
+ * lanes, all parameterised by the target workspace and none naming a child KIND:
+ *
+ *   1. THE VERIFIER-EPOCH PAIR — the child asks (`pull`, an enrolled-device request to its verified
+ *      parent), the parent answers (`serve`, gated on the parent's own {@link AUTH_PROVIDER_EPOCH_CONSUMER}
+ *      seat for that child) by replying with its CURRENT typed provider, and the child adopts it through the
+ *      verified-birth-parent recovery door (`acceptParentAuthProviderEpoch`, which also re-seats the
+ *      parent's authority so a child born before that seat existed heals itself).
+ *   2. CHILD-AUTHENTICATION REPAIR — a child refusing a device key it never seated
+ *      (`nomos.authz.signer_enrollment_missing`) is repaired by ONE parent action addressed to that child:
+ *      the parent discloses its current provider and its current signer grant for the person's exact
+ *      device; the child seats both atomically under its {@link AUTH_PROVIDER_AUTHORITY} gate.
+ *   3. THE GATE — the repair is an enrolled-device intent with NO parent-local write that addresses the
+ *      exact child from its typed input (the `repairsChildAuthenticationFor` shape), asserted here at
+ *      construction, and a device may repair only its own authenticated identity.
+ *
+ * COMPOSITION: the application-home policy law (`application_home.ts`) composes this set, presentation-
+ * internal, into the compiler-owned receiving-group lifecycle domain whenever the package declares any
+ * `.births()` child (business births or a tenant `.births()` directive). That domain runs on the platform
+ * and is installed into every born workspace, so one declaration serves both sides of every parent/child
+ * edge, and the compiler's exact-export rule (a workspace-effect target has exactly one owning domain) is
+ * met by construction. A package that births nothing composes none of it and is byte-identical.
+ *
+ * PROVENANCE: the framework form of CO2's per-child-kind copies (`co2_home/auth_provider_epoch_handler.ts`,
+ * `child_auth_provider_epoch_accept.ts`, `catalogue/auth_provider_epoch_accept.ts`,
+ * `co2_platform/auth_provider_epoch.ts`). The semantics are reproduced exactly, including the first
+ * disclosure carrying only VERIFYING material (no optional attestation member), so a child running law from
+ * before the attestation member existed can reopen and then adopt the complete provider through the second
+ * effect.
+ */
+import { z } from "zod";
+import type { Ports } from "../ctx.js";
+import { directive, nomosImplementationDetail } from "../directive.js";
+import { assertRepairsChildAuthentication, intent } from "../intent.js";
+import { query } from "../query.js";
+import { readFrameworkDeclaredRows } from "../read.js";
+import type { RelationTypeDecl } from "../relation_schema.js";
+import {
+  AUTH_PROVIDER_AUTHORITY,
+  AUTH_PROVIDER_EPOCH_CONSUMER,
+  AuthProvider,
+  AuthProviderCertificate,
+  AuthProviderKey,
+  authProvider,
+  authProviderCertificates,
+  authProviderConfiguration,
+  authProviderEpochConsumerRelations,
+  authProviderKeys,
+  authProviderSourceRelations,
+  readAuthProviderConfiguration,
+  writeAuthProviderConfiguration,
+} from "./auth_provider_law.js";
+import { BirthAttestation } from "./receiving_group.js";
+import { RelationTuple, relationTuplesByObject, writeTuple } from "./relations.js";
+import { SIGNER_RELATION, signerObject } from "./signing_identity.js";
+import { readSet, workspaceInvariant } from "./workspace_invariant.js";
+import { repairChildAuthProviderEpochConsumer } from "./legacy/child_auth_provider_epoch.js";
+
+// Kept in a compatibility module, registered through this framework declaration
+// boundary so runtime plan slicing resolves it just like the current lanes.
+export { repairChildAuthProviderEpochConsumer } from "./legacy/child_auth_provider_epoch.js";
+
+/** Wire ids — framework-internal, obscure on purpose (the 7c1f5e suffix convention). */
+export const ACCEPT_PARENT_AUTH_PROVIDER_EPOCH_ID = "nomosInternalAcceptParentAuthProviderEpoch7c1f5e";
+export const ACCEPT_CHILD_AUTHENTICATION_RECOVERY_ID = "nomosInternalAcceptChildAuthenticationRecovery7c1f5e";
+export const ACCEPT_CHILD_AUTHENTICATION_RECOVERY_EFFECT_ID =
+  "nomosInternalAcceptChildAuthenticationRecoveryEffect7c1f5e";
+export const SERVE_AUTH_PROVIDER_EPOCH_ID = "nomosInternalServeAuthProviderEpoch7c1f5e";
+export const PULL_PARENT_AUTH_PROVIDER_EPOCH_ID = "nomosInternalPullParentAuthProviderEpoch7c1f5e";
+export const REPAIR_CHILD_AUTHENTICATION_ID = "nomosInternalRepairChildAuthentication7c1f5e";
+
+/** The minimal typed state a parent discloses to one immediate child when that child can no longer
+ * recognise the person's current device/provider epoch. The parent derives every member from its
+ * committed signer relation; callers identify the child, their authenticated user and the exact device. */
+export const childAuthenticationRecoveryEvidence = z
+  .object({
+    user: z.string().min(1),
+    deviceKeySubject: z.string().regex(/^key:[0-9a-f]{64}$/),
+    enrolledAt: z.string().min(1),
+    verifiedVia: z.string().min(1),
+    validFromEpoch: z.number().int().nonnegative(),
+    authProvider: authProviderConfiguration,
+  })
+  .strict();
+export type ChildAuthenticationRecoveryEvidence = z.infer<typeof childAuthenticationRecoveryEvidence>;
+
+/** The parent's typed call: the affected child, the authenticated person and (when the person holds more
+ * than one active device on the parent) the exact device. Omitting the device is compatible only with a
+ * single active signer. */
+export const childAuthenticationRepairInput = z
+  .object({
+    workspace: z.string().min(1),
+    user: z.string().min(1),
+    deviceKeySubject: z.string().regex(/^key:[0-9a-f]{64}$/).optional(),
+  })
+  .strict();
+export type ChildAuthenticationRepairInput = z.infer<typeof childAuthenticationRepairInput>;
+
+/** The verified singleton birth record, addressed only by a law-authored constant, so the
+ * parent-authority seat can choose neither the parent workspace nor the relation it grants. */
+export const verifiedBirthAttestation = nomosImplementationDetail(
+  query("nomosInternalVerifiedBirthAttestation7c1f5e").key("verified").returns(BirthAttestation),
+);
+
+function writeVerifiedBirthParentAuthProviderAuthority(ctx: Ports) {
+  const births = readFrameworkDeclaredRows(verifiedBirthAttestation, BirthAttestation, { verified: "true" });
+  if (births.length !== 1) {
+    throw new Error(
+      `receiving-group recovery requires exactly one verified BirthAttestation; found ${births.length}`,
+    );
+  }
+  const birth = births[0]!;
+  if (birth.verified !== "true" || !birth.parentId?.trim()) {
+    throw new Error("receiving-group recovery requires a verified non-root parent");
+  }
+  return writeTuple({
+    object: "workspace:self",
+    relation: AUTH_PROVIDER_AUTHORITY,
+    subject: `workspace:${birth.parentId}`,
+    grantedBy: ctx.principal().asAttribution(),
+    grantedAt: String(ctx.clock().physical),
+  });
+}
+
+/** The one private consequence shared by exact-parent recovery transitions: the authority subject is
+ * derived from the child's verified birth record; neither sender nor host supplies it. */
+export const seatVerifiedBirthParentAuthority = nomosImplementationDetail(
+  directive("nomosInternalSeatVerifiedBirthParentAuthProviderAuthority7c1f5e")
+    .ensures(RelationTuple)
+    .payload(z.object({}).strict())
+    .plan((_payload, ctx) => writeVerifiedBirthParentAuthProviderAuthority(ctx))
+    .reads(verifiedBirthAttestation),
+);
+
+/** Accept only the parent's exact typed verifier configuration. */
+export const acceptParentAuthProviderEpochEffect = nomosImplementationDetail(
+  directive("nomosInternalAcceptParentAuthProviderEpochEffect7c1f5e")
+    .ensures(AuthProvider)
+    .payload(authProviderConfiguration)
+    .plan(writeAuthProviderConfiguration)
+    .alsoEnsuresMany(AuthProviderKey)
+    .alsoEnsuresMany(AuthProviderCertificate),
+);
+
+/** ONE child-authored transition seats the current device and verifier together. The caller cannot
+ * manufacture either value: parent law reads them from committed parent custody before emitting this
+ * exact effect, while the child independently requires the parent's authProviderAuthority relation. */
+export const acceptChildAuthenticationRecoveryEffect = nomosImplementationDetail(
+  directive(ACCEPT_CHILD_AUTHENTICATION_RECOVERY_EFFECT_ID)
+    .ensures(RelationTuple)
+    .payload(childAuthenticationRecoveryEvidence)
+    .plan((evidence, ctx) => [
+      ...writeTuple({
+        object: signerObject(evidence.user),
+        relation: SIGNER_RELATION,
+        subject: evidence.deviceKeySubject,
+        grantedBy: ctx.principal().asAttribution(),
+        grantedAt: evidence.enrolledAt,
+        verifiedVia: evidence.verifiedVia,
+        validFromEpoch: evidence.validFromEpoch,
+      }),
+      ...writeAuthProviderConfiguration(evidence.authProvider),
+    ])
+    .alsoEnsures(AuthProvider)
+    .alsoEnsuresMany(AuthProviderKey)
+    .alsoEnsuresMany(AuthProviderCertificate)
+    .requires(AUTH_PROVIDER_AUTHORITY, { object: "workspace:self" })
+    .acceptsWorkspaceEffect(),
+);
+
+function currentAuthProviderConfiguration() {
+  const configuration = readAuthProviderConfiguration();
+  if (configuration === undefined) {
+    throw new Error("serving a verifier epoch requires this workspace's current typed AuthProvider");
+  }
+  return configuration;
+}
+
+/**
+ * Existing child laws may predate the current nominal identity of the optional lineage attestation
+ * record. They only need the provider's VERIFYING configuration in order to reopen and lawfully enrol the
+ * current device, so the first disclosure omits that optional audit member. The complete current typed
+ * provider (attestation included) still travels in the subsequent child-authentication recovery effect
+ * once the child has adopted current law.
+ */
+function currentVerifyingAuthProviderConfiguration() {
+  const { attestation: _attestation, ...configuration } = currentAuthProviderConfiguration();
+  return configuration;
+}
+
+function currentChildAuthenticationRecoveryEvidence(user: string, deviceKeySubject?: string) {
+  // The parent is the child's authority. Its current signer relation is the fact to disclose, including
+  // grants whose old enrolment certificate was not retained. Re-reading that relation also prevents recovery
+  // from resurrecting a revoked key merely because an old certificate still exists.
+  const rows = readFrameworkDeclaredRows(relationTuplesByObject, RelationTuple, {
+    object: signerObject(user),
+  });
+  const matches = rows
+    .filter((row) => row.object === signerObject(user) && row.relation === SIGNER_RELATION)
+    .flatMap((row) =>
+      Object.entries(row.subjects ?? {}).filter(
+        ([subject, grant]) =>
+          subject.startsWith("key:") &&
+          grant.status === "active" &&
+          (deviceKeySubject === undefined || subject === deviceKeySubject),
+      ),
+    );
+  if (matches.length !== 1) {
+    throw new Error(
+      `child authentication repair requires exactly one current signer grant for '${user}' and the requested device; found ${matches.length}`,
+    );
+  }
+  const [subject, grant] = matches[0]!;
+  const provider = currentAuthProviderConfiguration();
+  if (grant.verifiedVia !== provider.issuer || grant.validFromEpoch === undefined) {
+    throw new Error(
+      "child authentication repair requires the parent's provider-verified signer grant and its recorded epoch",
+    );
+  }
+  return childAuthenticationRecoveryEvidence.parse({
+    user,
+    deviceKeySubject: subject,
+    enrolledAt: grant.grantedAt,
+    verifiedVia: grant.verifiedVia,
+    validFromEpoch: grant.validFromEpoch,
+    authProvider: provider,
+  });
+}
+
+/** The empty request body of the epoch pull/serve pair (a strict object: no field may ride it). */
+const emptyRequest = z.object({}).strict();
+
+/** The child adopts its parent's exact current verifier through the verified-birth-parent door, and
+ * re-seats that parent as its provider authority (a child born before the seat existed heals itself). */
+export const acceptParentAuthProviderEpoch = nomosImplementationDetail(
+  intent(ACCEPT_PARENT_AUTH_PROVIDER_EPOCH_ID)
+    .contract({ accepts: authProviderConfiguration })
+    .directs(acceptParentAuthProviderEpochEffect, (configuration) => configuration)
+    .directs(seatVerifiedBirthParentAuthority, () => ({}))
+    .acceptsVerifiedBirthParentRecoveryEffect()
+    .atomically(),
+);
+
+/** The nominal route of the gated acceptor effect — the target the parent's repair addresses. */
+export const acceptChildAuthenticationRecovery = nomosImplementationDetail(
+  intent(ACCEPT_CHILD_AUTHENTICATION_RECOVERY_ID).performs(acceptChildAuthenticationRecoveryEffect),
+);
+
+/** A verified child asks; parent law replies with its current typed verifier epoch. */
+export const serveAuthProviderEpoch = nomosImplementationDetail(
+  intent(SERVE_AUTH_PROVIDER_EPOCH_ID)
+    .contract({ accepts: emptyRequest })
+    .reads(authProvider, authProviderKeys, authProviderCertificates)
+    .repliesWorkspace(acceptParentAuthProviderEpoch, { payload: currentAuthProviderConfiguration })
+    .requires(AUTH_PROVIDER_EPOCH_CONSUMER, { object: "workspace:self" })
+    .acceptsWorkspaceEffect()
+    .atomically(),
+);
+
+/** The child asks its verified parent to refresh the verifier epoch. The route is resolved by the kernel
+ * from birth custody; no workspace string enters the payload. */
+export const pullParentAuthProviderEpoch = nomosImplementationDetail(
+  intent(PULL_PARENT_AUTH_PROVIDER_EPOCH_ID)
+    .contract({ accepts: emptyRequest })
+    .directsParentWorkspace(serveAuthProviderEpoch, { payload: () => ({}) })
+    .authenticatesWithEnrolledDevice()
+    .atomically(),
+);
+
+/** A child-open failure selects this exact parent action. The parent derives the recovery state from its
+ * own committed custody; the call identifies the affected child, the authenticated principal and the exact
+ * device. The first effect lets a child with a stale verifier reopen; the second seats the device. */
+export const repairChildAuthentication = nomosImplementationDetail(
+  intent(REPAIR_CHILD_AUTHENTICATION_ID)
+    .contract({ accepts: childAuthenticationRepairInput })
+    .reads(relationTuplesByObject, authProvider, authProviderKeys, authProviderCertificates)
+    .directsWorkspace(acceptParentAuthProviderEpoch, {
+      workspace: ({ workspace }) => workspace,
+      payload: currentVerifyingAuthProviderConfiguration,
+    })
+    .directsWorkspace(acceptChildAuthenticationRecovery, {
+      workspace: ({ workspace }) => workspace,
+      payload: ({ user, deviceKeySubject }) =>
+        currentChildAuthenticationRecoveryEvidence(user, deviceKeySubject),
+    })
+    .authenticatesWithEnrolledDevice()
+    .atomically(),
+);
+// THE GATE, applied by the framework: enrolled-device proof, no parent-local write, the exact child
+// addressed from the typed input. Asserted at definition so no composition can carry a differently
+// shaped repair.
+assertRepairsChildAuthentication(repairChildAuthentication, "framework child-authentication repair");
+
+/** A device may repair only its own authenticated identity. */
+export const repairChildAuthenticationBindsPrincipal = workspaceInvariant("RepairChildAuthenticationBindsPrincipal")
+  .on(REPAIR_CHILD_AUTHENTICATION_ID)
+  .reads(readSet())
+  .assert((_snapshots, ctx) =>
+    ctx?.principal === (ctx?.intent as { user?: unknown } | undefined)?.user
+      ? { accept: true }
+      : { reject: "child-authentication-repair-must-bind-authenticated-user" },
+  );
+
+/** The relation schema the lanes above gate on, declared once by the framework. The private-read lane
+ * already supplies the provider-authority fragment; both are the canonical singletons, so composing them
+ * beside it deduplicates by identity, and a tenant's byte-identical copy in another domain passes the
+ * cross-domain divergence guard. */
+export const childAuthenticationRelationFragments: readonly RelationTypeDecl[] = [
+  authProviderSourceRelations,
+  authProviderEpochConsumerRelations,
+];
+
+/**
+ * The export map the application-home policy law composes. Keys are the obscure `__nomos_*` slots; values
+ * are THE singletons above — the law graph folds an intent's step closure by object identity, so the
+ * exported effect must be the very object its intent directs. The gated acceptor effect is carried only
+ * through its nominal intent's step closure (the compiler qualifies relation-gated directives into fresh
+ * objects, so a second export slot would resolve the one effect to two declarations).
+ */
+export function childAuthenticationExports(): Readonly<Record<string, object>> {
+  return {
+    __nomos_verifiedBirthAttestation: verifiedBirthAttestation,
+    __nomos_seatVerifiedBirthParentAuthority: seatVerifiedBirthParentAuthority,
+    __nomos_acceptParentAuthProviderEpochEffect: acceptParentAuthProviderEpochEffect,
+    __nomos_acceptParentAuthProviderEpoch: acceptParentAuthProviderEpoch,
+    __nomos_acceptChildAuthenticationRecovery: acceptChildAuthenticationRecovery,
+    __nomos_serveAuthProviderEpoch: serveAuthProviderEpoch,
+    __nomos_pullParentAuthProviderEpoch: pullParentAuthProviderEpoch,
+    __nomos_repairChildAuthentication: repairChildAuthentication,
+    __nomos_repairChildAuthenticationBindsPrincipal: repairChildAuthenticationBindsPrincipal,
+    __nomos_repairChildAuthProviderEpochConsumer: repairChildAuthProviderEpochConsumer,
+    __nomos_authProviderSourceRelations: authProviderSourceRelations,
+    __nomos_authProviderEpochConsumerRelations: authProviderEpochConsumerRelations,
+  };
+}