@githolon/dsl 0.107.4 → 0.108.1

package/src/framework/home.ts

@@ -31,11 +31,16 @@ import { sha256Digest, t } from "../fields.js";
 import { Lww } from "../drivers.js";
 import { directive } from "../directive.js";
 import { ensure } from "../authoring.js";
-import { set, type PlannedOp } from "../ops.js";
+import { set, withMarker, type PlannedOp } from "../ops.js";
 import { query } from "../query.js";
 import { birth } from "../births.js";
-import { readFrameworkDeclared } from "../read.js";
-import { authProvider as authProviderQuery, seedAuthProvider } from "./auth_provider_law.js";
+import {
+  authProvider as authProviderQuery,
+  authProviderCertificates as authProviderCertificatesQuery,
+  authProviderKeys as authProviderKeysQuery,
+  readAuthProviderVerifyingConfiguration,
+  seedAuthProvider,
+} from "./auth_provider_law.js";
 import { readRef, readSet, workspaceInvariant, refAs } from "./workspace_invariant.js";
 import { identityRelations } from "./signing_identity.js";
 import { RelationTuple, writeTuple } from "./relations.js";
@@ -47,6 +52,7 @@ import {
   DomainInstallExecutor,
   domainInstallGenesisOffer,
 } from "./domain_lifecycle.js";
+import { birthCertificatePayload } from "./birth_certificate_law.js";
 
 // `nomos.sha256` — the TRUSTLESS, pure hash computed IN the githolon (Rust sha2 bound in the sealed engine;
 // see deterministic-rquickjs). Available as a global to plans + invariant predicates (like `nomos.mint`); it
