@wildo-ai/saas-models 1.1.4 → 1.1.6

package/dist/esm/resources/resources-config.shared.schemas.d.ts

@@ -1,3 +1,7 @@
+import { ResourceOperationIdempotencyKeyRequirement } from '../requests/idempotency-key.shared';
+import type { ResourceOperationSubmissionChallenge } from '../security/submission-challenge/submission-challenge.shared';
+import type { ResourceConfiguration_QueueConfig, ResourceConfiguration_QueueConfigAuthored } from '../queue/queues.shared.schemas';
+import type { ScheduledRecoveryPolicy } from '../queue/jobs.shared.schemas';
 /**
  * Operations Shared Schemas
  *
@@ -5,22 +9,39 @@
  */
 import { z } from 'zod';
 import { EnumLikeType, EnumValues, PrimitiveZodType } from '@wildo-ai/zod-decorators';
-import { ErasureRetentionMode, ResourceDataSubjectKind } from '../compliance/privacy/impersonalization.shared.schemas';
+import { ErasureRetentionMode, ResourceDataSubjectKind, StatutoryRetentionGround } from '../compliance/privacy/impersonalization.shared.schemas';
 import type { DataPortabilityProvenance } from '../compliance/privacy/subject-export.shared.schemas';
+import type { ResourceRetentionBinding } from '../compliance/privacy/retention-schedule.shared.schemas';
+import type { ResourceOperationConsentGateDeclaration } from '../compliance/privacy/consent-gate-vocabulary.shared.schemas';
 import type { HttpApiResourceBinding, HttpApiResourceBindingAuthored } from '../http-api-binding/http-api-binding.shared.schemas';
 import type { ExternalDataPipelineDeclaration, ExternalDataPipelineDeclarationAuthored } from '../external-data/external-data-pipeline.shared.schemas';
 import { HttpMethod } from '../requests/http-requests.shared';
 import { Roles } from '../security/authorizations/roles.shared.schemas';
 import { TokenAuthenticationConfig, TokenGenerationConfig, TokenRevocationConfig } from '../security/authentications/consumable-token.shared.schemas';
-import { ResourceOperation_ServiceRuntimeMode, ResourceOperationVariantType, ResourceOperationRiskLevel, ResourceOperationFrontendSurface, ResourcePrimaryScope, ResourceTranspositionPolicy, ResourceOperation_CustomServiceImplementationMode, ResourceRelationship, ResourceRelationshipAccessScopeStrategy, ManyToManyScopeJunctionMap, type ReferenceConstraints } from './resources.shared.schemas';
+import { ResourceOperation_ServiceRuntimeMode, ResourceOperationVariantType, ResourceOperationRiskLevel, ResourceOperationReversibility, ResourceOperationFrontendSurface, ResourcePrimaryScope, ResourceTranspositionPolicy, ResourceOperation_CustomServiceImplementationMode, ResourceRelationship, ResourceRelationshipAccessScopeStrategy, ManyToManyScopeJunctionMap, type ReferenceConstraints } from './resources.shared.schemas';
 import { NotificationBadgeKey, NotificationBadgeOperation } from '../notifications/notification-badges.schemas';
 import { M2MNotificationDefinition, UserNotificationDefinition } from '../notifications/notifications.shared.schemas';
 import { NotificationBadgeDefinition } from '../notifications/notification-badges.schemas';
 import { CoreResourceOperation, ResourceFieldIdentifier, ResourceType } from './resources.shared.core.definitions';
 import type { OrganizationUnitNarrowingDeclaration } from '../organizations/organization-unit-narrowing.shared';
+import type { ServiceProviderOrganizationWideAccessDeclaration } from '../organizations/organization-unit-narrowing-decision.shared';
 import { LimitCountingConfig } from '../features/feature-definition.shared.schemas';
 import { MainSchemaInfer, SchemaArrayInfer } from './utils/schema-type-inference.utils';
 import type { RateLimitConfiguration } from '../requests/rate-limits.shared.schemas';
+/**
+ * The page ceiling a collection verb has when its operation declares none — ONE number per verb.
+ *
+ * The factory materializes these onto every resolved LIST / SEARCH operation, so the request schema,
+ * the three repository adapters and the response schemas all read the SAME value off the operation.
+ * The literals used to live at seven sites (the schema defaults, the factory's two branches, the
+ * DTO builder's data bound, and each adapter's `_doList` / `_doSearch`) — which held only while every
+ * site happened to be edited together, and did not hold for the MCP collection tool, which built its
+ * input schema with no ceiling at all (#983). The adapters keep a fallback for an operation that
+ * reached them without the materialized field, and that fallback is these constants too.
+ */
+export declare const DEFAULT_LIST_PAGE_CEILING = 100;
+/** SEARCH ceilings are lower on purpose: a search page is scored and ranked, not scanned. */
+export declare const DEFAULT_SEARCH_PAGE_CEILING = 50;
 /**
  * The pagination block a collection RESPONSE echoes back, bounded by the operation's ceiling.
  *
@@ -126,12 +147,18 @@ export declare enum IntrospectionTenancyStance {
      * design system, compliance declarations — and carry no tenant dimension, so there is nothing for
      * a contextual scope predicate to filter on.
      *
-     * This is the only stance implemented, and it is declared rather than inferred for the reason
-     * `HttpApiTenancyStance` gives for its own: an unstated stance is indistinguishable from an
-     * overlooked one. Every other repository enforces scoping ITSELF — Mongo and PostgreSQL through
-     * `buildContextualFilter`, HTTP_API through its tenancy stance — so a read-through adapter that
-     * simply returned whatever its source produced would be the one backing kind with no scoping
-     * story, and nobody would be asked to notice.
+     * This is the only stance implemented, and it is DECLARED rather than inferred, because an
+     * unstated stance is indistinguishable from an overlooked one. Every other repository enforces
+     * scoping ITSELF — Mongo and PostgreSQL through `buildContextualFilter`, HTTP_API by STAMPING
+     * each projected row with the owner organization of the system of record it came from (#1055), so
+     * the ordinary per-row tenant gate decides it. A read-through adapter that simply returned
+     * whatever its source produced would be the one backing kind with no scoping story, and nobody
+     * would be asked to notice.
+     *
+     * (This paragraph cited `HttpApiTenancyStance` as the precedent until #1055 removed it. The
+     * argument it made — declare the stance, do not infer it — is why this enum still exists; what
+     * changed is that HTTP_API stopped needing a stance of its own, because the answer became the
+     * same for every system of record.)
      */
     APPLICATION_STRUCTURE = "application-structure",
     /**
@@ -213,16 +240,16 @@ export interface IntrospectionResourceBinding {
      *
      * The values are joined verbatim, so the key stays READABLE — `workspace__users__createdByUserId`
      * rather than an opaque hash. That is possible because an INTROSPECTION-backed resource resolves
-     * to `ResourceIdFormat.INTROSPECTION_SYNTHESIZED`, which admits a URL-safe charset instead of the
-     * ObjectId-or-UUID rule platform rows follow.
+     * to `ResourceIdFormat.INTROSPECTION_SYNTHESIZED`, which admits a readable charset (URL-unreserved characters
+     * plus the element-ref separators `:` `/` `[` `]`) instead of the ObjectId-or-UUID rule platform rows follow.
      *
      * It was briefly a deterministic UUIDv5, before that format existed. Hashing worked and was the
      * wrong trade: it made every id opaque, and it disguised the real property — a DERIVED id is only
      * as stable as the fields it is derived from, and hiding that behind a hash removes the reader's
      * ability to notice when a row's identity moves.
      *
-     * Each value must be URL-safe (`[a-zA-Z0-9_-]`) and the whole key at most 255 characters; the
-     * source refuses per row rather than emitting a key that lists and cannot be read.
+     * The whole key must satisfy that format (`Resources_SharedUtils.isIntrospectionSynthesizedId`) and be at most
+     * 255 characters; the source refuses per row rather than emitting a key that lists and cannot be read.
      *
      * Omit when the behavior's rows already carry an identifier of their own.
      */
@@ -340,9 +367,9 @@ export declare const DEFAULT_PERSISTENCE_ADAPTER: PersistenceAdapter;
  *
  * The refusal is right as a DEFAULT and wrong as an absolute — some resources provably never
  * participate in such a boundary, and for those the blanket refusal forbids a legitimate,
- * safe deployment (a retrieval corpus whose vector tier only PostgreSQL can serve, say) with
- * no way past it. Per `.claude/rules/design-philosophy.md`, a construct that refuses must ship
- * the door in the same change: this enum IS that door. Declaring a member is a positive claim
+ * safe deployment (a retrieval corpus kept on PostgreSQL in an application whose MongoDB runs no `mongot`, say) with
+ * no way past it. A construct that refuses must ship the door in the same change, or a correct
+ * refusal becomes a permanent lockout: this enum IS that door. Declaring a member is a positive claim
  * about the resource's write topology, made by its author, recorded in the config, and logged
  * at registration — never an ambient tolerance and never a flag that merely silences an error.
  *
@@ -468,6 +495,105 @@ export declare const Resources_Filter_DateRangeSchema: z.ZodObject<{
     startDate: z.ZodOptional<z.ZodDate>;
     endDate: z.ZodOptional<z.ZodDate>;
 }, z.core.$strip>;
