@githolon/dsl 0.14.0 → 0.16.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/relations.ts

@@ -46,6 +46,7 @@ import { Lww, MapOf } from "../drivers.js";
 import { directive } from "../directive.js";
 import { set, setEntry, withMarker, type PlannedOp } from "../ops.js";
 import { query } from "../query.js";
+import { endorsementOf, type AttributionPrincipal, type EndorsedAuthority } from "../principal_evidence.js";
 
 /** Tuple subject lifecycle — the same vocabulary the kernel read drops a non-active leaf by. */
 export const RELATION_STATUSES = ["active", "revoked"] as const;
@@ -126,8 +127,15 @@ function compact(obj: Record<string, unknown>): RelationSubjectLeaf {
 interface WriteTupleInput {
   object: string;
   relation: string;
-  subject: string;
-  grantedBy: string;
+  /**
+   * THE AUTHORITY SINK (the endorse model — security_model.md): who is granted the relation. A plain
+   * subject string (`user:<id>` from the payload) OR `ctx.principal().asAuthoritySubject(reason)` — an
+   * un-endorsed identity (`asAttribution()`) cannot be a subject (it won't typecheck), so identity
+   * never SILENTLY decides a grant.
+   */
+  subject: string | EndorsedAuthority<string>;
+  /** ATTRIBUTION (free): who recorded the grant. A plain string OR `ctx.principal().asAttribution()`. */
+  grantedBy: string | AttributionPrincipal;
   grantedAt: string;
 }
 
@@ -141,19 +149,30 @@ function lowerTuple(
   },
 ): PlannedOp[] {
   const rt = instance(RelationTuple, relationTupleInstanceId(p.object, p.relation));
+  // MATERIALISE PrincipalEvidence subjects/grantedBy → the raw principal (the endorse model). The
+  // subject's endorsement is recorded on the setEntry op so the discovery harvest lifts it into
+  // nomosFlowGate.endorse; grantedBy is free attribution (materialised, not gated).
+  //
+  // The captured authoring principal IS already a wire-form subject (`user:<uid>` / `key:<hash>`, the
+  // host-stamped actor — the SAME form the write gate parses via `Subject::parse`), so an endorsed
+  // authority subject lowers to that leaf verbatim and the gate's `engine.check` matches it.
+  const subjectE = endorsementOf(p.subject);
+  const subjectRaw = subjectE ? subjectE.principal : (p.subject as string);
+  const grantedByRaw = endorsementOf(p.grantedBy)?.principal ?? (p.grantedBy as string);
   const leaf = compact({
     status: p.status,
-    grantedBy: p.grantedBy,
+    grantedBy: grantedByRaw,
     grantedAt: p.grantedAt,
     revokedBy: p.revokedBy,
     revokedAt: p.revokedAt,
   });
+  const subjectEntry = setEntry(rt, "subjects", subjectRaw, JSON.stringify(leaf));
   return [
     // upsert the aggregate head (first relate creates it); without this the referential
     // gate would reject a setEntry on an absent id.
     withMarker(set(rt, "object", p.object), "ensures"),
     set(rt, "relation", p.relation),
-    setEntry(rt, "subjects", p.subject, JSON.stringify(leaf)),
+    subjectE ? { ...subjectEntry, endorsement: { facet: subjectE.facet, reason: subjectE.reason } } : subjectEntry,
   ];
 }
 

package/src/framework/signing_identity.ts

