@githolon/dsl 0.101.5 → 0.102.0

package/src/usd_state.ts

@@ -474,7 +474,7 @@ export function stateScrubStageUsda(opts: {
   if (opts.lawLayerRelPathsWeakToStrong.length === 0) {
     fail(
       `scrub stage for '${opts.domain}' has no law layers — emit them first ` +
-        `(nomos-compile --layered, spike 1) so state has law to compose over`,
+        `(nomos-compile always emits it) so state has law to compose over`,
     );
   }
   const strongestFirst = [opts.stateLayerRelPath, ...[...opts.lawLayerRelPathsWeakToStrong].reverse()];

package/src/value_object.ts

@@ -52,8 +52,10 @@
  * and `.optional()` on any of them (arrays/records of optionals excluded). Tuples, dates,
  * non-string-keyed records etc. are deliberately OUT — grow this surface deliberately.
  */
+
 import { z } from "zod";
 
+import { isRuntimeLaw } from "./authoring_context.js";
 import type { Driver } from "./drivers.js";
 import {
   valueObjectField,
@@ -251,28 +253,36 @@ export function unit<Z extends z.ZodTypeAny>(name: string, inner: Z): Z {
 }
 
 /**
- * THE TYPED-ID BRAND (dart_codegen_parity.md P2) — `idOf(Site)` in a directive payload is
- * wire-identical to `z.string()` but the generated Dart field is the aggregate's TYPED id
- * class (`SiteId`), and the generated TS references the branded alias. Passing another
- * aggregate's id where a SiteId belongs becomes a COMPILE error. Payload-side only — the
+ * THE AGGREGATE-REFERENCE BRAND (dart_codegen_parity.md P2) — `idOf(Site)` in a directive payload is
+ * wire-identical to `z.string()` but both generated languages expose it as `NomosRef<Site>`.
+ * Passing a bare string or `NomosRef<AnotherAggregate>` where the Site reference belongs becomes a
+ * COMPILE error. Payload-side only — the
  * kernel keeps seeing a string; validation and the aggregate field contract are untouched
  * because this is a directive-payload annotation.
  */
 export const NOMOS_IDOF_BRAND: unique symbol = Symbol.for("nomos.idOf");
 
-/** A payload field holding an EXISTING aggregate's id, typed: `siteId: idOf(Site)`. */
-export function idOf(aggregate: { id: string } | string): z.ZodType<string> {
+/** A payload field holding an EXISTING aggregate reference: `siteId: idOf(Site)` -> `NomosRef<Site>`. */
+export function idOf(aggregate: { id: string; __isContract?: true } | string): z.ZodType<string> {
   const aggregateType = typeof aggregate === "string" ? aggregate : aggregate.id;
   if (typeof aggregateType !== "string" || aggregateType === "") {
     throw new Error("idOf: pass the aggregate handle (idOf(Site)) or its type name.");
   }
   const schema = z.string().min(1);
-  Object.defineProperty(schema, NOMOS_IDOF_BRAND, { value: aggregateType, enumerable: false });
+  Object.defineProperty(schema, NOMOS_IDOF_BRAND, {
+    value: {
+      aggregateType,
+      targetKind: typeof aggregate === "object" && aggregate.__isContract === true
+        ? "contract"
+        : "aggregate",
+    },
+    enumerable: false,
+  });
   return schema;
 }
 
 /**
- * THE BRANDED-ID BRAND (dart_codegen_parity.md P2 — the standalone twin of {@link idOf}) —
+ * THE BRANDED-ID BRAND (dart_codegen_parity.md P2 — deliberately NOT an aggregate reference) —
  * `brandedId("SiteId")` is a NOMINAL string: wire-identical to `z.string()` but the generated TS is a branded alias
  * (`type SiteId = string & { readonly __brand }`) and the generated Dart a zero-cost
  * extension type (`extension type const SiteId(String value) {}`), so passing a bare string
@@ -313,6 +323,27 @@ export function idOfMetaOf(zt: z.ZodTypeAny): string | undefined {
   for (let hops = 0; cur !== undefined && hops < 16; hops++) {
     const branded = (cur as unknown as Record<symbol, unknown>)[NOMOS_IDOF_BRAND];
     if (typeof branded === "string") return branded;
+    if (typeof branded === "object" && branded !== null) {
+      const aggregateType = (branded as { aggregateType?: unknown }).aggregateType;
+      if (typeof aggregateType === "string") return aggregateType;
+    }
+    const kind = zodKind(cur);
+    if (kind !== "optional" && kind !== "default" && kind !== "nullable") return undefined;
+    cur = zodDef(cur).innerType;
+  }
+  return undefined;
+}
+
+/** Whether an `idOf(...)` target is a concrete aggregate or a shared aggregate contract. */
+export function idOfTargetKindOf(zt: z.ZodTypeAny): "aggregate" | "contract" | undefined {
+  let cur: z.ZodTypeAny | undefined = zt;
+  for (let hops = 0; cur !== undefined && hops < 16; hops++) {
+    const branded = (cur as unknown as Record<symbol, unknown>)[NOMOS_IDOF_BRAND];
+    if (typeof branded === "object" && branded !== null) {
+      const targetKind = (branded as { targetKind?: unknown }).targetKind;
+      if (targetKind === "aggregate" || targetKind === "contract") return targetKind;
+    }
+    if (typeof branded === "string") return "aggregate";
     const kind = zodKind(cur);
     if (kind !== "optional" && kind !== "default" && kind !== "nullable") return undefined;
     cur = zodDef(cur).innerType;
@@ -366,10 +397,9 @@ function describeZod(
     case "string": {
       const brandedBrand = (schema as unknown as Record<symbol, unknown>)[NOMOS_BRANDED_ID_BRAND];
       const idOfAgg = (schema as unknown as Record<symbol, unknown>)[NOMOS_IDOF_BRAND];
-      // idOf(Agg) REFERENCES the aggregate's canonical typed-id class `<Agg>Id` (emitted ONCE by the
-      // aggregate) — it must NOT re-declare a standalone extension type (that duplicated the id symbol and
-      // stripped its `.fromRow`, co2). Carry `idOf` so the emitter references + imports it and skips the
-      // brand-extension-type emission. A standalone `brandedId("X")` still declares its own extension type.
+      // idOf(Agg) REFERENCES the aggregate's canonical `NomosRef<Agg>`. Carry `idOf` in the stable
+      // descriptor so every emitter can recover the aggregate type while the wire remains a string.
+      // A standalone `brandedId("X")` remains an unrelated nominal string and declares its own wrapper.
       if (typeof idOfAgg === "string") {
         return { type: "string", brand: `${idOfAgg}Id`, idOf: idOfAgg };
       }
@@ -545,13 +575,19 @@ function makeValueObject<T>(
   geometry?: GeometryKind,
   example?: T,
 ): ValueObject<T> {
+  if (name === "User" || name === "Identity") {
+    throw new Error(
+      `valueObject '${name}': '${name}' is a first-class Nomos authority type, not application state. ` +
+        `Sorry mate, that concept is already taken by the framework; choose a business-specific name.`,
+    );
+  }
   if (!VO_NAME_RE.test(name)) {
     throw new Error(
       `valueObject: name '${name}' is not a valid identifier ([A-Za-z][A-Za-z0-9_]*) — it becomes the ` +
         `generated TS interface / Dart class name.`,
     );
   }
-  if (example !== undefined) {
+  if (example !== undefined && !isRuntimeLaw()) {
     const v = zodSchema.safeParse(example);
     if (!v.success) {
       throw new Error(

package/src/wire_encode.ts

@@ -19,8 +19,10 @@
  * one event; a multi-aggregate one yields several. Proto/numeric-tag wire is a
  * LATER coordinated migration — we target the current serde_json shape now.
  */
+import type { z } from "zod";
+
 import { encodeDriver } from "./drivers.js";
-import { __qualifyAggregateType } from "./framework/relations.js";
+import { __qualifyAggregateType, __setDispatchDomain } from "./framework/relations.js";
 import { __resetAuthoring, __drainAuthoring } from "./authoring.js";
 import { __resetReads, __drainReads } from "./read.js";
 import { __resetBirths, __drainBirths } from "./births.js";
@@ -51,6 +53,15 @@ import type {
   WireSchema,
   WireValue,
 } from "./wire.js";
+import {
+  zodArrayElement,
+  zodDef,
+  zodEnumValues,
+  zodKind,
+  zodObjectShape,
+  zodSampleNumber,
+  zodSampleString,
+} from "./zod_introspection.js";
 
 /** Map a directive's referential marker onto the kernel `RefMode` wire string. */
 export function encodeRefMode(marker: ReferentialMarker): WireRefMode {
@@ -103,6 +114,14 @@ function describeShape(value: unknown): string {
  *  `op` is passed purely for a NAMED diagnostic (aggregate + field + expected VO type) when a value
  *  can't be lowered — never `field '?'`. */
 function encodeKernelValue(field: Field | undefined, value: unknown, op?: FieldOp): WireValue {
+  if (value === undefined) {
+    const aggName = op?.aggregateType ?? op?.aggregateId ?? "?";
+    const fieldName = op?.field ?? field?.kind ?? "?";
+    throw new Error(
+      `${aggName}.${fieldName} attempted to write undefined. Omit the operation (for example with ` +
+        `setOptional(...)) or declare an explicit null/clear policy; undefined can never be ledger state.`,
+    );
+  }
   // An `evidence` field encodes as the FIRST-CLASS kernel `Value::Evidence` (NOT a JSON
   // string): the authored {hash, mediaType, byteLength, storageClass} maps to the
   // kernel's snake_case serde shape + the `Git`/`External` unit-variant. Checked BEFORE
@@ -380,12 +399,14 @@ export function executeDirectiveToIntent<P>(
     }
   }
 
-  // Group ops by aggregate id, preserving first-seen order (authored order).
-  // `aggregateId` is the address: for an unbound op it is the TYPE (legacy
-  // one-per-workspace shape); for an instance-bound op (`instance(h, id)`) it is
-  // the concrete INSTANCE id, with `aggregateType` carrying the TYPE (#105).
+  // Group ops by the complete aggregate address `(type, id)`, preserving first-seen order.
+  // `id` alone is never an address: two aggregate types may intentionally share a business key
+  // (Draft(id) + DraftPredecessorSelection(id)). Collapsing those buckets turns a lawful atomic
+  // Create+Ensure fan-out into one contradictory event and is exactly the sort of stringly identity
+  // bug `NomosRef<T>` exists to make impossible.
   const order: string[] = [];
   const byAggregate = new Map<string, WireFieldOp[]>();
+  const idOf = new Map<string, string>();
   // Per-bucket aggregate TYPE — only present for instance-bound ops. When set, we
   // auto-stamp `__type`/`__id` provenance field-ops so `view()` (api.rs
   // `project_view`) can recover the aggregate's TYPE off a per-instance id.
@@ -403,31 +424,33 @@ export function executeDirectiveToIntent<P>(
   const explicitMarker = new Map<string, WireRefMode>();
   const fieldsOf = agg.fields as Record<string, Field>;
   for (const op of ops) {
-    let bucket = byAggregate.get(op.aggregateId);
+    const bucketKey = JSON.stringify([op.aggregateType ?? null, op.aggregateId]);
+    let bucket = byAggregate.get(bucketKey);
     if (bucket === undefined) {
       bucket = [];
-      byAggregate.set(op.aggregateId, bucket);
-      order.push(op.aggregateId);
+      byAggregate.set(bucketKey, bucket);
+      idOf.set(bucketKey, op.aggregateId);
+      order.push(bucketKey);
     }
-    if (op.aggregateType !== undefined) typeOf.set(op.aggregateId, op.aggregateType);
+    if (op.aggregateType !== undefined) typeOf.set(bucketKey, op.aggregateType);
     if (op.marker !== undefined) {
       const encoded = encodeRefMode(op.marker);
-      const existing = explicitMarker.get(op.aggregateId);
+      const existing = explicitMarker.get(bucketKey);
       if (existing !== undefined && existing !== encoded) {
         throw new Error(
           `Directive '${directive.id}' emits conflicting markers for aggregate ` +
-            `'${op.aggregateId}': ${existing} vs ${encoded}.`,
+            `'${op.aggregateType ?? "?"}:${op.aggregateId}': ${existing} vs ${encoded}.`,
         );
       }
-      explicitMarker.set(op.aggregateId, encoded);
+      explicitMarker.set(bucketKey, encoded);
     }
     // Field kinds are known for ops targeting the directive's own aggregate — by
     // TYPE for a bound op (`aggregateType`), else by id for an unbound op.
     const isOwnTarget =
       op.aggregateType !== undefined ? op.aggregateType === agg.id : op.aggregateId === agg.id;
     // A bucket is the own target if ANY of its ops target the directive's own aggregate.
-    if (isOwnTarget) ownTarget.set(op.aggregateId, true);
-    else if (!ownTarget.has(op.aggregateId)) ownTarget.set(op.aggregateId, false);
+    if (isOwnTarget) ownTarget.set(bucketKey, true);
+    else if (!ownTarget.has(bucketKey)) ownTarget.set(bucketKey, false);
     // Resolve the field's schema from the OP'S OWN TARGET aggregate, not the dispatch primary: a fanned-out
     // sibling op carries its target's Field (`op.targetField`, captured at op-construction where the handle
     // knew its schema). For an own-target op `op.targetField` IS `fieldsOf[op.field]` (same Field object), so
@@ -437,13 +460,14 @@ export function executeDirectiveToIntent<P>(
     bucket.push(encodeKernelFieldOp(op, field));
   }
 
-  const events: WireEvent[] = order.map((aggregate) => {
-    const ops = byAggregate.get(aggregate)!;
-    const ty = typeOf.get(aggregate);
+  const events: WireEvent[] = order.map((bucketKey) => {
+    const aggregate = idOf.get(bucketKey)!;
+    const ops = byAggregate.get(bucketKey)!;
+    const ty = typeOf.get(bucketKey);
     // The directive's marker applies to its OWN target; a FAN-OUT bucket is a Mutate of an
     // existing sibling aggregate (so the id-mint gate never sees a spurious Create for it).
     const eventMarker: WireRefMode =
-      explicitMarker.get(aggregate) ?? (ownTarget.get(aggregate) ? marker : "Mutate");
+      explicitMarker.get(bucketKey) ?? (ownTarget.get(bucketKey) ? marker : "Mutate");
     if (ty !== undefined) {
       // Stamp provenance FIRST so the fold carries the TYPE + canonical id the
       // structured `view()` projects (the same `__type`/`__id` reserved fields the
@@ -487,6 +511,53 @@ export interface PrincipalFlow {
   readonly reason: string | null;
 }
 
+/**
+ * Build a schema-valid-enough value for security discovery without importing a
+ * code generator into the wire layer. Business intents validate their payload
+ * again while lowering private effects, so the old property-only Proxy could
+ * never reach their plans: Zod enumerates object keys before reading them.
+ * Unsupported/exotic schemas still fail closed at runtime exactly as before.
+ */
+function principalFlowProbeValue(
+  schema: z.ZodTypeAny,
+  visiting: ReadonlySet<z.ZodTypeAny> = new Set(),
+  hint = "value",
+): unknown {
+  if (visiting.has(schema)) return {};
+  const next = new Set(visiting).add(schema);
+  const def = zodDef(schema);
+  switch (zodKind(schema)) {
+    case "string": return zodSampleString(schema, hint);
+    case "number": return zodSampleNumber(schema);
+    case "boolean": return false;
+    case "enum": return zodEnumValues(schema)[0];
+    case "literal": return def.value ?? def.values?.[0];
+    case "array": return [principalFlowProbeValue(zodArrayElement(schema), next, "item")];
+    case "object": {
+      const value: Record<string, unknown> = {};
+      for (const [name, field] of Object.entries(zodObjectShape(schema))) {
+        const kind = zodKind(field);
+        if (kind === "optional" || kind === "default") continue;
+        value[name] = principalFlowProbeValue(field, next, name);
+      }
+      return value;
+    }
+    case "record": return {};
+    case "union": {
+      const first = def.options?.[0];
+      return first === undefined ? undefined : principalFlowProbeValue(first, next, hint);
+    }
+    case "nullable": return null;
+    case "optional": return undefined;
+    case "default": return def.innerType === undefined ? undefined : principalFlowProbeValue(def.innerType, next, hint);
+    case "lazy": return def.getter === undefined ? {} : principalFlowProbeValue(def.getter(), next, hint);
+    case "pipe": return def.in === undefined ? {} : principalFlowProbeValue(def.in, next, hint);
+    case "unknown":
+    case "any": return {};
+    default: return {};
+  }
+}
+
 /** Extract the principal flows carried by a plan's field ops (those with an `endorsement`). The ONE
  *  op→flow mapping shared by the discovery harvest (compile) and the runtime footprint (Slice B). */
 function flowsFromOps(ops: readonly FieldOp[]): PrincipalFlow[] {
@@ -509,23 +580,49 @@ function flowsFromOps(ops: readonly FieldOp[]): PrincipalFlow[] {
  * the omission is SAFE because the runtime/replay witness (Slice B) refuses any observed flow absent
  * from the manifest. The reasons are static law, so they are intent-independent. SORTED for determinism.
  */
-export function harvestPrincipalFlows(directive: Directive<unknown>): PrincipalFlow[] {
+export function harvestPrincipalFlows(directive: Directive<unknown>, domain?: string): PrincipalFlow[] {
   const ctx: Ports = deterministicPorts({ principal: "principal:probe" });
-  // A probe payload: any field access yields a benign string. Plans that need a typed shape (an
-  // array .map, etc.) may throw — caught below; that directive's flows are then witnessed at runtime.
-  const probe = new Proxy({}, { get: () => "probe" });
+  let candidate: unknown;
+  try {
+    candidate = principalFlowProbeValue(directive.payloadSchema as z.ZodTypeAny);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`principal-flow discovery for '${directive.id}' could not construct a lawful probe: ${detail}`, { cause: error });
+  }
+  const parsed = (directive.payloadSchema as z.ZodTypeAny).safeParse(candidate);
+  // Keep the historical property proxy as a fallback for unusual schemas whose plan does not validate
+  // its payload. A BusinessIntent does validate and therefore needs the enumerable parsed object above.
+  const probe = parsed.success ? parsed.data : new Proxy({}, { get: () => "probe-value" });
   // A plan that MINTS (`create(Agg)` — the common `.creates` shape) calls `globalThis.nomos.mint`; the
   // harvest runs at compile, where the engine's real shim is absent. Install a deterministic stub so the
   // probe plan runs to completion and its flows ARE harvested (an un-harvested authority flow would be
   // refused at runtime by the Slice B witness — fail-closed, but a false jam). The minted VALUE is
   // irrelevant — a flow's sink is the field path, not the id. Restore any pre-existing shim after.
-  const g = globalThis as unknown as { nomos?: { mint?: (t: string) => string; read?: unknown } };
+  const g = globalThis as unknown as {
+    nomos?: {
+      mint?: (t: string) => string;
+      sha256?: (text: string) => string;
+      read?: unknown;
+    };
+  };
   const hadNomos = "nomos" in g;
-  const prior: { mint?: (t: string) => string; read?: unknown } | undefined = g.nomos;
-  if (!hadNomos || typeof prior?.mint !== "function") {
-    g.nomos = { ...(prior ?? {}), mint: (typeTag: string) => `${typeTag}_0192f00d-0000-7000-8000-000000000000` };
+  const prior = g.nomos;
+  if (
+    !hadNomos ||
+    typeof prior?.mint !== "function" ||
+    typeof prior?.sha256 !== "function"
+  ) {
+    g.nomos = {
+      ...(prior ?? {}),
+      mint: prior?.mint ?? ((typeTag: string) => `${typeTag}_0192f00d-0000-7000-8000-000000000000`),
+      // Discovery needs only to drive the pure plan far enough to observe its
+      // declared flows. The address is irrelevant here; the runtime provides
+      // the real deterministic hash and separately verifies the plan bytes.
+      sha256: prior?.sha256 ?? (() => "0".repeat(64)),
+    };
   }
   let ops: FieldOp[];
+  if (domain !== undefined) __setDispatchDomain(domain);
   __resetAuthoring(ctx, String(ctx.clock().physical));
   __resetReads();
   try {
@@ -535,6 +632,7 @@ export function harvestPrincipalFlows(directive: Directive<unknown>): PrincipalF
     try { __drainAuthoring(); __drainReads(); } catch { /* sink already drained */ }
     return [];
   } finally {
+    if (domain !== undefined) __setDispatchDomain(undefined);
     if (hadNomos && prior !== undefined) g.nomos = prior; else delete g.nomos;
   }
   __drainReads();

package/src/workspace_sharing.ts

@@ -0,0 +1,269 @@
+// Durable, framework-owned delivery of a business application's access record.
+//
+// The domain records what should be shared and the business receipts that close
+// that order. Generated stateful clients perform and retry the cross-workspace
+// delivery. Tenant application code never sees a bridge, signer, home index, or
+// delivery protocol.
+
+import { aggregate, instance, type AggregateHandle } from "./aggregate.js";
+import { directive, nomosImplementationDetail, type Directive } from "./directive.js";
+import type { BusinessIntent } from "./intent.js";
+import { query, type QueryDecl } from "./query.js";
+import { z } from "zod";
+import { set, withMarker } from "./ops.js";
+import { t } from "./fields.js";
+import { Lww } from "./drivers.js";
+import { endorsementOf } from "./principal_evidence.js";
+import { RelationTuple, writeTuple } from "./framework/relations.js";
+import {
+  refAs,
+  workspaceInvariant,
+  type WorkspaceInvariantDecl,
+} from "./framework/workspace_invariant.js";
+import { recipientMetaOf } from "./recipient.js";
+import { zodKind, zodObjectShape } from "./zod_introspection.js";
+
+export type WorkspaceSharingPresence = "present" | "absent";
+
+export interface WorkspaceSharingWhen {
+  readonly field: string;
+  readonly is: WorkspaceSharingPresence;
+}
+
+export interface WorkspaceSharingReceipt {
+  readonly when?: WorkspaceSharingWhen;
+  /** Receipt payload field -> durable order field, when the business names differ. */
+  readonly payload?: Readonly<Record<string, string>>;
+  readonly records: Directive<any>;
+}
+
+export interface WorkspaceSharingPolicy {
+  readonly orders: AggregateHandle;
+  readonly initiatedBy: readonly BusinessIntent<any>[];
+  readonly pending: QueryDecl;
+  readonly pendingValue: string;
+  readonly person: string;
+  readonly role: string;
+  readonly scope: string;
+  readonly delivered: readonly WorkspaceSharingReceipt[];
+  readonly refused: readonly WorkspaceSharingReceipt[];
+  /** Generated law behind `Invitation<User>`; never exported to tenant code. */
+  readonly invitationLaw: WorkspaceSharingInvitationLaw;
+}
+
+export interface WorkspaceSharingInvitationLaw {
+  readonly claim: AggregateHandle;
+  readonly redeem: Directive<any>;
+  readonly gate: WorkspaceInvariantDecl;
+  readonly pendingByRecipient: QueryDecl;
+}
+
+/** One workspace-wide consumption record makes a bearer invitation single-use across every policy. */
+const NomosInvitationClaim = {
+  ...aggregate("NomosInternalInvitationClaim7c1f5e", {
+    publicKey: t.string().merge(Lww),
+    redeemedBy: t.string().merge(Lww),
+    redeemedAt: t.string().merge(Lww),
+  }, { global: true }).public(),
+  businessBirthInternal: true as const,
+} as AggregateHandle;
+
+export interface WorkspaceSharingOptions {
+  readonly orders: AggregateHandle;
+  /** Business actions after which the generated application owns delivery. */
+  readonly initiatedBy: readonly BusinessIntent<any>[];
+  /** An indexed, single-key query whose value selects pending delivery orders. */
+  readonly pending: QueryDecl;
+  readonly pendingValue?: string;
+  readonly person: string;
+  readonly role: string;
+  readonly scope: string;
+  readonly delivered: readonly WorkspaceSharingReceipt[];
+  readonly refused: readonly WorkspaceSharingReceipt[];
+}
+
+const requireOrderField = (orders: AggregateHandle, field: string, purpose: string): void => {
+  if (orders.fields[field] === undefined) {
+    throw new Error(
+      `workspaceSharing(${orders.id}): ${purpose} field '${field}' is not declared on the delivery order`,
+    );
+  }
+};
+
+/**
+ * Declare one durable business sharing policy. The order aggregate is ordinary
+ * domain state; delivery and retry are generated framework behaviour.
+ *
+ * This is the canonical access-delivery lane. Model the pending order and its
+ * delivered/refused business receipts here; never call a bridge from application
+ * code or mirror pending delivery in UI state.
+ *
+ * @example
+ * language("estate", intents, {
+ *   workspaceSharing: [workspaceSharing({
+ *     orders: EstateAccessShareOrder,
+ *     initiatedBy: [grantEstateAccess, acceptEstateInvitation],
+ *     pending: estateAccessShareOrdersByStatus,
+ *     person: "subject",
+ *     role: "relation",
+ *     scope: "object",
+ *     delivered: [{ records: recordEstateAccessDelivered }],
+ *     refused: [{ records: recordEstateAccessRefused }],
+ *   })],
+ * })
+ */
+export function workspaceSharing(options: WorkspaceSharingOptions): WorkspaceSharingPolicy {
+  const { orders, pending } = options;
+  if (pending.returns !== orders.id) {
+    throw new Error(
+      `workspaceSharing(${orders.id}): pending query '${pending.id}' returns '${pending.returns}'`,
+    );
+  }
+  if (pending.key.length !== 1) {
+    throw new Error(
+      `workspaceSharing(${orders.id}): pending query '${pending.id}' must have exactly one indexed key`,
+    );
+  }
+  if (options.initiatedBy.length === 0) {
+    throw new Error(
+      `workspaceSharing(${orders.id}): initiatedBy must name at least one business action`,
+    );
+  }
+  for (const action of options.initiatedBy) {
+    const schema = action.payloadSchema as z.ZodTypeAny;
+    const hasTypedRecipient = zodKind(schema) === "object" &&
+      Object.values(zodObjectShape(schema)).some((field) => recipientMetaOf(field) !== undefined);
+    if (!hasTypedRecipient) {
+      throw new Error(
+        `workspaceSharing(${orders.id}): business action '${action.id}' must accept a recipient() field; ` +
+          `plain uid/email/principal strings are not invitation recipients`,
+      );
+    }
+  }
+  requireOrderField(orders, options.person, "person");
+  requireOrderField(orders, options.role, "role");
+  requireOrderField(orders, options.scope, "scope");
+  if (options.delivered.length === 0 || options.refused.length === 0) {
+    throw new Error(
+      `workspaceSharing(${orders.id}): both delivered and refused business receipts are required`,
+    );
+  }
+  for (const receipt of [...options.delivered, ...options.refused]) {
+    if (receipt.when !== undefined) {
+      requireOrderField(orders, receipt.when.field, "receipt condition");
+    }
+    for (const [target, source] of Object.entries(receipt.payload ?? {})) {
+      requireOrderField(orders, source, `receipt payload '${target}'`);
+    }
+  }
+  const pendingValue = options.pendingValue ?? "pending";
+  const stem = options.orders.id.replace(/[^A-Za-z0-9]/g, "");
+  const redeemId = `nomosInternalRedeem${stem}Invitation7c1f5e`;
+  const pendingByRecipient = {
+    ...query(`nomosInternal${stem}InvitationsByRecipient7c1f5e`)
+      .key(options.person)
+      .returns(options.orders),
+    businessBirthInternal: true as const,
+  };
+  const b64 = z.string().regex(/^[A-Za-z0-9+/]+={0,2}$/, "expected base64");
+  const redeem = nomosImplementationDetail(
+    directive(redeemId)
+      .mutates(options.orders)
+      .payload(z.object({
+        orderId: z.string().min(1),
+        object: z.string().min(1),
+        relation: z.string().min(1),
+        invitationPublicKey: b64,
+        invitationSignature: b64,
+        invitationId: z.string().regex(/^nomos-invitation-[0-9a-f]{64}$/),
+        redeemedAt: z.string().min(1),
+      }))
+      .plan((facts, ctx) => {
+        const principal = endorsementOf(ctx.principal().asAttribution())?.principal ?? "";
+        const claim = instance(NomosInvitationClaim, facts.invitationId);
+        return [
+          ...writeTuple({
+            object: facts.object,
+            relation: facts.relation,
+            subject: ctx.principal().asAuthoritySubject(
+              "redeem a possession-proven, single-use business invitation",
+            ),
+            grantedBy: ctx.principal().asAttribution(),
+            grantedAt: facts.redeemedAt,
+          }),
+          set(instance(options.orders, facts.orderId), options.person, principal),
+          withMarker(set(claim, "publicKey", facts.invitationPublicKey), "ensures"),
+          set(claim, "redeemedBy", principal),
+          set(claim, "redeemedAt", facts.redeemedAt),
+        ];
+      })
+      .alsoEnsures(RelationTuple)
+      .alsoEnsures(NomosInvitationClaim),
+  );
+  const gate = workspaceInvariant(`NomosInvitationGate:${options.orders.id}`)
+    .on(redeemId)
+    .reads(({ intent }) => [
+      refAs("order", options.orders.id, `pre:${String(intent.orderId ?? "")}`),
+      refAs("claim", NomosInvitationClaim.id, `pre:${String(intent.invitationId ?? "")}`),
+    ])
+    .assert((snapshots, ctx) => {
+      const intent = ctx?.intent ?? {};
+      const order = snapshots.order ?? {};
+      const claim = snapshots.claim ?? {};
+      const publicKey = String(intent.invitationPublicKey ?? "");
+      const principal = String(ctx?.principal ?? "");
+      const invitationAddress = `nomos-invitation:v1:${publicKey}`;
+      if (ctx?.principalVerified !== true || !principal.startsWith("user:")) {
+        return { reject: "nomos.invitation.verified_user_required" };
+      }
+      if (claim.publicKey !== undefined) {
+        return { reject: "nomos.invitation.already_redeemed" };
+      }
+      const invitationId = `nomos-invitation-${(globalThis as unknown as { nomos: { sha256(value: string): string } }).nomos.sha256(publicKey)}`;
+      if (intent.invitationId !== invitationId) {
+        return { reject: "nomos.invitation.invalid_proof" };
+      }
+      if (
+        order[options.person] !== invitationAddress ||
+        order[options.role] !== intent.relation ||
+        order[options.scope] !== intent.object ||
+        order[pending.key[0]!] !== pendingValue
+      ) {
+        return { reject: "nomos.invitation.not_pending" };
+      }
+      const verifier = (globalThis as unknown as {
+        nomos?: {
+          attestationVerify?: (
+            publicKey: string,
+            signature: string,
+            asserterWorkspace: string,
+            object: string,
+            relation: string,
+            subject: string,
+            attestedAt: string,
+          ) => boolean;
+        };
+      }).nomos?.attestationVerify;
+      const valid = verifier?.(
+        publicKey,
+        String(intent.invitationSignature ?? ""),
+        "nomos-invitation-v1",
+        String(intent.orderId ?? ""),
+        String(intent.relation ?? ""),
+        principal,
+        String(intent.redeemedAt ?? ""),
+      ) === true;
+      return valid
+        ? { accept: true }
+        : { reject: "nomos.invitation.invalid_proof" };
+    });
+  const invitationLaw = Object.freeze({ claim: NomosInvitationClaim, redeem, gate, pendingByRecipient });
+
+  return Object.freeze({
+    ...options,
+    pendingValue,
+    delivered: Object.freeze([...options.delivered]),
+    refused: Object.freeze([...options.refused]),
+    invitationLaw,
+  });
+}