@wildo-ai/saas-models 1.1.5 → 1.1.6

package/dist/esm/resources/utils/resources-serialization.utils.d.ts

@@ -6,11 +6,28 @@
  */
 import { ResourceConfiguration_OperationPath } from '../resources-config.shared.schemas';
 import { ExecutionContext_ExecutionType, ExecutionContext_InitiatorIds, ExecutionContext_RoleInfo, ExecutionContext_RelationshipContext } from '../../runtime/execution-context.shared.schemas';
+import type { AuditAgentActor } from '../../compliance/audit-trails/audit-actor.shared.schemas';
+/**
+ * The ATTRIBUTION evidence an execution context carries beside its authority — who the trail says
+ * acted, never what the execution may do. Serialized with the context so a queued job's audit rows
+ * name the same principal, agent and delegating client as the request that enqueued it.
+ *
+ * Evidence only: the reconstructing side passes these to the context's evidence parameters, never
+ * into `initiatorIds`, and no authorization decision reads them.
+ */
+export interface SerializedExecutionContextAttribution {
+    /** The on-behalf-of principal of an internally-authorized execution (`ExecutionContext.auditActorUserId`). */
+    auditActorUserId?: string;
+    /** The agent that caused the work, when an agent's tool enqueued it (`ExecutionContext.agentActor`). */
+    agentActor?: AuditAgentActor;
+    /** The external OAuth client a person delegated to (`ExecutionContext.delegatingClientId`). */
+    delegatingClientId?: string;
+}
 /**
  * Serialized execution context data structure.
  * This is the plain object representation used in queue messages.
  */