@@ -67,7 +67,7 @@ const sha256Hex = z.string().regex(/^[0-9a-f]{64}$/, "expected lowercase sha256
  *    bootstrap chicken-and-egg. The forge surface a bare `relateSubject` would open is closed by
  *    DOMAIN PLACEMENT: this directive is composed into the CONTROL-PLANE governance law (domain
  *    `workspaces`/`nomos`), which the open session lane structurally refuses
- *    (`cloud/holon-host/src/engine.mjs` — only the birth door + the secret-gated `/author` + admin
+ *    (`cloud/cloudflare-shell/src/engine.mjs` — only the birth door + the secret-gated `/author` + admin
  *    lanes author it), so no tenant can forge a signer for another principal.
  *
  * THE ORDER IS THE CONTRACT (verified, zero gate change): `enrollSigner` (E, unsigned/pre-warrant) →

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/workspace_invariant.ts

@@ -99,6 +99,14 @@ export interface WorkspaceInvariantDecl {
   readonly reads: WorkspaceInvariantReads;
   /** The executable predicate — ships in the engine bundle, NOT the manifest. */
   readonly assert: WorkspaceInvariantAssert;
+  /**
+   * THE DECLASSIFY WAIVER (nomosFlowGate rule 4 — architecture/security_model.md): present iff
+   * the author acknowledged that this invariant's refusal MAY correlate with a secret it reads
+   * (a `requires`/`owned` aggregate). The reason is hashed into the `nomosFlowGate` era key (so
+   * it is replay-verified + the entire audit surface). Absent ⇒ the flow gate refuses to compile
+   * a secret-correlated refusal.
+   */
+  readonly declassify?: string;
   /** Brand so a plain object is never mistaken for a declaration. */
   readonly __isWorkspaceInvariant: true;
 }
@@ -112,22 +120,35 @@ export function workspaceInvariant(id: string): {
   on(directiveId: string): {
     reads(reads: WorkspaceInvariantReads): {
       assert(assert: WorkspaceInvariantAssert): WorkspaceInvariantDecl;
+      /** Acknowledge an intended secret-correlated refusal (nomosFlowGate rule 4). The reason
+       *  rides the `nomosFlowGate` era key; then chain `.assert(...)` as usual. */
+      declassify(reason: string): { assert(assert: WorkspaceInvariantAssert): WorkspaceInvariantDecl };
     };
   };
 } {
+  const finish = (directiveId: string, reads: WorkspaceInvariantReads, declassify: string | undefined) => ({
+    assert(assert: WorkspaceInvariantAssert): WorkspaceInvariantDecl {
+      return {
+        id,
+        on: directiveId,
+        reads,
+        assert,
+        ...(declassify !== undefined ? { declassify } : {}),
+        __isWorkspaceInvariant: true as const,
+      };
+    },
+  });
   return {
     on(directiveId: string) {
       return {
         reads(reads: WorkspaceInvariantReads) {
           return {
-            assert(assert: WorkspaceInvariantAssert): WorkspaceInvariantDecl {
-              return {
-                id,
-                on: directiveId,
-                reads,
-                assert,
-                __isWorkspaceInvariant: true,
-              };
+            assert: finish(directiveId, reads, undefined).assert,
+            declassify(reason: string) {
+              if (typeof reason !== "string" || reason.trim().length === 0) {
+                throw new Error(`workspaceInvariant('${id}').declassify(reason) needs a non-empty human reason — it is the audit record for an intended secret-correlated refusal.`);
+              }
+              return finish(directiveId, reads, reason);
             },
           };
         },

package/src/framework/workspaces.ts

@@ -75,6 +75,13 @@ import { query } from "../query.js";
 import { workspaceInvariant, refAs } from "./workspace_invariant.js";
 import { writeTuple, removeTuple, RelationTuple } from "./relations.js";
 import { relationType, self, user, key } from "../relation_schema.js";
+// THE GENESIS BOOTSTRAP (platform-birth genesis bootstrap, Approach A): governance carries the
+// warrant-flip primitives so the birth door can lawfully bootstrap a virgin platform's founding admin —
+// E `enrollSigner` (the founding signer tuple) → W `seedGenesis` (the GenesisWarrant) → A signed
+// `grantAdmin` (admitted by the kernel genesis clause). Re-exported so the package's shape-discovery picks
+// them up as part of the `workspaces` domain. (architecture/platform_birth_genesis_bootstrap.md)
+export { GenesisWarrant, seedGenesis } from "./genesis.js";
+export { identityRelations, enrollSigner } from "./signing_identity.js";
 
 // ── WORKSPACE SELF-IDENTITY (the law reads its OWN install-context) ──────────────────────────────────
 // The governance bundle runs on root AND every born platform. A workspace knows its ROLE via this

package/src/index.ts

@@ -32,7 +32,21 @@ export {
   type FieldKind,
   type EvidenceRefValue,
   evidenceRefSchema,
+  // FIELD FACETS (the endorse model — security_model.md): authority/standing/attribution gate
+  // set() acceptance of PrincipalEvidence; secret/public are the confidentiality lattice.
+  authorityField,
+  standingField,
+  attributionField,
+  secretField,
+  publicField,
 } from "./fields.js";
+export {
+  type PrincipalEvidence,
+  type AttributionPrincipal,
+  type EndorsedAuthority,
+  type EndorsedStanding,
+  type FieldFacet,
+} from "./principal_evidence.js";
 export {
   Lww,
   LwwCausal,
@@ -278,7 +292,7 @@ export {
   impureCapabilityAggregate,
   impureCapabilityInstanceId,
   impureCapability,
-  orderOps,
+  obligationOps,
   completeOps,
   failOps,
   blockOps,
@@ -410,6 +424,16 @@ export {
   type InvariantVerdict,
 } from "./relation.js";
 export { generateDartDomain, type DomainModule } from "./codegen_dart.js";
+// SHAPE COMPATIBILITY (#72) — the structural contract a client negotiates with a workspace
+// by, instead of the law hash. Pure + deterministic; the editor/CI mirror imports these.
+export {
+  domainInterface,
+  compatible,
+  type DomainInterface,
+  type CompatVerdict,
+  type DirectivePayloadShape,
+  type AggregateReadShape,
+} from "./shape_compat.js";
 // The OPTIONAL Graphviz `.dot` ER-diagram emitter (off-by-default presentation projection,
 // turned on by the `--emit-dot` compiler flag). Pure `DomainModule -> string`, deterministic;
 // NOT part of the domain identity. Barrel-safe (no node:* imports), so the engine bundle can