@wildo-ai/saas-models 1.1.4 → 1.1.6

package/dist/esm/resources/resources-config.shared.schemas.js

@@ -7,6 +7,31 @@ import { z } from 'zod';
 // --------------------------------
 // Resources Pagination Response
 // --------------------------------
+/**
+ * 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 const DEFAULT_LIST_PAGE_CEILING = 100;
+/** SEARCH ceilings are lower on purpose: a search page is scored and ranked, not scanned. */
+export const DEFAULT_SEARCH_PAGE_CEILING = 50;
+/**
+ * One schema per page ceiling, shared by every operation that declares it (#1587).
+ *
+ * Both pagination factories are pure functions of `maxLimit`, and the DTO builder called the
+ * response one for every collection operation and variant, building an identical four-field object
+ * each time. Zod 4 classic installs ~40 closures on every instance, so the duplicates were a
+ * measurable share of a resource registry's heap. A Zod schema is immutable, and nothing writes to
+ * these after they are built, so one instance per ceiling serves them all.
+ */
+const PAGINATION_RESPONSE_METADATA_SCHEMA_BY_CEILING = new Map();
+const PAGINATION_REQUEST_SCHEMA_BY_CEILING = new Map();
 /**
  * The pagination block a collection RESPONSE echoes back, bounded by the operation's ceiling.
  *
@@ -21,13 +46,18 @@ import { z } from 'zod';
  * response DATA array bound, and this. They are one invariant — "the operation's declared ceiling
  * governs" — and a fix applied to fewer than all of them just moves which layer says no.
  */