-export interface SerializedExecutionContextData {
+export interface SerializedExecutionContextData extends SerializedExecutionContextAttribution {
     executionType: ExecutionContext_ExecutionType;
     initiatorIds: ExecutionContext_InitiatorIds | null;
     initiatorRoles: ExecutionContext_RoleInfo[];
@@ -128,7 +145,7 @@ export declare class ResourceSerializationUtils {
         initiatorRoles: ExecutionContext_RoleInfo[];
         getContextResourceIds: () => ReadonlyMap<string, string | string[]>;
         relationshipContexts: ExecutionContext_RelationshipContext[];
-    }): string;
+    } & SerializedExecutionContextAttribution): string;
     /**
      * Deserialize to raw data.
      * Note: ExecutionContext reconstruction is backend-only and requires

package/dist/esm/resources/utils/resources-serialization.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resources-serialization.utils.d.ts","sourceRoot":"","sources":["../../../../../src/resources/utils/resources-serialization.utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,mCAAmC,EAAE,MAAM,oCAAoC,CAAC;AACzF,OAAO,EACL,8BAA8B,EAC9B,6BAA6B,EAC7B,yBAAyB,EACzB,oCAAoC,EACrC,MAAM,gDAAgD,CAAC;AAExD;;;GAGG;AACH,MAAM,WAAW,8BAA8B;IAC7C,aAAa,EAAE,8BAA8B,CAAC;IAC9C,YAAY,EAAE,6BAA6B,GAAG,IAAI,CAAC;IACnD,cAAc,EAAE,yBAAyB,EAAE,CAAC;IAC5C,+BAA+B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IACnE,oBAAoB,CAAC,EAAE,oCAAoC,EAAE,CAAC;CAC/D;AAED;;;GAGG;AACH,qBAAa,0BAA0B;IAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2DG;IACH,MAAM,CAAC,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO;IAIpE;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM;IAIlE;;;;;;OAMG;IACH,MAAM,CAAC,sBAAsB,CAAC,aAAa,EAAE,mCAAmC,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM;IAWnG;;;;;OAKG;IACH,MAAM,CAAC,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,mCAAmC,CAAC,GAAG,EAAE,GAAG,CAAC;IAI5F;;;;;;;;;OASG;IACH,MAAM,CAAC,yBAAyB,CAAC,GAAG,EAAE;QACpC,aAAa,EAAE,8BAA8B,CAAC;QAC9C,YAAY,EAAE,6BAA6B,GAAG,IAAI,CAAC;QACnD,cAAc,EAAE,yBAAyB,EAAE,CAAC;QAC5C,qBAAqB,EAAE,MAAM,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;QACpE,oBAAoB,EAAE,oCAAoC,EAAE,CAAC;KAC9D,GAAG,MAAM;IAgBV;;;;;;;OAOG;IACH,MAAM,CAAC,+BAA+B,CAAC,IAAI,EAAE,MAAM,GAAG,8BAA8B;IAIpF;;;;;;OAMG;IACH,MAAM,CAAC,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,6BAA6B,GAAG,IAAI;CAS3F"}
+{"version":3,"file":"resources-serialization.utils.d.ts","sourceRoot":"","sources":["../../../../../src/resources/utils/resources-serialization.utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,mCAAmC,EAAE,MAAM,oCAAoC,CAAC;AACzF,OAAO,EACL,8BAA8B,EAC9B,6BAA6B,EAC7B,yBAAyB,EACzB,oCAAoC,EACrC,MAAM,gDAAgD,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0DAA0D,CAAC;AAEhG;;;;;;;GAOG;AACH,MAAM,WAAW,qCAAqC;IACpD,8GAA8G;IAC9G,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,wGAAwG;IACxG,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,+FAA+F;IAC/F,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,8BAA+B,SAAQ,qCAAqC;IAC3F,aAAa,EAAE,8BAA8B,CAAC;IAC9C,YAAY,EAAE,6BAA6B,GAAG,IAAI,CAAC;IACnD,cAAc,EAAE,yBAAyB,EAAE,CAAC;IAC5C,+BAA+B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IACnE,oBAAoB,CAAC,EAAE,oCAAoC,EAAE,CAAC;CAC/D;AAED;;;GAGG;AACH,qBAAa,0BAA0B;IAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2DG;IACH,MAAM,CAAC,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO;IAIpE;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM;IAIlE;;;;;;OAMG;IACH,MAAM,CAAC,sBAAsB,CAAC,aAAa,EAAE,mCAAmC,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM;IAWnG;;;;;OAKG;IACH,MAAM,CAAC,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,mCAAmC,CAAC,GAAG,EAAE,GAAG,CAAC;IAI5F;;;;;;;;;OASG;IACH,MAAM,CAAC,yBAAyB,CAAC,GAAG,EAAE;QACpC,aAAa,EAAE,8BAA8B,CAAC;QAC9C,YAAY,EAAE,6BAA6B,GAAG,IAAI,CAAC;QACnD,cAAc,EAAE,yBAAyB,EAAE,CAAC;QAC5C,qBAAqB,EAAE,MAAM,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;QACpE,oBAAoB,EAAE,oCAAoC,EAAE,CAAC;KAC9D,GAAG,qCAAqC,GAAG,MAAM;IAoBlD;;;;;;;OAOG;IACH,MAAM,CAAC,+BAA+B,CAAC,IAAI,EAAE,MAAM,GAAG,8BAA8B;IAIpF;;;;;;OAMG;IACH,MAAM,CAAC,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,6BAA6B,GAAG,IAAI;CAS3F"}

package/dist/esm/resources/utils/resources-serialization.utils.js

@@ -136,6 +136,10 @@ export class ResourceSerializationUtils {
             initiatorRoles: ctx.initiatorRoles,
             contextResourcesFieldIdentifier: contextResourcesObj,
             relationshipContexts: ctx.relationshipContexts,
+            // Attribution evidence — absent keys stay absent so a context with none serializes exactly as before.
+            ...(ctx.auditActorUserId !== undefined ? { auditActorUserId: ctx.auditActorUserId } : {}),
+            ...(ctx.agentActor !== undefined ? { agentActor: ctx.agentActor } : {}),
+            ...(ctx.delegatingClientId !== undefined ? { delegatingClientId: ctx.delegatingClientId } : {}),
         });
     }
     /**

package/dist/esm/resources/utils/resources-serialization.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"resources-serialization.utils.js","sourceRoot":"","sources":["../../../../../src/resources/utils/resources-serialization.utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAsBH;;;GAGG;AACH,MAAM,OAAO,0BAA0B;IAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2DG;IACH,MAAM,CAAC,sBAAsB,CAAC,IAAY,EAAE,KAAc;QACxD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IAC9D,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,mBAAmB,CAAC,KAAc,EAAE,KAAc;QACvD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,0BAA0B,CAAC,sBAAsB,EAAE,KAAK,CAAC,CAAC;IACzF,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,sBAAsB,CAAC,aAA4D;QACxF,OAAO,IAAI,CAAC,SAAS,CAAC;YACpB,kBAAkB,EAAE,aAAa,CAAC,kBAAkB;YACpD,mBAAmB,EAAE,aAAa,CAAC,mBAAmB;YACtD,WAAW,EAAE,aAAa,CAAC,WAAW;YACtC,UAAU,EAAE,aAAa,CAAC,UAAU;YACpC,kBAAkB,EAAE,aAAa,CAAC,kBAAkB;YACpD,eAAe,EAAE,aAAa,CAAC,eAAe;SAC/C,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,wBAAwB,CAAC,IAAY;QAC1C,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,yBAAyB,CAAC,GAMhC;QACC,qDAAqD;QACrD,MAAM,mBAAmB,GAAsC,EAAE,CAAC;QAClE,GAAG,CAAC,qBAAqB,EAAE,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;YACjD,mBAAmB,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACnC,CAAC,CAAC,CAAC;QAEH,OAAO,IAAI,CAAC,SAAS,CAAC;YACpB,aAAa,EAAE,GAAG,CAAC,aAAa;YAChC,YAAY,EAAE,GAAG,CAAC,YAAY;YAC9B,cAAc,EAAE,GAAG,CAAC,cAAc;YAClC,+BAA+B,EAAE,mBAAmB;YACpD,oBAAoB,EAAE,GAAG,CAAC,oBAAoB;SAC/C,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,+BAA+B,CAAC,IAAY;QACjD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,mBAAmB,CAAC,IAAwB;QACjD,IAAI,CAAC,IAAI;YAAE,OAAO,IAAI,CAAC;QACvB,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC9B,OAAO,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC;QACnC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;CACF","sourcesContent":["/**\n * Resource Serialization Utilities\n * \n * Utilities for serializing/deserializing operation paths and execution contexts\n * for queue/RPC transport. Uses plain JSON serialization.\n */\n\nimport { ResourceConfiguration_OperationPath } from '../resources-config.shared.schemas';\nimport { \n  ExecutionContext_ExecutionType,\n  ExecutionContext_InitiatorIds,\n  ExecutionContext_RoleInfo,\n  ExecutionContext_RelationshipContext,\n} from '../../runtime/execution-context.shared.schemas';\n\n/**\n * Serialized execution context data structure.\n * This is the plain object representation used in queue messages.\n */\nexport interface SerializedExecutionContextData {\n  executionType: ExecutionContext_ExecutionType;\n  initiatorIds: ExecutionContext_InitiatorIds | null;\n  initiatorRoles: ExecutionContext_RoleInfo[];\n  contextResourcesFieldIdentifier: Record<string, string | string[]>;\n  relationshipContexts?: ExecutionContext_RelationshipContext[];\n}\n\n/**\n * Serialization utilities for queue/RPC transport.\n * Uses JSON.stringify/parse - no Zod schemas needed.\n */\nexport class ResourceSerializationUtils {\n\n  /**\n   * JSON replacer that makes `bigint` values serializable.\n   *\n   * RELATIONSHIP TO THE PRIMARY MECHANISM: since `installBigIntJsonEncoding`\n   * (`@wildo-ai/zod-decorators`) installs `BigInt.prototype.toJSON` at bootstrap,\n   * a bare `JSON.stringify` already encodes bigint as a decimal string everywhere.\n   * This replacer (and `stringifyWithBigInt` below) are now DEFENSE-IN-DEPTH:\n   * explicit, greppable bigint-safety at named transport boundaries (queue,\n   * webhook) that keeps them safe even if that bootstrap has not run, and produces\n   * the identical decimal-string wire form. See the full network-boundary\n   * mechanism map in `zod-decorators/src/install-bigint-json-encoding.ts`.\n   *\n   * `JSON.stringify` throws `TypeError: Do not know how to serialize a BigInt`\n   * for any `bigint` value — it has no default JSON representation. This is a\n   * real problem for the resource pipeline because `z_money` (`MoneyValue`)\n   * stores its `amount` as a `bigint` (see `@wildo-ai/zod-decorators` →\n   * `z_money`), deliberately, to avoid the >2^53 precision loss that `number`\n   * would introduce for monetary amounts. Any resource payload carrying a money\n   * field (prices, invoices, promotions, subscriptions, …) therefore cannot be\n   * fed to a bare `JSON.stringify` at a transport / logging boundary.\n   *\n   * This replacer encodes `bigint` as a **decimal string**, NOT a `number`:\n   * a string round-trips losslessly (`BigInt(\"1999\")`), whereas `Number(1999n)`\n   * reintroduces exactly the precision risk `bigint` exists to prevent. The\n   * provider-boundary `Number()` narrowing (e.g. Stripe's numeric amount API)\n   * stays a deliberate, provider-specific conversion and is intentionally NOT\n   * the framework default here.\n   *\n   * NOTE ON QUEUE ROUND-TRIP: worker-side re-hydration of a queued payload\n   * (`JSON.parse` → re-validate against the operation's `internalDto`) coerces a\n   * money `amount` string back to `bigint` because the DTO network boundary now\n   * performs BOTH date and money-bigint coercion (`applyNetworkBoundaryCoercion`\n   * rewrites `z.bigint()` leaves to accept the decimal-string form). So a queued\n   * `z_money` operation round-trips losslessly through this replacer + that input\n   * coercion. This replacer independently keeps the SERIALIZE boundary from\n   * crashing (strictly better than an un-catchable enqueue throw). No queued\n   * money operation exists today anyway (billing money ops are INTERNAL_CALL /\n   * INLINE), so the queue path is crash-safety hardening, not an exercised path.\n   *\n   * WHY NO EQUIVALENT FOR `Date` (the natural follow-up question): `Date` does\n   * NOT need a replacer, because the serialize/deserialize asymmetry runs the\n   * opposite way to `bigint`.\n   * - SERIALIZE: `JSON.stringify` throws on `bigint` (no `toJSON` on its\n   *   prototype) — hence this replacer. `Date` has `Date.prototype.toJSON`, so\n   *   `JSON.stringify` silently emits an ISO string (`\"2026-07-10T…Z\"`). No\n   *   throw, nothing to guard.\n   * - DESERIALIZE: both types land as strings after `JSON.parse`, and both are\n   *   coerced back to their runtime type by the SAME DTO network boundary\n   *   (`applyNetworkBoundaryCoercion` rewrites `z.date()` → `z.coerce.date()`\n   *   AND `z.bigint()` → a string-accepting bigint). A queued payload is\n   *   re-validated against the operation's `internalDto`, so an ISO-string date\n   *   becomes a `Date` and a decimal-string money amount becomes a `bigint`.\n   * The load-bearing invariant for BOTH types is that the payload is re-hydrated\n   * THROUGH that coercing DTO — a raw `JSON.parse` with no re-validation would\n   * hand back a string for a date field just as it would for a money bigint.\n   *\n   * @param _key   JSON key (unused — bigint can appear at any depth)\n   * @param value  Value being serialized\n   * @returns The value unchanged, or its decimal-string form when it is a bigint\n   */\n  static bigIntSafeJsonReplacer(_key: string, value: unknown): unknown {\n    return typeof value === 'bigint' ? value.toString() : value;\n  }\n\n  /**\n   * `JSON.stringify` variant that is safe for payloads containing `bigint`\n   * (notably `z_money` / `MoneyValue` amounts).\n   *\n   * Use this at every pipeline serialization boundary that may receive a\n   * resource `data` / payload object — queue job payloads, external payload\n   * storage, debug logging of resource data — instead of a bare\n   * `JSON.stringify`, which throws on the first `bigint` it encounters.\n   *\n   * @param value  Value to serialize\n   * @param space  Optional pretty-print indentation (as in `JSON.stringify`)\n   * @returns JSON string with bigint values encoded as decimal strings\n   */\n  static stringifyWithBigInt(value: unknown, space?: number): string {\n    return JSON.stringify(value, ResourceSerializationUtils.bigIntSafeJsonReplacer, space);\n  }\n\n  /**\n   * Serialize operation path for transport.\n   * Use operationPathKey for routing, full path for execution.\n   * \n   * @param operationPath The operation path to serialize\n   * @returns JSON string representation\n   */\n  static serializeOperationPath(operationPath: ResourceConfiguration_OperationPath<any, any>): string {\n    return JSON.stringify({\n      resourceIdentifier: operationPath.resourceIdentifier,\n      operationIdentifier: operationPath.operationIdentifier,\n      variantType: operationPath.variantType,\n      variantKey: operationPath.variantKey,\n      isOperationDefault: operationPath.isOperationDefault,\n      isBulkOperation: operationPath.isBulkOperation,\n    });\n  }\n  \n  /**\n   * Deserialize operation path from JSON string.\n   * \n   * @param json JSON string representation\n   * @returns Operation path object\n   */\n  static deserializeOperationPath(json: string): ResourceConfiguration_OperationPath<any, any> {\n    return JSON.parse(json);\n  }\n  \n  /**\n   * Serialize execution context for transport.\n   * Extracts serializable data from ExecutionContext instance.\n   * \n   * Note: This method accepts an object with the ExecutionContext interface.\n   * The actual ExecutionContext class is in saas-backend-lib.\n   * \n   * @param ctx ExecutionContext-like object with required properties\n   * @returns JSON string representation\n   */\n  static serializeExecutionContext(ctx: {\n    executionType: ExecutionContext_ExecutionType;\n    initiatorIds: ExecutionContext_InitiatorIds | null;\n    initiatorRoles: ExecutionContext_RoleInfo[];\n    getContextResourceIds: () => ReadonlyMap<string, string | string[]>;\n    relationshipContexts: ExecutionContext_RelationshipContext[];\n  }): string {\n    // Convert Map to plain object for JSON serialization\n    const contextResourcesObj: Record<string, string | string[]> = {};\n    ctx.getContextResourceIds().forEach((value, key) => {\n      contextResourcesObj[key] = value;\n    });\n    \n    return JSON.stringify({\n      executionType: ctx.executionType,\n      initiatorIds: ctx.initiatorIds,\n      initiatorRoles: ctx.initiatorRoles,\n      contextResourcesFieldIdentifier: contextResourcesObj,\n      relationshipContexts: ctx.relationshipContexts,\n    });\n  }\n  \n  /**\n   * Deserialize to raw data.\n   * Note: ExecutionContext reconstruction is backend-only and requires\n   * ExecutionContextCreatorBackendService.reconstructFromSerializedData()\n   * \n   * @param json JSON string representation\n   * @returns Plain object with execution context data\n   */\n  static deserializeExecutionContextData(json: string): SerializedExecutionContextData {\n    return JSON.parse(json);\n  }\n  \n  /**\n   * Parse serialized execution context to extract initiator IDs for querying.\n   * Useful for extracting org/user IDs without full reconstruction.\n   * \n   * @param json Serialized execution context JSON\n   * @returns Initiator IDs object or null\n   */\n  static extractInitiatorIds(json: string | undefined): ExecutionContext_InitiatorIds | null {\n    if (!json) return null;\n    try {\n      const data = JSON.parse(json);\n      return data.initiatorIds ?? null;\n    } catch {\n      return null;\n    }\n  }\n}\n"]}
+{"version":3,"file":"resources-serialization.utils.js","sourceRoot":"","sources":["../../../../../src/resources/utils/resources-serialization.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Resource Serialization Utilities\n * \n * Utilities for serializing/deserializing operation paths and execution contexts\n * for queue/RPC transport. Uses plain JSON serialization.\n */\n\nimport { ResourceConfiguration_OperationPath } from '../resources-config.shared.schemas';\nimport { \n  ExecutionContext_ExecutionType,\n  ExecutionContext_InitiatorIds,\n  ExecutionContext_RoleInfo,\n  ExecutionContext_RelationshipContext,\n} from '../../runtime/execution-context.shared.schemas';\nimport type { AuditAgentActor } from '../../compliance/audit-trails/audit-actor.shared.schemas';\n\n/**\n * The ATTRIBUTION evidence an execution context carries beside its authority — who the trail says\n * acted, never what the execution may do. Serialized with the context so a queued job's audit rows\n * name the same principal, agent and delegating client as the request that enqueued it.\n *\n * Evidence only: the reconstructing side passes these to the context's evidence parameters, never\n * into `initiatorIds`, and no authorization decision reads them.\n */\nexport interface SerializedExecutionContextAttribution {\n  /** The on-behalf-of principal of an internally-authorized execution (`ExecutionContext.auditActorUserId`). */\n  auditActorUserId?: string;\n  /** The agent that caused the work, when an agent's tool enqueued it (`ExecutionContext.agentActor`). */\n  agentActor?: AuditAgentActor;\n  /** The external OAuth client a person delegated to (`ExecutionContext.delegatingClientId`). */\n  delegatingClientId?: string;\n}\n\n/**\n * Serialized execution context data structure.\n * This is the plain object representation used in queue messages.\n */\nexport interface SerializedExecutionContextData extends SerializedExecutionContextAttribution {\n  executionType: ExecutionContext_ExecutionType;\n  initiatorIds: ExecutionContext_InitiatorIds | null;\n  initiatorRoles: ExecutionContext_RoleInfo[];\n  contextResourcesFieldIdentifier: Record<string, string | string[]>;\n  relationshipContexts?: ExecutionContext_RelationshipContext[];\n}\n\n/**\n * Serialization utilities for queue/RPC transport.\n * Uses JSON.stringify/parse - no Zod schemas needed.\n */\nexport class ResourceSerializationUtils {\n\n  /**\n   * JSON replacer that makes `bigint` values serializable.\n   *\n   * RELATIONSHIP TO THE PRIMARY MECHANISM: since `installBigIntJsonEncoding`\n   * (`@wildo-ai/zod-decorators`) installs `BigInt.prototype.toJSON` at bootstrap,\n   * a bare `JSON.stringify` already encodes bigint as a decimal string everywhere.\n   * This replacer (and `stringifyWithBigInt` below) are now DEFENSE-IN-DEPTH:\n   * explicit, greppable bigint-safety at named transport boundaries (queue,\n   * webhook) that keeps them safe even if that bootstrap has not run, and produces\n   * the identical decimal-string wire form. See the full network-boundary\n   * mechanism map in `zod-decorators/src/install-bigint-json-encoding.ts`.\n   *\n   * `JSON.stringify` throws `TypeError: Do not know how to serialize a BigInt`\n   * for any `bigint` value — it has no default JSON representation. This is a\n   * real problem for the resource pipeline because `z_money` (`MoneyValue`)\n   * stores its `amount` as a `bigint` (see `@wildo-ai/zod-decorators` →\n   * `z_money`), deliberately, to avoid the >2^53 precision loss that `number`\n   * would introduce for monetary amounts. Any resource payload carrying a money\n   * field (prices, invoices, promotions, subscriptions, …) therefore cannot be\n   * fed to a bare `JSON.stringify` at a transport / logging boundary.\n   *\n   * This replacer encodes `bigint` as a **decimal string**, NOT a `number`:\n   * a string round-trips losslessly (`BigInt(\"1999\")`), whereas `Number(1999n)`\n   * reintroduces exactly the precision risk `bigint` exists to prevent. The\n   * provider-boundary `Number()` narrowing (e.g. Stripe's numeric amount API)\n   * stays a deliberate, provider-specific conversion and is intentionally NOT\n   * the framework default here.\n   *\n   * NOTE ON QUEUE ROUND-TRIP: worker-side re-hydration of a queued payload\n   * (`JSON.parse` → re-validate against the operation's `internalDto`) coerces a\n   * money `amount` string back to `bigint` because the DTO network boundary now\n   * performs BOTH date and money-bigint coercion (`applyNetworkBoundaryCoercion`\n   * rewrites `z.bigint()` leaves to accept the decimal-string form). So a queued\n   * `z_money` operation round-trips losslessly through this replacer + that input\n   * coercion. This replacer independently keeps the SERIALIZE boundary from\n   * crashing (strictly better than an un-catchable enqueue throw). No queued\n   * money operation exists today anyway (billing money ops are INTERNAL_CALL /\n   * INLINE), so the queue path is crash-safety hardening, not an exercised path.\n   *\n   * WHY NO EQUIVALENT FOR `Date` (the natural follow-up question): `Date` does\n   * NOT need a replacer, because the serialize/deserialize asymmetry runs the\n   * opposite way to `bigint`.\n   * - SERIALIZE: `JSON.stringify` throws on `bigint` (no `toJSON` on its\n   *   prototype) — hence this replacer. `Date` has `Date.prototype.toJSON`, so\n   *   `JSON.stringify` silently emits an ISO string (`\"2026-07-10T…Z\"`). No\n   *   throw, nothing to guard.\n   * - DESERIALIZE: both types land as strings after `JSON.parse`, and both are\n   *   coerced back to their runtime type by the SAME DTO network boundary\n   *   (`applyNetworkBoundaryCoercion` rewrites `z.date()` → `z.coerce.date()`\n   *   AND `z.bigint()` → a string-accepting bigint). A queued payload is\n   *   re-validated against the operation's `internalDto`, so an ISO-string date\n   *   becomes a `Date` and a decimal-string money amount becomes a `bigint`.\n   * The load-bearing invariant for BOTH types is that the payload is re-hydrated\n   * THROUGH that coercing DTO — a raw `JSON.parse` with no re-validation would\n   * hand back a string for a date field just as it would for a money bigint.\n   *\n   * @param _key   JSON key (unused — bigint can appear at any depth)\n   * @param value  Value being serialized\n   * @returns The value unchanged, or its decimal-string form when it is a bigint\n   */\n  static bigIntSafeJsonReplacer(_key: string, value: unknown): unknown {\n    return typeof value === 'bigint' ? value.toString() : value;\n  }\n\n  /**\n   * `JSON.stringify` variant that is safe for payloads containing `bigint`\n   * (notably `z_money` / `MoneyValue` amounts).\n   *\n   * Use this at every pipeline serialization boundary that may receive a\n   * resource `data` / payload object — queue job payloads, external payload\n   * storage, debug logging of resource data — instead of a bare\n   * `JSON.stringify`, which throws on the first `bigint` it encounters.\n   *\n   * @param value  Value to serialize\n   * @param space  Optional pretty-print indentation (as in `JSON.stringify`)\n   * @returns JSON string with bigint values encoded as decimal strings\n   */\n  static stringifyWithBigInt(value: unknown, space?: number): string {\n    return JSON.stringify(value, ResourceSerializationUtils.bigIntSafeJsonReplacer, space);\n  }\n\n  /**\n   * Serialize operation path for transport.\n   * Use operationPathKey for routing, full path for execution.\n   * \n   * @param operationPath The operation path to serialize\n   * @returns JSON string representation\n   */\n  static serializeOperationPath(operationPath: ResourceConfiguration_OperationPath<any, any>): string {\n    return JSON.stringify({\n      resourceIdentifier: operationPath.resourceIdentifier,\n      operationIdentifier: operationPath.operationIdentifier,\n      variantType: operationPath.variantType,\n      variantKey: operationPath.variantKey,\n      isOperationDefault: operationPath.isOperationDefault,\n      isBulkOperation: operationPath.isBulkOperation,\n    });\n  }\n  \n  /**\n   * Deserialize operation path from JSON string.\n   * \n   * @param json JSON string representation\n   * @returns Operation path object\n   */\n  static deserializeOperationPath(json: string): ResourceConfiguration_OperationPath<any, any> {\n    return JSON.parse(json);\n  }\n  \n  /**\n   * Serialize execution context for transport.\n   * Extracts serializable data from ExecutionContext instance.\n   * \n   * Note: This method accepts an object with the ExecutionContext interface.\n   * The actual ExecutionContext class is in saas-backend-lib.\n   * \n   * @param ctx ExecutionContext-like object with required properties\n   * @returns JSON string representation\n   */\n  static serializeExecutionContext(ctx: {\n    executionType: ExecutionContext_ExecutionType;\n    initiatorIds: ExecutionContext_InitiatorIds | null;\n    initiatorRoles: ExecutionContext_RoleInfo[];\n    getContextResourceIds: () => ReadonlyMap<string, string | string[]>;\n    relationshipContexts: ExecutionContext_RelationshipContext[];\n  } & SerializedExecutionContextAttribution): string {\n    // Convert Map to plain object for JSON serialization\n    const contextResourcesObj: Record<string, string | string[]> = {};\n    ctx.getContextResourceIds().forEach((value, key) => {\n      contextResourcesObj[key] = value;\n    });\n    \n    return JSON.stringify({\n      executionType: ctx.executionType,\n      initiatorIds: ctx.initiatorIds,\n      initiatorRoles: ctx.initiatorRoles,\n      contextResourcesFieldIdentifier: contextResourcesObj,\n      relationshipContexts: ctx.relationshipContexts,\n      // Attribution evidence — absent keys stay absent so a context with none serializes exactly as before.\n      ...(ctx.auditActorUserId !== undefined ? { auditActorUserId: ctx.auditActorUserId } : {}),\n      ...(ctx.agentActor !== undefined ? { agentActor: ctx.agentActor } : {}),\n      ...(ctx.delegatingClientId !== undefined ? { delegatingClientId: ctx.delegatingClientId } : {}),\n    });\n  }\n  \n  /**\n   * Deserialize to raw data.\n   * Note: ExecutionContext reconstruction is backend-only and requires\n   * ExecutionContextCreatorBackendService.reconstructFromSerializedData()\n   * \n   * @param json JSON string representation\n   * @returns Plain object with execution context data\n   */\n  static deserializeExecutionContextData(json: string): SerializedExecutionContextData {\n    return JSON.parse(json);\n  }\n  \n  /**\n   * Parse serialized execution context to extract initiator IDs for querying.\n   * Useful for extracting org/user IDs without full reconstruction.\n   * \n   * @param json Serialized execution context JSON\n   * @returns Initiator IDs object or null\n   */\n  static extractInitiatorIds(json: string | undefined): ExecutionContext_InitiatorIds | null {\n    if (!json) return null;\n    try {\n      const data = JSON.parse(json);\n      return data.initiatorIds ?? null;\n    } catch {\n      return null;\n    }\n  }\n}\n"]}

package/dist/esm/resources/utils/shared-persistence-collection.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shared-persistence-collection.utils.d.ts","sourceRoot":"","sources":["../../../../../src/resources/utils/shared-persistence-collection.utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AACjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,2DAA2D,CAAC;AAEjG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,eAAO,MAAM,8CAA8C,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAe3F,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,sCAAsC,CAAC,YAAY,EAAE,YAAY,GAAG,MAAM,CAEzF;AAED,iGAAiG;AACjG,MAAM,WAAW,2CAA2C;IAC1D,QAAQ,CAAC,kBAAkB,EAAE,YAAY,CAAC;IAC1C,yFAAyF;IACzF,QAAQ,CAAC,kBAAkB,CAAC,EAAE,sBAAsB,GAAG,SAAS,CAAC;CAClE;AAED,gFAAgF;AAChF,MAAM,WAAW,6CAA6C;IAC5D,sEAAsE;IACtE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,yFAAyF;IACzF,QAAQ,CAAC,QAAQ,EAAE,SAAS;QAAE,YAAY,EAAE,YAAY,CAAC;QAAC,OAAO,EAAE,sBAAsB,CAAA;KAAE,EAAE,CAAC;IAC9F,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,kDAAkD,CAChE,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,2CAA2C,CAAC,EACnF,yBAAyB,EAAE,sBAAsB,GAChD,6CAA6C,EAAE,CAsDjD;AAED,mGAAmG;AACnG,MAAM,WAAW,6CAA6C;IAC5D,QAAQ,CAAC,kBAAkB,EAAE,YAAY,CAAC;IAC1C,QAAQ,CAAC,eAAe,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,oBAAoB,CAAA;KAAE,GAAG,SAAS,CAAC;CACxE;AAyBD,iFAAiF;AACjF,MAAM,WAAW,+CAA+C;IAC9D,8DAA8D;IAC9D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,sFAAsF;IACtF,QAAQ,CAAC,QAAQ,EAAE,SAAS;QAAE,YAAY,EAAE,YAAY,CAAC;QAAC,IAAI,EAAE,oBAAoB,GAAG,SAAS,CAAA;KAAE,EAAE,CAAC;IACrG,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAgB,oDAAoD,CAClE,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,6CAA6C,CAAC,GACpF,+CAA+C,EAAE,CA0DnD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,oBAAY,iCAAiC;IAC3C,IAAI,SAAS;IACb,KAAK,UAAU;IACf,MAAM,WAAW;IACjB,QAAQ,aAAa;CACtB"}
+{"version":3,"file":"shared-persistence-collection.utils.d.ts","sourceRoot":"","sources":["../../../../../src/resources/utils/shared-persistence-collection.utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AACjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,2DAA2D,CAAC;AAEjG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,eAAO,MAAM,8CAA8C,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAe3F,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,sCAAsC,CAAC,YAAY,EAAE,YAAY,GAAG,MAAM,CAEzF;AAED,iGAAiG;AACjG,MAAM,WAAW,2CAA2C;IAC1D,QAAQ,CAAC,kBAAkB,EAAE,YAAY,CAAC;IAC1C,yFAAyF;IACzF,QAAQ,CAAC,kBAAkB,CAAC,EAAE,sBAAsB,GAAG,SAAS,CAAC;CAClE;AAED,gFAAgF;AAChF,MAAM,WAAW,6CAA6C;IAC5D,sEAAsE;IACtE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,yFAAyF;IACzF,QAAQ,CAAC,QAAQ,EAAE,SAAS;QAAE,YAAY,EAAE,YAAY,CAAC;QAAC,OAAO,EAAE,sBAAsB,CAAA;KAAE,EAAE,CAAC;IAC9F,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,kDAAkD,CAChE,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,2CAA2C,CAAC,EACnF,yBAAyB,EAAE,sBAAsB,GAChD,6CAA6C,EAAE,CAsDjD;AAED,mGAAmG;AACnG,MAAM,WAAW,6CAA6C;IAC5D,QAAQ,CAAC,kBAAkB,EAAE,YAAY,CAAC;IAC1C,QAAQ,CAAC,eAAe,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,oBAAoB,CAAA;KAAE,GAAG,SAAS,CAAC;CACxE;AA8BD,iFAAiF;AACjF,MAAM,WAAW,+CAA+C;IAC9D,8DAA8D;IAC9D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,sFAAsF;IACtF,QAAQ,CAAC,QAAQ,EAAE,SAAS;QAAE,YAAY,EAAE,YAAY,CAAC;QAAC,IAAI,EAAE,oBAAoB,GAAG,SAAS,CAAA;KAAE,EAAE,CAAC;IACrG,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAgB,oDAAoD,CAClE,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,6CAA6C,CAAC,GACpF,+CAA+C,EAAE,CA0DnD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,oBAAY,iCAAiC;IAC3C,IAAI,SAAS;IACb,KAAK,UAAU;IACf,MAAM,WAAW;IACjB,QAAQ,aAAa;CACtB"}

package/dist/esm/resources/utils/shared-persistence-collection.utils.js

@@ -171,13 +171,13 @@ export function findSharedPersistenceCollectionAdapterIncoherences(resourceConfi
 /**
  * Canonical comparison key for a resource's retention POSTURE.
  *
- * Compares the WHOLE resolved policy, not just `mode`. `ResourceRetentionPolicy` carries a single
- * axis today, so `mode` alone would be exhaustive — but this guard exists precisely because config
- * checks that look sufficient go quietly wrong later, and a second axis (a disposal clock, a
- * jurisdiction) added to the policy would otherwise escape the comparison with no compile-time
- * signal. Two configs over one collection must agree on ALL of it.
+ * Compares the WHOLE resolved policy, not just `mode`. It carries two members since #1635 — `mode` and
+ * the nested `statutoryRetention` ground — and this is the case the whole-policy comparison was written
+ * for: comparing `mode` alone would let two configs over one collection agree on the treatment while
+ * one says a statute keeps the rows and the other does not. Two configs over one collection must agree
+ * on ALL of it.
  *
- * Key order is normalised so authoring order cannot masquerade as a disagreement. `undefined` gets
+ * Key order is normalised at EVERY depth so authoring order cannot masquerade as a disagreement. `undefined` gets
  * its own key rather than being skipped: "rows of this resource are hard-deleted" is a positive
  * claim, and the in-vs-out asymmetry is what produces both failure modes documented below.
  */
@@ -185,9 +185,15 @@ function buildRetentionPostureKey(retentionPolicy) {
     if (retentionPolicy === undefined || retentionPolicy === null) {
         return 'NOT_GOVERNED';
     }
-    const entries = Object.entries(retentionPolicy)
-        .filter(([, value]) => value !== undefined)
-        .sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey));
+    const canonical = (value) => {
+        if (value === null || typeof value !== 'object' || Array.isArray(value))
+            return value;
+        return Object.entries(value)
+            .filter(([, member]) => member !== undefined)
+            .sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey))
+            .map(([key, member]) => [key, canonical(member)]);
+    };
+    const entries = canonical(retentionPolicy);
     return entries.length === 0 ? 'NOT_GOVERNED' : JSON.stringify(entries);
 }
 /**

package/dist/esm/resources/utils/shared-persistence-collection.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"shared-persistence-collection.utils.js","sourceRoot":"","sources":["../../../../../src/resources/utils/shared-persistence-collection.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import { CoreResourceType } from '../resources.shared.core.definitions';\nimport type { ResourceType } from '../resources.shared.schemas';\nimport type { PersistenceAdapterType } from '../resources-config.shared.schemas';\nimport { ErasureRetentionMode } from '../../compliance/privacy/impersonalization.shared.schemas';\n\n/**\n * Resource types that deliberately project onto ANOTHER resource type's\n * persistence collection — THE authority for \"which configs address the same\n * physical rows?\".\n *\n * ## What this expresses\n *\n * A `USER_SELF*` resource is not a different record set; it is a different DOOR\n * onto the SAME record set, with its own operations, roles and scoping. The\n * `USERS` door is the admin surface (list every user, delete a user); the\n * `USER_SELF` door is the self surface (read/update MY row). They intentionally\n * share `UserSchema` and they intentionally share storage — the persistence\n * layer builds a SEPARATE model per resource config over ONE collection.\n *\n * Anything not listed here stores under its own resource type.\n *\n * ## Why it is a single named authority\n *\n * This mapping had already been copied twice inside the backend (the\n * zod→mongoose model builder, which is what actually creates and reads the\n * collection, and the aggregation collection resolver — whose earlier\n * divergence made every aggregation query a non-existent collection and return\n * zero rows). It now has a third consumer of a completely different kind:\n * {@link findSharedPersistenceCollectionRetentionIncoherences}, a boot-time\n * coherence guard. A per-resource config factory structurally cannot see this\n * relationship — it validates ONE config at a time — so the fact has to live\n * where every layer can read it, and it has to live exactly once.\n *\n * ## The alias belongs to the RESOURCE, not to the storage adapter\n *\n * Every persistence path resolves through this map, and each adapter has\n * exactly ONE composition point that does so: MongoDB's model builder and its\n * aggregation resolver, and — on the SQL side — the single\n * `resolveTableNameForResource` helper that the hybrid planner, the PostgreSQL\n * repository and the boot-time table verifier all call.\n *\n * This was NOT always true, and the way it failed is the reason to keep it\n * true: PostgreSQL used to derive its table name straight from\n * `resourceIdentifier`, so `USER_SELF` planned, wrote and verified a `userself`\n * table while `USERS` used `users`. An adapter choice must never silently\n * change WHICH RECORDS a resource addresses — that is not a storage detail, it\n * is the \"two doors, one record set\" contract itself. On the SQL side the\n * resolved name is additionally normalised into a SQL identifier; casing is an\n * adapter concern, the alias is not.\n *\n * The one thing a shared resolver still cannot see is an alias group whose\n * members are pointed at DIFFERENT adapters — each config is individually\n * valid, and only the pair is wrong. That is what\n * {@link findSharedPersistenceCollectionAdapterIncoherences} fails closed on.\n */\nexport const RESOURCE_SHARED_PERSISTENCE_COLLECTION_ALIASES: Readonly<Record<string, string>> = {\n  [CoreResourceType.USER_SELF]: CoreResourceType.USERS,\n  [CoreResourceType.USER_SELF_PROFILES]: CoreResourceType.USER_PROFILES,\n  [CoreResourceType.USER_SELF_PREFERENCES]: CoreResourceType.USER_PREFERENCES,\n  /*\n   * The application-scoped audit door addresses the organization-scoped resource's rows (#317).\n   *\n   * Unlike the `USER_SELF` group above — where the alias exists so a principal can address its OWN\n   * row through a narrower door — this pair exists because the two doors see DIFFERENT SUBSETS of\n   * one set: the organization door is tenant-filtered and structurally cannot return the rows that\n   * carry no organization (logins, session evictions, application-wide policy changes), which is\n   * 74% of them on a measured dogfood application. Splitting the storage would split the audit\n   * trail itself, so the alias is load-bearing rather than a convenience.\n   */\n  [CoreResourceType.APPLICATION_AUDIT_LOGS]: CoreResourceType.AUDIT_LOGS,\n};\n\n/**\n * The persistence collection a resource type's rows live in — its alias target\n * when it declares one, otherwise the resource type itself.\n *\n * @param resourceType - the resource type whose storage location is wanted.\n * @returns the collection name, as a plain string.\n */\nexport function resolveSharedPersistenceCollectionName(resourceType: ResourceType): string {\n  return RESOURCE_SHARED_PERSISTENCE_COLLECTION_ALIASES[resourceType as string] ?? (resourceType as string);\n}\n\n/** The minimal config shape {@link findSharedPersistenceCollectionAdapterIncoherences} reads. */\nexport interface SharedPersistenceCollectionAdapterCandidate {\n  readonly resourceIdentifier: ResourceType;\n  /** The config's OWN declaration; `undefined` means \"inherit the application default\". */\n  readonly persistenceAdapter?: PersistenceAdapterType | undefined;\n}\n\n/** One collection whose resource configs are pointed at different databases. */\nexport interface SharedPersistenceCollectionAdapterIncoherence {\n  /** The shared collection the disagreeing configs claim to address. */\n  readonly collectionName: string;\n  /** Every resource config addressing that collection, with the adapter it RESOLVED to. */\n  readonly adapters: readonly { resourceType: ResourceType; adapter: PersistenceAdapterType }[];\n  /** Operator-facing explanation naming the consequence and the fix. */\n  readonly message: string;\n}\n\n/**\n * Registry-ASSEMBLY guardrail: every resource config that resolves to the SAME\n * persistence collection must resolve to the SAME persistence adapter.\n *\n * ## Why the shared resolver cannot cover this on its own\n *\n * {@link resolveSharedPersistenceCollectionName} makes the alias\n * adapter-independent: whichever database a resource lands in, it addresses the\n * aliased NAME. That is necessary and not sufficient. A name is only an address\n * WITHIN one database, so pointing `USERS` at PostgreSQL while `USER_SELF`\n * inherits MongoDB yields two stores that both believe they own the same rows.\n * Nothing downstream can detect it: each config is individually valid, each\n * repository is correctly built, and every per-resource check passes.\n *\n * ## The failure it prevents\n *\n * The doors silently stop sharing records. The admin door lists users the self\n * door cannot read; a self-service update writes to a row the admin door will\n * never see; and — because retention is enforced against ROWS — an erasure\n * performed through one door leaves the other door's copy completely\n * untouched, which is the same compliance-grade lie that\n * {@link findSharedPersistenceCollectionRetentionIncoherences} exists to\n * prevent, arrived at from a different direction.\n *\n * The table name is not the only thing that follows from the adapter. Id FORMAT\n * does too — the PostgreSQL repository validates ids as UUIDs while Mongo\n * expects ObjectIds, each resolved from its OWN resource's adapter — so a split\n * group would also reject through one door the very ids the other door mints.\n * Anything keyed on \"this resource's adapter\" inherits this invariant.\n *\n * ## Why this is permanent, not a capability gate\n *\n * Unlike adapter gaps that close when the missing support is implemented, this\n * one has no future in which it becomes valid: two databases cannot hold one\n * set of rows. It is deliberately NOT a ban on aliased resources using\n * PostgreSQL — an alias group that agrees on PostgreSQL resolves to one shared\n * table, and whether that table was actually provisioned is a separate,\n * already-enforced question (the boot-time table verifier).\n *\n * Resources inherit the application default when they declare nothing, so the\n * caller supplies the resolved default rather than this function guessing it.\n *\n * Pure and side-effect free: it reports, the caller throws.\n *\n * @param resourceConfigurations - every assembled resource config, keyed by resource type.\n * @param defaultPersistenceAdapter - the adapter a config with no declaration inherits.\n * @returns one entry per incoherent collection; empty when the registry is coherent.\n */\nexport function findSharedPersistenceCollectionAdapterIncoherences(\n  resourceConfigurations: Record<string, SharedPersistenceCollectionAdapterCandidate>,\n  defaultPersistenceAdapter: PersistenceAdapterType,\n): SharedPersistenceCollectionAdapterIncoherence[] {\n  const adaptersByCollection = new Map<\n    string,\n    { resourceType: ResourceType; adapter: PersistenceAdapterType }[]\n  >();\n\n  for (const [resourceTypeKey, resourceConfig] of Object.entries(resourceConfigurations)) {\n    // Same reasoning as the retention guard: prefer the config's OWN identifier so a mis-keyed\n    // registry entry is diagnosed against the name its author actually wrote.\n    const resourceType = (resourceConfig?.resourceIdentifier ?? resourceTypeKey) as ResourceType;\n    const collectionName = resolveSharedPersistenceCollectionName(resourceType);\n    const entry = {\n      resourceType,\n      adapter: resourceConfig?.persistenceAdapter ?? defaultPersistenceAdapter,\n    };\n\n    const existing = adaptersByCollection.get(collectionName);\n    if (existing) {\n      existing.push(entry);\n    } else {\n      adaptersByCollection.set(collectionName, [entry]);\n    }\n  }\n\n  const incoherences: SharedPersistenceCollectionAdapterIncoherence[] = [];\n\n  for (const [collectionName, adapters] of adaptersByCollection) {\n    if (adapters.length < 2) {\n      continue;\n    }\n    if (new Set(adapters.map((entry) => entry.adapter)).size < 2) {\n      continue;\n    }\n\n    const declared = adapters\n      .map((entry) => `'${String(entry.resourceType)}' → ${entry.adapter}`)\n      .join(', ');\n\n    incoherences.push({\n      collectionName,\n      adapters,\n      message:\n        `Resource configs [${declared}] all address the '${collectionName}' persistence collection but ` +\n        `resolve to DIFFERENT persistence adapters. These configs are separate doors onto ONE set of ` +\n        `rows, and a collection name only addresses rows within a single database, so this splits them ` +\n        `across two stores that each believe they own the records: the admin door lists rows the self ` +\n        `door cannot read, a self-service write lands where the admin door will never see it, and an ` +\n        `erasure performed through one door leaves the other door's copy fully intact. Give every ` +\n        `config listed above the same persistenceAdapter (a resource sharing a collection cannot pick ` +\n        `its database alone), or stop sharing the collection.`,\n    });\n  }\n\n  return incoherences;\n}\n\n/** The minimal config shape {@link findSharedPersistenceCollectionRetentionIncoherences} reads. */\nexport interface SharedPersistenceCollectionRetentionCandidate {\n  readonly resourceIdentifier: ResourceType;\n  readonly retentionPolicy?: { mode?: ErasureRetentionMode } | undefined;\n}\n\n/**\n * Canonical comparison key for a resource's retention POSTURE.\n *\n * Compares the WHOLE resolved policy, not just `mode`. `ResourceRetentionPolicy` carries a single\n * axis today, so `mode` alone would be exhaustive — but this guard exists precisely because config\n * checks that look sufficient go quietly wrong later, and a second axis (a disposal clock, a\n * jurisdiction) added to the policy would otherwise escape the comparison with no compile-time\n * signal. Two configs over one collection must agree on ALL of it.\n *\n * Key order is normalised so authoring order cannot masquerade as a disagreement. `undefined` gets\n * its own key rather than being skipped: \"rows of this resource are hard-deleted\" is a positive\n * claim, and the in-vs-out asymmetry is what produces both failure modes documented below.\n */\nfunction buildRetentionPostureKey(retentionPolicy: { mode?: ErasureRetentionMode } | undefined): string {\n  if (retentionPolicy === undefined || retentionPolicy === null) {\n    return 'NOT_GOVERNED';\n  }\n  const entries = Object.entries(retentionPolicy as Record<string, unknown>)\n    .filter(([, value]) => value !== undefined)\n    .sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey));\n  return entries.length === 0 ? 'NOT_GOVERNED' : JSON.stringify(entries);\n}\n\n/** One collection whose resource configs disagree about retention governance. */\nexport interface SharedPersistenceCollectionRetentionIncoherence {\n  /** The shared collection the disagreeing configs write to. */\n  readonly collectionName: string;\n  /** Every resource config addressing that collection, with the posture it declared. */\n  readonly postures: readonly { resourceType: ResourceType; mode: ErasureRetentionMode | undefined }[];\n  /** Operator-facing explanation naming both failure modes and the fix. */\n  readonly message: string;\n}\n\n/**\n * Registry-ASSEMBLY guardrail: every resource config that resolves to the SAME\n * persistence collection must declare the SAME retention posture.\n *\n * ## Why a config that passes every per-resource check can still be broken\n *\n * `retentionPolicy` is validated PER RESOURCE CONFIG by the config factory: it\n * checks that resource's operations, its field treatments, its system-access\n * grants. It cannot check what a SIBLING config declares, because a factory\n * invocation never sees one. But retention is enforced against ROWS, and two\n * configs can own the same rows (see\n * {@link RESOURCE_SHARED_PERSISTENCE_COLLECTION_ALIASES}). So a pair that\n * disagrees produces a config where every individual resource is valid and the\n * COLLECTION is not.\n *\n * ## The two concrete failure modes\n *\n * **1. Fail-open erasure.** The retention hide filter (rows marked `RETAINED`\n * are invisible) and the immutability freeze are injected per resource config,\n * in `buildContextualFilter`. A row erased through the governed door stays\n * fully READABLE and UPDATABLE through the ungoverned one. For the\n * `USERS`/`USER_SELF` pair that ungoverned door exposes READ + UPDATE to\n * `APP_USER` — i.e. the erased subject can still read and edit their own\n * \"erased\" record. The row is erased only from the door that was opted in,\n * which is a compliance-grade lie about the record.\n *\n * **2. Unique-index collision — a hard functional abort.** A retention-governed\n * config scopes each unique index to NON-retained rows (a partial filter on the\n * retention marker), precisely so scrubbed rows leave the index and cannot\n * collide on the shared mask value. An ungoverned config over the same\n * collection emits a PLAIN unique index on the same field. The FIRST erasure\n * succeeds; the SECOND writes the same mask value, hits the plain index, and\n * fails E11000 — inside the erasure transaction, so the whole erasure rolls\n * back. The capability is silently single-use.\n *\n * Both modes are invisible until a real erasure runs, which is why this is a\n * BOOT-time guard and not a test: the point is that a config which passes at\n * boot must actually be able to perform an erasure.\n *\n * ## Why \"one opted in, one not\" is a disagreement, not a default\n *\n * An absent `retentionPolicy` is a positive statement — \"rows of this resource\n * are hard-deleted\" — not an unset value the governed sibling can supply. Both\n * failure modes above are produced by exactly that asymmetry, so `undefined`\n * participates in the comparison as its own posture rather than being skipped.\n *\n * Pure and side-effect free: it reports, the caller throws. That keeps the\n * shared-collection fact and its invariant in the layer both persistence and\n * validation can import, while the registry owns the error shape.\n *\n * @param resourceConfigurations - every assembled resource config, keyed by resource type.\n * @returns one entry per incoherent collection; empty when the registry is coherent.\n */\nexport function findSharedPersistenceCollectionRetentionIncoherences(\n  resourceConfigurations: Record<string, SharedPersistenceCollectionRetentionCandidate>,\n): SharedPersistenceCollectionRetentionIncoherence[] {\n  const posturesByCollection = new Map<\n    string,\n    { resourceType: ResourceType; mode: ErasureRetentionMode | undefined; postureKey: string }[]\n  >();\n\n  for (const [resourceTypeKey, resourceConfig] of Object.entries(resourceConfigurations)) {\n    // Prefer the config's OWN identifier over the map key: the registry keys by resource type, but a\n    // host that mis-keyed an entry would otherwise be diagnosed against a name it never authored.\n    const resourceType = (resourceConfig?.resourceIdentifier ?? resourceTypeKey) as ResourceType;\n    const collectionName = resolveSharedPersistenceCollectionName(resourceType);\n    const posture = {\n      resourceType,\n      mode: resourceConfig?.retentionPolicy?.mode,\n      postureKey: buildRetentionPostureKey(resourceConfig?.retentionPolicy),\n    };\n\n    const existing = posturesByCollection.get(collectionName);\n    if (existing) {\n      existing.push(posture);\n    } else {\n      posturesByCollection.set(collectionName, [posture]);\n    }\n  }\n\n  const incoherences: SharedPersistenceCollectionRetentionIncoherence[] = [];\n\n  for (const [collectionName, postures] of posturesByCollection) {\n    if (postures.length < 2) {\n      continue;\n    }\n    const distinctPostures = new Set(postures.map((posture) => posture.postureKey));\n    if (distinctPostures.size < 2) {\n      continue;\n    }\n\n    const declared = postures\n      .map((posture) => `'${String(posture.resourceType)}' → ${posture.mode ?? 'NOT retention-governed'}`)\n      .join(', ');\n\n    incoherences.push({\n      collectionName,\n      postures,\n      message:\n        `Resource configs [${declared}] all store in the '${collectionName}' collection but declare ` +\n        `DIFFERENT retention postures. They are separate models over ONE set of rows, and retention is ` +\n        `enforced per resource config, so this ships two defects that only appear when a real erasure ` +\n        `runs: (1) FAIL-OPEN ERASURE — the retention hide filter and the immutability freeze are absent ` +\n        `on the ungoverned door, leaving an erased row readable and updatable there; (2) UNIQUE-INDEX ` +\n        `COLLISION — the governed config scopes its unique indexes to non-retained rows while the ` +\n        `ungoverned one emits plain unique indexes on the same collection, so the SECOND erased row ` +\n        `collides (E11000) and the erasure transaction rolls back. Declare the SAME retentionPolicy on ` +\n        `every config listed above (a resource sharing a collection cannot opt in or out alone), or ` +\n        `stop sharing the collection.`,\n    });\n  }\n\n  return incoherences;\n}\n\n/**\n * The privilege AXES a database credential issued to a named runtime principal (a minion) is built\n * from — one closed vocabulary shared by every storage adapter that mints such a credential.\n *\n * Each axis is a distinct verb set, not a strength on a scale, and they must never be merged:\n *\n * - {@link READ} — read rows.\n * - {@link WRITE} — insert, update and delete. The only axis that can REMOVE a row.\n * - {@link APPEND} — insert only. A principal can add a row and never amend or remove it, which is\n *   what makes it the axis for evidence: an audit trail a principal can rewrite is not an audit trail.\n * - {@link MAINTAIN} — insert and update, never delete, for durable runtime state whose history must\n *   survive the principal that advances it.\n *\n * It lives beside the collection aliases because a grant is issued per COLLECTION: the alias map says\n * which rows a grant on a resource type reaches, and this says which verbs it carries there. The\n * derivation that fills each axis, and the engine floor it adds, live in `platform-config-lib`\n * (`deriveMinionDatabaseGrants`); the MongoDB and PostgreSQL adapters each translate an axis into\n * their own privilege dialect.\n *\n * Scope, stated because it is easy to over-read: this governs NAMED runtime principals only. The\n * application backend is not issued an axis-scoped credential — it owns its database — so nothing\n * here constrains what the backend's own credential can do to a row.\n */\nexport enum RuntimePrincipalDatabaseGrantAxis {\n  READ = 'read',\n  WRITE = 'write',\n  APPEND = 'append',\n  MAINTAIN = 'maintain',\n}\n"]}
+{"version":3,"file":"shared-persistence-collection.utils.js","sourceRoot":"","sources":["../../../../../src/resources/utils/shared-persistence-collection.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import { CoreResourceType } from '../resources.shared.core.definitions';\nimport type { ResourceType } from '../resources.shared.schemas';\nimport type { PersistenceAdapterType } from '../resources-config.shared.schemas';\nimport { ErasureRetentionMode } from '../../compliance/privacy/impersonalization.shared.schemas';\n\n/**\n * Resource types that deliberately project onto ANOTHER resource type's\n * persistence collection — THE authority for \"which configs address the same\n * physical rows?\".\n *\n * ## What this expresses\n *\n * A `USER_SELF*` resource is not a different record set; it is a different DOOR\n * onto the SAME record set, with its own operations, roles and scoping. The\n * `USERS` door is the admin surface (list every user, delete a user); the\n * `USER_SELF` door is the self surface (read/update MY row). They intentionally\n * share `UserSchema` and they intentionally share storage — the persistence\n * layer builds a SEPARATE model per resource config over ONE collection.\n *\n * Anything not listed here stores under its own resource type.\n *\n * ## Why it is a single named authority\n *\n * This mapping had already been copied twice inside the backend (the\n * zod→mongoose model builder, which is what actually creates and reads the\n * collection, and the aggregation collection resolver — whose earlier\n * divergence made every aggregation query a non-existent collection and return\n * zero rows). It now has a third consumer of a completely different kind:\n * {@link findSharedPersistenceCollectionRetentionIncoherences}, a boot-time\n * coherence guard. A per-resource config factory structurally cannot see this\n * relationship — it validates ONE config at a time — so the fact has to live\n * where every layer can read it, and it has to live exactly once.\n *\n * ## The alias belongs to the RESOURCE, not to the storage adapter\n *\n * Every persistence path resolves through this map, and each adapter has\n * exactly ONE composition point that does so: MongoDB's model builder and its\n * aggregation resolver, and — on the SQL side — the single\n * `resolveTableNameForResource` helper that the hybrid planner, the PostgreSQL\n * repository and the boot-time table verifier all call.\n *\n * This was NOT always true, and the way it failed is the reason to keep it\n * true: PostgreSQL used to derive its table name straight from\n * `resourceIdentifier`, so `USER_SELF` planned, wrote and verified a `userself`\n * table while `USERS` used `users`. An adapter choice must never silently\n * change WHICH RECORDS a resource addresses — that is not a storage detail, it\n * is the \"two doors, one record set\" contract itself. On the SQL side the\n * resolved name is additionally normalised into a SQL identifier; casing is an\n * adapter concern, the alias is not.\n *\n * The one thing a shared resolver still cannot see is an alias group whose\n * members are pointed at DIFFERENT adapters — each config is individually\n * valid, and only the pair is wrong. That is what\n * {@link findSharedPersistenceCollectionAdapterIncoherences} fails closed on.\n */\nexport const RESOURCE_SHARED_PERSISTENCE_COLLECTION_ALIASES: Readonly<Record<string, string>> = {\n  [CoreResourceType.USER_SELF]: CoreResourceType.USERS,\n  [CoreResourceType.USER_SELF_PROFILES]: CoreResourceType.USER_PROFILES,\n  [CoreResourceType.USER_SELF_PREFERENCES]: CoreResourceType.USER_PREFERENCES,\n  /*\n   * The application-scoped audit door addresses the organization-scoped resource's rows (#317).\n   *\n   * Unlike the `USER_SELF` group above — where the alias exists so a principal can address its OWN\n   * row through a narrower door — this pair exists because the two doors see DIFFERENT SUBSETS of\n   * one set: the organization door is tenant-filtered and structurally cannot return the rows that\n   * carry no organization (logins, session evictions, application-wide policy changes), which is\n   * 74% of them on a measured dogfood application. Splitting the storage would split the audit\n   * trail itself, so the alias is load-bearing rather than a convenience.\n   */\n  [CoreResourceType.APPLICATION_AUDIT_LOGS]: CoreResourceType.AUDIT_LOGS,\n};\n\n/**\n * The persistence collection a resource type's rows live in — its alias target\n * when it declares one, otherwise the resource type itself.\n *\n * @param resourceType - the resource type whose storage location is wanted.\n * @returns the collection name, as a plain string.\n */\nexport function resolveSharedPersistenceCollectionName(resourceType: ResourceType): string {\n  return RESOURCE_SHARED_PERSISTENCE_COLLECTION_ALIASES[resourceType as string] ?? (resourceType as string);\n}\n\n/** The minimal config shape {@link findSharedPersistenceCollectionAdapterIncoherences} reads. */\nexport interface SharedPersistenceCollectionAdapterCandidate {\n  readonly resourceIdentifier: ResourceType;\n  /** The config's OWN declaration; `undefined` means \"inherit the application default\". */\n  readonly persistenceAdapter?: PersistenceAdapterType | undefined;\n}\n\n/** One collection whose resource configs are pointed at different databases. */\nexport interface SharedPersistenceCollectionAdapterIncoherence {\n  /** The shared collection the disagreeing configs claim to address. */\n  readonly collectionName: string;\n  /** Every resource config addressing that collection, with the adapter it RESOLVED to. */\n  readonly adapters: readonly { resourceType: ResourceType; adapter: PersistenceAdapterType }[];\n  /** Operator-facing explanation naming the consequence and the fix. */\n  readonly message: string;\n}\n\n/**\n * Registry-ASSEMBLY guardrail: every resource config that resolves to the SAME\n * persistence collection must resolve to the SAME persistence adapter.\n *\n * ## Why the shared resolver cannot cover this on its own\n *\n * {@link resolveSharedPersistenceCollectionName} makes the alias\n * adapter-independent: whichever database a resource lands in, it addresses the\n * aliased NAME. That is necessary and not sufficient. A name is only an address\n * WITHIN one database, so pointing `USERS` at PostgreSQL while `USER_SELF`\n * inherits MongoDB yields two stores that both believe they own the same rows.\n * Nothing downstream can detect it: each config is individually valid, each\n * repository is correctly built, and every per-resource check passes.\n *\n * ## The failure it prevents\n *\n * The doors silently stop sharing records. The admin door lists users the self\n * door cannot read; a self-service update writes to a row the admin door will\n * never see; and — because retention is enforced against ROWS — an erasure\n * performed through one door leaves the other door's copy completely\n * untouched, which is the same compliance-grade lie that\n * {@link findSharedPersistenceCollectionRetentionIncoherences} exists to\n * prevent, arrived at from a different direction.\n *\n * The table name is not the only thing that follows from the adapter. Id FORMAT\n * does too — the PostgreSQL repository validates ids as UUIDs while Mongo\n * expects ObjectIds, each resolved from its OWN resource's adapter — so a split\n * group would also reject through one door the very ids the other door mints.\n * Anything keyed on \"this resource's adapter\" inherits this invariant.\n *\n * ## Why this is permanent, not a capability gate\n *\n * Unlike adapter gaps that close when the missing support is implemented, this\n * one has no future in which it becomes valid: two databases cannot hold one\n * set of rows. It is deliberately NOT a ban on aliased resources using\n * PostgreSQL — an alias group that agrees on PostgreSQL resolves to one shared\n * table, and whether that table was actually provisioned is a separate,\n * already-enforced question (the boot-time table verifier).\n *\n * Resources inherit the application default when they declare nothing, so the\n * caller supplies the resolved default rather than this function guessing it.\n *\n * Pure and side-effect free: it reports, the caller throws.\n *\n * @param resourceConfigurations - every assembled resource config, keyed by resource type.\n * @param defaultPersistenceAdapter - the adapter a config with no declaration inherits.\n * @returns one entry per incoherent collection; empty when the registry is coherent.\n */\nexport function findSharedPersistenceCollectionAdapterIncoherences(\n  resourceConfigurations: Record<string, SharedPersistenceCollectionAdapterCandidate>,\n  defaultPersistenceAdapter: PersistenceAdapterType,\n): SharedPersistenceCollectionAdapterIncoherence[] {\n  const adaptersByCollection = new Map<\n    string,\n    { resourceType: ResourceType; adapter: PersistenceAdapterType }[]\n  >();\n\n  for (const [resourceTypeKey, resourceConfig] of Object.entries(resourceConfigurations)) {\n    // Same reasoning as the retention guard: prefer the config's OWN identifier so a mis-keyed\n    // registry entry is diagnosed against the name its author actually wrote.\n    const resourceType = (resourceConfig?.resourceIdentifier ?? resourceTypeKey) as ResourceType;\n    const collectionName = resolveSharedPersistenceCollectionName(resourceType);\n    const entry = {\n      resourceType,\n      adapter: resourceConfig?.persistenceAdapter ?? defaultPersistenceAdapter,\n    };\n\n    const existing = adaptersByCollection.get(collectionName);\n    if (existing) {\n      existing.push(entry);\n    } else {\n      adaptersByCollection.set(collectionName, [entry]);\n    }\n  }\n\n  const incoherences: SharedPersistenceCollectionAdapterIncoherence[] = [];\n\n  for (const [collectionName, adapters] of adaptersByCollection) {\n    if (adapters.length < 2) {\n      continue;\n    }\n    if (new Set(adapters.map((entry) => entry.adapter)).size < 2) {\n      continue;\n    }\n\n    const declared = adapters\n      .map((entry) => `'${String(entry.resourceType)}' → ${entry.adapter}`)\n      .join(', ');\n\n    incoherences.push({\n      collectionName,\n      adapters,\n      message:\n        `Resource configs [${declared}] all address the '${collectionName}' persistence collection but ` +\n        `resolve to DIFFERENT persistence adapters. These configs are separate doors onto ONE set of ` +\n        `rows, and a collection name only addresses rows within a single database, so this splits them ` +\n        `across two stores that each believe they own the records: the admin door lists rows the self ` +\n        `door cannot read, a self-service write lands where the admin door will never see it, and an ` +\n        `erasure performed through one door leaves the other door's copy fully intact. Give every ` +\n        `config listed above the same persistenceAdapter (a resource sharing a collection cannot pick ` +\n        `its database alone), or stop sharing the collection.`,\n    });\n  }\n\n  return incoherences;\n}\n\n/** The minimal config shape {@link findSharedPersistenceCollectionRetentionIncoherences} reads. */\nexport interface SharedPersistenceCollectionRetentionCandidate {\n  readonly resourceIdentifier: ResourceType;\n  readonly retentionPolicy?: { mode?: ErasureRetentionMode } | undefined;\n}\n\n/**\n * Canonical comparison key for a resource's retention POSTURE.\n *\n * Compares the WHOLE resolved policy, not just `mode`. It carries two members since #1635 — `mode` and\n * the nested `statutoryRetention` ground — and this is the case the whole-policy comparison was written\n * for: comparing `mode` alone would let two configs over one collection agree on the treatment while\n * one says a statute keeps the rows and the other does not. Two configs over one collection must agree\n * on ALL of it.\n *\n * Key order is normalised at EVERY depth so authoring order cannot masquerade as a disagreement. `undefined` gets\n * its own key rather than being skipped: \"rows of this resource are hard-deleted\" is a positive\n * claim, and the in-vs-out asymmetry is what produces both failure modes documented below.\n */\nfunction buildRetentionPostureKey(retentionPolicy: { mode?: ErasureRetentionMode } | undefined): string {\n  if (retentionPolicy === undefined || retentionPolicy === null) {\n    return 'NOT_GOVERNED';\n  }\n  const canonical = (value: unknown): unknown => {\n    if (value === null || typeof value !== 'object' || Array.isArray(value)) return value;\n    return Object.entries(value as Record<string, unknown>)\n      .filter(([, member]) => member !== undefined)\n      .sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey))\n      .map(([key, member]) => [key, canonical(member)]);\n  };\n  const entries = canonical(retentionPolicy) as unknown[];\n  return entries.length === 0 ? 'NOT_GOVERNED' : JSON.stringify(entries);\n}\n\n/** One collection whose resource configs disagree about retention governance. */\nexport interface SharedPersistenceCollectionRetentionIncoherence {\n  /** The shared collection the disagreeing configs write to. */\n  readonly collectionName: string;\n  /** Every resource config addressing that collection, with the posture it declared. */\n  readonly postures: readonly { resourceType: ResourceType; mode: ErasureRetentionMode | undefined }[];\n  /** Operator-facing explanation naming both failure modes and the fix. */\n  readonly message: string;\n}\n\n/**\n * Registry-ASSEMBLY guardrail: every resource config that resolves to the SAME\n * persistence collection must declare the SAME retention posture.\n *\n * ## Why a config that passes every per-resource check can still be broken\n *\n * `retentionPolicy` is validated PER RESOURCE CONFIG by the config factory: it\n * checks that resource's operations, its field treatments, its system-access\n * grants. It cannot check what a SIBLING config declares, because a factory\n * invocation never sees one. But retention is enforced against ROWS, and two\n * configs can own the same rows (see\n * {@link RESOURCE_SHARED_PERSISTENCE_COLLECTION_ALIASES}). So a pair that\n * disagrees produces a config where every individual resource is valid and the\n * COLLECTION is not.\n *\n * ## The two concrete failure modes\n *\n * **1. Fail-open erasure.** The retention hide filter (rows marked `RETAINED`\n * are invisible) and the immutability freeze are injected per resource config,\n * in `buildContextualFilter`. A row erased through the governed door stays\n * fully READABLE and UPDATABLE through the ungoverned one. For the\n * `USERS`/`USER_SELF` pair that ungoverned door exposes READ + UPDATE to\n * `APP_USER` — i.e. the erased subject can still read and edit their own\n * \"erased\" record. The row is erased only from the door that was opted in,\n * which is a compliance-grade lie about the record.\n *\n * **2. Unique-index collision — a hard functional abort.** A retention-governed\n * config scopes each unique index to NON-retained rows (a partial filter on the\n * retention marker), precisely so scrubbed rows leave the index and cannot\n * collide on the shared mask value. An ungoverned config over the same\n * collection emits a PLAIN unique index on the same field. The FIRST erasure\n * succeeds; the SECOND writes the same mask value, hits the plain index, and\n * fails E11000 — inside the erasure transaction, so the whole erasure rolls\n * back. The capability is silently single-use.\n *\n * Both modes are invisible until a real erasure runs, which is why this is a\n * BOOT-time guard and not a test: the point is that a config which passes at\n * boot must actually be able to perform an erasure.\n *\n * ## Why \"one opted in, one not\" is a disagreement, not a default\n *\n * An absent `retentionPolicy` is a positive statement — \"rows of this resource\n * are hard-deleted\" — not an unset value the governed sibling can supply. Both\n * failure modes above are produced by exactly that asymmetry, so `undefined`\n * participates in the comparison as its own posture rather than being skipped.\n *\n * Pure and side-effect free: it reports, the caller throws. That keeps the\n * shared-collection fact and its invariant in the layer both persistence and\n * validation can import, while the registry owns the error shape.\n *\n * @param resourceConfigurations - every assembled resource config, keyed by resource type.\n * @returns one entry per incoherent collection; empty when the registry is coherent.\n */\nexport function findSharedPersistenceCollectionRetentionIncoherences(\n  resourceConfigurations: Record<string, SharedPersistenceCollectionRetentionCandidate>,\n): SharedPersistenceCollectionRetentionIncoherence[] {\n  const posturesByCollection = new Map<\n    string,\n    { resourceType: ResourceType; mode: ErasureRetentionMode | undefined; postureKey: string }[]\n  >();\n\n  for (const [resourceTypeKey, resourceConfig] of Object.entries(resourceConfigurations)) {\n    // Prefer the config's OWN identifier over the map key: the registry keys by resource type, but a\n    // host that mis-keyed an entry would otherwise be diagnosed against a name it never authored.\n    const resourceType = (resourceConfig?.resourceIdentifier ?? resourceTypeKey) as ResourceType;\n    const collectionName = resolveSharedPersistenceCollectionName(resourceType);\n    const posture = {\n      resourceType,\n      mode: resourceConfig?.retentionPolicy?.mode,\n      postureKey: buildRetentionPostureKey(resourceConfig?.retentionPolicy),\n    };\n\n    const existing = posturesByCollection.get(collectionName);\n    if (existing) {\n      existing.push(posture);\n    } else {\n      posturesByCollection.set(collectionName, [posture]);\n    }\n  }\n\n  const incoherences: SharedPersistenceCollectionRetentionIncoherence[] = [];\n\n  for (const [collectionName, postures] of posturesByCollection) {\n    if (postures.length < 2) {\n      continue;\n    }\n    const distinctPostures = new Set(postures.map((posture) => posture.postureKey));\n    if (distinctPostures.size < 2) {\n      continue;\n    }\n\n    const declared = postures\n      .map((posture) => `'${String(posture.resourceType)}' → ${posture.mode ?? 'NOT retention-governed'}`)\n      .join(', ');\n\n    incoherences.push({\n      collectionName,\n      postures,\n      message:\n        `Resource configs [${declared}] all store in the '${collectionName}' collection but declare ` +\n        `DIFFERENT retention postures. They are separate models over ONE set of rows, and retention is ` +\n        `enforced per resource config, so this ships two defects that only appear when a real erasure ` +\n        `runs: (1) FAIL-OPEN ERASURE — the retention hide filter and the immutability freeze are absent ` +\n        `on the ungoverned door, leaving an erased row readable and updatable there; (2) UNIQUE-INDEX ` +\n        `COLLISION — the governed config scopes its unique indexes to non-retained rows while the ` +\n        `ungoverned one emits plain unique indexes on the same collection, so the SECOND erased row ` +\n        `collides (E11000) and the erasure transaction rolls back. Declare the SAME retentionPolicy on ` +\n        `every config listed above (a resource sharing a collection cannot opt in or out alone), or ` +\n        `stop sharing the collection.`,\n    });\n  }\n\n  return incoherences;\n}\n\n/**\n * The privilege AXES a database credential issued to a named runtime principal (a minion) is built\n * from — one closed vocabulary shared by every storage adapter that mints such a credential.\n *\n * Each axis is a distinct verb set, not a strength on a scale, and they must never be merged:\n *\n * - {@link READ} — read rows.\n * - {@link WRITE} — insert, update and delete. The only axis that can REMOVE a row.\n * - {@link APPEND} — insert only. A principal can add a row and never amend or remove it, which is\n *   what makes it the axis for evidence: an audit trail a principal can rewrite is not an audit trail.\n * - {@link MAINTAIN} — insert and update, never delete, for durable runtime state whose history must\n *   survive the principal that advances it.\n *\n * It lives beside the collection aliases because a grant is issued per COLLECTION: the alias map says\n * which rows a grant on a resource type reaches, and this says which verbs it carries there. The\n * derivation that fills each axis, and the engine floor it adds, live in `platform-config-lib`\n * (`deriveMinionDatabaseGrants`); the MongoDB and PostgreSQL adapters each translate an axis into\n * their own privilege dialect.\n *\n * Scope, stated because it is easy to over-read: this governs NAMED runtime principals only. The\n * application backend is not issued an axis-scoped credential — it owns its database — so nothing\n * here constrains what the backend's own credential can do to a row.\n */\nexport enum RuntimePrincipalDatabaseGrantAxis {\n  READ = 'read',\n  WRITE = 'write',\n  APPEND = 'append',\n  MAINTAIN = 'maintain',\n}\n"]}

package/dist/esm/resources/work-unit.shared.schemas.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+/** @wildo_source:part:start saas.models.work-unit-ref facet:layer:shared facet:audience:app-developer */
+/**
+ * A reference to one CASE — the unit of work an application sells an outcome for (a matter, a file, a
+ * claim, a ticket). Model-call cost attribution, expert decisions on agent work and agent turns all carry it
+ * as `caseRef`. Import it from `@wildo-ai/saas-models`.
+ *
+ * `resourceType` is an OPEN application identifier (resource names are not a closed vocabulary), so the
+ * shape alone proves nothing: a ref is accepted at a service boundary only after the registry confirms
+ * the resource exists and the caller's own authorization can READ that row. The tenant is always derived
+ * from the row, never from the caller. And the resource must declare `workUnit: true` in its resource
+ * configuration: a ref to any other resource is refused as NOT_A_WORK_UNIT.
+ */
+export declare const WorkUnitRefSchema: z.ZodObject<{
+    resourceType: z.ZodString;
+    resourceId: z.ZodString;
+}, z.core.$strict>;
+export type WorkUnitRef = z.infer<typeof WorkUnitRefSchema>;
+/** @wildo_source:part:end saas.models.work-unit-ref */
+//# sourceMappingURL=work-unit.shared.schemas.d.ts.map

package/dist/esm/resources/work-unit.shared.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"work-unit.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/resources/work-unit.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,yGAAyG;AACzG;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB;;;kBAG5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,uDAAuD"}

package/dist/esm/resources/work-unit.shared.schemas.js

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+/** @wildo_source:part:start saas.models.work-unit-ref facet:layer:shared facet:audience:app-developer */
+/**
+ * A reference to one CASE — the unit of work an application sells an outcome for (a matter, a file, a
+ * claim, a ticket). Model-call cost attribution, expert decisions on agent work and agent turns all carry it
+ * as `caseRef`. Import it from `@wildo-ai/saas-models`.
+ *
+ * `resourceType` is an OPEN application identifier (resource names are not a closed vocabulary), so the
+ * shape alone proves nothing: a ref is accepted at a service boundary only after the registry confirms
+ * the resource exists and the caller's own authorization can READ that row. The tenant is always derived
+ * from the row, never from the caller. And the resource must declare `workUnit: true` in its resource
+ * configuration: a ref to any other resource is refused as NOT_A_WORK_UNIT.
+ */
+export const WorkUnitRefSchema = z.strictObject({
+    resourceType: z.string().min(1).max(120).describe('Name of the resource the case is a row of, as the API names it (for example `todos`). The resource must exist, and the caller must be able to read the row.'),
+    resourceId: z.string().min(1).max(200).describe('Id of that row. The case belongs to the organization that owns the row, whatever organization the request names.'),
+});
+/** @wildo_source:part:end saas.models.work-unit-ref */
+//# sourceMappingURL=work-unit.shared.schemas.js.map

package/dist/esm/resources/work-unit.shared.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"work-unit.shared.schemas.js","sourceRoot":"","sources":["../../../../src/resources/work-unit.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,yGAAyG;AACzG;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,YAAY,CAAC;IAC9C,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,6JAA6J,CAAC;IAChN,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,kHAAkH,CAAC;CACpK,CAAC,CAAC;AAEH,uDAAuD","sourcesContent":["import { z } from 'zod';\n\n/** @wildo_source:part:start saas.models.work-unit-ref facet:layer:shared facet:audience:app-developer */\n/**\n * A reference to one CASE — the unit of work an application sells an outcome for (a matter, a file, a\n * claim, a ticket). Model-call cost attribution, expert decisions on agent work and agent turns all carry it\n * as `caseRef`. Import it from `@wildo-ai/saas-models`.\n *\n * `resourceType` is an OPEN application identifier (resource names are not a closed vocabulary), so the\n * shape alone proves nothing: a ref is accepted at a service boundary only after the registry confirms\n * the resource exists and the caller's own authorization can READ that row. The tenant is always derived\n * from the row, never from the caller. And the resource must declare `workUnit: true` in its resource\n * configuration: a ref to any other resource is refused as NOT_A_WORK_UNIT.\n */\nexport const WorkUnitRefSchema = z.strictObject({\n  resourceType: z.string().min(1).max(120).describe('Name of the resource the case is a row of, as the API names it (for example `todos`). The resource must exist, and the caller must be able to read the row.'),\n  resourceId: z.string().min(1).max(200).describe('Id of that row. The case belongs to the organization that owns the row, whatever organization the request names.'),\n});\nexport type WorkUnitRef = z.infer<typeof WorkUnitRefSchema>;\n/** @wildo_source:part:end saas.models.work-unit-ref */\n"]}

package/dist/esm/runtime/execution-context.shared.schemas.d.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { ResourcePrimaryScope } from "../resources/resources.shared.schemas";
+import { InboundChannelKind, InboundSenderAssurance } from "../inbound/inbound-channels.shared.schemas";
 /**
  * Execution type enum defining how the execution context was initiated.
  *
@@ -37,7 +38,22 @@ export declare enum ExecutionContext_ExecutionType {
      * Created by WebhookHandlerBackendService after signature verification + scope resolution.
      */
     WEBHOOK_CALLBACK = "webhook_callback",
-    ANONYMOUS_SESSION = "anonymous_session"
+    ANONYMOUS_SESSION = "anonymous_session",
+    /**
+     * An application-declared inbound HANDLER running one verified, durably stored delivery (#1596).
+     *
+     * Unlike `WEBHOOK_CALLBACK`, this is an AUTHORIZED principal: it carries the handler's declared
+     * `actingRoles` as its roles, is pinned to the one scope the delivery resolved to, and goes through
+     * role authorization, organization-unit narrowing, scope-root confinement and cross-tenant read
+     * observation exactly like a user. `WEBHOOK_CALLBACK` skips all four because signature verification
+     * is its whole trust story; application code must never inherit that, or a handler would be
+     * role-free and cross-tenant.
+     *
+     * `initiatorIds` is REQUIRED and names the delivery (`inboundDeliveryId`) and the handler
+     * (`inboundHandlerRef`); it never carries a user or a machine credential — nobody authenticated, a
+     * sender's signature was verified.
+     */
+    INBOUND_DELIVERY = "inbound_delivery"
 }
 /**
  * How a MACHINE principal ({@link ExecutionContext_ExecutionType.ORGANIZATION_MACHINE} /
@@ -96,6 +112,13 @@ export declare const ExecutionContext_InitiatorIdsSchema: z.ZodObject<{
     consumableTokenId: z.ZodOptional<z.ZodString>;
     webhookProviderId: z.ZodOptional<z.ZodString>;
     anonymousUserId: z.ZodOptional<z.ZodString>;
+    inboundDeliveryId: z.ZodOptional<z.ZodString>;
+    inboundHandlerRef: z.ZodOptional<z.ZodString>;
+    inboundScopeUserId: z.ZodOptional<z.ZodString>;
+    inboundSender: z.ZodOptional<z.ZodObject<{
+        channel: z.ZodEnum<typeof InboundChannelKind>;
+        assurance: z.ZodEnum<typeof InboundSenderAssurance>;
+    }, z.core.$strict>>;
 }, z.core.$strip>;
 export type ExecutionContext_InitiatorIds = z.infer<typeof ExecutionContext_InitiatorIdsSchema>;
 /**
@@ -106,6 +129,8 @@ export declare const ExecutionContext_RoleInfoSchema: z.ZodObject<{
     relatedPrimaryScope: z.ZodEnum<typeof ResourcePrimaryScope>;
     relatedResourceId: z.ZodOptional<z.ZodString>;
     organizationUnitId: z.ZodOptional<z.ZodString>;
+    viaServiceProviderRelationshipId: z.ZodOptional<z.ZodString>;
+    viaProviderOrganizationId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ExecutionContext_RoleInfo = z.infer<typeof ExecutionContext_RoleInfoSchema>;
 /**
@@ -127,6 +152,28 @@ export declare function isOrganizationWideRoleInfo(roleInfo: ExecutionContext_Ro
  * question is explicitly unit-aware.
  */
 export declare function selectOrganizationWideRoles(initiatorRoles: readonly ExecutionContext_RoleInfo[] | undefined): string[];