+/**
+ * A NUMERIC BOUND PAIR — the number sibling of {@link Resources_Filter_DateRangeSchema}, and the
+ * only way to express "cost under 500" in a collection filter.
+ *
+ * A `z.number()` filter field means EQUALITY, which is almost never the question anyone asks of a
+ * number: a price, a score, an age and a count are all read as thresholds. Until this existed the
+ * framework had a range vocabulary for dates and none for numbers, so a listing could be narrowed
+ * to "created this week" and not to "cheaper than this".
+ *
+ * ## Why it is OPT-IN, where the date range is automatic
+ *
+ * `z.ZodDate` converts to a range unconditionally, because a date EQUALITY filter is meaningless —
+ * nobody filters rows by an exact millisecond. A number equality filter is perfectly meaningful
+ * ("priority 3", "version 2"), so converting every `z.number()` would silently change what every
+ * existing numeric filter in every application means. The author asks for the range by writing
+ * this schema in `filterFields`, and a plain `z.number()` keeps equality.
+ *
+ * ## `min`/`max`, not `from`/`to`
+ *
+ * It matches the date range's habit of naming the bounds after what they BOUND rather than after
+ * their position, and it keeps this vocabulary distinct from `z_range('number')`, which is a
+ * stored FIELD of two values (`from`/`to`) rather than a filter over one.
+ *
+ * Both bounds are optional so an open-ended range ("under 500", with no floor) is expressible; a
+ * value carrying neither is dropped rather than compiled into a degenerate condition.
+ */
+export declare const Resources_Filter_NumberRangeSchema: z.ZodObject<{
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** The two sub-keys of a {@link Resources_Filter_NumberRangeSchema} value, as the wire carries them. */
+export declare const RESOURCES_FILTER_NUMBER_RANGE_SUBKEYS: readonly string[];
+/**
+ * What an author may write for one FILTER FIELD.
+ *
+ * The primitives mean equality (or, for a date, the range the factory converts it into), and
+ * {@link Resources_Filter_NumberRangeSchema} is the one structured shape a caller may send —
+ * deliberately a NAMED addition rather than a widening to "any object", because the collection
+ * controller's filter guard is an allow-list and every shape it admits has to be one somebody
+ * decided to admit.
+ */
+export type ResourceFilterFieldSchema = PrimitiveZodType | typeof Resources_Filter_NumberRangeSchema;
+/** The two sub-keys of a {@link Resources_Filter_DateRangeSchema} value, as the wire carries them. */
+export declare const RESOURCES_FILTER_DATE_RANGE_SUBKEYS: readonly string[];
+/**
+ * Is this the numeric-range filter vocabulary?
+ *
+ * Structural rather than an identity check on the exported schema: an author may legitimately
+ * write `Resources_Filter_NumberRangeSchema.optional()` or attach decorators, both of which
+ * produce a different object. What identifies it is its shape — an object whose keys are exactly
+ * `min` and `max`.
+ */
+export declare function isResourcesFilterNumberRangeSchema(schema: unknown): boolean;
+/**
+ * A boolean filter that asks whether ANOTHER field is set (#1806).
+ *
+ * `hasExpiration` on the API-key and OAuth-client searches was declared as a plain `z.boolean()` and
+ * passed to the database verbatim, where no row has a `hasExpiration` field — so it matched nothing,
+ * with no error to say so. Its meaning was "is `expiresAt` set", and nothing said that anywhere a
+ * machine could read.
+ *
+ * Declare it with the field it asks about:
+ *
+ * ```ts
+ * filterFields: { hasExpiration: createResourcesFilterPresenceSchema('expiresAt') }
+ * ```
+ *
+ * On the wire it is still a plain boolean — the request schema, the published query parameter, MCP and
+ * the filter panel see `z.boolean()` — and {@link translateResourcesPresenceFilters} turns it into a
+ * condition on the target before the filter reaches a repository: `true` → set (`{ $ne: null }`),
+ * `false` → not set (`null`). Those two forms, not `$exists`, because they give the same answer on
+ * both adapters: on MongoDB `$exists: true` also matches a stored `null`, and on PostgreSQL a stored
+ * `null` is `IS NULL`.
+ *
+ * The factory refuses a presence filter whose target is not a field of the resource, exactly as it
+ * refuses a filter key that is not one.
+ *
+ * Call it once per declaration and do not chain onto the result: the target is attached to the exact
+ * object returned, and `.describe()` / `.optional()` return new objects that do not carry it.
+ */
+export declare function createResourcesFilterPresenceSchema(targetField: string): z.ZodBoolean;
+/** The field a presence filter asks about, or `undefined` when `schema` is not a presence filter. */
+export declare function getResourcesFilterPresenceTarget(schema: unknown): string | undefined;
+/** Every field a presence filter in `filterFields` asks about — the keys a translated filter may carry. */
+export declare function resourcesFilterPresenceTargets(filterFields: Record<string, unknown> | undefined): string[];
+/**
+ * Replace each presence filter in `filter` with the condition it stands for (see
+ * {@link createResourcesFilterPresenceSchema}).
+ *
+ * Accepts the boolean and its query-string spelling (`'true'` / `'false'`), because a GET collection
+ * query carries raw strings and the collection controller does not coerce them. Any other value is
+ * DROPPED, which is how the collection filter guard already treats a value it does not admit.
+ *
+ * Idempotent — a translated filter no longer carries the presence key, so running it again changes
+ * nothing — which is what lets both the collection controller and each repository's filter sanitizer
+ * call it. When the target already has a condition, the presence condition joins it under `$and`
+ * rather than replacing it.
+ */
+export declare function translateResourcesPresenceFilters<T extends Record<string, unknown>>(filter: T, filterFields: Record<string, unknown> | undefined): Record<string, unknown>;
 export declare const Resources_Filter_BaseSchema: z.ZodObject<{
     searchRequest: z.ZodOptional<z.ZodString>;
     createdAt: z.ZodOptional<z.ZodObject<{
@@ -522,7 +648,7 @@ export declare const Resources_SearchQueryRequestSchema: z.ZodObject<{
         }, z.core.$strip>>;
     }, z.core.$catchall<z.ZodOptional<z.ZodAny>>>>;
 }, z.core.$strip>;
-export type ResourceSearchQueryRequestResult<TFilterFields extends Record<string, PrimitiveZodType | ((filterRef: PrimitiveZodType) => string)> | undefined, TSortFields extends readonly string[] | undefined> = z.ZodObject<{
+export type ResourceSearchQueryRequestResult<TFilterFields extends Record<string, PrimitiveZodType> | undefined, TSortFields extends readonly string[] | undefined> = z.ZodObject<{
     pagination: z.ZodOptional<typeof Resources_PaginationRequestSchema>;
     sorting: z.ZodOptional<typeof Resources_SortingRequestSchema>;
     filters: z.ZodOptional<typeof Resources_Filter_BaseSchema>;
@@ -588,7 +714,16 @@ export declare enum ResourceCollectionExportFormat {
      * The rows exactly as the listing's response DTO carries them — nested objects, arrays, nulls and
      * types intact. Choose this when the export feeds another system rather than a human.
      */
-    JSON = "json"
+    JSON = "json",
+    /**
+     * A DOCUMENT for a person to read, print or send — the rows rendered through a PDF template the
+     * backend binds by {@link ResourceCollectionExportConfig.pdfTemplateId} (#1645).
+     *
+     * Unlike CSV and JSON it is not a copy of the rows: the template decides what is shown and how, so
+     * a declaration must name one. The template receives exactly the rows the listing returns, under the
+     * same access rules, so it cannot show more than the caller could read.
+     */
+    PDF = "pdf"
 }
 /**
  * WHICH rows a collection export contains.
@@ -613,7 +748,7 @@ export declare enum ResourceCollectionExportRowScope {
     FULL_RESULT_SET = "full_result_set"
 }
 /**
- * Opt a LIST/SEARCH operation into CSV/JSON export of its own result set.
+ * Opt a LIST/SEARCH operation into CSV, JSON or PDF export of its own result set.
  *
  * ## What declaring this does
  *
@@ -645,7 +780,7 @@ export declare enum ResourceCollectionExportRowScope {
 /**
  * What a collection-export route answers with, described for specs and OpenAPI.
  *
- * ⚠️ The BODY is the exported FILE — a CSV or JSON byte stream, not this object. The controller owns
+ * ⚠️ The BODY is the exported FILE — a CSV, JSON or PDF byte stream, not this object. The controller owns
  * the response for this operation family and streams it, so nothing ever serialises this schema.
  * What it documents is the METADATA CONTRACT, which rides in response headers beside the bytes:
  * `Content-Type`, `Content-Disposition` (carrying the filename) and `X-Wildo-Export-Row-Count`.
@@ -665,16 +800,33 @@ export type ResourceCollectionExportConfig = {
     rowScopes: readonly ResourceCollectionExportRowScope[];
     /**
      * Refuse (do not truncate) a `FULL_RESULT_SET` export whose match count exceeds this.
-     * Omit for no ceiling.
+     * Omit for no ceiling — except when a whole-set PDF is offered, which must declare one: a PDF is built
+     * in memory from every row before a byte is sent, where CSV and JSON stream (#1645).
      */
     maximumExportedRows?: number;
+    /**
+     * The PDF template that renders this export — REQUIRED when `formats` includes
+     * {@link ResourceCollectionExportFormat.PDF}, and refused otherwise (#1645).
+     *
+     * An id, not the template: shared configuration never carries backend code. The backend binds the
+     * id to a `PdfCollectionTemplateDefinition` at startup and refuses to boot when an export names a
+     * template nothing binds.
+     */
+    pdfTemplateId?: string;
 };
 export type CollectionViewFields_Shared = {
     pageSize?: number;
-    filterFields?: Record<string, PrimitiveZodType | ((filterRef: PrimitiveZodType) => string)>;
+    /**
+     * The filters a caller may send, by name. Each key must be a field of the resource — or a presence
+     * filter (`createResourcesFilterPresenceSchema`) whose target is one — and the factory refuses
+     * anything else (#1806): these names reach the repository verbatim, so a name that is not a field
+     * matches nothing.
+     */
+    filterFields?: Record<string, ResourceFilterFieldSchema>;
+    /** The fields a caller may sort by. Each must be a field of the resource; the factory refuses any other (#1806). */
     sortFields?: readonly string[];
     /**
-     * Opt this LIST/SEARCH operation into CSV/JSON export — see {@link ResourceCollectionExportConfig}.
+     * Opt this LIST/SEARCH operation into CSV, JSON or PDF export — see {@link ResourceCollectionExportConfig}.
      * It belongs in this bucket because it is read by the BACKEND, like its three neighbours.
      */
     collectionExport?: ResourceCollectionExportConfig;
@@ -829,9 +981,126 @@ export type CollectionViewFields_Search = CollectionViewFields_Shared & {
  * validates away to nothing, and then fails as "`_ids` is required" — which is exactly what every
  * frontend bulk surface did until 2026-08-29.
  */
+/**
+ * How many rows one synchronous bulk request may name, unless the operation declares otherwise.
+ *
+ * A batch documents and ENFORCES its maximum — spec-cite: Google AIP-233 / AIP-234 ("The comment above
+ * the `requests` field should document the maximum number of requests allowed"),
+ * https://google.aip.dev/234 . Before this, `_ids` had a minimum and no maximum, so any client could
+ * name an unbounded list in one synchronous write.
+ *
+ * 100 is the default page ceiling of a listing (`DEFAULT_LIST_PAGE_CEILING`): the largest selection
+ * a person can make from one loaded page. Acting beyond a page is a different mechanism — a filter
+ * evaluated server-side, run in the background (issue #1461) — not a longer id list.
+ */
+export declare const BULK_OPERATION_SELECTOR_FIELD: "_ids";
+/**
+ * The single named source for the MATCH selector's field name — the cross-page sibling of
+ * {@link BULK_OPERATION_SELECTOR_FIELD}, and a selector for the same reason: it names rows, it is
+ * never written.
+ */
+export declare const BULK_OPERATION_MATCH_FIELD: "_match";
+/**
+ * Every request key the COLLECTION fills for a bulk action — the two selectors — and therefore never
+ * a field a person fills in the action's form.
+ *
+ * One list, because the form hides these keys, the presentation ladder does not count them, and the
+ * execution merge writes them. When only `_ids` was hidden, the bulk "Change status" dialog rendered
+ * `_match` as three empty inputs (Match / Filters / Search) and submitted `_match: {}` — an empty
+ * query that replaced the listing the person had selected from (#1461, #2035 run 2026-09-30).
+ */
+export declare const BULK_OPERATION_HOST_SUPPLIED_FIELDS: readonly [typeof BULK_OPERATION_SELECTOR_FIELD, typeof BULK_OPERATION_MATCH_FIELD];
+export declare const BULK_OPERATION_DEFAULT_MAX_SELECTION: 100;
+/**
+ * How many rows a BACKGROUND bulk run may be given, when the operation declares a non-inline runtime.
+ *
+ * The synchronous maximum exists because one request may not hold a client waiting on an unbounded
+ * write; a backgrounded run has no one waiting, so that reason does not apply to it. Capping the two
+ * lanes at the same number made the second lane unreachable — the whole point of "act on all 2,340
+ * matching" is that 2,340 is more than a page, and the controller refused it before the runtime mode
+ * was ever consulted.
+ *
+ * It is still BOUNDED, for a reason the synchronous cap does not have: the resolved ids travel in
+ * the job payload, and a payload is a message. 10,000 ids is roughly 250 KB, which the payload store
+ * already handles by reference — beyond that, the honest answer is not a longer list but a selector
+ * the WORKER re-evaluates as it pages, which is deliberately not built yet (a population read at
+ * enqueue and a population read during the run are different things, and the difference needs
+ * deciding rather than defaulting).
+ */
+export declare const BULK_OPERATION_BACKGROUND_MAX_SELECTION: 10000;
+/** The effective limit for one bulk operation: its declared `bulkOperationMaxSelection`, else the default. */
+export declare function resolveBulkOperationMaxSelection(operation: {
+    bulkOperationMaxSelection?: number;
+}): number;
+/**
+ * The MATCH selector: the rows a listing would return, named by the query that produced them.
+ *
+ * A selection that spans pages is a FILTER, never an id list — the client cannot enumerate a
+ * population it has not loaded, and an id list long enough to hold one would be the unbounded
+ * request the batch maximum exists to refuse. This is what "select all N matching" sends
+ * (spec-cite: N/A — the pattern is Gmail's "select all conversations that match this search"; the
+ * words here are this repository's).
+ *
+ * It is typed LOOSELY on the wire on purpose. Each resource declares its own `filterFields`, so the
+ * only schema that can say what a filter MEANS for this resource is the one its LIST operation was
+ * built with — and that schema lives in the registry, at the server. Embedding it in the bulk twin's
+ * request DTO would copy one contract into another and let the two drift; re-parsing the client's
+ * filter server-side against the LIST's own schema keeps one source, and makes the server the
+ * authority on what was asked for. A filter that does not parse there is refused.
+ *
+ * The population is then scoped exactly as the listing was — the same business filter — so a match
+ * selector can never reach a row its sender could not have listed.
+ */
+export declare const Resources_BulkOperationMatchSelectorSchema: z.ZodObject<{
+    filters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    search: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Resources_BulkOperationMatchSelector = z.infer<typeof Resources_BulkOperationMatchSelectorSchema>;
 export declare const Resources_BulkOperationBaseSchema: z.ZodObject<{
-    _ids: z.ZodArray<z.ZodString>;
+    _ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    _match: z.ZodOptional<z.ZodObject<{
+        filters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        search: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
+/**
+ * The bulk selector schema for a given limit — what an operation declaring its own limit is built with.
+ *
+ * Both members are OPTIONAL here and the schema stays a plain object, deliberately. "Exactly one of
+ * them" is a rule a `.refine` would express perfectly and at the wrong tier: refining returns a
+ * wrapped schema, and `getZodObjectShape` answers `{}` for anything that is not a plain object — so
+ * the whole bulk request's fields would go invisible to field-spec extraction, form building and
+ * every other consumer that reads a DTO by shape. Measured: two DTO-builder pins went red the
+ * moment the selector was refined, both on `.shape` lookups.
+ *
+ * The rule therefore lives at the service chokepoint, in {@link readBulkOperationSelector}, which
+ * is also the only tier MCP, queue and programmatic callers pass through — they never meet a
+ * request DTO at all, so a DTO-tier rule would have covered the narrower population anyway.
+ */
+export declare function buildBulkOperationSelectorSchema(maxSelection: number): typeof Resources_BulkOperationBaseSchema;
+/**
+ * The request a BULK twin accepts, built from its row variant's request and the batch limit — the one
+ * construction both the resource factory and the DTO builder use. They each built it themselves, and
+ * the builder (which runs later and wins) always used the fixed base schema, so a limit a variant
+ * declared was silently replaced by the default.
+ *
+ * - a bulk CREATE takes `{ data: row[] }`, at most `maxSelection` rows;
+ * - every other bulk verb takes the `_ids` selector (at most `maxSelection`) plus the row request's
+ *   own fields. `rowRequestDto` is `undefined` when the row variant takes no input.
+ */
+export declare function wrapRequestDtoAsBulk(params: {
+    rowRequestDto: z.ZodTypeAny | undefined;
+    maxSelection: number;
+    isCreate: boolean;
+}): z.ZodTypeAny;
+/**
+ * The ROW a batch-create request carries — the inverse of {@link wrapRequestDtoAsBulk} for `isCreate`.
+ *
+ * A batch create's request is `{ data: row[] }`, and a repository persists ROWS, so whatever validates
+ * what is written needs the row schema back out of the envelope. Kept beside the construction so the
+ * envelope's shape is known in one place; `undefined` when the DTO is not that envelope.
+ */
+export declare function readBatchCreateRowRequestDto(requestDto: z.ZodTypeAny | undefined): z.ZodTypeAny | undefined;
 /**
  * The single named source for the bulk selector's field name.
  *
@@ -839,7 +1108,6 @@ export declare const Resources_BulkOperationBaseSchema: z.ZodObject<{
  * the generated relationship-bulk selector) reads the name from here, so the two halves of the wire
  * contract cannot drift apart silently.
  */
-export declare const BULK_OPERATION_SELECTOR_FIELD: "_ids";
 /**
  * Read the bulk selector out of a request payload, or `undefined` when it carries none.
  *
@@ -850,6 +1118,27 @@ export declare const BULK_OPERATION_SELECTOR_FIELD: "_ids";
  * than a half-resolved selector reaching persistence.
  */
 export declare function readBulkOperationSelectorIds(payload: unknown): string[] | undefined;
+/**
+ * Read the bulk selector out of a request payload — WHICH selector it carries, and its content.
+ *
+ * `readBulkOperationSelectorIds` answers only the id list, which was the whole vocabulary until the
+ * match selector existed. A caller that must distinguish "named these rows" from "named the query
+ * that finds them" asks here: the two resolve differently (an id list is already a target; a match
+ * has to be evaluated, scoped and capped) and nothing may treat one as the other by accident.
+ *
+ * Tolerant of an unparsed body for the same reason as its sibling: the service tier is reached both
+ * through the HTTP controller, where the request DTO has already validated the shape, and by MCP /
+ * batch / programmatic callers, where it has not. A payload naming BOTH is `undefined` — the
+ * ambiguity is the request DTO's to refuse, and honouring one of them here would make the other
+ * silently inert.
+ */
+export declare function readBulkOperationSelector(payload: unknown): {
+    kind: 'ids';
+    ids: string[];
+} | {
+    kind: 'match';
+    match: Resources_BulkOperationMatchSelector;
+} | undefined;
 /**
  * Strip the bulk selector from a request payload.
  *
@@ -971,7 +1260,7 @@ export type RequiredFeaturesNormalized = RequiredFeaturesFullConfig;
 export type ResourceConfiguration_FunctionWithContextNeeds<TFunction extends (...args: any[]) => any> = TFunction & ResourceConfiguration_FunctionContextNeeds;
 export declare enum ResourceGeneratedOperationKind {
     GENERATED_FILE_REGENERATE = "generated_file_regenerate",
-    /** The CSV/JSON export companion of a LIST/SEARCH operation — see {@link ResourceCollectionExportConfig}. */
+    /** The file-export companion of a LIST/SEARCH operation — see {@link ResourceCollectionExportConfig}. */
     GENERATED_COLLECTION_EXPORT = "generated_collection_export"
 }
 export type ResourceConfiguration_GeneratedFileRegenerateOperationMetadata = {
@@ -1038,7 +1327,19 @@ export type ResourceConfiguration_GeneratedOperationMetadata = ResourceConfigura
 export type ResourceOperation_UnimplementedAcknowledgement = {
     /** Why the operation is declared without an implementation, in the author's own words. */
     reason: string;
-    /** Where the gap is tracked — a plan path, issue id, or equivalent durable reference. */
+    /**
+     * Where the gap is tracked, as an address a STRANGER can resolve.
+     *
+     * This value rides a runtime refusal: `services-registry-handler` throws a `CONFIGURATION` error
+     * carrying it when the operation is called, so it is read by an operator holding a log line and
+     * nothing else. A `.claude/plans/` path is therefore not an acceptable value however precise it
+     * is — that tree is gitignored, so such a reference resolves on the machine that wrote it and
+     * nowhere else. This doc used to offer "a plan path" as the first example and one was duly used,
+     * reaching fourteen tracked files and every operator who hit the refusal.
+     *
+     * A tracker issue URL is the durable form. A commit sha works too; a path into an untracked tree
+     * does not.
+     */
     trackingRef: string;
 };
 /**
@@ -1102,11 +1403,70 @@ export declare enum ResourceOperationRequestContractBreadth {
     OVERBROAD_INHERITED_FULL_CONTRACT = "overbroad_inherited_full_contract"
 }
 /**
- * Where the engine's own inherited implementation gaps are tracked — the 2026-08-01 catalogue
- * sweep that found 41 routed operations answering a success status having performed nothing.
- * One authority so the backlog cannot fragment across 37 hand-typed strings.
- */
-export declare const UNIMPLEMENTED_ENGINE_OPERATION_BACKLOG_REF = ".claude/plans/routed-unimplemented-operations-fail-closed.md";
+ * Whether an AUTHORED request contract re-admits a field its resource schema SEALED, without
+ * naming who owns that field's value.
+ *
+ * The third verdict in this family, and the one whose two members are easiest to conflate: a sealed
+ * field appearing in an authored contract is not by itself a defect. It is a defect when NOBODY
+ * owns it.
+ *
+ * ## What "sealed" means, and why authoring a contract silently unseals it
+ *
+ * `.excludeFromCreate()` / `.excludeFromUpdate()` say what NOBODY may send. The DTO builder honours
+ * them by OMITTING the field — `applyCreateOmissionsToSchema` and its update twin — but that pass
+ * runs only for a SYNTHESIZED contract. An operation that authors a `requestDto` has it "preserved
+ * verbatim, never rebuilt", so the omission pass never runs and every sealed field the authored
+ * contract happens to name is back in the validated write.
+ *
+ * The two authorities are different and the precedence silently inverted: an author supplying a
+ * narrow contract states what a caller MAY send, while a field-level seal states what NOBODY may.
+ *
+ * On CREATE the omission IS the entire protection — a client that sends a sealed field gets a
+ * success and the value goes nowhere, deliberately, and there is no runtime guard behind it. So an
+ * authored CREATE contract that re-admits a sealed field removes the only thing standing there.
+ *
+ * ## Why the answer is an OWNER rather than a subtraction (#109)
+ *
+ * Subtracting the seal from an authored contract — running the omission pass ON TOP of it — was
+ * measured over the whole catalogue and refused, because what it removes depends on how the
+ * contract was SPELLED rather than on the seal:
+ *
+ *  - the access-grant decision verbs re-declare `decisionReason` as a fresh, UNDECORATED
+ *    `z.string().max(1000).optional()`, so a decorator-aware subtraction would not touch it, while
+ *    `consumableTokens | create` authors `MainSchema.omit({…})` and carries the decorated field, so
+ *    it would. Identical situations, opposite outcomes, decided by authoring style;
+ *  - the pass ALSO omits a hardcoded NAME list, and that half does bite: it would strip the audit
+ *    export's `createdAt` date-range filter, a different type meaning a different thing that merely
+ *    shares a name with the sealed timestamp — an unbounded export, silently.
+ *
+ * So subtraction enforces the seal unpredictably and breaks a legitimate contract while doing it.
+ *
+ * What distinguishes the legitimate cases is not the field; it is that something already answers
+ * "who decides this value". Two answers exist in the model already, and both are what makes those
+ * cases safe today:
+ *
+ *  - the operation declares the field in `authoritativeFields` AND has a prefix hook that can own
+ *    it. The hook decides the value, and may legitimately derive it from the caller's input — the
+ *    access-grant verbs echo `decisionReason`, and should, because the tenant's stated reason is the
+ *    tenant's words. What the declaration buys is not an overwrite; it is a NAMED OWNER that
+ *    decided, in place of a field nobody claimed. The hook is required rather than assumed: an
+ *    unbacked declaration preserves the CALLER's value and additionally silences the read-only
+ *    runtime refusal, which would make the remediation a bypass;
+ *  - the operation SINGLE-OWNS its execution (`OVERRIDE_ALL` / `REPLACE_CORE_OPERARTIONS`) — the
+ *    generic core write never runs, so a decorator about the generic create/update contract has no
+ *    write to bar.
+ *
+ * Neither is new surface. What is new is that silence is no longer an answer.
+ *
+ * assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — a field the schema seals against every caller must
+ * not become writable merely because an operation described its own request body.
+ */
+export declare enum ResourceOperationSealedRequestFieldAdmission {
+    /** No sealed field is re-admitted, or every re-admitted one names an owner. */
+    SEALED_FIELDS_OWNED = "sealed_fields_owned",
+    /** The authored contract re-admits a sealed field that nothing claims. */
+    UNOWNED_SEALED_FIELD_READMITTED = "unowned_sealed_field_readmitted"
+}
 /**
  * Acknowledge an engine operation as a known, fail-closed implementation gap.
  *
@@ -1114,22 +1474,30 @@ export declare const UNIMPLEMENTED_ENGINE_OPERATION_BACKLOG_REF = ".claude/plans
  * that adds nothing is a reason not worth reading during triage. State what the operation was
  * meant to do, so whoever picks it up knows the target behaviour without re-deriving it.
  *
- * @see ResourceOperation_UnimplementedAcknowledgement for the two effects this has.
+ * And requires the gap's OWN `trackingRef`, which used to be a module constant
+ * (`UNIMPLEMENTED_ENGINE_OPERATION_BACKLOG_REF`) naming one shared backlog document — a path under
+ * `.claude/plans/`, which is gitignored. One global address for every gap is what made a
+ * machine-local one look reasonable: nobody chooses a bad address per gap, they inherit the one
+ * that is already there. The field always varied in principle — this factory's own tests pass
+ * literals — so parameterising it costs one argument and removes the shared default that rotted.
+ *
+ * @see ResourceOperation_UnimplementedAcknowledgement for the two effects this has, and for why the
+ * ref must be resolvable by a stranger.
  */
-export declare const acknowledgeUnimplementedEngineOperation: (reason: string) => ResourceOperation_UnimplementedAcknowledgement;
+export declare const acknowledgeUnimplementedEngineOperation: (reason: string, trackingRef: string) => ResourceOperation_UnimplementedAcknowledgement;
 /**
  * @wildo_source:part:start saas.models.resource-config.operation-auditable-event facet:layer:shared facet:audience:app-developer
  *
  * Declarative control over this variant's audit emission.
  *
- * **The baseline needs no declaration.** Every `HIGH` / `CRITICAL` variant emits
+ * **The baseline needs no declaration.** Every framework-managed write-shaped `HIGH` / `CRITICAL` variant emits
  * `RESOURCE_OPERATION_PERFORMED` automatically — `riskLevel` is already the framework's canonical
  * danger axis (it drives MCP destructive hints, frontend danger-zone placement and CRITICAL typed
  * confirmation), and a risk-driven floor is fail-closed by omission. A declarative-ONLY mechanism
  * was rejected for exactly that reason: it fails OPEN when an author forgets, which is how 20 event
  * types came to be declared in `CoreAuditableEventType` and wired to nothing.
  *
- * This declaration exists for the two cases the floor cannot express on its own.
+ * This declaration selects below-floor writes and explicit operator justification evidence.
  */
 export type ResourceOperation_AuditableEvent = {
     /**
@@ -1140,6 +1508,16 @@ export type ResourceOperation_AuditableEvent = {
      * question to "is this evidence an auditor needs".
      */
     auditBelowRiskFloor?: boolean;
+    /**
+     * Top-level request string carrying the operator's justification, e.g. `reasonField: 'reason'`.
+     * Captured before custom input transformations and recorded as `eventData.reason` after commit.
+     * This explicitly authorizes retaining that text in audit destinations; do not select a secret
+     * or an unrestricted business-data field. Bound the text in the request DTO and tell callers
+     * to supply an operational justification. Other request values are never copied by this option.
+     * This does not change the risk floor: below-floor writes still need `auditBelowRiskFloor`.
+     * OVERRIDE_ALL implementations own their persistence and must emit their committed audit event.
+     */
+    reasonField?: string;
 };
 /** @wildo_source:part:end saas.models.resource-config.operation-auditable-event */
 type ResourceConfiguration_OperationVariant_Base<TMainSchema extends z.ZodTypeAny = z.ZodAny> = {
@@ -1155,6 +1533,21 @@ type ResourceConfiguration_OperationVariant_Base<TMainSchema extends z.ZodTypeAn
     isDefault?: boolean;
     variantKey?: string;
     riskLevel: ResourceOperationRiskLevel;
+    /**
+     * Whether a later operation can undo this one — see {@link ResourceOperationReversibility}.
+     *
+     * OMIT IT unless the verb's name does not carry the answer. The default is derived by
+     * {@link resolveOperationReversibility}: DELETE-like is irreversible, everything else reversible.
+     * Declare it only to correct that derivation — a custom verb that destroys something
+     * (`ROTATE` replaces a secret, `PURGE_ALL` empties a queue, `RESET_FEATURES` clears a ledger), or,
+     * rarely, a DELETE-like verb that is genuinely recoverable because it only marks a row and a
+     * `RESTORE` exists to bring it back.
+     *
+     * This is the axis the DANGER ZONE is filtered on. It is deliberately NOT `riskLevel`: risk says
+     * how much an act matters, reversibility says whether you can take it back, and a section headed
+     * "Danger Zone" is a promise about the second.
+     */
+    reversibility?: ResourceOperationReversibility;
     /**
      * @wildo_source:part:start saas.models.resource-config.operation-variant-client-timeout facet:layer:shared facet:family:resource-config
      *
@@ -1269,6 +1662,11 @@ type ResourceConfiguration_OperationVariant_Base<TMainSchema extends z.ZodTypeAn
      *   two role tables, and membership `roles` is free-form (`OrgRolesSchema` admits any string), so
      *   without the scope qualifier a tenant admin could type their way into cross-tenant reach.
      * - The variant must declare this flag. Absent, behaviour is unchanged and the caller is denied.
+     * - The caller must hold a usable platform-access grant for the target organization. Platform
+     *   authority and this flag alone do not authorize ordinary cross-tenant operations.
+     *   The REQUEST_ACCESS operation is the bootstrap exception: it asks for the grant and therefore
+     *   cannot require one first. An ownerless-tenant recovery may auto-approve that request; recovery
+     *   operations still require the resulting usable grant.
      *
      * Declare it only on operations whose PURPOSE is cross-tenant administration, and expect each one
      * to justify itself: this is the seam a reviewer should look at first.
@@ -1316,6 +1714,53 @@ type ResourceConfiguration_OperationVariant_Base<TMainSchema extends z.ZodTypeAn
      * is authorized by the caller's ROLE, never by caller and subject being the same person.
      */
     admitsCrossSubjectUserAdministration?: boolean;
+    /**
+     * Admits this variant to perform a COLLECTION-shaped write on a scope-ROOT resource that the
+     * caller's own execution context confines — the ANONYMOUS-scope sibling of
+     * {@link admitsCrossTenantPlatformAdministration} and {@link admitsCrossSubjectUserAdministration},
+     * following the same doctrine: per-variant, empty by default, enumerable by grep.
+     *
+     * ## Why it is needed
+     *
+     * A collection-shaped operation on a scope root is classified by
+     * `isUnconfinedScopeRootDirectoryRead` as an unconfined DIRECTORY write, and
+     * `enforceApplicationWideReadAdmission` then demands a two-person application access grant. That
+     * classification is right for the population it was written for — `SCOPE_ROOT_CONFINED_OPERATIONS`
+     * deliberately includes `UPDATE_MANY` so that "a set-shaped write on the tenant resource" cannot
+     * appear unconfined — and it is right because the gate reads the DECLARED shape and can know
+     * nothing about the row a custom implementation will actually select.
+     *
+     * But a collection shape is also the only shape in which a request CANNOT NAME A ROW, which is
+     * exactly what an anonymous self-write wants: `ANONYMOUS_USERS.record_consent` carries no entity id
+     * precisely so a visitor cannot address another visitor's session, and its implementation selects
+     * `{ uuidRef }` from the verified session JWT. Without this flag that operation answers 403 to the
+     * only caller it exists for (#1267).
+     *
+     * ## Why the confinement authority was NOT extended instead
+     *
+     * `assignScopeRootCollectionConfinementToFilter` states on its own disposition enum that
+     * `USER_SELF` / `ANONYMOUS` instances come from `initiatorIds`, *"which the request supplies about
+     * ITSELF and which therefore cannot be an authority set"*. Teaching it to confine by
+     * `anonymousUserId` would reverse that measured decision for every scope-root operation at once.
+     * This flag changes nothing there: the tenant derivation, its disposition vocabulary and every
+     * other operation are untouched.
+     *
+     * ## What the declaring operation owes
+     *
+     * The flag says "this write is confined by something the gate cannot see". The operation must
+     * therefore CONFINE IT — from the execution context, never from the request — and say where. A
+     * variant that declares this and then writes an unfiltered set has made the declaration a lie, and
+     * the gate will not catch it. Declare it only where the operation's PURPOSE is a principal acting
+     * on its own single row, and expect each one to justify itself: this is a seam a reviewer should
+     * look at first.
+     *
+     * It relaxes only the DIRECTORY classification. The operation's `roles` gate, the parent-scope
+     * check and the repository's own filters all run unchanged.
+     *
+     * assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — a collection-shaped write is admitted without a
+     * platform elevation only where the acting principal is confined to its own row by construction.
+     */
+    admitsSelfConfinedScopeRootWrite?: boolean;
     /** @wildo_source:part:end saas.models.resource-config.operation-scope-admissions */
     /**
      * @wildo_source:part:start saas.models.resource-config.operation-step-up facet:layer:shared facet:audience:app-developer
@@ -1353,24 +1798,24 @@ type ResourceConfiguration_OperationVariant_Base<TMainSchema extends z.ZodTypeAn
      * (a code or a backup code, through the same anti-replay authority login uses) and `PASSKEY` (a
      * WebAuthn assertion produced under {@link PasskeyAuthenticationCeremony.STEP_UP}, which pins user
      * verification to REQUIRED and uses a challenge key a login assertion cannot redeem). A principal
-     * satisfies this gate if they hold ANY of the three.
+     * satisfies this gate only by proving an enrolled factor accepted by the effective policy.
+     * Holding a credential alone does not mean its method is currently permitted.
      *
-     * That was not always true, and the earlier text here is worth knowing because it inverted the
-     * advice: until TOTP and passkey re-auth landed, this said the gate was PASSWORD-only and told
-     * authors not to declare the flag on operations SSO-only, passkey-only or directory-managed users
-     * perform. Both populations can satisfy it now.
+     * A person who signs in through SSO can use an accepted local factor; a genuinely SSO-only
+     * account without one cannot satisfy this gate with its upstream SSO session. Passkey-only
+     * accounts can satisfy it when their passkey remains accepted by the effective policy.
      *
      *  - **directory-managed (SCIM) users** in particular. The framework deliberately destroys their
      *    `passwordHash` AND passkeys as a compliance control
      *    (`_reconcileLocalCredentialsForDirectoryManaged` — a local first factor would survive IdP
      *    deprovisioning) and deliberately PRESERVES their TOTP, which sits on top of the IdP first
      *    factor. TOTP re-auth is what makes that preserved factor usable, and it is why an ORG_ADMIN
-     *    of a directory-managed tenant can now start a teardown they were once locked out of.
+     *    of a directory-managed tenant can start a teardown when enrolled TOTP is accepted by policy.
      *
      * A principal holding NONE of the three still cannot satisfy the gate, and is still refused
-     * fail-closed with a diagnosable message. Check the user type's `authMethodsEnabled` — and any
-     * per-ORGANIZATION override of it, since an app-level policy is not the whole answer — before
-     * declaring this flag on an operation that population must perform.
+     * fail-closed with a diagnosable message. Check the effective `stepUpAuth` policy, including
+     * organization overrides and its accepted `methods` when enabled, before declaring this flag
+     * on an operation that population must perform. Login-method availability is a separate decision.
      *
      * This is also why the requirement is a per-operation flag rather than a hardcoded `password`
      * field in a request DTO: the proof is negotiated by the auth policy, not frozen into the resource
@@ -1385,6 +1830,97 @@ type ResourceConfiguration_OperationVariant_Base<TMainSchema extends z.ZodTypeAn
      */
     requiresStepUpAuthentication?: boolean;
     /** @wildo_source:part:end saas.models.resource-config.operation-step-up */
+    /**
+     * @wildo_source:part:start saas.models.resource-config.operation-idempotency-key facet:layer:shared facet:audience:app-developer
+     *
+     * Whether this variant takes the `Idempotency-Key` request header, so a caller's retry receives the first request's
+     * outcome instead of running the effect again.
+     *
+     * Declare it on a mutation whose effect happens OUTSIDE your database — a payment provider, an email, a third-party
+     * write — where a retry after a lost response is the duplicate you cannot roll back. A pure database write already
+     * gets optimistic locking from `If-Match`; this is for what a transaction cannot undo.
+     *
+     * - `ACCEPTED`: the header is honored when sent, and a request without it runs unkeyed. Right for an effect that
+     *   converges when repeated (cancelling something twice leaves it cancelled).
+     * - `REQUIRED`: a request without the header is refused with 400 (`idempotency_key_required`). Right for an effect
+     *   whose repeat is a second, different effect (adding an item twice adds two).
+     *
+     * What the framework does for you: parses and bounds the header (a quoted String or a bare token of 1 to 200 printable
+     * ASCII characters, otherwise 400 `idempotency_key_malformed`); refuses the header on a MUTATION that does not declare
+     * this (400 `idempotency_key_not_accepted` — ignoring it would silently leave the caller's retry undeduplicated), while a
+     * read ignores it; documents the header in the OpenAPI reference; makes the framework's own HTTP client send one key per
+     * call and reuse it on its automatic retries; and hands the key to your implementation as `utils.requestIdempotencyKey`,
+     * removing it from the options so that forwarding `utils.serviceOptions` to another operation never passes your caller's
+     * key along.
+     *
+     * Honored on the `INLINE` runtime mode only: a key sent to a queued or background variant is refused, because those
+     * paths cannot carry it to the implementation.
+     *
+     * Mutations only: a read-shaped variant (a read, list, search or count, or a custom operation borrowing one of those
+     * verbs) that declares it stops the application from starting. A read-shaped variant claims that repeating it changes
+     * nothing, so the key would protect no retry and `REQUIRED` would only refuse harmless repeats. A custom operation whose
+     * effect must not run twice is not a read: borrow a mutation verb in `resourceOperationLike` and declare the key there.
+     *
+     * What it does NOT do: remember outcomes. Deciding that a key was seen, replaying its result and refusing the same key
+     * sent with a different request (422, `ErrorCustomMessageReference.IDEMPOTENCY_KEY_REUSED`) is the implementation's
+     * job, because only it knows what "the same request" and "its result" mean for its effect.
+     *
+     * @example a provider-backed mutation that must not run twice
+     * variants: [{
+     *   variantType: ResourceOperationVariantType.API_CALL,
+     *   roles: [CORE_ORG_ROLES.ORG_OWNER],
+     *   riskLevel: ResourceOperationRiskLevel.HIGH,
+     *   idempotencyKey: ResourceOperationIdempotencyKeyRequirement.REQUIRED,
+     *   requestDto: AddSeatRequest_Schema,
+     * }]
+     */
+    idempotencyKey?: ResourceOperationIdempotencyKeyRequirement;
+    /** @wildo_source:part:end saas.models.resource-config.operation-idempotency-key */
+    /**
+     * @wildo_source:part:start saas.models.resource-config.operation-submission-challenge facet:layer:shared facet:audience:app-developer
+     *
+     * Whether a caller who is NOT signed in must answer a submission challenge — a captcha vendor's token or the
+     * framework's proof of work — for this variant to run (#1985).
+     *
+     * Declare it on a public operation a script could flood: a contact form, a waitlist, a quote request. `action` names
+     * the form, in your own vocabulary (letters, digits, `_` and `/`); a vendor token is minted for that action and one
+     * minted for another is refused, so give each form its own. The framework's own contact form declares
+     * `SubmissionChallengeAction.INBOUND_CONTACT`.
+     *
+     * When it applies: only when the application declares a captcha provider (Google reCAPTCHA is `recaptcha`), and only
+     * to a caller who proved no identity (an anonymous-session or public request). A signed-in person, a machine credential
+     * and the application's own internal calls are not asked: a challenge tells a person from a script, and those callers
+     * already proved who they are. An application without a captcha provider asks nobody.
+     *
+     * What the framework does for you: checks the `x-submission-challenge-response` header before anything else in the
+     * operation runs — before your prefix hooks, before any read — and refuses with 400 and `error.code`
+     * `SUBMISSION_CHALLENGE_REQUIRED` (no answer) or `SUBMISSION_CHALLENGE_REFUSED` (an answer it did not accept); a
+     * submission it cannot check, because no verifier is bound, is refused too. It counts each refusal by reason, records
+     * each vendor verification, and documents the header and both refusals in the OpenAPI reference. Your implementation
+     * does nothing: do not call the challenge service from a prefix hook.
+     *
+     * Who sends the answer: a website form — the framework's `InboundContactForm`, or your own form calling
+     * `obtainSubmissionChallengeAnswer` from `@wildo-ai/saas-website` with this action. The application's own frontend
+     * client sends none, so do not declare it on an anonymous operation your application's screens call: every such call
+     * would be refused once a captcha provider is declared.
+     *
+     * Constraints, each refused when the resource configuration is built or when the application starts: a variant reached
+     * by an HTTP request (`API_CALL` or `API_CALL_WITH_CALLBACK`; no other variant receives a request header), an action
+     * matching the vendor's grammar, and the `INLINE` runtime mode (a queued or background execution re-enters without
+     * the header).
+     *
+     * @example a public waitlist signup, protected like the contact form
+     * variants: [{
+     *   variantType: ResourceOperationVariantType.API_CALL,
+     *   isDefault: true,
+     *   roles: [CORE_APP_ROLES.APP_ANONYMOUS],
+     *   riskLevel: ResourceOperationRiskLevel.LOW,
+     *   rateLimit: { requestsPerMinute: 5, requestsPerHour: 30 },
+     *   submissionChallenge: { action: WaitlistChallengeAction.JOIN },
+     * }]
+     */
+    submissionChallenge?: ResourceOperationSubmissionChallenge;
+    /** @wildo_source:part:end saas.models.resource-config.operation-submission-challenge */
     /**
      * Default **frontend surface** for this operation when no app preset declares
      * one (see {@link ResourceOperationFrontendSurface}). Lets the framework mark
@@ -1405,10 +1941,11 @@ type ResourceConfiguration_OperationVariant_Base<TMainSchema extends z.ZodTypeAn
      * — this is a field on an operation variant inside a resource's `operations` config.
      *
      * Opt-in + FAIL-CLOSED: absent or `false` ⇒ the operation is NOT a tool. Only DEFAULT,
-     * non-bulk, URL-bearing operations (the standard `API_CALL` create / read / list / search /
-     * count / update / delete and URL-bearing custom ops) of ORGANIZATION- or APPLICATION-scoped
-     * resources are eligible. A machine principal cannot reach USER_SELF resources, so setting
-     * `exposed` on a USER_SELF operation has no machine-callable effect.
+     * non-bulk, URL-bearing API_CALL or API_CALL_WITH_CALLBACK operations are eligible.
+     * Machine principals reach ORGANIZATIONS / APPLICATION resources; user-delegated principals
+     * additionally reach USER_SELF. The verified principal selects the discovery scope set;
+     * anonymous discovery has no reachable tools. A USER_SELF opt-in therefore has no machine-callable
+     * effect but can be listed for a delegated user, subject to the remaining eligibility gates.
      *
      * `description` is the agent-facing tool description — the prose the calling agent reads to
      * decide when to use the tool. When omitted, the tool description falls back to the resource
@@ -1456,6 +1993,13 @@ type ResourceConfiguration_OperationVariant_Base<TMainSchema extends z.ZodTypeAn
      * only the fields the verb changes is therefore both sufficient and safer than spreading the
      * current object — a spread makes every field a server-injected key, which re-writes
      * `.excludeFromUpdate()` fields such as an owning foreign key on every call.
+     *
+     * **To CLEAR a field, return it as `null` — never `undefined`.** The write is a merge patch: an
+     * absent or `undefined` key means "leave the stored value", and only `null` means "no value"
+     * (persisted as removal for an `.optional()` field). `{ assignedToUserId: undefined }` answers 200
+     * and changes nothing — Wonder Todos' "unassign" and "set as one-time" verbs shipped that way.
+     * `undefined` is deliberately NOT read as a clear: a patch like `{ title: inputDto.title }` would
+     * then erase the stored title whenever the caller omitted it.
      */
     basicPrefixOperation?: ResourceConfiguration_FunctionWithContextNeeds<(params: ResourceConfiguration_OperationVariant_CustomImplementation_FunctionParameters<TMainSchema>) => Partial<MainSchemaInfer<TMainSchema>>>;
     /**
@@ -1470,9 +2014,24 @@ type ResourceConfiguration_OperationVariant_Base<TMainSchema extends z.ZodTypeAn
      * operation answers success having written nothing.
      *
      * Declaring the field makes the ownership explicit: it is always preserved, always with the
-     * POST-hook value, so a caller-supplied value is overwritten rather than honored. This does NOT
-     * make the field client-writable — reachability stays governed by {@link requestDto} and the
-     * schema decorators.
+     * POST-hook value — so the HOOK decides it, in place of a field nobody claimed.
+     *
+     * ⚠️ **That is not the same as overwriting the caller** (corrected 2026-09-10, #109). A hook may
+     * legitimately DERIVE the post-hook value from the caller's input, and the engine's own
+     * access-grant decision verbs do exactly that: they return `input.decisionReason` unchanged,
+     * because the tenant's stated reason for a decision is the tenant's words. What the declaration
+     * buys is an accountable owner, not a guaranteed replacement — read it that way when reasoning
+     * about what a caller can reach.
+     *
+     * ⚠️ **And declaring a field has a COST on the update side.** `preserveServerInjectedFields` is
+     * also what `assertNoForbiddenReadOnlyFieldChange` skips, so declaring an `.excludeFromUpdate()`
+     * field turns that guard's loud `4xx` into silence. With a hook that is right (the hook owns the
+     * value); with NO hook the preserved value is the caller's own, which makes the field
+     * client-writable and removes the refusal — so a declaration without a hook is a bypass, and
+     * `collectUnownedSealedRequestFieldReadmissionIssues` refuses to accept one as an owner.
+     *
+     * Declaring does NOT by itself make the field client-writable — reachability stays governed by
+     * {@link requestDto} and the schema decorators.
      *
      * Any hook that forces a server-owned lifecycle value (a `status` transition, an ownership
      * stamp) should declare it. A hook that only derives a value from other authored input does not
@@ -1493,6 +2052,13 @@ type ResourceConfiguration_OperationVariant_ApiCall_BuilderParameters<TMainSchem
     variantType: ResourceOperationVariantType.API_CALL;
     isDefault?: boolean;
     haveBulkOperation?: boolean;
+    /**
+     * How many rows one request of this operation's BULK twin may name. Omitted means
+     * `BULK_OPERATION_DEFAULT_MAX_SELECTION` (100). Enforced by the bulk request schema and shown by
+     * the collection bar before anyone clicks. Declare it only when the write genuinely cannot take a
+     * page of rows at once (a heavy per-row side effect) — to act on more, see issue #1461.
+     */
+    bulkOperationMaxSelection?: number;
     isApiKeyAccessDisabled?: boolean;
     /** Declares which consumable token types this operation accepts for authentication */
     tokenAuthentication?: TokenAuthenticationConfig;
@@ -1550,6 +2116,13 @@ type ResourceConfiguration_OperationVariant_ApiCallWithCallback_BuilderParameter
     variantType: ResourceOperationVariantType.API_CALL_WITH_CALLBACK;
     isDefault?: boolean;
     haveBulkOperation?: boolean;
+    /**
+     * How many rows one request of this operation's BULK twin may name. Omitted means
+     * `BULK_OPERATION_DEFAULT_MAX_SELECTION` (100). Enforced by the bulk request schema and shown by
+     * the collection bar before anyone clicks. Declare it only when the write genuinely cannot take a
+     * page of rows at once (a heavy per-row side effect) — to act on more, see issue #1461.
+     */
+    bulkOperationMaxSelection?: number;
     isApiKeyAccessDisabled?: boolean;
     /** Declares which consumable token types this operation accepts for authentication */
     tokenAuthentication?: TokenAuthenticationConfig;
@@ -1589,13 +2162,15 @@ type ResourceConfiguration_OperationVariant_ApiCallWithCallback_BuilderParameter
  * signed tick back onto your application's queue. Four consequences follow, and none of them is
  * visible from this type:
  *
- * **The expression is always interpreted in UTC.** There is no timezone field here and no
- * application-level setting for one — the sync sends `UTC` for every job. `'0 3 * * *'` is 03:00 UTC
- * wherever your users are, so a job meant to run outside a business day has to be written in UTC.
+ * **This declaration is interpreted in UTC.** There is no timezone field here: automatic resource
+ * schedule extraction sends `UTC`. `'0 3 * * *'` is 03:00 UTC wherever your users are. The lower-level
+ * authenticated jobs-sync API supports an explicit timezone; that does not give this declaration
+ * local-time or daylight-saving behavior.
  *
- * **A change takes effect on the next BOOT, not at runtime.** Schedules move only through the startup
- * sync, so retiming or withdrawing a job means editing the declaration and restarting the
- * application. Nothing can ask the scheduler for a different schedule while the application is up.
+ * **Editing this declaration takes effect through startup synchronization.** There is no file watch
+ * that retimes a running application's jobs when its source changes. The lower-level synchronization
+ * API can update jobs while the application is running; its full replacement contract is distinct
+ * from this declaration-driven startup path. Keep one owner for the complete submitted schedule set.
  *
  * **A failed sync does not fail startup.** The application boots, one capped in-process retry is kept
  * pending, and until it succeeds the scheduler keeps running the schedule it was last given. So a
@@ -1608,6 +2183,8 @@ type ResourceConfiguration_OperationVariant_ApiCallWithCallback_BuilderParameter
  * the platform's execution record.
  */
 type ResourceConfiguration_OperationVariant_CronJob_BuilderParameters = ResourceConfiguration_OperationVariant_Base & {
+    /** Recovery contract for this exact scheduled handler; undeclared effects require manual review after an unknown outcome. */
+    scheduledRecovery?: Partial<ScheduledRecoveryPolicy>;
     variantType: ResourceOperationVariantType.CRON_JOB;
     /** Standard five-field cron expression, interpreted in UTC. See the note above this type. */
     cronExpression: string;
@@ -1626,6 +2203,7 @@ type ResourceConfiguration_OperationVariant_CronJob_BuilderParameters = Resource
 };
 /** @wildo_source:part:end saas.models.resource-config.operation-cron-job */
 type ResourceConfiguration_OperationVariant_BatchJob_BuilderParameters = ResourceConfiguration_OperationVariant_Base & {
+    scheduledRecovery?: Partial<ScheduledRecoveryPolicy>;
     variantType: ResourceOperationVariantType.BATCH_JOB;
 };
 type ResourceConfiguration_OperationVariant_InternalCall_BuilderParameters = ResourceConfiguration_OperationVariant_Base & {
@@ -1654,6 +2232,8 @@ export type ResourceConfiguration_Operation_Base<TCustomOperationEnum extends En
     operationIdentifier: TCustomOperationEnum | TCoreOperationEnum;
     isOperationDefault: boolean;
     serviceRuntimeMode: ResourceOperation_ServiceRuntimeMode;
+    /** Validated operation policy, shared by authored and generated variants. */
+    queueConfig?: ResourceConfiguration_QueueConfig;
     generatedOperation?: ResourceConfiguration_GeneratedOperationMetadata;
     requestDto?: z.ZodSchema<any>;
     responseDto?: z.ZodSchema<any>;
@@ -1712,6 +2292,12 @@ export type ResourceConfiguration_Operation_Base<TCustomOperationEnum extends En
     m2mNotifications: M2MNotificationDefinitionWithoutIdentifier[];
     /** Authored metered-usage recording for this operation; `undefined` when it consumes nothing. */
     recordsUsage?: MeteredUsageRecordingDefinition;
+    /**
+     * The purpose this operation's own processing rests on, and what a missing grant costs (#1258
+     * Step 3). `undefined` means this operation declares nothing beyond whatever
+     * `serviceConsentRequirement` already requires application-wide.
+     */
+    consentGate?: ResourceOperationConsentGateDeclaration;
 };
 /** @wildo_source:part:end saas.models.resource-config.operation-base */
 /**
@@ -1722,10 +2308,12 @@ export type ResourceConfiguration_Operation_Base<TCustomOperationEnum extends En
 export type ResourceConfiguration_Operation_BaseType<TCustomOperationEnum extends EnumLikeType | undefined, TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined, TMainSchema extends z.ZodTypeAny = z.ZodAny> = ResourceConfiguration_Operation_Base<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>;
 export type ResourceConfiguration_Operation_CronJob<TCustomOperationEnum extends EnumLikeType | undefined, TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined, TMainSchema extends z.ZodTypeAny = z.ZodAny> = ResourceConfiguration_Operation_Base<TCustomOperationEnum, TCoreOperationEnum, TMainSchema> & {
     variantType: ResourceOperationVariantType.CRON_JOB;
+    scheduledRecovery?: ScheduledRecoveryPolicy;
     cronExpression: string;
 };
 export type ResourceConfiguration_Operation_BatchJob<TCustomOperationEnum extends EnumLikeType | undefined, TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined, TMainSchema extends z.ZodTypeAny = z.ZodAny> = ResourceConfiguration_Operation_Base<TCustomOperationEnum, TCoreOperationEnum, TMainSchema> & {
     variantType: ResourceOperationVariantType.BATCH_JOB;
+    scheduledRecovery?: ScheduledRecoveryPolicy;
 };
 export type ResourceConfiguration_Operation_InternalCall<TCustomOperationEnum extends EnumLikeType | undefined, TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined, TMainSchema extends z.ZodTypeAny = z.ZodAny> = ResourceConfiguration_Operation_Base<TCustomOperationEnum, TCoreOperationEnum, TMainSchema> & {
     variantType: ResourceOperationVariantType.INTERNAL_CALL;
@@ -1772,6 +2360,8 @@ export type ResourceConfiguration_Operation_ApiCall<TCustomOperationEnum extends
     httpVerb: HttpMethod;
     isApiKeyAccessDisabled: boolean;
     isBulkOperation: boolean;
+    /** On a bulk twin: the resolved limit on rows per request (`resolveBulkOperationMaxSelection`). */
+    bulkOperationMaxSelection?: number;
     initiatorInfos?: ResourceConfiguration_Operation_UrlInitiatorInfo[];
     tokenAuthentication?: TokenAuthenticationConfig;
     tokenGeneration?: TokenGenerationConfig;
@@ -1818,6 +2408,8 @@ export type ResourceConfiguration_Operation_ApiCallWithCallback<TCustomOperation
     httpVerb: HttpMethod;
     isApiKeyAccessDisabled: boolean;
     isBulkOperation: boolean;
+    /** On a bulk twin: the resolved limit on rows per request (`resolveBulkOperationMaxSelection`). */
+    bulkOperationMaxSelection?: number;
     initiatorInfos?: ResourceConfiguration_Operation_UrlInitiatorInfo[];
     tokenAuthentication?: TokenAuthenticationConfig;
     tokenGeneration?: TokenGenerationConfig;
@@ -1869,6 +2461,8 @@ export type OperationVariant_ForKey<K, TMainSchema extends z.ZodTypeAny = z.ZodA
  */
 export type OperationConfig_ForKey<K, TMainSchema extends z.ZodTypeAny = z.ZodAny> = {
     variants: OperationVariant_ForKey<K, TMainSchema>[];
+    /** Reply deadline, initial routing priority and failure retry budget/backoff. Does not cancel execution. */
+    queueConfig?: ResourceConfiguration_QueueConfigAuthored;
     serviceRuntimeMode?: ResourceOperation_ServiceRuntimeMode;
     parentResourceAccessScopeStrategyOverrides?: {
         resourceType: ResourceType;
@@ -1881,6 +2475,8 @@ export type OperationConfig_ForKey<K, TMainSchema extends z.ZodTypeAny = z.ZodAn
     }[];
     m2mNotifications?: M2MNotificationDefinitionWithoutIdentifier[];
     recordsUsage?: MeteredUsageRecordingDefinition;
+    /** See {@link ResourceOperationConsentGateDeclaration} (#1258 Step 3). */
+    consentGate?: ResourceOperationConsentGateDeclaration;
 };
 /** @wildo_source:part:end saas.models.resource-config.operation-variant-for-key */
 /**
@@ -1992,6 +2588,8 @@ export type ResourceConfiguration_InheritanceSchemaDefinition<TDiscriminationEnu
 };
 export type ResourceConfiguration_Operation_BuilderParameters<TMainSchema extends z.ZodTypeAny = z.ZodAny> = {
     variants: ResourceConfiguration_OperationVariant_BuilderParameters<TMainSchema>[];
+    /** Reply deadline, initial routing priority and failure retry budget/backoff. Does not cancel execution. */
+    queueConfig?: ResourceConfiguration_QueueConfigAuthored;
     serviceRuntimeMode?: ResourceOperation_ServiceRuntimeMode;
     parentResourceAccessScopeStrategyOverrides?: {
         resourceType: ResourceType;
@@ -2004,6 +2602,8 @@ export type ResourceConfiguration_Operation_BuilderParameters<TMainSchema extend
     }[];
     m2mNotifications?: M2MNotificationDefinitionWithoutIdentifier[];
     recordsUsage?: MeteredUsageRecordingDefinition;
+    /** See {@link ResourceOperationConsentGateDeclaration} (#1258 Step 3). */
+    consentGate?: ResourceOperationConsentGateDeclaration;
 };
 /**
  * @wildo_source:part:start saas.models.resource-config.builder-parameters facet:layer:shared facet:family:resource-config
@@ -2070,6 +2670,100 @@ export declare enum ResourceSystemAccessMode {
  * framework infrastructure does NOT imply that an ACL bypass is acceptable
  * for its data. Keep the two concepts separate.
  */
+/**
+ * Declares that THIS resource is the application's subject-erasure request lane, and how to read it.
+ *
+ * ## Why the application declares it rather than the framework knowing it
+ *
+ * The erasure lane is application-owned — four of the five marked sites for
+ * `WILDO.PRIVACY.SUBJECT_ERASURE` are in an application, not the engine — and its evidence demand
+ * (`evidence-requirement:subject-erasure-execution-record`) says so in terms: *"the row's schema and
+ * status vocabulary are the application's, so a collector queries it against that application's
+ * specification"*, and its verification step adds *"do NOT assert a specific channel vocabulary:
+ * that is one application's modelling choice"*.
+ *
+ * So a collector may not know that a request is raised through a field called `channel` carrying a
+ * value called `SUBJECT`. It has to be TOLD, by the application, in a form it can read. Before this
+ * existed, three clauses of that demand had a durable row holding every fact they wanted and no way
+ * to find it (#1209): not a missing control, a control nobody could point at.
+ *
+ * ## It binds FIELDS, never values the framework invents
+ *
+ * Every member below names something the application already authored. The one value the
+ * declaration carries — {@link ResourceSubjectErasureLane.raisedBy}`.subjectValue` — is the
+ * application's OWN enum member, quoted back so a reader can tell the two populations apart. The
+ * framework supplies no vocabulary here and must never grow one.
+ *
+ * ## What is deliberately NOT declared
+ *
+ * The SCHEDULE. C3 asks that requests be executed on the declared schedule, and that schedule is
+ * already on the executing operation's `CRON_JOB` variant (`cronExpression`) — declaring it again
+ * here would be a second copy that can only ever disagree with the one the scheduler reads.
+ * `executionOperationIdentifier` names the operation; the schedule is read from it.
+ */
+export type ResourceSubjectErasureLane = {
+    /**
+     * How a row says WHO raised the request — the subject exercising their own right, or the
+     * controller acting on their behalf. C1's whole obligation is that the two are distinguishable.
+     */
+    raisedBy: {
+        /** The field carrying it. Must be a persisted field of this resource. */
+        fieldName: string;
+        /**
+         * The value of that field meaning the SUBJECT raised it themselves. Every other value is read as
+         * controller-raised — stated this way round because a lane may grow a second controller channel
+         * without the declaration going stale, whereas enumerating the controller values could not.
+         */
+        subjectValue: string;
+    };
+    /**
+     * The field carrying WHICH user raised a controller-raised request.
+     *
+     * Omitting it is a positive claim, not a gap: it says this lane admits no controller-raised
+     * request at all. A collector reads it that way and a row carrying a non-subject value then
+     * contradicts the declaration, which is a finding about the application rather than about the
+     * evidence.
+     */
+    requesterFieldName?: string;
+    /** The field carrying the justification a controller-raised request was made on, where the lane records one. */
+    justificationFieldName?: string;
+    /** The field carrying the instant the request was executed or failed. C3 judges execution against it. */
+    completedAtFieldName: string;
+    /** The field carrying what the execution did. Its vocabulary is the application's. */
+    outcomeFieldName: string;
+    /**
+     * The operation a SUBJECT uses to withdraw their own pending request (C2). Named rather than
+     * inferred: "the operation that cancels" is not derivable from an operation vocabulary, and
+     * guessing it would make the evidence depend on a naming convention no application agreed to.
+     */
+    withdrawalOperationIdentifier: string;
+    /**
+     * How a WITHDRAWN row is recognisable afterwards — the same shape as {@link raisedBy}, and for the
+     * same reason: the vocabulary is the application's.
+     *
+     * C2 asks for the withdrawal door AND for "any cancelled rows", and those are two different
+     * questions. The door is answered from {@link withdrawalOperationIdentifier} — is the operation
+     * reachable to a subject while the request is pending — and needs no data at all. The rows need a
+     * marker, and there is nothing to derive one from: withdrawal and execution both leave a request in
+     * a terminal state, so a reader that knows only `completedAtFieldName` cannot tell "the subject
+     * changed their mind" from "the sweep ran".
+     *
+     * OPTIONAL, because an application may not model withdrawal as a value at all — it may delete the
+     * row, or move it. Omitting it says the count is unavailable, and a collector reports that rather
+     * than guessing; it never turns into a zero, which would read as "nobody withdrew anything".
+     *
+     * Note an EMPTY withdrawal set is explicitly not a deficiency in the demand — people do not have
+     * to change their minds — so this exists to make the number REPORTABLE, never to make it a target.
+     */
+    withdrawnMarker?: {
+        /** The field carrying it. Must be a persisted field of this resource. */
+        fieldName: string;
+        /** The value of that field meaning the SUBJECT withdrew the request before it executed. */
+        withdrawnValue: string;
+    };
+    /** The scheduled operation that executes due requests. Its `cronExpression` IS the declared schedule. */
+    executionOperationIdentifier: string;
+};
 export type ResourceSystemAccessPolicy = {
     /** Governs `readAsSystem`. Omitted ⇒ FORBIDDEN. */
     read?: ResourceSystemAccessMode;
@@ -2128,41 +2822,6 @@ export type ResourceSystemAccessPolicy = {
     exportSubject?: ResourceSystemAccessMode;
 };
 /** @wildo_source:part:end saas.models.resource-config.system-access-policy */
-/**
- * Resource-level opt-in to the **impersonalization-on-erasure** capability: on erasure the
- * resource is impersonalized-and-retained (personal fields scrubbed, row kept for a legal/audit
- * obligation) instead of hard-deleted. When set, the factory injects a `retentionStatus` marker
- * and derives the `updateMany` + `seeRetained` system-access grants.
- *
- * RESOURCE-level (intrinsic, trigger-agnostic). The per-EDGE trigger is
- * `onParentDelete.strategy = IMPERSONALIZE_AND_RETAIN`; the per-FIELD scrub is `.impersonalizeWith()`.
- *
- * **LIVE — opting in has real effect today.** The marker + derived grants, the in-place scrub writer,
- * the `IMPERSONALIZE_AND_RETAIN` cascade mode and the hidden-by-default read filter all exist and are
- * enforced. A RETAINED row is invisible to reads, lists, counts and CHART aggregates, and immutable
- * to ordinary writes, on BOTH persistence adapters; the only door is the audited see-through path.
- *
- * Runtime-proven, not asserted — and scoped precisely, because an earlier revision of this block
- * over-claimed it. Against a real MongoDB, the erasure orchestrator reaches its terminal path and its
- * receipt is truthful over a registered subset of resources
- * (`subject-erasure-completion.mongo.integration.test.ts`); the retention OUTCOME and a SECOND erasure
- * are observed (`subject-impersonalization-retention-outcome.mongo.integration.test.ts`); and a
- * retained row is absent from a real application chart over real HTTP
- * (Wonder Todos `e2e/chart-retention-hide.e2e.ts`).
- *
- * What is NOT proven: that an erasure completes over the FULL `onParentDelete` closure, and that
- * external (provider-side) effects run. The completion lane deliberately requires
- * `declinedEdges.length > 0`, so it asserts a state in which some edges were NOT executed, and
- * `externalEffects` is stubbed empty. Do not read "runtime-proven" here as end-to-end completeness.
- *
- * (This block previously read "Contract only in this phase … No record is impersonalized-and-retained
- * yet." That was true when written and became false without being revisited — it is the public
- * authoring contract an app developer reads before declaring this policy, so it is corrected here
- * rather than left to mislead.)
- *
- * ⚠️ NOT the anonymous-user concept (`isAnonymizable` is pre-auth ownership transposition — the
- * opposite direction). Reuse of that mechanism, never its name.
- */
 /**
  * WHO a row of this resource is with respect to an erasure, and where that person's session lives.
  * The companion of {@link ResourceRetentionPolicy}: retention says what happens to the ROW and whether
@@ -2194,6 +2853,24 @@ export interface ResourceDataSubjectPolicy {
      */
     sessionPrincipalField?: string;
 }
+/** @wildo_source:part:start saas.models.resource-config.retention-policy facet:layer:shared facet:audience:app-developer */
+/**
+ * `retentionPolicy` on a resource configuration — what a subject ERASURE does to this resource's rows, and,
+ * for a record a statute keeps, on what ground and for how long it survives one.
+ *
+ * Imported from `@wildo-ai/saas-models`. Declaring it requires a `dataSubjectPolicy` and a service-resolvable
+ * `UPDATE_MANY`, `READ` and `LIST`; the factory injects the `retentionStatus` marker every retained row carries.
+ *
+ * @example A statutory business record — kept through an erasure, restricted, until its period ends
+ * ```ts
+ * retentionPolicy: {
+ *   mode: ErasureRetentionMode.RETAIN_ONLY,
+ *   statutoryRetention: { ground: StatutoryRetentionGround.LEGAL_OBLIGATION, rationale: 'HGB §257(1) no. 4, AO §147(1)' },
+ * },
+ * dataSubjectPolicy: { kind: ResourceDataSubjectKind.NO_PRINCIPAL },
+ * retentionBinding: { retentionClass: DataRetentionClass.BUSINESS_RECORDS, startPoint: RetentionStartPoint.END_OF_CALENDAR_YEAR },
+ * ```
+ */
 export interface ResourceRetentionPolicy {
     /**
      * WHAT happens to a row of this resource when its subject is erased.
@@ -2206,7 +2883,47 @@ export interface ResourceRetentionPolicy {
      * retention entirely; keeping them distinct is what makes "retain, nothing to scrub" expressible.
      */
     mode: ErasureRetentionMode;
+    /**
+     * WHY an erasure may not delete these rows yet: the law requires them kept (#1635).
+     *
+     * Declared by a resource bound to `DataRetentionClass.BUSINESS_RECORDS` — and REQUIRED there: the factory
+     * refuses that binding without it, and refuses this member on any other class. A subject erasure then
+     * RESTRICTS each row still inside its statutory period instead of treating it as the author's choice:
+     * the row is kept with {@link mode}'s treatment (flipped to `RETAINED`, so hidden from every ordinary
+     * read and refused every ordinary write — the GDPR Art. 18(2) effect), listed in the erasure report
+     * with this ground and the instant its period ends, and deleted by the retention-class sweep when it
+     * does. Every other row of the request is erased as usual; the request is never refused for these.
+     *
+     * ## The PERIOD is not here, on purpose
+     *
+     * How long the rows are kept is `dataRetention[BUSINESS_RECORDS].retentionDays`, counted from the
+     * resource's `retentionBinding.startPoint`. A second number on this declaration would be a second
+     * authority for one period, and the two would drift.
+     *
+     * ## One erasure authority
+     *
+     * This lives INSIDE `retentionPolicy` rather than beside it: `retentionPolicy` is the declaration whose
+     * whole subject is what an erasure does to a row, and a separate "erasure exemption" beside it would give
+     * one row two erasure authorities.
+     */
+    statutoryRetention?: ResourceStatutoryRetention;
+}
+/**
+ * The legal ground on which a {@link ResourceRetentionPolicy} keeps its rows through an erasure, and the
+ * operator's words for it (#1635).
+ */
+export interface ResourceStatutoryRetention {
+    /** The GDPR Art. 17(3) exemption relied on. One member today — see {@link StatutoryRetentionGround}. */
+    ground: StatutoryRetentionGround;
+    /**
+     * WHICH statute, in the operator's words — "HGB §257(1) no. 4 and AO §147(1): accounting source documents,
+     * 8 years from the end of the calendar year". Required and non-empty: an operator telling a data subject
+     * why a record was kept (Art. 12(4)) has to be able to name the law, and a ground with no law named is a
+     * claim nobody can check.
+     */
+    rationale: string;
 }
+/** @wildo_source:part:end saas.models.resource-config.retention-policy */
 /**
  * Resource-level DEFAULT for where this resource's field values came from — the axis that decides
  * GDPR Art. 20 (portability) scope. Per-field overrides are `.portabilityProvenance()`.
@@ -2352,6 +3069,13 @@ export type ResourceConfiguration_BuilderParameters<TCustomOperationEnum extends
      * explicit alternative authorization.
      */
     systemAccessPolicy?: ResourceSystemAccessPolicy;
+    /**
+     * Declares this resource as the application's SUBJECT-ERASURE REQUEST LANE and binds the fields an
+     * evidence collector reads. Omitted ⇒ this resource is not that lane, which is the honest default:
+     * most resources are not, and an application that never built an erasure lane has declared none
+     * rather than failed a control. See {@link ResourceSubjectErasureLane}.
+     */
+    subjectErasureLane?: ResourceSubjectErasureLane;
     coreOperations: TCoreOperationEnum[];
     customOperation?: TCustomOperationEnum;
     operationsConfiguration: {
@@ -2400,6 +3124,23 @@ export type ResourceConfiguration_BuilderParameters<TCustomOperationEnum extends
      * {@link ResourceDataSubjectPolicy}.
      */
     dataSubjectPolicy?: ResourceDataSubjectPolicy;
+    /**
+     * How long this resource's rows are KEPT: a binding to one of the application's declared retention
+     * classes, and the moment each row's clock starts. An engine sweep deletes a bound row once its
+     * class's `retentionDays` have passed since that start point, through the service layer, on both
+     * persistence adapters.
+     *
+     * ⚠️ NOT {@link retentionPolicy}. That is what an ERASURE does to a row (delete, or retain and
+     * scrub); this is how long a row lives at all. The two compose: a row an erasure retained is still
+     * deleted when its class period ends.
+     *
+     * Optional. An unbound resource is kept until it is erased, and is reported as unbound
+     * (`unboundRetentionResources`) so the undecided period stays visible. A resource that binds a class
+     * may not also declare a `.ttl()` field — one row, one retention authority.
+     *
+     * {@link RetentionStartPoint.SCOPE_DELETED} injects a server-owned `retentionStartedAt` field.
+     */
+    retentionBinding?: ResourceRetentionBinding;
     /**
      * Resource-level DEFAULT provenance for GDPR Art. 20 (portability) scoping; per-field overrides
      * are `.portabilityProvenance()`. Optional — Art. 15 (access) never consults provenance, so an
@@ -2407,6 +3148,20 @@ export type ResourceConfiguration_BuilderParameters<TCustomOperationEnum extends
      * {@link ResourcePortabilityPolicy}.
      */
     portabilityPolicy?: ResourcePortabilityPolicy;
+    /**
+     * Declares every row of this resource a CASE: the unit of work an application sells an outcome for (a
+     * matter, a file, a claim, a ticket). Model calls made while working on a row are attributed to it, so the
+     * application can compute its cost per case (#1598), and expert decisions on agent work name it (#1599).
+     *
+     * A reference to a case is a `WorkUnitRef` (`{ resourceType, resourceId }`), and the engine accepts one at a
+     * service boundary only when `resourceType` names a resource declaring `workUnit: true` and the caller can
+     * READ that row. Several resources of one application may be work units. Default `false`.
+     *
+     * The engine opens the case frame by itself around every single-row operation on a work-unit resource (and
+     * around a CREATE once the new row's id is assigned, before its after-create hooks), so a model call made
+     * by a hook, a tool or a queued job started there is attributed without the application passing anything.
+     */
+    workUnit?: boolean;
 };
 /** @wildo_source:part:end saas.models.resource-config.builder-parameters */
 /**
@@ -2522,6 +3277,13 @@ export type ResourceConfiguration<TCustomOperationEnum extends EnumLikeType | un
      * any verb not explicitly ALLOWED — as forbidden and throw.
      */
     systemAccessPolicy?: ResourceSystemAccessPolicy;
+    /**
+     * Declares this resource as the application's SUBJECT-ERASURE REQUEST LANE and binds the fields an
+     * evidence collector reads. Omitted ⇒ this resource is not that lane, which is the honest default:
+     * most resources are not, and an application that never built an erasure lane has declared none
+     * rather than failed a control. See {@link ResourceSubjectErasureLane}.
+     */
+    subjectErasureLane?: ResourceSubjectErasureLane;
     /**
      * W7.3a: Marks this resource as accessible to anonymous sessions.
      * When true, the engine generates dual URL paths and a STANDALONE relationship to ANONYMOUS_USERS.
@@ -2541,10 +3303,14 @@ export type ResourceConfiguration<TCustomOperationEnum extends EnumLikeType | un
      * the other without a second existence check.
      */
     dataSubjectPolicy?: ResourceDataSubjectPolicy;
+    /** Resolved retention-class binding, exactly as declared (undefined when the resource binds no class). */
+    retentionBinding?: ResourceRetentionBinding;
     /** Resolved portability default (undefined when the resource declared no `portabilityPolicy` — an
      *  Art. 15 export is unaffected, an Art. 20 export refuses on any field that also lacks its own
      *  `.portabilityProvenance()`). */
     portabilityPolicy?: ResourcePortabilityPolicy;
+    /** Resolved `workUnit` declaration (#1598): `true` when every row of this resource is a case. */
+    workUnit?: boolean;
     operations: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>[];
 };
 /** @wildo_source:part:end saas.models.resource-config.resource-configuration */
@@ -2689,6 +3455,14 @@ export type ResourcesRegistry = {
      * from the presence of a unit field. See `OrganizationUnitNarrowingDeclaration`.
      */
     organizationUnitNarrowing: Readonly<Partial<Record<ResourceType, OrganizationUnitNarrowingDeclaration>>>;
+    /**
+     * Resources a UNIT-scoped service-provider expert may READ across the whole client organization even
+     * though they do not narrow by unit — a shared reference list, say (#1597). Each entry carries the
+     * rationale a reviewer reads. Validated at boot: never an authorization-plane resource, never a
+     * resource that also narrows by unit. Absent or empty ⇒ a unit-scoped expert reaches only the
+     * resources that narrow by unit (fail closed).
+     */
+    serviceProviderOrganizationWideAccess?: Readonly<Partial<Record<ResourceType, ServiceProviderOrganizationWideAccessDeclaration>>>;
 };
 /** @wildo_source:part:end saas.models.resource-config.resources-registry */
 export type ResourceRegistry_InitializerParameters<TResourceType extends ResourceType | undefined = undefined> = [