@githolon/dsl 0.13.0 → 0.15.0

package/src/framework/impure_capability.ts

@@ -6,7 +6,7 @@
 // If a file isn't this / hosting this / authoring for this / proving this — it's gone.
 
 /**
- * framework/impure_capability.ts — the FRAMEWORK Order→Receipt mechanism (tenant-agnostic).
+ * framework/impure_capability.ts — the FRAMEWORK Obligation→Receipt mechanism (tenant-agnostic).
  *
  * ── Why this module exists (the framework↔tenant line) ───────────────────────
  * A *provider-side intent* in Nomos 1 was an ephemeral job: dispatch → the
@@ -17,12 +17,12 @@
  *
  * Nomos 2's law is "**every authored intent folds SOME aggregate**" (contract §1) —
  * there is no ephemeral job. The faithful shape of an async impure capability is therefore
- * an **Order → Receipt** pair of ordinary `WireIntent`s with a first-class lifecycle law:
+ * an **Obligation → Receipt** pair of ordinary `WireIntent`s with a first-class lifecycle law:
  *
- *   • **Order**   — a normal intent whose role is the request: a peer dispatches
- *                   `order…(params, status:'requested')`,
- *                   `.creates` a task aggregate keyed by a KERNEL-MINTED order id
- *                   (`<OrderType>_<uuidv7>`, via the marker-driven front-door; idempotent on
+ *   • **Obligation** — a normal intent whose role is the request: a peer dispatches
+ *                   `oblige…(params, status:'requested')`,
+ *                   `.creates` a task aggregate keyed by a KERNEL-MINTED obligation id
+ *                   (`<ObligationType>_<uuidv7>`, via the marker-driven front-door; idempotent on
  *                   replay by capture).
  *   • **(impure work)** — a capability provider watches `status:'requested'` rows, performs
  *                   the side-effect (rendering / upload / multi-target provider work — a host/report
@@ -33,14 +33,14 @@
  *                   Some domains also expose explicit blocked/DLQ receipts using the
  *                   same envelope fields below.
  *
- * Order and Receipt are roles/facets of `Intent`, not special admission objects, job-table rows,
+ * Obligation and Receipt are roles/facets of `Intent`, not special admission objects, job-table rows,
  * or a privileged mutation channel.
  *
  * **Reporting upward = the authoring peer reactively WATCHES the task aggregate.** The receipt
  * arrives as an ordinary projection update (no polling, no fire-and-forget push, no
  * response-mutation). This is exactly the proven `ExportJobAggregate` shape
  * (the tenant domains package `thing_structures`) generalised into a reusable framework pattern so a
- * domain dev does NOT hand-roll the {aggregate + order + complete + fail} quartet each
+ * domain dev does NOT hand-roll the {aggregate + obligation + complete + fail} quartet each
  * time — they DECLARE the task's params and get the quartet for free, like `relations.ts`
  * gives grant/revoke for free.
  *
@@ -77,7 +77,7 @@ import type { Ports } from "../ctx.js";
 
 /**
  * The impure-capability lifecycle vocabulary — framework-fixed. A task is `requested` when
- * the peer orders it; the provider authors the ordinary Receipt intent that flips it
+ * the peer obligates it; the provider authors the ordinary Receipt intent that flips it
  * to `completed` (with a `resultRef`) or `failed` (with a `failureReason`). One-way after a
  * terminal state: the lifecycle law is terminal-once at the gate/envelope, not a separate
  * privileged mutation channel.
@@ -92,14 +92,14 @@ export const IMPURE_CAPABILITY_STATUSES = [
 export type ImpureCapabilityStatus = (typeof IMPURE_CAPABILITY_STATUSES)[number];
 
 /**
- * The framework envelope fields EVERY impure-capability aggregate carries — the Order→Receipt
+ * The framework envelope fields EVERY impure-capability aggregate carries — the Obligation→Receipt
  * lifecycle, independent of the tenant's request params:
  *
  *  - requestId      Lww — the task's own id (== the aggregate instance id; a
- *                   KERNEL-MINTED `<OrderType>_<uuidv7>`). Immutable-after-create (the
+ *                   KERNEL-MINTED `<ObligationType>_<uuidv7>`). Immutable-after-create (the
  *                   create-only gap; modelled Lww).
- *  - requestedBy    Lww — who ordered the task (provenance). Immutable-after-create.
- *  - requestedAt    Int — epoch-ms the order was authored. Immutable-after-create.
+ *  - requestedBy    Lww — who obligated the task (provenance). Immutable-after-create.
+ *  - requestedAt    Int — epoch-ms the obligation was authored. Immutable-after-create.
  *  - status         Lww enum — `requested` → the reactor flips to a terminal status.
  *  - resultRef      Lww json (OPTIONAL) — the content-addressed RESULT the reactor
  *                   records on completion (a blob ref / download url JSON leaf). Absent
@@ -111,10 +111,10 @@ export type ImpureCapabilityStatus = (typeof IMPURE_CAPABILITY_STATUSES)[number]
  *                   external condition.
  *  - blockedAt      Int (OPTIONAL) — epoch-ms the task was parked as blocked.
  *  - nextAction     Lww (OPTIONAL) — human/host-action hint, e.g. refreshAuth.
- *  - deadLetterReason Lww (OPTIONAL) — why the order was moved to the DLQ.
- *  - deadLetteredAt Int (OPTIONAL) — epoch-ms the order entered the DLQ.
+ *  - deadLetterReason Lww (OPTIONAL) — why the obligation was moved to the DLQ.
+ *  - deadLetteredAt Int (OPTIONAL) — epoch-ms the obligation entered the DLQ.
  *
- * The OPTIONALs are `.optional()` so a freshly-ordered task (which folds none of them)
+ * The OPTIONALs are `.optional()` so a freshly-obligated task (which folds none of them)
  * decodes on the generated read type — the same read-decode discipline the rest of the
  * framework uses (identity NOTE 1a / gap 1).
  */