+/**
+ * The role entries that may speak for a request acting inside ONE organization.
+ *
+ * Every entry that is not ORGANIZATIONS-scoped (the APPLICATION role set, chiefly) is kept: those
+ * roles are not held "in" a tenant, and they resolve against their own role table. An
+ * ORGANIZATIONS-scoped entry is kept only when it names `organizationId` — organization-wide and
+ * unit-scoped entries alike, so a caller partitions on {@link isOrganizationWideRoleInfo} AFTER this.
+ *
+ * ## Why this exists — measured 2026-09-25
+ *
+ * The per-instance role gate, the unit-narrowing decision and the role ceiling each unioned
+ * organization-wide entries across EVERY organization the caller belongs to, and answered the tenant
+ * question separately ("does the caller hold ANY org-wide entry for this row's organization?"). The
+ * two answers composed into "ORG_ADMIN somewhere + ORG_GUEST here = ORG_ADMIN here": an ORG_ADMIN of
+ * tenant A who was a guest of tenant B passed every ORG_ADMIN per-instance verb on B's rows, and could
+ * grant ORG_ADMIN in B through the role ceiling. A role is a fact about a membership, so it is only
+ * ever evaluated inside the organization that membership belongs to.
+ *
+ * An absent `organizationId` keeps no ORGANIZATIONS entry at all — fail closed: a request that names
+ * no tenant has no tenant role to speak for it.
+ */
+export declare function selectRoleInfosActingInOrganization(initiatorRoles: readonly ExecutionContext_RoleInfo[] | undefined, organizationId: string | undefined): ExecutionContext_RoleInfo[];
 /**
  * The unit-scoped grants a principal holds, as `(organizationUnitId, roles)` pairs.
  *

package/dist/esm/runtime/execution-context.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execution-context.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/runtime/execution-context.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAE7E;;;;;;;;;GASG;AACH,oBAAY,8BAA8B;IACtC;;;;;;;OAOG;IACH,oBAAoB,yBAAyB;IAC7C;;;;;OAKG;IACH,mBAAmB,wBAAwB;IAC3C,YAAY,iBAAiB;IAC7B,gBAAgB,qBAAqB;IACrC,4BAA4B,iCAAiC;IAC7D,gBAAgB,qBAAqB;IACrC;;;;OAIG;IACH,gBAAgB,qBAAqB;IACrC,iBAAiB,sBAAsB;CAC1C;AAED;;;;;GAKG;AACH,oBAAY,iBAAiB;IACzB,oFAAoF;IACpF,OAAO,YAAY;IACnB;;;;OAIG;IACH,YAAY,iBAAiB;CAChC;AAED,oBAAY,uCAAuC;IAC/C,YAAY,iBAAiB;IAC7B,gBAAgB,qBAAqB;IACrC,gBAAgB,qBAAqB;IACrC,iBAAiB,sBAAsB;CAC1C;AAED;;GAEG;AACH,oBAAY,WAAW;IACrB,UAAU,eAAe;IACzB,OAAO,YAAY;CACpB;AAEC;;GAEG;AACH;;;;;;;;GAQG;AACH,eAAO,MAAM,wCAAwC;;;iBAKnD,CAAC;AAEH,MAAM,MAAM,kCAAkC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wCAAwC,CAAC,CAAC;AAE1G,eAAO,MAAM,mCAAmC;;;;;;;;;;;iBAiB9C,CAAC;AAEH,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mCAAmC,CAAC,CAAC;AAIlG;;GAEG;AAGH,eAAO,MAAM,+BAA+B;;;;;iBAoBxC,CAAC;AAEL,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,yBAAyB,GAAG,OAAO,CAEvF;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,cAAc,EAAE,SAAS,yBAAyB,EAAE,GAAG,SAAS,GAAG,MAAM,EAAE,CAEtH;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,cAAc,EAAE,SAAS,yBAAyB,EAAE,GAAG,SAAS,GAC/D;IAAE,kBAAkB,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,EAAE,CAInD;AAGD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,0CAA0C;;;;;iBAkBrD,CAAC;AAEH,MAAM,MAAM,oCAAoC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0CAA0C,CAAC,CAAC"}
+{"version":3,"file":"execution-context.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/runtime/execution-context.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAC7E,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,4CAA4C,CAAC;AAExG;;;;;;;;;GASG;AACH,oBAAY,8BAA8B;IACtC;;;;;;;OAOG;IACH,oBAAoB,yBAAyB;IAC7C;;;;;OAKG;IACH,mBAAmB,wBAAwB;IAC3C,YAAY,iBAAiB;IAC7B,gBAAgB,qBAAqB;IACrC,4BAA4B,iCAAiC;IAC7D,gBAAgB,qBAAqB;IACrC;;;;OAIG;IACH,gBAAgB,qBAAqB;IACrC,iBAAiB,sBAAsB;IACvC;;;;;;;;;;;;;OAaG;IACH,gBAAgB,qBAAqB;CACxC;AAED;;;;;GAKG;AACH,oBAAY,iBAAiB;IACzB,oFAAoF;IACpF,OAAO,YAAY;IACnB;;;;OAIG;IACH,YAAY,iBAAiB;CAChC;AAED,oBAAY,uCAAuC;IAC/C,YAAY,iBAAiB;IAC7B,gBAAgB,qBAAqB;IACrC,gBAAgB,qBAAqB;IACrC,iBAAiB,sBAAsB;CAC1C;AAED;;GAEG;AACH,oBAAY,WAAW;IACrB,UAAU,eAAe;IACzB,OAAO,YAAY;CACpB;AAEC;;GAEG;AACH;;;;;;;;GAQG;AACH,eAAO,MAAM,wCAAwC;;;iBAKnD,CAAC;AAEH,MAAM,MAAM,kCAAkC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wCAAwC,CAAC,CAAC;AAE1G,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;;;;;iBAuD9C,CAAC;AAEH,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mCAAmC,CAAC,CAAC;AAIlG;;GAEG;AAGH,eAAO,MAAM,+BAA+B;;;;;;;iBAiCxC,CAAC;AAEL,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,yBAAyB,GAAG,OAAO,CAEvF;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,cAAc,EAAE,SAAS,yBAAyB,EAAE,GAAG,SAAS,GAAG,MAAM,EAAE,CAEtH;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mCAAmC,CACjD,cAAc,EAAE,SAAS,yBAAyB,EAAE,GAAG,SAAS,EAChE,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,yBAAyB,EAAE,CAI7B;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,cAAc,EAAE,SAAS,yBAAyB,EAAE,GAAG,SAAS,GAC/D;IAAE,kBAAkB,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,EAAE,CAInD;AAGD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,0CAA0C;;;;;iBAkBrD,CAAC;AAEH,MAAM,MAAM,oCAAoC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0CAA0C,CAAC,CAAC"}

package/dist/esm/runtime/execution-context.shared.schemas.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { ResourcePrimaryScope } from "../resources/resources.shared.schemas.js";
+import { InboundChannelKind, InboundSenderAssurance } from "../inbound/inbound-channels.shared.schemas.js";
 /**
  * Execution type enum defining how the execution context was initiated.
  *
@@ -39,6 +40,21 @@ export var ExecutionContext_ExecutionType;
      */
     ExecutionContext_ExecutionType["WEBHOOK_CALLBACK"] = "webhook_callback";
     ExecutionContext_ExecutionType["ANONYMOUS_SESSION"] = "anonymous_session";