@@ -354,18 +360,9 @@ export function birthReceivingGroupForDomain(
     // THE PARENT'S DECLARED VERIFIER. This captured read supplies the inherited provider seed.
     // Birth-certificate verification and founding-signer enrollment belong to the kernel-owned
     // attestation step, so neither fact is duplicated in this tenant plan or payload.
-    const apRows = p.inheritAuthProvider !== false
-      ? readFrameworkDeclared<Array<Record<string, unknown>>>("authProvider", { scope: "platform" })
-      : undefined;
-    const apRaw = Array.isArray(apRows) && apRows.length > 0 ? apRows[0] : undefined;
-    // Projected rows are `{type,id,data:{…fields}}`; folded shapes may be flat — accept both.
-    const ap = (apRaw && typeof apRaw === "object" && typeof (apRaw as { data?: unknown }).data === "object"
-      ? (apRaw as { data: Record<string, unknown> }).data
-      : apRaw) as Record<string, unknown> | undefined;
-    const apStr = (k: string): string | undefined => {
-      const v = ap?.[k];
-      return typeof v === "string" && v.length > 0 ? v : undefined;
-    };
+    const inheritedProvider = p.inheritAuthProvider === false
+      ? undefined
+      : readAuthProviderVerifyingConfiguration();
     const genesisChain: Array<{ domain: string; directiveId: string; actor: string; payload: Record<string, unknown>; domainHash?: string }> = [
       // THE ORDER-DECLARED LAW INSTALL: two typed closure identities. The kernel resolves each
       // closure from the parent's custody when it folds the birth; law bytes never ride the intent.
@@ -424,23 +421,14 @@ export function birthReceivingGroupForDomain(
     // (the up-front captured read above) AS DATA into the child genesis. The child owns the copy as its
     // own law-state; nothing is inherited-by-reference. Opt out: `inheritAuthProvider: false`.
     if (p.inheritAuthProvider !== false) {
-      const str = apStr;
-      const issuer = str("issuer");
-      if (issuer !== undefined) {
+      if (inheritedProvider !== undefined) {
         genesisChain.push({
           domain: groupLawDomain,
           directiveId: "seedAuthProvider",
           actor: founder,
           payload: {
-            issuer,
-            jwksUrl: str("jwksUrl") ?? issuer, // required by the framework schema; a keys-only provider mirrors its issuer
-            ...(str("keys") !== undefined ? { keys: str("keys") } : {}),
-            ...(str("audience") !== undefined ? { audience: str("audience") } : {}),
-            ...(str("principalClaim") !== undefined ? { principalClaim: str("principalClaim") } : {}),
-            ...(str("rootCert") !== undefined ? { rootCert: str("rootCert") } : {}),
-            ...(str("deviceBindingClaim") !== undefined ? { deviceBindingClaim: str("deviceBindingClaim") } : {}),
-            ...(str("requireDeviceBinding") !== undefined ? { requireDeviceBinding: str("requireDeviceBinding") } : {}),
-            label: str("label") ?? "inherited-from-parent",
+            ...inheritedProvider,
+            label: "inherited-from-parent",
             setBy: p.owner,
             setAt: 1, // genesis position — deterministic, like enrollSigner's grantedAt
           },
@@ -454,6 +442,8 @@ export function birthReceivingGroupForDomain(
     return [];
   })
   .reads(authProviderQuery) // the parent-side AuthProvider capture the inheritance copies (the #58 lane)
+  .reads(authProviderKeysQuery)
+  .reads(authProviderCertificatesQuery)
   .births(); // BIRTH IS A DECLARED KERNEL PRIMITIVE — emits the `nomosBirthGate` era key; the kernel folds the recipe
   return {
     ...birthDirective,
@@ -581,6 +571,7 @@ export const sharedByObject = query("sharedByObject").key("object").returns(Shar
  * verify doors); this aggregate is the human-readable mirror.
  */
 export const BIRTH_ATTESTATION_ID = "birth-attestation:self";
+export const BIRTH_ATTESTATION_LINK_PREFIX = "birth-attestation-link:";
 export const BirthAttestation = aggregate("BirthAttestation", {
   /** This home's self-id (`home-<sha256(founder)>`) — the cert's `child`. */
   child: t.string().merge(Lww),
@@ -594,12 +585,29 @@ export const BirthAttestation = aggregate("BirthAttestation", {
   parentKey: t.string().merge(Lww),
   /** The parent's SignerEpoch at the attestation (informational; the cert is judged at birth-time validity). */
   epoch: t.int().merge(Lww),
-  /** THE TRAVELLING SIGNED CERT CHAIN (JSON: `executor::birth_cert::BirthCertChain`) — the home's own
-   *  P-signed cert FIRST, then each ancestor's birth-cert up to root. The kernel verify doors parse THIS,
-   *  verify the signature chain to the pinned `K_root` OFFLINE (no cross-ws read), and assert it binds this
-   *  home (`child`==self-id, `founder`==HomeOwner.principal, `verified`). It travels because it folds into
-   *  the home's own genesis (seeded by the parent's offer-effect), so a peer holding only the home has it. */
-  certChain: t.string().merge(Lww),
+  /** Legacy replay slot for histories authored before `BirthAttestationLink`. New histories write the
+   *  travelling chain only as ordered, typed link records below. */
+  certChain: t.string().merge(Lww).optional(),
+}).public();
+
+/** One exact link in the travelling certificate chain. The zero-padded index is custody order; every
+ * certificate member is a separate typed USDA property. `certChain` above remains only as a replay fallback
+ * for histories authored before this aggregate existed. */
+export const BirthAttestationLink = aggregate("BirthAttestationLink", {
+  index: t.int().merge(Lww),
+  child: t.string().merge(Lww),
+  founder: t.string().merge(Lww),
+  verified: t.bool().merge(Lww),
+  parentKey: t.string().merge(Lww),
+  parentId: t.string().merge(Lww),
+  epoch: t.int().merge(Lww),
+  signature: t.string().merge(Lww),
+  verifiedVia: t.string().merge(Lww).optional(),
+  idpToken: t.string().merge(Lww).optional(),
+  capturedClock: t.int().merge(Lww).optional(),
+  authProviderIssuer: t.string().merge(Lww).optional(),
+  authProviderJwks: t.string().merge(Lww).optional(),
+  authProviderAudience: t.string().merge(Lww).optional(),
 }).public();
 
 /** Audit read: this home's birth attestation (who attested it + the verified verdict). */
@@ -611,7 +619,7 @@ export const birthAttestation = query("birthAttestation").key("child").returns(B
  * the [`BirthAttestation`] singleton so the home's own state carries its travelling cert. A CONTROL-PLANE
  * write seeded once at birth (the open session lane structurally refuses it by directive id). The values
  * are the parent's GATE VERDICT (`founder`/`verified` lowered from the captured port — CAS-as-law, never
- * the offer payload) + the signed chain bytes; the home's verify doors re-derive trust from the chain.
+ * the offer payload) + the typed signed links; the home's verify doors re-derive trust from the chain.
  */
 export const seedBirthAttestation = directive("seedBirthAttestation")
   .ensures(BirthAttestation)
@@ -625,21 +633,56 @@ export const seedBirthAttestation = directive("seedBirthAttestation")
       parentId: z.string(),
       parentKey: z.string().min(1), // base64 K_P
       epoch: z.number().int().nonnegative(),
-      certChain: z.string().min(1), // JSON BirthCertChain
+      links: z.array(birthCertificatePayload).min(1),
+      /** Law-declared target roles for the verified immediate parent workspace. The kernel injects this
+       * value from the admitted birth recipe and supplies `parentId`; no host chooses either fact. */
+      parentWorkspaceRoles: z.array(z.string().regex(/^[A-Za-z][A-Za-z0-9_-]*$/)).optional(),
+    }).superRefine((payload, ctx) => {
+      if ((payload.parentWorkspaceRoles?.length ?? 0) > 0 && payload.parentId.length === 0) {
+        ctx.addIssue({ code: "custom", message: "parent workspace roles require a verified non-root parentId" });
+      }
     }),
   )
   .plan((p) => {
     const h = instance(BirthAttestation, BIRTH_ATTESTATION_ID);
-    return [
+    const header = [
       set(h, "child", p.child),
       set(h, "founder", p.founder),
       set(h, "verified", p.verified),
       set(h, "parentId", p.parentId),
       set(h, "parentKey", p.parentKey),
       set(h, "epoch", p.epoch),
-      set(h, "certChain", p.certChain),
     ];
-  });
+    const links = p.links.flatMap((certificate, index) => {
+      const link = instance(BirthAttestationLink, `${BIRTH_ATTESTATION_LINK_PREFIX}${String(index).padStart(8, "0")}`);
+      return [
+        withMarker(set(link, "index", index), "ensures"),
+        withMarker(set(link, "child", certificate.child), "ensures"),
+        withMarker(set(link, "founder", certificate.founder), "ensures"),
+        withMarker(set(link, "verified", certificate.verified), "ensures"),
+        withMarker(set(link, "parentKey", certificate.parentKey), "ensures"),
+        withMarker(set(link, "parentId", certificate.parentId), "ensures"),
+        withMarker(set(link, "epoch", certificate.epoch), "ensures"),
+        withMarker(set(link, "signature", certificate.signature), "ensures"),
+        ...(certificate.verifiedVia ? [withMarker(set(link, "verifiedVia", certificate.verifiedVia), "ensures")] : []),
+        ...(certificate.idpToken ? [withMarker(set(link, "idpToken", certificate.idpToken), "ensures")] : []),
+        ...(certificate.capturedClock === undefined ? [] : [withMarker(set(link, "capturedClock", certificate.capturedClock), "ensures")]),
+        ...(certificate.authProviderIssuer ? [withMarker(set(link, "authProviderIssuer", certificate.authProviderIssuer), "ensures")] : []),
+        ...(certificate.authProviderJwks ? [withMarker(set(link, "authProviderJwks", certificate.authProviderJwks), "ensures")] : []),
+        ...(certificate.authProviderAudience ? [withMarker(set(link, "authProviderAudience", certificate.authProviderAudience), "ensures")] : []),
+      ];
+    });
+    const parentAuthority = (p.parentWorkspaceRoles ?? []).flatMap((relation) => writeTuple({
+      object: "workspace:self",
+      relation,
+      subject: `workspace:${p.parentId}`,
+      grantedBy: `workspace:${p.parentId}`,
+      grantedAt: String(p.epoch),
+    }));
+    return [...header, ...links, ...parentAuthority];
+  })
+  .alsoEnsures(BirthAttestationLink)
+  .alsoEnsures(RelationTuple);
 
 /**
  * THE ERA DECLARATION (the `nomosParentAttestedBirth` USD key). Exporting this sentinel from the home law
@@ -652,8 +695,8 @@ export const seedBirthAttestation = directive("seedBirthAttestation")
 export const parentAttestedBirth: ParentAttestedBirthMarker = {
   ...requireParentAttestedBirth,
   // DECLARE the owner + cert locators so the KERNEL reads them (it names neither): the home owner lives at
-  // the `HomeOwner` singleton's `principal`, the travelling cert at the `BirthAttestation` singleton's
-  // `certChain`. Mirrors how `.attestationAuthorized()` declares its owner-source — the kernel hardcodes none.
+  // the `HomeOwner` singleton's `principal`. `certObject`/`certField` retain the legacy chain locator for
+  // old histories; current histories are discovered through the typed `BirthAttestationLink` aggregate.
   ownerObject: RECEIVING_GROUP_ID,
   ownerField: "principal",
   certObject: BIRTH_ATTESTATION_ID,

package/src/framework/owned_custody.ts

@@ -19,10 +19,11 @@ import {
   writeWrap,
 } from "./encryption_scope.js";
 import { GenesisWarrant, seedGenesis } from "./genesis.js";
-import { BirthAttestation, seedBirthAttestation } from "./home.js";
+import { BirthAttestation, BirthAttestationLink, seedBirthAttestation } from "./home.js";
 import { RelationTuple, __qualifyAggregateType, removeTuple, writeTuple } from "./relations.js";
 import { SIGNER_RELATION, enrollSigner, signerObject, identityRelations } from "./signing_identity.js";
 import { impureCapability, impureCapabilityAggregate } from "./impure_capability.js";
+import { OwnedCustodyValue, OwnedDeviceRequestValue } from "./owned_custody_value.js";
 
 /** Obscure stable law id: deliberately unavailable as a generated tenant directive method. */
 export const OWNED_DEVICE_APPROVAL_DIRECTIVE = "nomos_internal_approve_owned_device_7c1f5e";
@@ -68,7 +69,7 @@ export const OwnedRecoveryPolicy = aggregate("NomosOwnedRecoveryPolicy", {
 const recoveryOrderParams = {
   ownerPrincipal: t.string().merge(Lww),
   recoveryPrincipal: t.string().merge(Lww),
-  deviceRequest: t.string().merge(Lww),
+  deviceRequest: OwnedDeviceRequestValue.merge(Lww),
 };
 
 /**
@@ -81,14 +82,14 @@ const recoveryOrderParams = {
  * the last thing that should degrade quietly.
  */
 const recoveryReceipt = {
-  ownedCustody: z.string().min(1),
+  ownedCustody: OwnedCustodyValue.zod,
 };
 
 /** Order fields ⊕ the receipt field, so the aggregate can hold what the Receipt writes. */
 const recoveryOrderFields = {
   ...recoveryOrderParams,
   // Absent until the recovery principal's Receipt lands (the read-decode discipline).
-  ownedCustody: t.string().merge(Lww).optional(),
+  ownedCustody: OwnedCustodyValue.merge(Lww).optional(),
 };
 
 /** Private framework Order -> Receipt journal. Generated business clients never expose this aggregate. */
@@ -105,7 +106,7 @@ const ownedRecoveryLifecycle = impureCapability({
   paramsSchema: {
     ownerPrincipal: principal,
     recoveryPrincipal: principal,
-    deviceRequest: z.string().min(1),
+    deviceRequest: OwnedDeviceRequestValue.zod,
   },
   writeParams: (id, p) => [
     set(instance(OwnedRecoveryOrder, id), "ownerPrincipal", p.ownerPrincipal),
@@ -114,7 +115,7 @@ const ownedRecoveryLifecycle = impureCapability({
   ],
   receiptSchema: recoveryReceipt,
   writeReceipt: (id, r) => [
-    set(instance(OwnedRecoveryOrder, id), "ownedCustody", r.ownedCustody as string),
+    set(instance(OwnedRecoveryOrder, id), "ownedCustody", OwnedCustodyValue.zod.parse(r.ownedCustody)),
   ],
   // This is intentionally unaddressed: opening the designated principal's ordinary generated
   // client is the provider. Declaring the capability still matters because every durable Order must
@@ -132,6 +133,13 @@ const hiddenRecoveryLifecycle = {
   deadLetter: hidden(ownedRecoveryLifecycle.deadLetter),
   reschedule: hidden(ownedRecoveryLifecycle.reschedule),
 };
+
+/** Compiler-contract handles for the two generated recovery calls used by the
+ * host. They remain framework-private directives; exporting the authored
+ * objects here lets code generation derive the cross-language signatures
+ * instead of maintaining another payload mirror. */
+export const requestOwnedRecovery = hiddenRecoveryLifecycle.obligation;
+export const completeOwnedRecovery = hiddenRecoveryLifecycle.complete;
 const ownedRecoveryCapability = {
   ...ownedRecoveryLifecycle,
   // Capability expansion deliberately re-seats the lifecycle quartet after application-language
@@ -152,7 +160,7 @@ export const ownedRecoveryOrdersByRecoveryPrincipal = query("nomosOwnedRecoveryO
   .returns(OwnedRecoveryOrder);
 
 /** Opt in once. Retrying the same policy is idempotent; replacing the principal is refused by the kernel. */
-const protectOwnedIdentity = Object.assign(
+export const protectOwnedIdentity = Object.assign(
   directive(OWNED_RECOVERY_PROTECT_DIRECTIVE)
     .ensures(OwnedRecoveryPolicy)
     .payload(z.object({
@@ -196,13 +204,13 @@ const protectOwnedIdentity = Object.assign(
   { businessBirthInternal: true as const, ownedAuthoringInternal: true as const },
 );
 
-const acceptOwnedRecovery = Object.assign(
+export const acceptOwnedRecovery = Object.assign(
   directive(OWNED_RECOVERY_ACCEPT_DIRECTIVE)
     .ensures(RelationTuple)
     .payload(z.object({
       requestId: z.string().min(1),
       newKeySubject: keySubject,
-      ownedCustody: z.string().min(1),
+      ownedCustody: OwnedCustodyValue.zod,
       recoveredAt: z.string().min(1),
     }))
     .plan((p, ctx) => {
@@ -249,7 +257,7 @@ const approval = directive(OWNED_DEVICE_APPROVAL_DIRECTIVE)
   .ensures(RelationTuple)
   .payload(z.object({
     newKeySubject: keySubject,
-    ownedCustody: z.string().min(1),
+    ownedCustody: OwnedCustodyValue.zod,
     verifiedVia: z.string().min(1),
     validFromEpoch: z.number().int().nonnegative(),
     approvedAt: z.string().min(1),
@@ -287,12 +295,12 @@ export const approveOwnedDevice = Object.assign(approval, {
 });
 
 /** Establish this principal's shared owned-data root before another principal shares to them. */
-const initializeOwnedIdentity = Object.assign(
+export const initializeOwnedIdentity = Object.assign(
   directive(OWNED_INITIALIZE_DIRECTIVE)
     .ensures(RelationTuple)
     .payload(z.object({
       newKeySubject: keySubject,
-      ownedCustody: z.string().min(1),
+      ownedCustody: OwnedCustodyValue.zod,
       initializedAt: z.string().min(1),
     }))
     .plan((p, ctx) => {
@@ -430,6 +438,7 @@ const CUSTODY_RELATIONS_EXPORT = "__nomos_owned_custody_relations_7c1f5e";
 const WARRANT_EXPORT = "__nomos_owned_genesis_warrant_7c1f5e";
 const SEED_EXPORT = "__nomos_owned_seed_genesis_7c1f5e";
 const BIRTH_ATTESTATION_EXPORT = "__nomos_owned_birth_attestation_7c1f5e";
+const BIRTH_ATTESTATION_LINK_EXPORT = "__nomos_owned_birth_attestation_link_7c1f5e";
 const BIRTH_ATTESTATION_SEED_EXPORT = "__nomos_owned_seed_birth_attestation_7c1f5e";
 const ENROLL_EXPORT = "__nomos_owned_enroll_signer_7c1f5e";
 const INITIALIZE_EXPORT = "__nomos_owned_initialize_identity_7c1f5e";
@@ -452,6 +461,7 @@ const RECOVERY_CAPABILITY_EXPORT = "__nomos_owned_recovery_capability_7c1f5e";
 const ownedGenesisWarrant = hidden(GenesisWarrant);
 const ownedSeedGenesis = hidden(seedGenesis);
 const ownedBirthAttestation = hidden(BirthAttestation);
+const ownedBirthAttestationLink = hidden(BirthAttestationLink);
 const ownedSeedBirthAttestation = hidden(seedBirthAttestation);
 const ownedEnrollSigner = hidden(enrollSigner);
 const ownedIdentityRelations = hidden(identityRelations);
@@ -543,6 +553,7 @@ export function withOwnedCustodyExports<M extends Record<string, unknown>>(mod:
     [WARRANT_EXPORT, ownedGenesisWarrant],
     [SEED_EXPORT, ownedSeedGenesis],
     [BIRTH_ATTESTATION_EXPORT, ownedBirthAttestation],
+    [BIRTH_ATTESTATION_LINK_EXPORT, ownedBirthAttestationLink],
     [BIRTH_ATTESTATION_SEED_EXPORT, ownedSeedBirthAttestation],
     [ENROLL_EXPORT, ownedEnrollSigner],
   ] as const) {
@@ -574,6 +585,7 @@ export function withOwnedCustodyExports<M extends Record<string, unknown>>(mod:
       [GenesisWarrant, ownedGenesisWarrant],
       [seedGenesis, ownedSeedGenesis],
       [BirthAttestation, ownedBirthAttestation],
+      [BirthAttestationLink, ownedBirthAttestationLink],
       [seedBirthAttestation, ownedSeedBirthAttestation],
       [enrollSigner, ownedEnrollSigner],
     ] as const) {
@@ -639,6 +651,7 @@ export function withOwnedCustodyExports<M extends Record<string, unknown>>(mod:
     [WARRANT_EXPORT]: ownedGenesisWarrant,
     [SEED_EXPORT]: ownedSeedGenesis,
     [BIRTH_ATTESTATION_EXPORT]: ownedBirthAttestation,
+    [BIRTH_ATTESTATION_LINK_EXPORT]: ownedBirthAttestationLink,
     [BIRTH_ATTESTATION_SEED_EXPORT]: ownedSeedBirthAttestation,
     [ENROLL_EXPORT]: ownedEnrollSigner,
   };

package/src/framework/owned_custody_value.ts

@@ -0,0 +1,51 @@
+// NOMOS — framework-owned typed custody values shared by relation facts, recovery Orders,
+// generated clients and the kernel. USDA is the canonical semantic representation; these
+// descriptors are the authored source from which TS/Dart encoders and decoders are generated.
+
+import { z } from "zod";
+import { valueObject, type ValueObjectValue } from "../value_object.js";
+
+const base64 = z.string().regex(/^[A-Za-z0-9+/]+={0,2}$/);
+const sha256 = z.string().regex(/^[0-9a-f]{64}$/);
+
+export const OwnedDeviceRequestValue = valueObject("OwnedDeviceRequest", {
+  v: z.number().int().min(1).max(255),
+  workspace: z.string().min(1),
+  principal: z.string().min(1),
+  scope: z.string().min(1),
+  signingPublic: base64,
+  wrappingPublic: base64,
+  signature: base64,
+});
+
+export type OwnedDeviceRequest = ValueObjectValue<typeof OwnedDeviceRequestValue>;
+
+export const OwnedCustodyValue = valueObject("OwnedCustody", {
+  v: z.number().int().min(1).max(255),
+  request: OwnedDeviceRequestValue,
+  hpkeEpk: base64,
+  ct: base64,
+  keyCommitment: sha256,
+  principalWrappingPublic: base64,
+});
+
+export type OwnedCustody = ValueObjectValue<typeof OwnedCustodyValue>;
+
+/** Deterministic compile/proof value. It is structurally valid but intentionally has no
+ * cryptographic authority; the live executor will reject it if it ever reaches admission. */
+export const OWNED_CUSTODY_PROBE: OwnedCustody = {
+  v: 1,
+  request: {
+    v: 1,
+    workspace: "nomos-probe",
+    principal: "user:nomos-probe",
+    scope: "nomos-probe",
+    signingPublic: "AA==",
+    wrappingPublic: "AA==",
+    signature: "AA==",
+  },
+  hpkeEpk: "AA==",
+  ct: "AA==",
+  keyCommitment: "0".repeat(64),
+  principalWrappingPublic: "AA==",
+};

package/src/framework/relations.ts

@@ -41,7 +41,7 @@
  */
 import { z } from "zod";
 import { aggregate, instance } from "../aggregate.js";
-import { t, type JsonValue } from "../fields.js";
+import { t } from "../fields.js";
 import { Lww, MapOf } from "../drivers.js";
 import { directive } from "../directive.js";
 import { set, setEntry, withMarker, type PlannedOp } from "../ops.js";
@@ -49,6 +49,8 @@ import { query } from "../query.js";
 import { endorsementOf, type AttributionPrincipal, type EndorsedAuthority } from "../principal_evidence.js";
 import { isRelationObjectToken, qualifyRelationType, type RelationObjectToken } from "../relation_schema.js";
 import { qualifyReadProjectionType } from "../read_projection_namespace.js";
+import { valueObject } from "../value_object.js";
+import { OwnedCustodyValue, type OwnedCustody } from "./owned_custody_value.js";
 
 // ─────────────────────────────── the dispatch context (relation-namespacing) ───────────────────────────────
 //
@@ -192,46 +194,70 @@ export function relationTupleInstanceId(object: string, relation: string): strin
  *  - relation  Lww (the edge label)
  *  - subjects  MapOf(Lww) — subject → typed `RelationshipSubject` runtime leaf
  */
+/** The exact law-level value stored for one subject in a relation tuple.
+ *
+ * This used to be `t.json()` and forced every generated reader to recover an
+ * unstructured object after the kernel had already proved a typed
+ * `RelationshipSubject`. Keeping the descriptor here makes the DSL graph the
+ * one authority for TS, Dart, USDA and the kernel's map leaf. */
+export const RelationshipSubjectValue = valueObject("RelationshipSubject", {
+  status: z.enum(["active", "revoked"]),
+  grantedBy: z.string(),
+  grantedAt: z.string(),
+  revokedBy: z.string().optional(),
+  revokedAt: z.string().optional(),
+  validFromEpoch: z.number().int().nonnegative().optional(),
+  verifiedVia: z.string().optional(),
+  ownedCustody: OwnedCustodyValue.optional(),
+});
+
 export const RelationTuple = aggregate("RelationTuple", {
   object: t.string().merge(Lww),
   relation: t.string().merge(Lww),
-  subjects: t.map(t.json()).merge(MapOf(Lww)),
+  subjects: t.map(RelationshipSubjectValue.field()).merge(MapOf(Lww)),
 }).public();
 export type RelationTupleHandle = typeof RelationTuple;
 
 /** The per-subject leaf the `subjects` map stores as a typed kernel value. */
 export interface RelationSubjectLeaf {
-  status: RelationStatus;
-  grantedBy: string;
-  grantedAt: string;
-  revokedBy?: string;
-  revokedAt?: string;
+  readonly status: RelationStatus;
+  readonly grantedBy: string;
+  readonly grantedAt: string;
+  readonly revokedBy?: string;
+  readonly revokedAt?: string;
   /**
    * VA-core (signer-provenance) — the SignerEpoch this leaf was authored under. OMITTED when absent so
    * every pre-VA chain (and every non-signer relation) stays byte-identical: `compact()` strips an
    * `undefined`. A revoke (`unrelateSubject`) backdates by bumping the SignerEpoch; a key whose
    * `validFromEpoch` predates the current epoch is stale (the full backdate gate is phase 4).
    */
-  validFromEpoch?: number;
+  readonly validFromEpoch?: number;
   /**
    * VA-core (signer-provenance) — the IdP/issuer that VOUCHED for the enrolling principal at enroll time
    * (e.g. the `AuthProvider.issuer`). The kernel's `verify_captured_principal` DERIVES `principal_verified`
    * from THIS leaf field (provenance, not the wire): an enrollment vouched by a real IdP reads verified on
    * every lane. OMITTED when absent (legacy / unverified enrollment) so existing chains stay byte-identical.
    */
-  verifiedVia?: string;
+  readonly verifiedVia?: string;
   /**
    * Secure-by-default owned-data device handoff. Framework-reserved and omitted from every ordinary
-   * relation leaf; the opaque JSON is independently verified by the kernel before it may land.
+   * relation leaf; the typed encrypted handoff is independently verified by the kernel before it may land.
    */
-  ownedCustody?: string;
+  readonly ownedCustody?: OwnedCustody;
 }
 
 /** Strip undefined keys so the typed leaf has one stable optional-field shape. */
-function compact(obj: Record<string, unknown>): RelationSubjectLeaf & Record<string, JsonValue> {
-  const out: Record<string, unknown> = {};
-  for (const [k, v] of Object.entries(obj)) if (v !== undefined) out[k] = v;
-  return out as RelationSubjectLeaf & Record<string, JsonValue>;
+function compact(leaf: RelationSubjectLeaf): RelationSubjectLeaf {
+  return {
+    status: leaf.status,
+    grantedBy: leaf.grantedBy,
+    grantedAt: leaf.grantedAt,
+    ...(leaf.revokedBy === undefined ? {} : { revokedBy: leaf.revokedBy }),
+    ...(leaf.revokedAt === undefined ? {} : { revokedAt: leaf.revokedAt }),
+    ...(leaf.validFromEpoch === undefined ? {} : { validFromEpoch: leaf.validFromEpoch }),
+    ...(leaf.verifiedVia === undefined ? {} : { verifiedVia: leaf.verifiedVia }),
+    ...(leaf.ownedCustody === undefined ? {} : { ownedCustody: leaf.ownedCustody }),
+  };
 }
 
 interface WriteTupleInput {
@@ -261,7 +287,7 @@ interface WriteTupleInput {
   /** VA-core: the IdP/issuer that vouched for the enrolling principal (signer relations only; omitted otherwise). */
   verifiedVia?: string;
   /** Framework-internal encrypted owned-data handoff (owned device relation only). */
-  ownedCustody?: string;
+  ownedCustody?: OwnedCustody;
 }
 
 /** Lower a tuple write to plan ops. The first op MATERIALIZES the (object, relation)
@@ -297,13 +323,13 @@ function lowerTuple(
     status: p.status,
     grantedBy: grantedByRaw,
     grantedAt: p.grantedAt,
-    revokedBy: revokedByRaw,
-    revokedAt: p.revokedAt,
+    ...(revokedByRaw === undefined ? {} : { revokedBy: revokedByRaw }),
+    ...(p.revokedAt === undefined ? {} : { revokedAt: p.revokedAt }),
     // VA-core signer-provenance leaf fields — `compact` strips an `undefined`, so a non-signer relation
     // (these never set) stays byte-identical to a pre-VA leaf (the era rule on the wire shape).
-    validFromEpoch: p.validFromEpoch,
-    verifiedVia: p.verifiedVia,
-    ownedCustody: p.ownedCustody,
+    ...(p.validFromEpoch === undefined ? {} : { validFromEpoch: p.validFromEpoch }),
+    ...(p.verifiedVia === undefined ? {} : { verifiedVia: p.verifiedVia }),
+    ...(p.ownedCustody === undefined ? {} : { ownedCustody: p.ownedCustody }),
   });
   const subjectEntry = {
     ...setEntry(rt, "subjects", subjectRaw, leaf),