-export function createPaginationResponseMetadataSchema(maxLimit = 100) {
-    return z.object({
+export function createPaginationResponseMetadataSchema(maxLimit = DEFAULT_LIST_PAGE_CEILING) {
+    const cached = PAGINATION_RESPONSE_METADATA_SCHEMA_BY_CEILING.get(maxLimit);
+    if (cached !== undefined)
+        return cached;
+    const built = z.object({
         page: z.number().min(1).default(1),
         limit: z.number().min(1).max(maxLimit).default(20),
         total: z.number().min(0),
         totalPages: z.number().min(0)
     });
+    PAGINATION_RESPONSE_METADATA_SCHEMA_BY_CEILING.set(maxLimit, built);
+    return built;
 }
 /** The default-bounded response metadata. Prefer {@link createPaginationResponseMetadataSchema} where the ceiling is known. */
 export const Resources_PaginationResponseMetadataSchema = createPaginationResponseMetadataSchema();
@@ -42,11 +72,16 @@ export const Resources_PaginationResponseMetadataSchema = createPaginationRespon
  *
  * `maxLimit` defaults to 100 so every existing caller keeps its current contract.
  */
-export function createPaginationRequestSchema(maxLimit = 100) {
-    return z.object({
+export function createPaginationRequestSchema(maxLimit = DEFAULT_LIST_PAGE_CEILING) {
+    const cached = PAGINATION_REQUEST_SCHEMA_BY_CEILING.get(maxLimit);
+    if (cached !== undefined)
+        return cached;
+    const built = z.object({
         page: z.number().min(1).default(1),
         limit: z.number().min(1).max(maxLimit).default(20)
     });
+    PAGINATION_REQUEST_SCHEMA_BY_CEILING.set(maxLimit, built);
+    return built;
 }
 /** The default-bounded pagination block. Prefer {@link createPaginationRequestSchema} where the operation's ceiling is known. */
 export const Resources_PaginationRequestSchema = createPaginationRequestSchema();
@@ -106,12 +141,18 @@ export var 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.)
      */
     IntrospectionTenancyStance["APPLICATION_STRUCTURE"] = "application-structure";
     /**
@@ -254,9 +295,9 @@ export const DEFAULT_PERSISTENCE_ADAPTER = PersistenceAdapter.MONGODB;
  *
  * 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.
  *
@@ -334,9 +375,149 @@ export var SortOrder;
     SortOrder["DESC"] = "desc";
 })(SortOrder || (SortOrder = {}));
 export const Resources_Filter_DateRangeSchema = z.object({
-    startDate: z.date().optional(),
-    endDate: z.date().optional()
+    startDate: z.date().optional().describe('The earliest date and time to include, inclusive. Omit for no lower bound.'),
+    endDate: z.date().optional().describe('The latest date and time to include, inclusive. Omit for no upper bound.'),
 });
+/**
+ * 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 const Resources_Filter_NumberRangeSchema = z.object({
+    min: z.number().optional(),
+    max: z.number().optional()
+});
+/** The two sub-keys of a {@link Resources_Filter_NumberRangeSchema} value, as the wire carries them. */
+export const RESOURCES_FILTER_NUMBER_RANGE_SUBKEYS = ['min', 'max'];
+/** The two sub-keys of a {@link Resources_Filter_DateRangeSchema} value, as the wire carries them. */
+export const RESOURCES_FILTER_DATE_RANGE_SUBKEYS = ['startDate', 'endDate'];
+/**
+ * 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 function isResourcesFilterNumberRangeSchema(schema) {
+    if (!(schema instanceof z.ZodObject))
+        return false;
+    const keys = Object.keys(schema.shape);
+    return keys.length === RESOURCES_FILTER_NUMBER_RANGE_SUBKEYS.length
+        && keys.every((key) => RESOURCES_FILTER_NUMBER_RANGE_SUBKEYS.includes(key));
+}
+/**
+ * The target field of every presence filter, keyed by the exact schema object an author declared.
+ *
+ * A WeakMap rather than Zod metadata: `.describe()` and `.meta()` each REPLACE a schema's registry
+ * entry, so a target stored there would be lost the moment anything described the schema. The
+ * translation reads the operation's DECLARED `filterFields` — the objects this map was keyed with —
+ * never the request schema the factory derives from them, so the derived `.optional()` copies do not
+ * need to carry it.
+ */
+const RESOURCES_FILTER_PRESENCE_TARGETS = new WeakMap();
+/**
+ * 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 function createResourcesFilterPresenceSchema(targetField) {
+    const schema = z
+        .boolean()
+        .describe(`\`true\` returns only the records where \`${targetField}\` is set; \`false\` only the records where it is not.`);
+    RESOURCES_FILTER_PRESENCE_TARGETS.set(schema, targetField);
+    return schema;
+}
+/** The field a presence filter asks about, or `undefined` when `schema` is not a presence filter. */
+export function getResourcesFilterPresenceTarget(schema) {
+    return schema !== null && typeof schema === 'object' ? RESOURCES_FILTER_PRESENCE_TARGETS.get(schema) : undefined;
+}
+/** Every field a presence filter in `filterFields` asks about — the keys a translated filter may carry. */
+export function resourcesFilterPresenceTargets(filterFields) {
+    return Object.values(filterFields ?? {})
+        .map((schema) => getResourcesFilterPresenceTarget(schema))
+        .filter((target) => target !== undefined);
+}
+/**
+ * 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 function translateResourcesPresenceFilters(filter, filterFields) {
+    if (!filter || typeof filter !== 'object' || !filterFields)
+        return filter;
+    let out;
+    for (const [key, schema] of Object.entries(filterFields)) {
+        const target = getResourcesFilterPresenceTarget(schema);
+        if (target === undefined || !(key in filter))
+            continue;
+        out ??= { ...filter };
+        const value = out[key];
+        delete out[key];
+        const present = value === true || value === 'true' ? true : value === false || value === 'false' ? false : undefined;
+        if (present === undefined)
+            continue;
+        const condition = present ? { $ne: null } : null;
+        if (target in out) {
+            out.$and = [...(Array.isArray(out.$and) ? out.$and : []), { [target]: condition }];
+        }
+        else {
+            out[target] = condition;
+        }
+    }
+    return out ?? filter;
+}
 export const Resources_Filter_BaseSchema = z.object({
     searchRequest: z.string().optional(),
     createdAt: Resources_Filter_DateRangeSchema.optional(),
@@ -407,6 +588,15 @@ export var ResourceCollectionExportFormat;
      * types intact. Choose this when the export feeds another system rather than a human.
      */
     ResourceCollectionExportFormat["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.
+     */
+    ResourceCollectionExportFormat["PDF"] = "pdf";
 })(ResourceCollectionExportFormat || (ResourceCollectionExportFormat = {}));
 /**
  * WHICH rows a collection export contains.
@@ -432,7 +622,7 @@ export var ResourceCollectionExportRowScope;
     ResourceCollectionExportRowScope["FULL_RESULT_SET"] = "full_result_set";
 })(ResourceCollectionExportRowScope || (ResourceCollectionExportRowScope = {}));
 /**
- * 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
  *
@@ -464,7 +654,7 @@ export var 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`.
@@ -474,11 +664,11 @@ export var ResourceCollectionExportRowScope;
  */
 export const ResourceCollectionExportResponseSchema = z.object({
     /** Mirrors the `filename=` of the `Content-Disposition` header. */
-    filename: z.string(),
-    /** Mirrors `Content-Type`: `text/csv` or `application/json`. */
-    contentType: z.string(),
+    filename: z.string().describe("The downloaded file's name, sent in the `Content-Disposition` header. The response body is the exported file itself, not a JSON object."),
+    /** Mirrors `Content-Type`: `text/csv`, `application/json` or `application/pdf`. */
+    contentType: z.string().describe("The file's format, sent as the `Content-Type` header: `text/csv`, `application/json` or `application/pdf`."),
     /** Mirrors `X-Wildo-Export-Row-Count` — the number of rows actually written. */
-    rowCount: z.number().int().nonnegative(),
+    rowCount: z.number().int().nonnegative().describe("How many rows the file holds, sent in the `X-Wildo-Export-Row-Count` header."),
 });
 /** Runtime guard distinguishing a relational descriptor from an own-field name. */
 export function isSearchableRelationDescriptor(field) {
@@ -501,9 +691,145 @@ export function isSearchableRelationDescriptor(field) {
  * 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 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 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 const BULK_OPERATION_HOST_SUPPLIED_FIELDS = [
+    BULK_OPERATION_SELECTOR_FIELD,
+    BULK_OPERATION_MATCH_FIELD,
+];
+export 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 const BULK_OPERATION_BACKGROUND_MAX_SELECTION = 10_000;
+/** The effective limit for one bulk operation: its declared `bulkOperationMaxSelection`, else the default. */
+export function resolveBulkOperationMaxSelection(operation) {
+    return operation.bulkOperationMaxSelection ?? BULK_OPERATION_DEFAULT_MAX_SELECTION;
+}
+/**
+ * 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 const Resources_BulkOperationMatchSelectorSchema = z.object({
+    /** The listing's filters, as the LIST request carried them. Re-parsed server-side per resource. */
+    filters: z.record(z.string(), z.unknown()).optional().describe("The listing's filters, as its list request sends them. They are checked against this resource's list filters."),
+    /** The listing's free-text search, when one was active. */
+    search: z.string().min(1).optional().describe("The listing's free-text search, when one was active."),
+});
 export const Resources_BulkOperationBaseSchema = z.object({
-    _ids: z.array(z.string().min(1)).min(1),
+    _ids: z.array(z.string().min(1)).min(1).max(BULK_OPERATION_DEFAULT_MAX_SELECTION).optional().describe("The ids of the records to act on. Give either `_ids` or `_match`, not both."),
+    _match: Resources_BulkOperationMatchSelectorSchema.optional().describe("Act on every record a listing returns rather than on named ids: the listing's filters and search. The server runs this resource's list with them in the caller's scope, so it reaches only records the caller could list. Give either `_ids` or `_match`, not both."),
 });
+/**
+ * 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 function buildBulkOperationSelectorSchema(maxSelection) {
+    return z.object({
+        _ids: z.array(z.string().min(1)).min(1).max(maxSelection).optional().describe("The ids of the records to act on. Give either `_ids` or `_match`, not both."),
+        _match: Resources_BulkOperationMatchSelectorSchema.optional().describe("Act on every record a listing returns rather than on named ids: the listing's filters and search. The server runs this resource's list with them in the caller's scope, so it reaches only records the caller could list. Give either `_ids` or `_match`, not both."),
+    });
+}
+/**
+ * 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 function wrapRequestDtoAsBulk(params) {
+    const { rowRequestDto, maxSelection, isCreate } = params;
+    if (isCreate) {
+        return z.object({ data: z.array(rowRequestDto ?? z.object({})).max(maxSelection) });
+    }
+    const selector = buildBulkOperationSelectorSchema(maxSelection);
+    if (!rowRequestDto)
+        return selector;
+    // Extending keeps the result a plain object, which every shape-reading consumer depends on.
+    return rowRequestDto instanceof z.ZodObject
+        ? selector.extend(rowRequestDto.shape)
+        : selector.and(rowRequestDto);
+}
+/**
+ * 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 function readBatchCreateRowRequestDto(requestDto) {
+    if (!(requestDto instanceof z.ZodObject))
+        return undefined;
+    const data = requestDto.shape.data;
+    return data instanceof z.ZodArray ? data.element : undefined;
+}
 /**
  * The single named source for the bulk selector's field name.
  *
@@ -511,7 +837,6 @@ export const Resources_BulkOperationBaseSchema = z.object({
  * the generated relationship-bulk selector) reads the name from here, so the two halves of the wire
  * contract cannot drift apart silently.
  */
-export const BULK_OPERATION_SELECTOR_FIELD = '_ids';
 /**
  * Read the bulk selector out of a request payload, or `undefined` when it carries none.
  *
@@ -532,6 +857,36 @@ export function readBulkOperationSelectorIds(payload) {
     const ids = raw.filter((candidate) => typeof candidate === 'string' && candidate.length > 0);
     return ids.length > 0 ? ids : 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 function readBulkOperationSelector(payload) {
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+        return undefined;
+    }
+    const ids = readBulkOperationSelectorIds(payload);
+    const rawMatch = payload[BULK_OPERATION_MATCH_FIELD];
+    const parsedMatch = Resources_BulkOperationMatchSelectorSchema.safeParse(rawMatch);
+    const match = rawMatch !== undefined && parsedMatch.success ? parsedMatch.data : undefined;
+    if (ids && match)
+        return undefined;
+    if (ids)
+        return { kind: 'ids', ids };
+    if (match)
+        return { kind: 'match', match };
+    return undefined;
+}
 /**
  * Strip the bulk selector from a request payload.
  *
@@ -544,16 +899,20 @@ export function stripBulkOperationSelector(payload) {
     if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
         return payload;
     }
-    if (!(BULK_OPERATION_SELECTOR_FIELD in payload)) {
+    const record = payload;
+    // BOTH members are stripped: a match selector left in place rides to persistence exactly as `_ids`
+    // did, and is dropped there by the strict re-parse — silently, and after the read-only-field guard
+    // has already reasoned about a payload that is not the payload.
+    if (!(BULK_OPERATION_SELECTOR_FIELD in record) && !(BULK_OPERATION_MATCH_FIELD in record)) {
         return payload;
     }
-    const { [BULK_OPERATION_SELECTOR_FIELD]: _selector, ...rest } = payload;
+    const { [BULK_OPERATION_SELECTOR_FIELD]: _ids, [BULK_OPERATION_MATCH_FIELD]: _match, ...rest } = record;
     return rest;
 }
 export var ResourceGeneratedOperationKind;
 (function (ResourceGeneratedOperationKind) {
     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}. */
     ResourceGeneratedOperationKind["GENERATED_COLLECTION_EXPORT"] = "generated_collection_export";
 })(ResourceGeneratedOperationKind || (ResourceGeneratedOperationKind = {}));
 /**
@@ -620,11 +979,71 @@ export var ResourceOperationRequestContractBreadth;
     ResourceOperationRequestContractBreadth["OVERBROAD_INHERITED_FULL_CONTRACT"] = "overbroad_inherited_full_contract";
 })(ResourceOperationRequestContractBreadth || (ResourceOperationRequestContractBreadth = {}));
 /**
- * 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.
+ * 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 const UNIMPLEMENTED_ENGINE_OPERATION_BACKLOG_REF = '.claude/plans/routed-unimplemented-operations-fail-closed.md';
+export var ResourceOperationSealedRequestFieldAdmission;
+(function (ResourceOperationSealedRequestFieldAdmission) {
+    /** No sealed field is re-admitted, or every re-admitted one names an owner. */
+    ResourceOperationSealedRequestFieldAdmission["SEALED_FIELDS_OWNED"] = "sealed_fields_owned";
+    /** The authored contract re-admits a sealed field that nothing claims. */
+    ResourceOperationSealedRequestFieldAdmission["UNOWNED_SEALED_FIELD_READMITTED"] = "unowned_sealed_field_readmitted";
+})(ResourceOperationSealedRequestFieldAdmission || (ResourceOperationSealedRequestFieldAdmission = {}));
 /**
  * Acknowledge an engine operation as a known, fail-closed implementation gap.
  *
@@ -632,11 +1051,19 @@ export const UNIMPLEMENTED_ENGINE_OPERATION_BACKLOG_REF = '.claude/plans/routed-
  * 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 const acknowledgeUnimplementedEngineOperation = (reason) => ({
+export const acknowledgeUnimplementedEngineOperation = (reason, trackingRef) => ({
     reason,
-    trackingRef: UNIMPLEMENTED_ENGINE_OPERATION_BACKLOG_REF,
+    trackingRef,
 });
 /**
  * @wildo_source:part:start saas.models.resource-config.system-access-policy facet:layer:shared facet:family:resource-config