+    /**
+     * An application-declared inbound HANDLER running one verified, durably stored delivery (#1596).
+     *
+     * Unlike `WEBHOOK_CALLBACK`, this is an AUTHORIZED principal: it carries the handler's declared
+     * `actingRoles` as its roles, is pinned to the one scope the delivery resolved to, and goes through
+     * role authorization, organization-unit narrowing, scope-root confinement and cross-tenant read
+     * observation exactly like a user. `WEBHOOK_CALLBACK` skips all four because signature verification
+     * is its whole trust story; application code must never inherit that, or a handler would be
+     * role-free and cross-tenant.
+     *
+     * `initiatorIds` is REQUIRED and names the delivery (`inboundDeliveryId`) and the handler
+     * (`inboundHandlerRef`); it never carries a user or a machine credential — nobody authenticated, a
+     * sender's signature was verified.
+     */
+    ExecutionContext_ExecutionType["INBOUND_DELIVERY"] = "inbound_delivery";
 })(ExecutionContext_ExecutionType || (ExecutionContext_ExecutionType = {}));
 /**
  * How a MACHINE principal ({@link ExecutionContext_ExecutionType.ORGANIZATION_MACHINE} /
@@ -86,27 +102,65 @@ export var SessionType;
  */
 export const ExecutionContext_MachineCredentialSchema = z.object({
     /** Whether authentication used a static API key or an OAuth client. */
-    authMethod: z.enum(MachineAuthMethod),
+    authMethod: z.enum(MachineAuthMethod).describe("The kind of machine credential: `api_key` for an API key, `oauth_client` for an OAuth client."),
     /** The authenticating credential's `_id` (the ApiKey row, or the OAuthClient row). */
-    credentialId: z.string(),
+    credentialId: z.string().describe("The id of that API key or OAuth client."),
 });
 export const ExecutionContext_InitiatorIdsSchema = z.object({
-    organizationId: z.string().optional(),
-    userId: z.string().optional(),
-    applicationId: z.string().optional(),
+    organizationId: z.string().optional().describe("The organization the request ran in, when it ran in one."),
+    userId: z.string().optional().describe("The signed-in user who made the request."),
+    applicationId: z.string().optional().describe("The application the request was made to."),
     /**
      * Credential provenance for a machine principal (see
      * {@link ExecutionContext_MachineCredentialSchema}). Absent for human / anonymous /
      * webhook / internal principals.
      */
-    machineCredential: ExecutionContext_MachineCredentialSchema.optional(),
-    consumableTokenId: z.string().optional(),
+    machineCredential: ExecutionContext_MachineCredentialSchema.optional().describe("The API key or OAuth client that authenticated the request, when a machine made it."),
+    consumableTokenId: z.string().optional().describe("The one-time token the request was authorized by, such as an invitation or a sign-in link."),
     /**
      * Provider reference that triggered the webhook (e.g., 'stripe', 'google').
      * Only populated for WEBHOOK_CALLBACK execution type.
      */
-    webhookProviderId: z.string().optional(),
-    anonymousUserId: z.string().optional(),
+    webhookProviderId: z.string().optional().describe("The provider whose webhook call started the request, such as `stripe`."),
+    anonymousUserId: z.string().optional().describe("The anonymous visitor who made the request, before signing in."),
+    /**
+     * The stored inbound delivery this execution runs (its `_id`). Only populated for
+     * `INBOUND_DELIVERY`, where it is required — it is what the audit trail names as the source of
+     * every write the handler makes.
+     */
+    inboundDeliveryId: z.string().optional().describe("The stored inbound delivery the request was processing."),
+    /** The declared handler running the delivery. Only populated for `INBOUND_DELIVERY`, where it is required. */
+    inboundHandlerRef: z.string().optional().describe("The handler that was processing that inbound delivery."),
+    /**
+     * The person a USER-scope inbound delivery belongs to (#1629) — its SCOPE, never its identity.
+     *
+     * Deliberately not `userId`: `userId` means somebody authenticated as that person, which no inbound
+     * delivery ever did (a sender's signature was verified). Keeping the two apart is what lets the
+     * constructor keep refusing an authenticated identity on `INBOUND_DELIVERY` while personal-scope
+     * resources are still confined to one person: the ownership check reads this field for an inbound
+     * principal, and the repository's scope filter reads the same id from the context map.
+     *
+     * Only populated for a USER-scope `INBOUND_DELIVERY`.
+     */
+    inboundScopeUserId: z.string().optional().describe("The person a user-scoped inbound delivery belongs to. It scopes the records the delivery may reach; nobody signed in as that person."),
+    /**
+     * Who sent the message an `INBOUND_DELIVERY` runs, as IDENTIFICATION only (#1630, I8): the channel and
+     * how well the sender is known. It never grants anything — no authorization decision reads it, and the
+     * roles stay the handler's declared `actingRoles`.
+     *
+     * The address is deliberately NOT carried. A context is serialized into job payloads and trace
+     * attributes, where an address would outlive its erasure; the address lives on the conversation
+     * message, which the erasure writer can reach.
+     *
+     * Only populated for `INBOUND_DELIVERY`.
+     */
+    inboundSender: z
+        .strictObject({
+        channel: z.enum(InboundChannelKind).describe("The channel the inbound message arrived through."),
+        assurance: z.enum(InboundSenderAssurance).describe("How well the sender is known on that channel."),
+    })
+        .optional()
+        .describe("Who sent the inbound message the request was processing, as identification only: it grants nothing, and the sender's address is not included."),
 });
 /**
  * Role information with related scope and resource context
@@ -131,6 +185,19 @@ export const ExecutionContext_RoleInfoSchema = z.object({
      * exactly one definition.
      */
     organizationUnitId: z.string().optional(),
