@wildo-ai/saas-models 1.1.3 → 1.1.5

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

@@ -1,3 +1,6 @@
+import { ResourceOperationIdempotencyKeyRequirement } from '../requests/idempotency-key.shared';
+import type { ResourceConfiguration_QueueConfig, ResourceConfiguration_QueueConfigAuthored } from '../queue/queues.shared.schemas';
+import type { ScheduledRecoveryPolicy } from '../queue/jobs.shared.schemas';
 /**
  * Operations Shared Schemas
  *
@@ -7,12 +10,13 @@ import { z } from 'zod';
 import { EnumLikeType, EnumValues, PrimitiveZodType } from '@wildo-ai/zod-decorators';
 import { ErasureRetentionMode, ResourceDataSubjectKind } from '../compliance/privacy/impersonalization.shared.schemas';
 import type { DataPortabilityProvenance } from '../compliance/privacy/subject-export.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';
@@ -21,6 +25,20 @@ import type { OrganizationUnitNarrowingDeclaration } from '../organizations/orga
 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 +144,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",
     /**
@@ -340,9 +364,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 +492,59 @@ 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;
 export declare const Resources_Filter_BaseSchema: z.ZodObject<{
     searchRequest: z.ZodOptional<z.ZodString>;
     createdAt: z.ZodOptional<z.ZodObject<{
@@ -671,7 +748,7 @@ export type ResourceCollectionExportConfig = {
 };
 export type CollectionViewFields_Shared = {
     pageSize?: number;
-    filterFields?: Record<string, PrimitiveZodType | ((filterRef: PrimitiveZodType) => string)>;
+    filterFields?: Record<string, ResourceFilterFieldSchema | ((filterRef: PrimitiveZodType) => string)>;
     sortFields?: readonly string[];
     /**
      * Opt this LIST/SEARCH operation into CSV/JSON export — see {@link ResourceCollectionExportConfig}.
@@ -829,9 +906,116 @@ 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";
+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 +1023,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 +1033,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.
  *
@@ -1038,7 +1242,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 +1318,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 +1389,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 +1423,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 +1448,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
      *
@@ -1222,6 +1530,22 @@ type ResourceConfiguration_OperationVariant_Base<TMainSchema extends z.ZodTypeAn
      * automatically, and everything else is deliberately not.
      */
     auditableEvent?: ResourceOperation_AuditableEvent;
+    /**
+     * @wildo_source:part:start saas.models.resource-config.operation-scope-admissions facet:layer:shared facet:audience:app-developer
+     *
+     * The two per-variant admissions that relax WHOSE row an operation may address. Both are empty by
+     * default, both are declared on the VARIANT rather than the resource, and both are the seam a
+     * security reviewer should read first.
+     *
+     * Neither touches WHO may call: the operation's `roles` gate runs independently and unchanged, so
+     * an admitted variant is still reachable only by the roles it declares. Role decides who; these
+     * decide whose.
+     *
+     * The trap is the generic verb. Declaring an admission on a general UPDATE opens every field of
+     * every row it can reach — which is why the framework's own cross-tenant repair is authored as its
+     * own verb that writes one field in one direction and overwrites whatever else the payload carried.
+     * Give the crossing its own narrow operation.
+     */
     /**
      * Admits an APPLICATION-scope platform super-administrator to a resource whose primary scope is a
      * PER-INSTANCE tenant scope (today: `ORGANIZATIONS`) without requiring membership of that tenant.
@@ -1234,7 +1558,7 @@ type ResourceConfiguration_OperationVariant_Base<TMainSchema extends z.ZodTypeAn
      * they are denied on every org-scoped resource, INCLUDING the organization row itself. That is
      * normally exactly right: it is what makes tenant isolation hold against the most privileged
      * principal in the system, and it is pinned by
-     * `cross-tenant-super-admin-reach.mongo.integration.test.ts`.
+     * `cross-tenant-super-admin-reach.integration.test.ts`.
      *
      * It also means a tenant that loses its last owner cannot be repaired by anyone, which is the other
      * half of the administrative-continuity pattern: protect the tenant tier and
@@ -1253,6 +1577,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.
@@ -1300,6 +1629,54 @@ 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
      *
@@ -1336,24 +1713,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
@@ -1368,6 +1745,52 @@ 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 */
     /**
      * Default **frontend surface** for this operation when no app preset declares
      * one (see {@link ResourceOperationFrontendSurface}). Lets the framework mark
@@ -1388,10 +1811,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
@@ -1439,6 +1863,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>>>;
     /**
@@ -1453,9 +1884,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
@@ -1476,6 +1922,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;
@@ -1533,6 +1986,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;
@@ -1562,8 +2022,41 @@ type ResourceConfiguration_OperationVariant_ApiCallWithCallback_BuilderParameter
     callbackTimeout?: number;
     callbackRetryAttempts?: number;
 };
+/**
+ * @wildo_source:part:start saas.models.resource-config.operation-cron-job facet:layer:shared facet:audience:app-developer
+ *
+ * A CRON_JOB variant — the declaration that makes an operation run on a schedule.
+ *
+ * The job does not run inside your application's own process on a timer. Your application PUBLISHES
+ * its declared schedules to the platform scheduler at startup, and the scheduler later delivers a
+ * signed tick back onto your application's queue. Four consequences follow, and none of them is
+ * visible from this type:
+ *
+ * **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.
+ *
+ * **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
+ * retimed job that appears not to have moved is the expected shape of a sync that has not landed yet,
+ * not a broken expression.
+ *
+ * **The scheduler records that it PUBLISHED the tick, never that your application ran it.** A tick
+ * that reached the broker and then failed inside the application still reads as a successful run on
+ * the scheduler's side, so verify a scheduled job by its effect in your own storage rather than by
+ * 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;
     /**
      * Explicit response contract for a CRON_JOB custom operation whose return shape
@@ -1578,7 +2071,9 @@ type ResourceConfiguration_OperationVariant_CronJob_BuilderParameters = Resource
      */
     customResponseDto?: z.ZodSchema<any>;
 };
+/** @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 & {
@@ -1607,6 +2102,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>;
@@ -1665,6 +2162,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 */
 /**
@@ -1675,10 +2178,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;
@@ -1725,6 +2230,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;
@@ -1771,6 +2278,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;
@@ -1822,6 +2331,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;
@@ -1834,6 +2345,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 */
 /**
@@ -1945,6 +2458,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;
@@ -1957,6 +2472,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
@@ -2023,6 +2540,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;
@@ -2305,6 +2916,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: {
@@ -2475,6 +3093,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.