@@ -122,6 +122,8 @@ export const IMPURE_CAPABILITY_ENVELOPE = {
   requestId: t.string().merge(Lww),
   requestedBy: t.string().merge(Lww),
   requestedAt: t.int().merge(Lww),
+  scheduledAt: t.int().merge(Lww),
+  deadlineAt: t.int().merge(Lww),
   status: t.enum(IMPURE_CAPABILITY_STATUSES).merge(Lww),
   resultRef: t.json().merge(Lww).optional(),
   failureReason: t.string().merge(Lww).optional(),
@@ -131,16 +133,16 @@ export const IMPURE_CAPABILITY_ENVELOPE = {
   nextAction: t.string().merge(Lww).optional(),
   deadLetterReason: t.string().merge(Lww).optional(),
   deadLetteredAt: t.int().merge(Lww).optional(),
-  // The FRAMEWORK Order↔Receipt CLOSURE link (OPTIONAL): the id of the Order this
+  // The FRAMEWORK Obligation↔Receipt CLOSURE link (OPTIONAL): the id of the Obligation this
   // RECEIPT closes (== the task's own requestId — the reactor mutates the task instance).
   // GENERIC, written by every impureCapability Receipt (complete OR fail), so the read
-  // projection answers "is Order O closed, by which Receipt, with what result" in O(1)
-  // off the `(closesOrder, order_id)` index — never a ledger scan. Absent while
-  // `requested` (a fresh order has no closing receipt). The kernel supplies its
+  // projection answers "is Obligation O closed, by which Receipt, with what result" in O(1)
+  // off the `(closesObligation, obligation_id)` index — never a ledger scan. Absent while
+  // `requested` (a fresh obligation has no closing receipt). The kernel supplies its
   // framework-fixed Lww driver (`kernel::manifest_view::IMPURE_CAPABILITY_RECEIPT_FIELDS`)
-  // and the gate enforces the lifecycle around it (`nomos_executor::check_order_receipt` —
-  // admit step 5.5: OrphanReceipt / ReceiptOnTerminalOrder, terminal-once as law).
-  closesOrder: t.string().merge(Lww).optional(),
+  // and the gate enforces the lifecycle around it (`nomos_executor::check_obligation_receipt` —
+  // admit step 5.5: OrphanReceipt / ReceiptOnTerminalObligation, terminal-once as law).
+  closesObligation: t.string().merge(Lww).optional(),
 } as const;
 
 /**
@@ -163,9 +165,9 @@ export function impureCapabilityAggregate<
 }
 
 /**
- * The deterministic instance-id rule: a impure capability is keyed by its OWN order id.
- * That id is KERNEL-MINTED (`<OrderType>_<uuidv7>`, via the marker-driven front-door),
- * captured + committed — so the `order` create is idempotent on replay by capture, and the
+ * The deterministic instance-id rule: a impure capability is keyed by its OWN obligation id.
+ * That id is KERNEL-MINTED (`<ObligationType>_<uuidv7>`, via the marker-driven front-door),
+ * captured + committed — so the `obligation` create is idempotent on replay by capture, and the
  * `complete`/`fail` receipt addresses the SAME instance by reading the committed minted id.
  * Trivial today (identity), but centralised here so the keying rule has ONE home (the
  * symmetry with `relations.ts`'s `relationTupleInstanceId`).
@@ -174,11 +176,13 @@ export function impureCapabilityInstanceId(requestId: string): string {
   return requestId;
 }
 
-/** The Zod schema for the framework envelope fields the ORDER payload always carries. */
-const orderEnvelopeSchema = z.object({
+/** The Zod schema for the framework envelope fields the Obligation payload always carries. */
+const obligationEnvelopeSchema = z.object({
   requestId: z.string(),
   requestedBy: z.string(),
   requestedAt: z.number().int(),
+  scheduledAt: z.number().int(),
+  deadlineAt: z.number().int(),
 });
 
 /** The receipt-COMPLETE payload: the request id + the content-addressed result + when. */
@@ -204,7 +208,7 @@ const blockSchema = z.object({
   nextAction: z.string(),
 });
 
-/** The receipt-DLQ payload: terminal dead-letter, requiring a fresh order to recover. */
+/** The receipt-DLQ payload: terminal dead-letter, requiring a fresh obligation to recover. */
 const deadLetterSchema = z.object({
   requestId: z.string(),
   deadLetterReason: z.string(),
@@ -232,13 +236,13 @@ function envelopeInstance(aggregateId: string, requestId: string) {
 }
 
 /**
- * orderOps — the ORDER half. Seeds the envelope provenance + `status:'requested'`,
+ * obligationOps — the Obligation half. Seeds the envelope provenance + timing + `status:'requested'`,
  * PLUS the tenant's request params (the `paramOps` the caller's `.plan` supplies for
  * its own fields). The task is bound to its requestId instance (#105).
  */
-export function orderOps(
+export function obligationOps(
   aggregateId: string,
-  p: z.infer<typeof orderEnvelopeSchema>,
+  p: z.infer<typeof obligationEnvelopeSchema>,
   paramOps: PlannedOp[] = [],
 ): PlannedOp[] {
   const taskInstance = envelopeInstance(aggregateId, p.requestId);
@@ -246,6 +250,8 @@ export function orderOps(
     set(taskInstance, "requestId", p.requestId),
     set(taskInstance, "requestedBy", p.requestedBy),
     set(taskInstance, "requestedAt", p.requestedAt),
+    set(taskInstance, "scheduledAt", p.scheduledAt),
+    set(taskInstance, "deadlineAt", p.deadlineAt),
     set(taskInstance, "status", "requested"),
     ...paramOps,
   ];
@@ -266,10 +272,10 @@ export function completeOps(
     set(taskInstance, "status", "completed"),
     set(taskInstance, "resultRef", p.resultRef),
     set(taskInstance, "completedAt", p.completedAt),
-    // The FRAMEWORK Order↔Receipt CLOSURE link — this Receipt closes the Order whose
+    // The FRAMEWORK Obligation↔Receipt CLOSURE link — this Receipt closes the Obligation whose
     // id == requestId (the task instance the reactor mutates). Indexed by the read
     // projection for the O(1) closure read. Wire-identical to the Rust reactor's op.
-    set(taskInstance, "closesOrder", impureCapabilityInstanceId(p.requestId)),
+    set(taskInstance, "closesObligation", impureCapabilityInstanceId(p.requestId)),
     // The TENANT RESULT FIELDS the Receipt writes into the task aggregate (e.g.
     // `transcription = <text>`). The envelope is auto; these are the tenant's own
     // structured result. Framework writes them verbatim; the tenant owns their meaning.
@@ -293,8 +299,8 @@ export function failOps(
     set(taskInstance, "failureReason", p.failureReason),
     set(taskInstance, "completedAt", p.failedAt),
     // CLOSURE link — a FAILED task is still CLOSED by its receipt (the closure read
-    // reports it CLOSED with no result). Same `closesOrder == requestId` as `completeOps`.
-    set(taskInstance, "closesOrder", impureCapabilityInstanceId(p.requestId)),
+    // reports it CLOSED with no result). Same `closesObligation == requestId` as `completeOps`.
+    set(taskInstance, "closesObligation", impureCapabilityInstanceId(p.requestId)),
   ];
 }
 
@@ -309,11 +315,11 @@ export function blockOps(
     set(taskInstance, "blockedReason", p.blockedReason),
     set(taskInstance, "blockedAt", p.blockedAt),
     set(taskInstance, "nextAction", p.nextAction),
-    set(taskInstance, "closesOrder", impureCapabilityInstanceId(p.requestId)),
+    set(taskInstance, "closesObligation", impureCapabilityInstanceId(p.requestId)),
   ];
 }
 
-/** deadLetterOps — terminal DLQ receipt. Recovery is a fresh explicit Order. */
+/** deadLetterOps — terminal DLQ receipt. Recovery is a fresh explicit Obligation. */
 export function deadLetterOps(
   aggregateId: string,
   p: z.infer<typeof deadLetterSchema>,
@@ -323,7 +329,7 @@ export function deadLetterOps(
     set(taskInstance, "status", "deadLettered"),
     set(taskInstance, "deadLetterReason", p.deadLetterReason),
     set(taskInstance, "deadLetteredAt", p.deadLetteredAt),
-    set(taskInstance, "closesOrder", impureCapabilityInstanceId(p.requestId)),
+    set(taskInstance, "closesObligation", impureCapabilityInstanceId(p.requestId)),
   ];
 }
 
@@ -331,11 +337,11 @@ export function deadLetterOps(
  * The generated directive QUARTET for a impure capability. A domain dev calls
  * {@link impureCapability} ONCE and gets:
  *   • `aggregate`  — the task aggregate handle (envelope ⊕ params),
- *   • `order`      — `.creates` directive (the authored Order),
+ *   • `obligation` — `.creates` directive (the authored Obligation),
  *   • `complete`   — `.mutates` directive (the reactor's success Receipt),
  *   • `fail`       — `.mutates` directive (the reactor's failure Receipt),
- * plus the deterministic `instanceId` rule. The `order` payload is the framework
- * order-envelope MERGED with the tenant's `paramsSchema`; `complete`/`fail` are fixed.
+ * plus the deterministic `instanceId` rule. The `obligation` payload is the framework
+ * obligation-envelope MERGED with the tenant's `paramsSchema`; `complete`/`fail` are fixed.
  */
 export interface ImpureCapability<
   Id extends string,
@@ -343,7 +349,7 @@ export interface ImpureCapability<
   F extends Record<string, Field>,
 > {
   readonly aggregate: AggregateHandle<Id, typeof IMPURE_CAPABILITY_ENVELOPE & F>;
-  readonly order: RequirableDirective<OrderPayload<ParamsShape>>;
+  readonly obligation: RequirableDirective<ObligationPayload<ParamsShape>>;
   readonly complete: RequirableDirective<z.infer<typeof completeSchema>>;
   readonly fail: RequirableDirective<z.infer<typeof failSchema>>;
   readonly block: RequirableDirective<z.infer<typeof blockSchema>>;
@@ -364,17 +370,17 @@ export interface ImpureCapability<
 }
 
 /**
- * The inferred ORDER payload type = the framework envelope schema EXTENDED with the
- * tenant's param shape — the EXACT inference `orderEnvelopeSchema.extend(paramsSchema)`
- * produces (so the declared `ImpureCapability.order` directive type and the value the factory
+ * The inferred Obligation payload type = the framework envelope schema EXTENDED with the
+ * tenant's param shape — the EXACT inference `obligationEnvelopeSchema.extend(paramsSchema)`
+ * produces (so the declared `ImpureCapability.obligation` directive type and the value the factory
  * builds are the same type, with no brittle hand-written intersection).
  */
-export type OrderPayload<ParamsShape extends z.ZodRawShape> = z.infer<
-  ReturnType<typeof orderEnvelopeSchema.extend<ParamsShape>>
+export type ObligationPayload<ParamsShape extends z.ZodRawShape> = z.infer<
+  ReturnType<typeof obligationEnvelopeSchema.extend<ParamsShape>>
 >;
 
 /**
- * impureCapability — the framework FACTORY. Declares an Order→Receipt task in ONE call:
+ * impureCapability — the framework FACTORY. Declares an Obligation→Receipt task in ONE call:
  *
  * ```ts
  * // Build the aggregate handle FIRST so `writeParams` references it without a
@@ -384,7 +390,7 @@ export type OrderPayload<ParamsShape extends z.ZodRawShape> = z.infer<
  *
  * export const exportJob = impureCapability({
  *   aggregateId: "ExportJobAggregate",
- *   orderDirectiveId: "createExportJob",
+ *   obligationDirectiveId: "createExportJob",
  *   completeDirectiveId: "completeExportJob",
  *   failDirectiveId: "failExportJob",
  *   blockDirectiveId: "blockExportJob",
@@ -400,33 +406,33 @@ export type OrderPayload<ParamsShape extends z.ZodRawShape> = z.infer<
  *
  * The tenant declares the wire ids (so they're stable, minify-safe DATA — the same
  * declared-once rule as `aggregate()`/`directive()`), the param FIELDS (for the
- * aggregate shape + codegen) and the param SCHEMA (for the order payload + the
+ * aggregate shape + codegen) and the param SCHEMA (for the obligation payload + the
  * `writeParams` plan fragment). The framework wires the lifecycle: status defaulting,
  * the requestId keying, and the complete/fail receipt directives.
  *
  * `writeParams(taskInstanceId, params)` returns the `PlannedOp[]` for the tenant's OWN
- * fields (the framework already writes the envelope) — the param half of the order
+ * fields (the framework already writes the envelope) — the param half of the obligation
  * plan, kept type-checked against the tenant's param fields via the `set()` helper.
  */
 export function impureCapability<
   const Id extends string,
-  const OrderId extends string,
+  const ObligationId extends string,
   const CompleteId extends string,
   const FailId extends string,
   ParamsShape extends z.ZodRawShape,
   F extends Record<string, Field>,
 >(spec: {
   aggregateId: Id;
-  orderDirectiveId: OrderId;
+  obligationDirectiveId: ObligationId;
   completeDirectiveId: CompleteId;
   failDirectiveId: FailId;
   blockDirectiveId: string;
   deadLetterDirectiveId: string;
   /** The task's request-param FIELDS (merged onto the envelope for the aggregate shape). */
   params: F;
-  /** The task's request-param Zod SHAPE (merged onto the order envelope schema). */
+  /** The task's request-param Zod SHAPE (merged onto the obligation envelope schema). */
   paramsSchema: ParamsShape;
-  /** Plan fragment writing the tenant's param fields for the order (envelope is auto). */
+  /** Plan fragment writing the tenant's param fields for the obligation (envelope is auto). */
   writeParams: (
     taskInstanceId: string,
     params: z.infer<z.ZodObject<ParamsShape>>,
@@ -434,7 +440,7 @@ export function impureCapability<
   /**
    * OPTIONAL plan fragment writing the tenant's STRUCTURED RESULT fields onto the task
    * aggregate when the `complete` Receipt is authored (the lifecycle envelope + the
-   * `closesOrder` link are auto). The receipt's `resultRef` carries the content-addressed
+   * `closesObligation` link is auto). The receipt's `resultRef` carries the content-addressed
    * Evidence ref (the authoritative artifact); a tenant that ALSO wants the result in a
    * typed, queryable field (e.g. a voice-note's `transcription`) supplies it here. The
    * `resultRef` string is passed through so the tenant can derive the field value from the
@@ -451,22 +457,22 @@ export function impureCapability<
 }): ImpureCapability<Id, ParamsShape, F> {
   const taskAggregate = impureCapabilityAggregate(spec.aggregateId, spec.params);
 
-  // The order payload = the framework provenance envelope ⊕ the tenant's params.
-  const orderPayload = orderEnvelopeSchema.extend(spec.paramsSchema);
+  // The obligation payload = the framework provenance/timing envelope ⊕ the tenant's params.
+  const obligationPayload = obligationEnvelopeSchema.extend(spec.paramsSchema);
 
-  const order: RequirableDirective<OrderPayload<ParamsShape>> = directive(
-    spec.orderDirectiveId,
+  const obligation: RequirableDirective<ObligationPayload<ParamsShape>> = directive(
+    spec.obligationDirectiveId,
   )
     .creates(taskAggregate)
-    .payload(orderPayload)
+    .payload(obligationPayload)
     .plan((p) => {
       // The validated payload carries BOTH the envelope (required string/int) and the
-      // tenant params. `orderOps` writes the envelope; the tenant's `writeParams`
+      // tenant params. `obligationOps` writes the envelope; the tenant's `writeParams`
       // writes its own fields. Extract the envelope explicitly (it is required on the
       // schema, so these are present non-undefined values).
-      const envelope = orderEnvelopeSchema.parse(p);
+      const envelope = obligationEnvelopeSchema.parse(p);
       const params = p as z.infer<z.ZodObject<ParamsShape>>;
-      return orderOps(
+      return obligationOps(
         spec.aggregateId,
         envelope,
         spec.writeParams(impureCapabilityInstanceId(envelope.requestId), params),
@@ -502,7 +508,7 @@ export function impureCapability<
 
   return {
     aggregate: taskAggregate,
-    order,
+    obligation,
     complete,
     fail,
     block,
@@ -516,7 +522,7 @@ export function impureCapability<
 
 // ─────────────────────────── THE CAPABILITY PROVIDER ─────────────────────────
 //
-// The Order half (`order`) is an ordinary Intent authored by the peer through the one write
+// The Obligation half (`obligation`) is an ordinary Intent authored by the peer through the one write
 // path. The Receipt half (`complete`/`fail`) is an ordinary Intent authored by a capability
 // PROVIDER — itself a Nomos author (`admission-hosting.md`: hosted/provider-originated
 // intents author *through* a policy unit too"). The provider is the runtime ROLE; this

package/src/framework/sync_lifecycle.ts

@@ -10,7 +10,7 @@
  * Nomos sync lifecycle.
  *
  * Sync is a control-plane impure capability: Nomos records the desired workspace
- * reconciliation as an ordinary Order, a host/provider performs transport using
+ * reconciliation as an ordinary Obligation, a host/provider performs transport using
  * explicit capabilities, and the outcome comes back as an ordinary Receipt. The
  * remote/JWT/network is never ambient domain state; the ledger carries request,
  * status, cursors, heads, and errors.
@@ -85,7 +85,7 @@ function syncResultOps(taskId: string, resultRef: string): PlannedOp[] {
 
 const workspaceSyncTask = impureCapability({
   aggregateId: "WorkspaceSyncOperation",
-  orderDirectiveId: "requestWorkspaceSync",
+  obligationDirectiveId: "requestWorkspaceSync",
   completeDirectiveId: "completeWorkspaceSync",
   failDirectiveId: "failWorkspaceSync",
   blockDirectiveId: "blockWorkspaceSync",
@@ -113,7 +113,7 @@ const workspaceSyncTask = impureCapability({
   completeResult: syncResultOps,
 });
 
-export const requestWorkspaceSync = workspaceSyncTask.order.requires("requestWorkspaceSync");
+export const requestWorkspaceSync = workspaceSyncTask.obligation.requires("requestWorkspaceSync");
 export const completeWorkspaceSync = workspaceSyncTask.complete.requires("completeWorkspaceSync");
 export const failWorkspaceSync = workspaceSyncTask.fail.requires("failWorkspaceSync");
 export const blockWorkspaceSync = workspaceSyncTask.block.requires("blockWorkspaceSync");

package/src/framework/workspaces.ts

@@ -641,6 +641,11 @@ export const AuthProvider = aggregate("AuthProvider", {
   issuer: t.string().merge(Lww),
   /** The provider's public JWKS endpoint (asymmetric verification keys). */
   jwksUrl: t.string().merge(Lww),
+  /** OPTIONAL expected `aud` claim. When the platform sets it, a token's `aud` MUST carry this value
+   *  (defense-in-depth beyond the issuer match — e.g. a Firebase project id, an Auth0 API audience).
+   *  Absent ⇒ issuer match alone. This is LAW-STATE the PLATFORM owns; the host merely enforces it as a
+   *  capability (it never chooses the audience). */
+  audience: t.string().merge(Lww),
   /** Human label for audit ("acme supabase", ...). */
   label: t.string().merge(Lww),
   /** Who set it (attribution). */
@@ -661,6 +666,7 @@ export const setAuthProvider = directive("setAuthProvider")
       // deterministic engine does not provide — a regex keeps the plan pure.
       issuer: z.string().regex(/^https?:\/\/\S+$/, "expected an http(s) URL"),
       jwksUrl: z.string().regex(/^https?:\/\/\S+$/, "expected an http(s) URL"),
+      audience: z.string().min(1).optional(),
       label: z.string().min(1),
       setBy: z.string().min(1),
       setAt: epochMs,
@@ -672,6 +678,7 @@ export const setAuthProvider = directive("setAuthProvider")
       withMarker(set(ap, "scope", "platform"), "ensures"),
       set(ap, "issuer", p.issuer),
       set(ap, "jwksUrl", p.jwksUrl),
+      ...(p.audience ? [set(ap, "audience", p.audience)] : []),
       set(ap, "label", p.label),
       set(ap, "setBy", p.setBy),
       set(ap, "setAt", p.setAt),

package/src/index.ts

@@ -278,7 +278,7 @@ export {
   impureCapabilityAggregate,
   impureCapabilityInstanceId,
   impureCapability,
-  orderOps,
+  obligationOps,
   completeOps,
   failOps,
   blockOps,

package/src/usd.ts

@@ -33,6 +33,7 @@ import {
   type CanonicalManifest,
   type CanonicalProjectionReturn,
 } from "./manifest.js";
+import type { AggregateHandle } from "./aggregate.js";
 import {
   mergeRequiresScope,
   CompositionViolation,
@@ -126,10 +127,46 @@ export interface UsdCombined {
   readonly returns: CanonicalProjectionReturn;
 }
 
+/** One field's read-projection descriptor: the field kind plus a map's value kind. */
+export interface UsdFieldKindDescriptor {
+  readonly kind: string;
+  readonly mapValueKind?: string;
+}
+
+export interface UsdReadProjection {
+  readonly aggregateFieldKinds: Record<string, Record<string, UsdFieldKindDescriptor>>;
+  readonly queries: { id: string; key: { field: string; kind: string }[]; returns: string }[];
+  readonly counts: { id: string; of: string; by: string | null; where?: unknown }[];
+  readonly spatials: { id: string; of: string; on: string }[];
+  readonly deriveds: { id: string; of: string; returns: CanonicalProjectionReturn }[];
+  readonly combineds: { id: string; of: string; refField: string; reads: string; returns: CanonicalProjectionReturn }[];
+  readonly sums?: { id: string; of: string; field: string; by: string | null; where?: unknown }[];
+  readonly mins?: { id: string; of: string; field: string; by: string | null; where?: unknown }[];
+  readonly maxes?: { id: string; of: string; field: string; by: string | null; where?: unknown }[];
+  readonly orderedReads?: {
+    id: string;
+    of: string;
+    orderKey: string;
+    orderDesc?: true;
+    where?: unknown;
+    limit: number;
+  }[];
+}
+
 /** One USD layer: a stage path + its prims (canonically sorted by prim path). */
 export interface UsdLayer {
   readonly path: string;
   readonly prims: UsdPrim[];
+  /**
+   * The canonical admission/merge manifest for this layer, committed inside the package.
+   * Hosts must not stage or mutate this view; holons derive it from active installed law.
+   */
+  readonly nomosIdentityManifest?: CanonicalManifest;
+  /**
+   * The projection schema/read-routing fragment for this layer, committed inside the package.
+   * It carries the projection-only field-kind data that cannot be recovered from merge drivers.
+   */
+  readonly nomosReadProjection?: UsdReadProjection;
   /**
    * The layer's NAMED, INDEXED read declarations (read-side closure step 1), SORTED
    * by id. OMITTED (`undefined`) when the module declares no query, so a query-free
@@ -363,6 +400,123 @@ function encodeModuleToPrims(layerPath: string, mod: DomainModule): UsdPrim[] {
   return sortPrims(prims);
 }
 
+function aggregateFieldKindsForModule(
+  mod: DomainModule,
+): Record<string, Record<string, UsdFieldKindDescriptor>> {
+  const out: Record<string, Record<string, UsdFieldKindDescriptor>> = {};
+  for (const agg of [...(mod.aggregates as AggregateHandle[])].sort((a, b) =>
+    a.id < b.id ? -1 : a.id > b.id ? 1 : 0,
+  )) {
+    const fields: Record<string, UsdFieldKindDescriptor> = {};
+    for (const name of Object.keys(agg.fields).sort()) {
+      const field = agg.fields[name]!;
+      fields[name] = {
+        kind: field.kind,
+        ...(field.mapValueKind !== undefined ? { mapValueKind: field.mapValueKind } : {}),
+      };
+    }
+    out[agg.id] = fields;
+  }
+  return out;
+}
+
+function readKeyFieldKind(
+  byType: Record<string, Record<string, UsdFieldKindDescriptor>>,
+  queryId: string,
+  returns: string,
+  keyField: string,
+): string {
+  const schema = byType[returns];
+  if (schema === undefined) {
+    throw new Error(
+      `usd: query '${queryId}' returns '${returns}', which has no field schema in nomosReadProjection`,
+    );
+  }
+  const lookup = keyField.includes(".") ? keyField.split(".")[0]! : keyField;
+  const descriptor = schema[lookup];
+  if (descriptor === undefined) {
+    throw new Error(
+      `usd: query '${queryId}' is keyed on '${keyField}' (field '${lookup}'), which '${returns}' does not declare`,
+    );
+  }
+  return descriptor.kind;
+}
+
+function readProjectionForModule(mod: DomainModule, manifest: CanonicalManifest): UsdReadProjection {
+  const aggregateFieldKinds = aggregateFieldKindsForModule(mod);
+  return {
+    aggregateFieldKinds,
+    queries: (manifest.queries ?? []).map((q) => ({
+      id: q.id,
+      key: q.key.map((field) => ({
+        field,
+        kind: readKeyFieldKind(aggregateFieldKinds, q.id, q.returns, field),
+      })),
+      returns: q.returns,
+    })),
+    counts: (manifest.counts ?? []).map((c) => ({
+      id: c.id,
+      of: c.of,
+      by: c.by ?? null,
+      ...(c.where !== undefined ? { where: c.where } : {}),
+    })),
+    spatials: (manifest.spatials ?? []).map((s) => ({ id: s.id, of: s.of, on: s.on })),
+    deriveds: (manifest.deriveds ?? []).map((d) => ({ id: d.id, of: d.of, returns: d.returns })),
+    combineds: (manifest.combineds ?? []).map((c) => ({
+      id: c.id,
+      of: c.of,
+      refField: c.refField,
+      reads: c.reads,
+      returns: c.returns,
+    })),
+    ...((manifest.sums ?? []).length > 0
+      ? {
+          sums: manifest.sums!.map((s) => ({
+            id: s.id,
+            of: s.of,
+            field: s.sumField,
+            by: s.by ?? null,
+            ...(s.where !== undefined ? { where: s.where } : {}),
+          })),
+        }
+      : {}),
+    ...((manifest.mins ?? []).length > 0
+      ? {
+          mins: manifest.mins!.map((e) => ({
+            id: e.id,
+            of: e.of,
+            field: e.valueField,
+            by: e.by ?? null,
+            ...(e.where !== undefined ? { where: e.where } : {}),
+          })),
+        }
+      : {}),
+    ...((manifest.maxes ?? []).length > 0
+      ? {
+          maxes: manifest.maxes!.map((e) => ({
+            id: e.id,
+            of: e.of,
+            field: e.valueField,
+            by: e.by ?? null,
+            ...(e.where !== undefined ? { where: e.where } : {}),
+          })),
+        }
+      : {}),
+    ...((manifest.orderedReads ?? []).length > 0
+      ? {
+          orderedReads: manifest.orderedReads!.map((r) => ({
+            id: r.id,
+            of: r.of,
+            orderKey: r.orderKey,
+            ...(r.orderDesc ? { orderDesc: true as const } : {}),
+            ...(r.where !== undefined ? { where: r.where } : {}),
+            limit: r.limit,
+          })),
+        }
+      : {}),
+  };
+}
+
 /**
  * Lower a layer's `relationType` decls into the canonical `nomosRelations` wire object (P1) —
  * keys SORTED for byte-determinism, omit-when-empty (the era rule). Multiple decls for one type
@@ -549,6 +703,8 @@ export function emitUsd(
       return {
         path: l.path,
         prims: encodeModuleToPrims(l.path, l.module),
+        nomosIdentityManifest: manifest,
+        nomosReadProjection: readProjectionForModule(l.module, manifest),
         ...(manifest.queries !== undefined ? { queries: manifest.queries } : {}),
         ...(manifest.deriveds !== undefined ? { deriveds: manifest.deriveds } : {}),
         ...(manifest.combineds !== undefined ? { combineds: manifest.combineds } : {}),