+    /**
+     * Present ⇒ this entry was conferred by a live service-provider relationship (#1597): the caller is
+     * a firm's expert (or an admitted firm machine client) acting inside a CLIENT organization.
+     *
+     * ⚠️ AUDIT ATTRIBUTION ONLY. No authority decision may read it — the entry's authority is fully
+     * expressed by `roles`, `relatedResourceId` and `organizationUnitId`, exactly like any other entry.
+     * It exists so an audit row written by a provider principal can name the relationship and the firm,
+     * which is what lets the client read "who from which firm did this, under which relationship" from
+     * its own trail. A system context derived from a request must not inherit it.
+     */
+    viaServiceProviderRelationshipId: z.string().optional(),
+    /** The firm behind {@link viaServiceProviderRelationshipId}. Audit attribution only, like it. */
+    viaProviderOrganizationId: z.string().optional(),
 });
 /**
  * Does this entry confer authority across the WHOLE owning scope?
@@ -155,6 +222,31 @@ export function isOrganizationWideRoleInfo(roleInfo) {
 export function selectOrganizationWideRoles(initiatorRoles) {
     return (initiatorRoles ?? []).filter(isOrganizationWideRoleInfo).flatMap((roleInfo) => roleInfo.roles);
 }
+/**
+ * The role entries that may speak for a request acting inside ONE organization.
+ *
+ * Every entry that is not ORGANIZATIONS-scoped (the APPLICATION role set, chiefly) is kept: those
+ * roles are not held "in" a tenant, and they resolve against their own role table. An
+ * ORGANIZATIONS-scoped entry is kept only when it names `organizationId` — organization-wide and
+ * unit-scoped entries alike, so a caller partitions on {@link isOrganizationWideRoleInfo} AFTER this.
+ *
+ * ## Why this exists — measured 2026-09-25
+ *
+ * The per-instance role gate, the unit-narrowing decision and the role ceiling each unioned
+ * organization-wide entries across EVERY organization the caller belongs to, and answered the tenant
+ * question separately ("does the caller hold ANY org-wide entry for this row's organization?"). The
+ * two answers composed into "ORG_ADMIN somewhere + ORG_GUEST here = ORG_ADMIN here": an ORG_ADMIN of
+ * tenant A who was a guest of tenant B passed every ORG_ADMIN per-instance verb on B's rows, and could
+ * grant ORG_ADMIN in B through the role ceiling. A role is a fact about a membership, so it is only
+ * ever evaluated inside the organization that membership belongs to.
+ *
+ * An absent `organizationId` keeps no ORGANIZATIONS entry at all — fail closed: a request that names
+ * no tenant has no tenant role to speak for it.
+ */
+export function selectRoleInfosActingInOrganization(initiatorRoles, organizationId) {
+    return (initiatorRoles ?? []).filter((roleInfo) => roleInfo.relatedPrimaryScope !== ResourcePrimaryScope.ORGANIZATIONS
+        || (Boolean(organizationId) && String(roleInfo.relatedResourceId ?? '') === organizationId));
+}
 /**
  * The unit-scoped grants a principal holds, as `(organizationUnitId, roles)` pairs.
  *