@wildo-ai/saas-models 1.0.1 → 1.1.1

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

@@ -5,26 +5,69 @@
  */
 import { z } from 'zod';
 import { EnumLikeType, EnumValues, PrimitiveZodType } from '@wildo-ai/zod-decorators';
-import { HttpMethod } from '../requests/http-requests.shared.js';
-import { Roles } from '../security/authorizations/roles.shared.schemas.js';
-import { TokenAuthenticationConfig, TokenGenerationConfig, TokenRevocationConfig } from '../security/authentications/consumable-token.shared.schemas.js';
-import { ResourceOperation_ServiceRuntimeMode, ResourceOperationVariantType, ResourceOperationRiskLevel, ResourcePrimaryScope, ResourceTranspositionPolicy, ResourceOperation_CustomServiceImplementationMode, ResourceRelationship, ResourceRelationshipAccessScopeStrategy } from './resources.shared.schemas.js';
-import { NotificationBadgeIdentifier, NotificationBadgeOperation } from '../notifications/notification-badges.schemas.js';
-import { M2MNotificationDefinition, UserNotificationDefinition } from '../notifications/notifications.shared.schemas.js';
-import { NotificationBadgeDefinition } from '../notifications/notification-badges.schemas.js';
-import { CoreResourceOperation, ResourceFieldIdentifier, ResourceType } from './resources.shared.core.definitions.js';
-import { LimitCountingConfig } from '../features/feature-definition.shared.schemas.js';
-import { MainSchemaInfer, SchemaArrayInfer } from './utils/schema-type-inference.utils.js';
+import { ErasureRetentionMode, ResourceDataSubjectKind } from '../compliance/privacy/impersonalization.shared.schemas';
+import type { DataPortabilityProvenance } from '../compliance/privacy/subject-export.shared.schemas';
+import type { HttpApiResourceBinding } from '../http-api-binding/http-api-binding.shared.schemas';
+import type { ExternalDataPipelineDeclaration } 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 { NotificationBadgeIdentifier, NotificationBadgeOperation } from '../notifications/notification-badges.schemas';
+import { M2MNotificationDefinition, UserNotificationDefinition } from '../notifications/notifications.shared.schemas';
+import { NotificationBadgeDefinition } from '../notifications/notification-badges.schemas';
+import { CoreResourceOperation, ResourceFieldIdentifier, ResourceType } from './resources.shared.core.definitions';
+import type { OrganizationUnitNarrowingDeclaration } from '../organizations/organization-unit-narrowing.shared';
+import { 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 pagination block a collection RESPONSE echoes back, bounded by the operation's ceiling.
+ *
+ * `limit` here reports the page size that was actually SERVED, so its bound has to be at least as
+ * permissive as the one the repository is allowed to serve. It was a hard-coded `.max(100)`, which
+ * made it the LAST of five separate pagination ceilings to ignore the operation's declaration — and
+ * the one that turned a legitimately-served 120-row page into a 500 (`too_big` at
+ * `pagination.limit`) after the request and data-array bounds had already been fixed.
+ *
+ * The five, for anyone changing one of them: the REQUEST bound
+ * ({@link createPaginationRequestSchema}), the repository's `_doList` and `_doSearch` maxima, the
+ * 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 declare function createPaginationResponseMetadataSchema(maxLimit?: number): z.ZodObject<{
+    page: z.ZodDefault<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    total: z.ZodNumber;
+    totalPages: z.ZodNumber;
+}>;
+/** The default-bounded response metadata. Prefer {@link createPaginationResponseMetadataSchema} where the ceiling is known. */
 export declare const Resouces_PaginationResponseMetadataSchema: z.ZodObject<{
     page: z.ZodDefault<z.ZodNumber>;
     limit: z.ZodDefault<z.ZodNumber>;
     total: z.ZodNumber;
     totalPages: z.ZodNumber;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
+/**
+ * The pagination block a collection request may carry, bounded by the operation's declared ceiling.
+ *
+ * The bound used to be a hard-coded `.max(100)` on a single shared constant, which made it the
+ * STRICTEST of the three pagination ceilings in the framework — the repository serves up to the
+ * operation's declared limit and the response DTO accepts up to the same, but a request asking for
+ * more than 100 was rejected before either ran. An operation declaring 200 therefore advertised a
+ * limit it answered 400 to.
+ *
+ * `maxLimit` defaults to 100 so every existing caller keeps its current contract.
+ */
+export declare function createPaginationRequestSchema(maxLimit?: number): z.ZodObject<{
+    page: z.ZodDefault<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}>;
+/** The default-bounded pagination block. Prefer {@link createPaginationRequestSchema} where the operation's ceiling is known. */
 export declare const Resouces_PaginationRequestSchema: z.ZodObject<{
     page: z.ZodDefault<z.ZodNumber>;
     limit: z.ZodDefault<z.ZodNumber>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 export type ResourcePaginatedResponseResultSchema<T extends z.ZodTypeAny> = {
     data: SchemaArrayInfer<T>;
     pagination: z.infer<typeof Resouces_PaginationResponseMetadataSchema>;
@@ -36,12 +79,16 @@ export type Resources_PaginatedResult<T> = {
     pagination: Resources_PaginationMetadata;
 };
 /**
+ * @wildo_source:part:start saas.models.data-mode-read-list facet:layer:shared facet:family:resource-config
+ *
  * Data mode for read/list operations — controls API data shape.
  * SUMMARY = backend returns only `isSummaryField()` fields and populates `isSummaryField({ populate: true })` FKs.
  *
  * Note: "summary" here is about *data shape*, not FK rendering (see ForeignKeyDisplayMode.SUMMARY)
  * or operation bar density (see ResourceOperationDisplayMode.SUMMARY).
  * Values are lowercase strings matching URL/serialization format directly.
+ *
+ * @remarks Import from `@wildo-ai/saas-models`. Used by read/list/search configs and DTO shaping.
  */
 export declare enum DataMode {
     /** All stored fields, no population */
@@ -52,20 +99,277 @@ export declare enum DataMode {
     CONTEXT = "context"
 }
 /**
- * Persistence adapter type for database selection.
+ * Canonical persistence adapters supported by the resource system.
  *
- * Determines which database backend is used for a resource:
- * - `mongodb`: MongoDB with Mongoose ORM
- * - `postgresql`: PostgreSQL (SQL adapter)
+ * Determines which backing store serves a resource's rows:
+ * - `mongodb`: MongoDB with Mongoose ORM (platform-provisioned)
+ * - `postgresql`: PostgreSQL SQL adapter (platform-provisioned)
+ * - `http-api`: a system reached over an authenticated HTTP API (OData or REST/JSON dialect) —
+ *   the platform provisions NOTHING for it; rows are queried on demand
  *
  * If not specified at resource level, uses `appConfig.database.defaultAdapter`.
+ */
+/**
+ * What an INTROSPECTION-backed resource projects.
+ *
+ * Declared BY THE AUTHOR beside the resource, exactly as `httpApiBinding` is, and for the same
+ * reason: the adapter answers "how rows are reached", and everything specific to THIS resource's
+ * reach is a typed declaration rather than runtime inference.
+ *
+ * Keeping it here rather than in a companion-side lookup table matters. A table keyed by resource
+ * type would be a second enumeration of a population the resource configs already define — the
+ * shape that silently drifts when one side gains an entry.
+ */
+export declare enum IntrospectionTenancyStance {
+    /**
+     * The rows describe the APPLICATION'S OWN STRUCTURE — its modules, resource specifications,
+     * 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.
+     */
+    APPLICATION_STRUCTURE = "application-structure",
+    /**
+     * The rows carry a tenant dimension and a scope predicate must be pushed into the source.
+     *
+     * REFUSED AT REGISTRATION today: no introspection behavior takes a scope argument, so the engine
+     * has nothing to push down. Declared as a member rather than omitted so the refusal is explicit
+     * and a future scoped behavior is a deliberate design step — the alternative is that the first
+     * author needing it discovers the gap by shipping unscoped rows.
+     */
+    SCOPE_FILTER_PUSHDOWN = "scope-filter-pushdown"
+}
+export interface IntrospectionResourceBinding {
+    /**
+     * The companion introspection behavior whose output becomes this resource's rows.
+     *
+     * A plain string on purpose: the behavior catalog lives in the companion (23 behaviors as of
+     * 2026-08-29) and the engine must not depend on it. An unknown id is refused by the companion at
+     * read time, naming the id and the supported set.
+     */
+    readonly behavior: string;
+    /**
+     * Path into the behavior's result that holds the rows, dot-separated. Omitted means the result
+     * itself is the row collection.
+     *
+     * Behaviors answer their own natural shape — `{ frontendChartRegistrationRefs: [...] }` — and
+     * teaching each one to answer a uniform envelope would change 23 working behaviors to suit a
+     * consumer that arrived later.
+     */
+    readonly rowsPath?: string;
+    /**
+     * REQUIRED. Why these rows need no contextual scope predicate, or that they do.
+     *
+     * Not optional and not defaulted: a default would make "nobody thought about tenancy" and
+     * "tenancy does not apply here" the same declaration.
+     */
+    readonly tenancy: IntrospectionTenancyStance;
+    /**
+     * Fields whose values COMPOSE each row's primary key, in order, when the behavior's rows carry no
+     * identifier of their own.
+     *
+     * Most introspection behaviors answer structural projections rather than records: a module row
+     * carries `moduleId` and needs nothing here, while a relationship row carries only the two
+     * resource types it joins. Without a key such a resource can be LISTed and never READ, because
+     * there is no value to address a row by.
+     *
+     * Composition is DECLARED rather than derived because only the author knows which fields are
+     * jointly unique for a given behavior — and being wrong is not hypothetical. `resourceType1` +
+     * `resourceType2` is unique across all 16 relationships in the dogfood application and is still
+     * unsafe in general, since the framework permits several edges between the same pair (a junction
+     * with two roles, a self-relationship). So the source FAILS LOUDLY when two rows compose the same
+     * key rather than serving both under one id, which would make READ return an arbitrary one of
+     * them and give no sign anything was wrong.
+     *
+     * The composed value is written to the resource's own `resourceFieldIdentifier`, which is the one
+     * key name resolvable from the registry without introspecting the schema's decorators. A resource
+     * declaring `identityFields` must therefore name that field as its primary key.
+     *
+     * The values are joined verbatim, so the key stays READABLE — `workspace__users__createdByUserId`
+     * rather than an opaque hash. That is possible because an INTROSPECTION-backed resource resolves
+     * to `ResourceIdFormat.INTROSPECTION_SYNTHESIZED`, which admits a URL-safe charset instead of the
+     * ObjectId-or-UUID rule platform rows follow.
+     *
+     * It was briefly a deterministic UUIDv5, before that format existed. Hashing worked and was the
+     * wrong trade: it made every id opaque, and it disguised the real property — a DERIVED id is only
+     * as stable as the fields it is derived from, and hiding that behind a hash removes the reader's
+     * ability to notice when a row's identity moves.
+     *
+     * Each value must be URL-safe (`[a-zA-Z0-9_-]`) and the whole key at most 255 characters; the
+     * source refuses per row rather than emitting a key that lists and cannot be read.
+     *
+     * Omit when the behavior's rows already carry an identifier of their own.
+     */
+    readonly identityFields?: readonly string[];
+}
+export declare enum PersistenceAdapter {
+    MONGODB = "mongodb",
+    POSTGRESQL = "postgresql",
+    /**
+     * Rows are DERIVED on demand by asking the running dev companion to introspect the application —
+     * its resource registry, specifications, design system, compliance facts, assertions, market and
+     * persona context. Nothing is stored: every read recomputes.
+     *
+     * ## Why this is an adapter and not a service call
+     *
+     * The companion already computes all of it — 23 named introspection behaviors — and today each is
+     * reachable only through a bespoke route. Making it an adapter is what turns those behaviors into
+     * ordinary RESOURCES: list, read, filter, search, labels, navigation, all generated, with no
+     * per-behavior UI. That is the same argument `HTTP_API` settled on 2026-08-26 — the adapter answers
+     * "how rows are reached", and the mechanism behind it is a binding an author declares.
+     *
+     * Distinct from `HTTP_API`, deliberately, and not merely because the transport differs. Retrieval
+     * is a SUBPROCESS that imports the target application's built modules; it costs seconds rather than
+     * milliseconds, it requires that application's `dist` to exist, and its failure mode is a behavior
+     * throwing rather than a row being absent. Collapsing the two would give one declaration whose
+     * discriminator chooses between an HTTP call and a subprocess — two adapters wearing one name.
+     *
+     * ## What every adapter decision site must honor
+     *
+     * - **READ-ONLY, absolutely.** There is no writable target: a row is a projection of the
+     *   application's own source. Every write method refuses, as `HTTP_API`'s twelve do.
+     * - **No provisioning, migration or schema surface.** Nothing is stored, so there is nothing to
+     *   create, migrate or verify — the platform must never believe it owns a store here.
+     * - **Never a legal application-wide DEFAULT adapter.** It is a per-resource declaration only;
+     *   an application whose default was introspection could persist nothing at all.
+     * - **It must DEGRADE, never fail closed at boot.** The companion is the only thing that can run
+     *   an introspection behavior, so a boot path that refuses on an introspection failure would need
+     *   the companion to fix the companion — see `continuity-drift-and-cas-basis.md` Rule 3.
+     */
+    INTROSPECTION = "introspection",
+    /**
+     * Rows live in a system reached over an authenticated HTTP API and are queried on demand
+     * (read-through). Decided 2026-08-26 (ETL workstream, D1): this IS a persistence-adapter answer
+     * — "how rows are reached" — not a separate axis; the dialect (OData vs REST/JSON-RPC) and every
+     * other binding property live in the REQUIRED companion declaration
+     * (`HttpApiResourceBindingSchema`, published by `@wildo-ai/saas-models/external-data`).
+     *
+     * ## Why that companion lives in a SHARED package at all (asked 2026-08-29, measured not argued)
+     *
+     * Only the backend has a runtime for it — 19 references there, none in any frontend package — so
+     * "surely this is backend-only" is the natural reading. It is wrong, for one decisive reason: an
+     * application author writes the binding in `*.resources-config.ts`, which lives in the app's
+     * `shared-lib`, and that package depends on `@wildo-ai/saas-models` and deliberately NOT on
+     * `@wildo-ai/saas-backend-lib` (the frontend imports `shared-lib`, so a backend dependency there
+     * would pull the backend graph browser-ward — the opposite of the isolation wanted). Moving the
+     * declaration to the backend would leave an author unable to type their own declaration.
+     *
+     * Nothing in that companion is runtime: dialects, tenancy, erasure, key fields, remote-call
+     * semantics are all typed by a human. The runtime that consumes them — read client, extraction
+     * source, transform, run service, batch — is already backend-only. So the tiers are already
+     * split where they should be; what was owed was SURFACE hygiene, which is why the companion is
+     * published by a subpath instead of the root barrel rather than moved.
+     *
+     * This asymmetry with MONGODB / POSTGRESQL is therefore principled, not accidental: those need
+     * no AUTHORED companion at all (their detail is infra config plus a runtime planner), while
+     * HTTP_API is the one adapter whose detail an app developer writes.
+     *
+     * Consequences every adapter decision site must honor explicitly (compile-forced via
+     * `PersistenceAdapterCases`):
+     * - provisioning/migration/schema surfaces have NOTHING to do — the platform does not own the
+     *   store and must never mutate its schema;
+     * - it is never a legal application-wide DEFAULT adapter — only a per-resource declaration
+     *   accompanied by its binding;
+     * - until the external repository ships, `createRepository()` refuses it loudly.
+     */
+    HTTP_API = "http-api"
+}
+/**
+ * String-value form accepted by authored resource configuration.
  *
+ * This remains a string union so declarative configuration may use either the
+ * enum members or their serialized values, while deriving the vocabulary from
+ * the single canonical enum above.
  */
-export type PersistenceAdapterType = 'mongodb' | 'postgresql';
+export type PersistenceAdapterType = `${PersistenceAdapter}`;
 /**
- * Default persistence adapter when not specified
+ * Runtime guard for persistence-adapter values entering through erased,
+ * serialized, or otherwise untyped configuration boundaries.
+ *
+ * Keeping this beside the canonical enum ensures future adapter additions are
+ * recognized by validation without duplicating a second vocabulary.
  */
-export declare const DEFAULT_PERSISTENCE_ADAPTER: PersistenceAdapterType;
+export declare function isPersistenceAdapter(value: unknown): value is PersistenceAdapterType;
+/**
+ * Default persistence adapter when not specified.
+ *
+ * Typed as the ENUM member (not the string-union `PersistenceAdapterType`) so it satisfies
+ * enum-typed configuration fields directly; enum member types are assignable to the string
+ * union, so every union-typed consumer is unaffected.
+ */
+export declare const DEFAULT_PERSISTENCE_ADAPTER: PersistenceAdapter;
+/**
+ * A resource's declared relationship to CROSS-ADAPTER ATOMIC WRITE BOUNDARIES.
+ *
+ * **Why this exists.** An application is wholly one persistence adapter by default, and the
+ * resources registry REFUSES a per-resource `persistenceAdapter` that disagrees with
+ * `database.defaultAdapter`. That refusal protects exactly one property: a mixed application
+ * cannot commit two resources in one native transaction, so every cross-resource boundary
+ * silently degrades from atomic to at-least-once.
+ *
+ * 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
+ * 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.
+ *
+ * **This declaration is a claim, not an exemption.** It does not weaken any runtime guarantee:
+ * `ResourcePersistenceUnitOfWorkBackendService.assessCompatibility` still classifies any real
+ * boundary whose ATOMIC participants resolve to more than one adapter as
+ * `MIXED_PERSISTENCE_ADAPTERS`, and `executeInUnitOfWork` still THROWS on it. So a resource
+ * that declares a member here and then IS reached by a cross-adapter atomic boundary fails
+ * loudly at that boundary, exactly as it would have without the declaration. What the
+ * declaration buys is the right to boot; what it can never buy is a silent degradation.
+ *
+ * assurance-control: WILDO.DATA.TRANSACTIONAL_INTEGRITY — the declaration a resource must make
+ * before it may sit on a non-default persistence adapter.
+ */
+export declare enum ResourcePersistenceAdapterIsolation {
+    /**
+     * This resource participates in NO cross-adapter atomic write boundary.
+     *
+     * The author asserts that no operation commits this resource and a resource on another
+     * adapter inside one native transaction — neither as the subject of a
+     * `ResourcePersistenceUnitOfWork` boundary nor as a participant in someone else's.
+     *
+     * Legitimate when the resource is a self-contained store whose writes stand alone: a
+     * retrieval corpus, an append-only analytical sink, a projection rebuilt from its source
+     * rather than written beside it. It is NOT legitimate merely because no such boundary
+     * exists *today* — the claim is about the resource's design, and a later operation that
+     * makes it false must change the declaration rather than discover the refusal at runtime.
+     */
+    NO_CROSS_ADAPTER_TRANSACTION = "NO_CROSS_ADAPTER_TRANSACTION"
+}
+/**
+ * String-value form accepted by authored resource configuration, mirroring the
+ * {@link PersistenceAdapterType} convention so declarative config may use either the enum
+ * member or its serialized value.
+ *
+ * **Deliberately one member.** A second — "participates only as a COMPENSATABLE participant",
+ * mirroring the persistence unit of work's own
+ * `ResourcePersistenceParticipantCoupling.COMPENSATABLE` — is describable, but no resource is
+ * asking for it, and an admission path with no caller is an admission path with no coverage.
+ * Add it when a real resource needs it, with the compensating path named at its call site.
+ */
+export type ResourcePersistenceAdapterIsolationType = `${ResourcePersistenceAdapterIsolation}`;
+/**
+ * Runtime guard for isolation declarations entering through erased, serialized, or otherwise
+ * untyped configuration boundaries — which is exactly how the resources registry sees them, since
+ * it reads heterogeneous resource configurations through an erased index.
+ *
+ * Deliberately a MEMBERSHIP test rather than a presence test: the registry admits a non-default
+ * adapter only on a recognised member, so a typo, a stale value from an older vocabulary, or a
+ * truthy non-string cannot open the door. Fail-closed is the point — an unrecognised declaration
+ * is treated as no declaration at all, and the application is refused with the standard message.
+ */
+export declare function isResourcePersistenceAdapterIsolation(value: unknown): value is ResourcePersistenceAdapterIsolationType;
 /**
  * Variant key constants for operation variants.
  * Values are identical to DataMode.SUMMARY and DataMode.CONTEXT.
@@ -111,6 +415,7 @@ export interface ListOperationOptions {
      */
     pagination?: Resources_PaginationRequest;
 }
+/** @wildo_source:part:end saas.models.data-mode-read-list */
 /**
  * Configuration for auto-generated operation variants.
  * Controls which READ/LIST variants (summary, context) are auto-generated.
@@ -136,61 +441,61 @@ export declare enum SortOrder {
 export declare const Resouces_Filter_DateRangeSchema: z.ZodObject<{
     startDate: z.ZodOptional<z.ZodDate>;
     endDate: z.ZodOptional<z.ZodDate>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 export declare const Resouces_Filter_BaseSchema: z.ZodObject<{
     searchRequest: z.ZodOptional<z.ZodString>;
     createdAt: z.ZodOptional<z.ZodObject<{
         startDate: z.ZodOptional<z.ZodDate>;
         endDate: z.ZodOptional<z.ZodDate>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
+    }, z.core.$strip>>;
     updatedAt: z.ZodOptional<z.ZodObject<{
         startDate: z.ZodOptional<z.ZodDate>;
         endDate: z.ZodOptional<z.ZodDate>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export declare const Resouces_FilterRequestSchema: z.ZodObject<{
     searchRequest: z.ZodOptional<z.ZodString>;
     createdAt: z.ZodOptional<z.ZodObject<{
         startDate: z.ZodOptional<z.ZodDate>;
         endDate: z.ZodOptional<z.ZodDate>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
+    }, z.core.$strip>>;
     updatedAt: z.ZodOptional<z.ZodObject<{
         startDate: z.ZodOptional<z.ZodDate>;
         endDate: z.ZodOptional<z.ZodDate>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
-}, z.core.$catchall<z.ZodOptional<z.ZodAny>>, core.$ZodObjectExtra>;
+    }, z.core.$strip>>;
+}, z.core.$catchall<z.ZodOptional<z.ZodAny>>>;
 export declare const Resouces_SortingFieldSchema: z.ZodObject<{
     field: z.ZodString;
     order: z.ZodDefault<z.ZodEnum<typeof SortOrder>>;
     priority: z.ZodDefault<z.ZodNumber>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 export declare const Resouces_SortingRequestSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodObject<{
     field: z.ZodString;
     order: z.ZodDefault<z.ZodEnum<typeof SortOrder>>;
     priority: z.ZodDefault<z.ZodNumber>;
-}, z.core.$strip, core.$ZodObjectExtra>>>>;
+}, z.core.$strip>>>>;
 export declare const Resouces_SearchQueryRequestSchema: z.ZodObject<{
     pagination: z.ZodOptional<z.ZodObject<{
         page: z.ZodDefault<z.ZodNumber>;
         limit: z.ZodDefault<z.ZodNumber>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
+    }, z.core.$strip>>;
     sorting: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodObject<{
         field: z.ZodString;
         order: z.ZodDefault<z.ZodEnum<typeof SortOrder>>;
         priority: z.ZodDefault<z.ZodNumber>;
-    }, z.core.$strip, core.$ZodObjectExtra>>>>>;
+    }, z.core.$strip>>>>>;
     filters: z.ZodOptional<z.ZodObject<{
         searchRequest: z.ZodOptional<z.ZodString>;
         createdAt: z.ZodOptional<z.ZodObject<{
             startDate: z.ZodOptional<z.ZodDate>;
             endDate: z.ZodOptional<z.ZodDate>;
-        }, z.core.$strip, core.$ZodObjectExtra>>;
+        }, z.core.$strip>>;
         updatedAt: z.ZodOptional<z.ZodObject<{
             startDate: z.ZodOptional<z.ZodDate>;
             endDate: z.ZodOptional<z.ZodDate>;
-        }, z.core.$strip, core.$ZodObjectExtra>>;
-    }, z.core.$catchall<z.ZodOptional<z.ZodAny>>, core.$ZodObjectExtra>>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+        }, z.core.$strip>>;
+    }, z.core.$catchall<z.ZodOptional<z.ZodAny>>>>;
+}, z.core.$strip>;
 export type ResourceSearchQueryRequestResult<TFilterFields extends Record<string, PrimitiveZodType | ((filterRef: PrimitiveZodType) => string)> | undefined, TSortFields extends readonly string[] | undefined> = z.ZodObject<{
     pagination: z.ZodOptional<typeof Resouces_PaginationRequestSchema>;
     sorting: z.ZodOptional<typeof Resouces_SortingRequestSchema>;
@@ -199,7 +504,16 @@ export type ResourceSearchQueryRequestResult<TFilterFields extends Record<string
 export type Ressources_RequestSortPriority<T extends EnumLikeType> = {
     [K in keyof T as T[K]]: number;
 };
-type UserNotificationDefinitionWithoutPrimaryScopeAndIdentifier = Omit<UserNotificationDefinition, 'primaryScope' | 'identifier'>;
+/**
+ * Distributive omit. `UserNotificationDefinition` is a discriminated union (by
+ * `channel`); a bare `Omit<Union, K>` collapses to only the COMMON keys and silently
+ * drops every channel-specific field (the EMAIL variant's `recipientEmailField`, the
+ * FRONT_END_SUCCESS variant's `celebration`/`nextStep`). Routing through a naked type
+ * parameter distributes the omit over each union member so those per-channel fields
+ * survive in the config-authoring type.
+ */
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+type UserNotificationDefinitionWithoutPrimaryScopeAndIdentifier = DistributiveOmit<UserNotificationDefinition, 'primaryScope' | 'identifier'>;
 type M2MNotificationDefinitionWithoutIdentifier = Omit<M2MNotificationDefinition, 'identifier'>;
 export type CollectionView_SearchOptions = {
     caseSensitive?: boolean;
@@ -209,31 +523,332 @@ export type CollectionView_SearchOptions = {
  * Shared collection-view fields for operations that render a collection of items (LIST, SEARCH).
  * These fields are integrated directly into the variant builder type — not nested.
  * The factory flattens them onto the final operation object.
+ *
+ * NOTE: cards-vs-table presentation (`displayMode` / `userSwitchableDisplayMode`)
+ * is intentionally NOT here. It is a pure FRONTEND concern with no backend meaning,
+ * so it is authored on the operation's `operationFrontendConfig.collectionDisplayConfig`
+ * in the resource UI behavior layer (`CollectionDisplayMode` in
+ * `@wildo-ai/saas-frontend-lib`). The fields that remain here are the ones the
+ * BACKEND also reads: `pageSize` (pagination), `filterFields` (filtering), and
+ * `sortFields` (sort validation).
+ */
+/**
+ * The wire format a collection export is rendered into.
+ *
+ * ## Why this is NOT `SubjectExportFormat`
+ *
+ * That enum has the same two members and answers a different question. Its `JSON` member is
+ * documented as "the format an Art. 20 request should receive by default", and its `CSV` member as
+ * "Never the default for portability" — statements about a data subject's PORTABILITY RIGHT. A
+ * listing export owes no such duty: it is an operator exporting rows they can already read, and CSV
+ * is a perfectly good default for it.
+ *
+ * In this codebase an enum member is where the per-member "why" lives (that is the whole reason an
+ * anonymous string union is refused), so sharing the enum would attach Art. 20 reasoning to a
+ * toolbar button, where every word of it is false. It breaks the other way too: adding `XLSX` for
+ * listings would land it in the subject-export vocabulary, where someone then has to reason about
+ * whether a spreadsheet satisfies Art. 20.
+ *
+ * What IS shared is the MECHANISM — RFC 4180 cell escaping and column resolution — which is format
+ * mechanics with no legal content. See `renderCollectionExportCsv`.
  */
+export declare enum ResourceCollectionExportFormat {
+    /**
+     * Tabular, one file. Nested values are JSON-encoded into their cell and type information is lost,
+     * which is the accepted trade for a file every spreadsheet opens. The usual default for a listing.
+     */
+    CSV = "csv",
+    /**
+     * The rows exactly as the listing's response DTO carries them — nested objects, arrays, nulls and
+     * types intact. Choose this when the export feeds another system rather than a human.
+     */
+    JSON = "json"
+}
+/**
+ * WHICH rows a collection export contains.
+ *
+ * The axis is ROWS, deliberately — not columns. An export carries the same fields the listing's read
+ * DTO carries, which is already the caller's permitted projection; there is no separate
+ * "visible columns" notion to select from.
+ */
+export declare enum ResourceCollectionExportRowScope {
+    /**
+     * Exactly the rows the caller's request would have returned — same page, same filters, same sort.
+     * One service call, and what the user sees is what they get.
+     */
+    VISIBLE_PAGE = "visible_page",
+    /**
+     * Every row the caller's filters match, with the page bound removed.
+     *
+     * Implemented by ITERATING pages at the operation's own declared ceiling, never by asking for one
+     * huge page: the page bound is enforced at eight independent sites (see `maxPageSize` below) and
+     * raising it for an export would move the effective ceiling for the whole operation.
+     */
+    FULL_RESULT_SET = "full_result_set"
+}
+/**
+ * Opt a LIST/SEARCH operation into CSV/JSON export of its own result set.
+ *
+ * ## What declaring this does
+ *
+ * The factory derives a companion operation — one `GENERATED_COLLECTION_EXPORT` per exporting
+ * LIST/SEARCH operation — that runs **the same service call as the listing** and renders the result.
+ * That is the load-bearing property: tenant isolation, role ACL, contextual filters, retention
+ * row-hide, backend-only/secret field stripping, relationship population and sort validation all hold
+ * by construction rather than through a second implementation kept in step by hand. (`_doList` and
+ * `buildContextualFilter` each exist twice — once per persistence adapter — and have diverged before;
+ * an export with its own query would be a third place to get the tenant boundary right.)
+ *
+ * The derived operation copies the source operation's `roles` and CANNOT widen them: an export is
+ * exactly as reachable as the listing it exports, never more.
+ *
+ * ## What it deliberately does NOT inherit
+ *
+ * `mcp` / agent exposure. A LIST curated onto an MCP server is a PAGINATED read tool; an export tool
+ * returns the whole table in one call, which is a different risk. Inheriting the flag would widen an
+ * existing application's agent surface the moment it declared an export, so the derived operation is
+ * never agent-exposed and an app that wants one declares it deliberately.
+ *
+ * ## Ceilings
+ *
+ * `maximumExportedRows` is OPTIONAL and has NO default — an operation that declares none exports
+ * whatever its filters match. When declared and exceeded, the export FAILS with an error naming the
+ * matched count and the ceiling; it never truncates. A short file is indistinguishable from a
+ * complete one once it is open in a spreadsheet, and a silent partial export is the worse outcome.
+ */
+/**
+ * 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 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`.
+ *
+ * Modelling the response as "a JSON envelope containing the file" was rejected: a large CSV inside a
+ * JSON string doubles the payload, defeats streaming, and gives the browser nothing to download.
+ */
+export declare const ResourceCollectionExportResponseSchema: z.ZodObject<{
+    filename: z.ZodString;
+    contentType: z.ZodString;
+    rowCount: z.ZodNumber;
+}, z.core.$strip>;
+export type ResourceCollectionExportConfig = {
+    /** Offered formats. Non-empty — an empty array is a startup error, never a silent "all". */
+    formats: readonly ResourceCollectionExportFormat[];
+    /** Offered row scopes. Non-empty, same rule. */
+    rowScopes: readonly ResourceCollectionExportRowScope[];
+    /**
+     * Refuse (do not truncate) a `FULL_RESULT_SET` export whose match count exceeds this.
+     * Omit for no ceiling.
+     */
+    maximumExportedRows?: number;
+};
 export type CollectionViewFields_Shared = {
     pageSize?: number;
-    displayMode?: 'list' | 'table' | 'cards';
     filterFields?: Record<string, PrimitiveZodType | ((filterRef: PrimitiveZodType) => string)>;
     sortFields?: readonly string[];
+    /**
+     * Opt this LIST/SEARCH operation into CSV/JSON export — see {@link ResourceCollectionExportConfig}.
+     * It belongs in this bucket because it is read by the BACKEND, like its three neighbours.
+     */
+    collectionExport?: ResourceCollectionExportConfig;
 };
 /** LIST-specific collection-view fields (LIST and custom ops with resourceOperationLike: LIST) */
 export type CollectionViewFields_List = CollectionViewFields_Shared & {
     searchEnabled?: boolean;
     filtersEnabled?: boolean;
+    /**
+     * Maximum page size this operation will accept, serve and return.
+     *
+     * ## Read this before changing any pagination bound
+     *
+     * ONE declaration, enforced at EIGHT independent sites. That is not an accident of style — each
+     * layer validates the page from its own side, and a bound tightened at any one of them silently
+     * becomes the effective ceiling for the whole operation. Getting fewer than all eight to agree
+     * does not fail loudly; it just moves which layer says no:
+     *
+     * | # | Where | What it bounds |
+     * |---|---|---|
+     * | 1 | `createPaginationRequestSchema` | the `pagination.limit` a caller may ASK for (400 if exceeded) |
+     * | 2 | Mongo `_doList` | the rows the query is allowed to fetch |
+     * | 3 | PostgreSQL `_doList` | same, and it must MATCH #2 — the adapters diverged here once |
+     * | 4 | Mongo/PostgreSQL `_doSearch` | same for the SEARCH verb |
+     * | 5 | response DTO `data` array `.max()` | the rows the response schema will serialise (500 if exceeded) |
+     * | 6 | `createPaginationResponseMetadataSchema` | the `limit` VALUE echoed in the envelope (500 if exceeded) |
+     * | 7 | `internalDto` pagination wrappers (default + SUMMARY + CONTEXT variants) | SERVICE-layer validation, *after* the page is built |
+     * | 8 | `wrapInPaginationStructure` (dataMode SUMMARY/CONTEXT) | the dataMode-selected response shape |
+     *
+     * ⚠️ Sites 7 and 8 are the ones that hide. They validate the SERVICE result, so they only speak
+     * once the request has been accepted and the repository has already produced the page — a bound
+     * left stale there surfaces as `service_resource_transformation_failed`, not as a validation
+     * error, and only for collections large enough to reach it.
+     *
+     * ## The default is 100, and it is load-bearing
+     *
+     * An operation that declares nothing gets **100**, because that is the value the Mongo `_doList`
+     * hard-coded before these sites were unified. Defaulting to 50 (SEARCH's own default) was tried
+     * and reverted: it silently HALVED every caller asking for more — billing usage-metering
+     * (`limit: 10000`), the sidebar resource browser, the flows-actors controller and the audit
+     * export, none of which declare a ceiling and none of which would have errored. Symmetry with
+     * SEARCH is not worth a silent truncation.
+     *
+     * DECLARE a value when a caller depends on it, even if it equals the default — `auditLogs | LIST`
+     * does exactly that, because its export path breaks quietly if the default ever moves.
+     *
+     * The operation declaration is the sole pagination authority. The resolved default operation and
+     * every auto-generated LIST representation inherit the same effective ceiling, so request,
+     * repository, response and API-reference contracts cannot diverge by data mode.
+     */
+    maxPaginatedResultPerPageLimit?: number;
+};
+/**
+ * @wildo_source:part:start saas.models.resource-config.searchable-relation facet:layer:shared facet:family:resource-config
+ *
+ * Relational search descriptor — lets a SEARCH operation match rows of THIS
+ * resource by searching a RELATED ("juncted") resource's own searchable fields,
+ * WITHOUT denormalizing those fields onto this resource. Author it inline inside
+ * a SEARCH operation's `searchableFields` array, alongside plain own-field names.
+ *
+ * WHY IT EXISTS — some human-meaningful search keys live on a related resource
+ * and are MUTABLE there (e.g. a user's first/last name on a user-profile
+ * resource). Copying such a field onto this row would go stale and demand a
+ * change-propagation sync on every mutation path of the owning resource. This
+ * descriptor reuses the related resource's OWN searchable surface at query time
+ * instead — single source of truth, never stale, no sync hooks to maintain.
+ *
+ * HOW IT WORKS (tenant-safe by construction) — at search time the framework runs
+ * a secondary, system-level match on {@link relatedResource} using {@link fields}
+ * (defaulting to that resource's own string `searchableFields`), collects the
+ * matching rows' {@link relatedJoinField} values, and adds "this resource's
+ * {@link localField} is one of those values" as an extra match branch, OR-ed
+ * with the own-field matches. The primary query stays scoped (e.g. by
+ * organization) via the normal contextual filter, so the secondary match's own
+ * (often global) scope is irrelevant to safety: a row outside the caller's scope
+ * can never enter the already-scoped primary result set. Because the join
+ * collapses to a single-collection lookup, pagination and totals are unchanged.
+ *
+ * FAIL-SAFE — a relational entry only ever ADDS matches within the already-scoped
+ * set, so if the related resource cannot be resolved the entry contributes
+ * nothing (the search under-matches; it can never widen visibility).
+ *
+ * @remarks Import from `@wildo-ai/saas-models`. Supported on MongoDB-backed
+ * resources today; on a PostgreSQL-backed resource the relational entries are
+ * skipped and only the own-field entries apply (own-field search is unaffected).
+ *
+ * @example
+ * // Search org members by the linked user's name. The user's firstName/lastName
+ * // live on a separate USER_PROFILES resource (mutable) and are deliberately NOT
+ * // copied onto the member row; both members and profiles carry the same `userId`,
+ * // so we join on it and reuse the profile's own searchableFields.
+ * searchableFields: [
+ *   'userEmail',
+ *   { localField: 'userId', relatedResource: CoreResourceType.USER_PROFILES,
+ *     relatedJoinField: 'userId', fields: ['firstName', 'lastName'] },
+ * ]
+ */
+export type SearchableRelationDescriptor = {
+    /** Field on THIS resource matched against the resolved related ids (e.g. `userId`). */
+    localField: string;
+    /** The related resource whose own searchable surface is reused (e.g. `USER_PROFILES`). */
+    relatedResource: ResourceType;
+    /**
+     * Field on the related resource whose values are matched against
+     * {@link localField}'s values. Defaults to the related primary key (`_id`) —
+     * set it explicitly when joining on a shared key other than the primary key
+     * (e.g. members and profiles both carry `userId`).
+     */
+    relatedJoinField?: string;
+    /**
+     * Which related fields to match the search term against. Defaults to the
+     * related resource's OWN (string) `searchableFields` — i.e. literally "use the
+     * juncted element's own search". Provide an explicit list only to narrow it.
+     */
+    fields?: string[];
 };
+/**
+ * A SEARCH `searchableFields` entry: either an OWN-resource field name (string),
+ * matched on this collection, or a {@link SearchableRelationDescriptor} that
+ * matches via a related resource. The two forms coexist in one array and are
+ * OR-ed together at query time.
+ */
+export type SearchableFieldDescriptor = string | SearchableRelationDescriptor;
+/** Runtime guard distinguishing a relational descriptor from an own-field name. */
+export declare function isSearchableRelationDescriptor(field: SearchableFieldDescriptor): field is SearchableRelationDescriptor;
+/** @wildo_source:part:end saas.models.resource-config.searchable-relation */
 /** SEARCH-specific collection-view fields (SEARCH and custom ops with resourceOperationLike: SEARCH) */
 export type CollectionViewFields_Search = CollectionViewFields_Shared & {
     isSearchable?: boolean;
-    searchableFields?: string[];
+    /**
+     * Fields this SEARCH matches against. Each entry is either an own-collection
+     * field name or a {@link SearchableRelationDescriptor} that reaches into a
+     * related resource (see that type for the tenant-safety contract). Own-field
+     * and relational entries OR together.
+     */
+    searchableFields?: SearchableFieldDescriptor[];
     searchableOptions?: CollectionView_SearchOptions;
+    /** SEARCH's page ceiling. Same eight-site contract as the LIST field — see its JSDoc above. */
     maxPaginatedResultPerPageLimit?: number;
 };
+/**
+ * The wire selector every bulk operation carries.
+ *
+ * The DTO builder wraps EVERY `isBulkOperation` request DTO in this shape
+ * (`buildEnhancedRequestDto`), so `_ids` is the ONE field name a client may use to name the rows a
+ * bulk operation targets. It is a SELECTOR, not data: it never reaches persistence.
+ *
+ * The leading underscore is deliberate and load-bearing — it keeps the selector out of the resource's
+ * own field namespace, so a resource that legitimately owns a field called `ids` cannot collide with
+ * it. Read it through {@link BULK_OPERATION_SELECTOR_FIELD} rather than spelling the string, and
+ * resolve it through {@link readBulkOperationSelectorIds}: a producer that spells it `ids` type-checks,
+ * validates away to nothing, and then fails as "`_ids` is required" — which is exactly what every
+ * frontend bulk surface did until 2026-08-29.
+ */
 export declare const Resouces_BulkOperationBaseSchema: z.ZodObject<{
     _ids: z.ZodArray<z.ZodString>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
+/**
+ * The single named source for the bulk selector's field name.
+ *
+ * Every producer (frontend request builders) and every consumer (the service-tier target resolution,
+ * 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.
+ *
+ * Deliberately tolerant of an unparsed body: this runs at the service tier, which is reached both by
+ * the HTTP controller (where the request DTO has already validated the shape) and by MCP / batch /
+ * programmatic callers (where it has not). Anything that is not a non-empty array of non-empty
+ * strings yields `undefined`, so the caller's own missing-target refusal reports the failure rather
+ * than a half-resolved selector reaching persistence.
+ */
+export declare function readBulkOperationSelectorIds(payload: unknown): string[] | undefined;
+/**
+ * Strip the bulk selector from a request payload.
+ *
+ * `_ids` is NOT in `createOrUpdateMandatoryDiscardFields`, so without this it rides the payload all
+ * the way to the repository and is silently dropped there by the strict re-parse against the main
+ * schema. Removing it at the point the target is resolved keeps "who targets" and "what is written"
+ * separate, which is what lets the read-only-field guard reason about the payload honestly.
+ */
+export declare function stripBulkOperationSelector<T>(payload: T): T;
 export type ResourceConfiguration_OperationVariant_CustomImplementation_FunctionParameters<TMainSchema extends z.ZodTypeAny = z.ZodAny> = {
     inputDto: MainSchemaInfer<TMainSchema>;
     currentObject: MainSchemaInfer<TMainSchema>;
+    /**
+     * The row as it stood BEFORE the write (the pre-image), when the framework captured one.
+     *
+     * Present only for a SINGLE-row UPDATE/DELETE (the framework fetches a pre-image only when
+     * exactly one id is selected); `undefined` for CREATE (nothing existed) and for bulk writes.
+     * It lets a consumer reason about what CHANGED rather than only the final state. Its wired
+     * consumer today is the derived-badge recompute, which re-counts the scope a mutation moved a
+     * row OUT of (not just the one it moved it into) — see `dispatchDerivedBadgeRecomputes`. Other
+     * consumers (e.g. a `userIdsSelector` notifying the PRIOR assignee a task was taken from them)
+     * would need the notification dispatcher to forward it into the selector call first; it is not
+     * plumbed there yet. Never assume it is populated; branch on its presence.
+     */
+    previousObject?: MainSchemaInfer<TMainSchema>;
     objectContext: any;
     initiatorUserContext?: any;
     initiatorIds?: {
@@ -297,9 +912,120 @@ export type RequiredFeaturesNormalized = RequiredFeaturesFullConfig;
  * Stores both the function and metadata about its context needs.
  */
 export type ResourceConfiguration_FunctionWithContextNeeds<TFunction extends (...args: any[]) => any> = TFunction & ResourceConfiguration_FunctionContextNeeds;
+export declare enum ResourceGeneratedOperationKind {
+    GENERATED_FILE_REGENERATE = "generated_file_regenerate",
+    /** The CSV/JSON export companion of a LIST/SEARCH operation — see {@link ResourceCollectionExportConfig}. */
+    GENERATED_COLLECTION_EXPORT = "generated_collection_export"
+}
+export type ResourceConfiguration_GeneratedFileRegenerateOperationMetadata = {
+    kind: ResourceGeneratedOperationKind.GENERATED_FILE_REGENERATE;
+    fieldName: string;
+};
+/**
+ * Identifies an operation as the export companion of one LIST/SEARCH operation, and carries the
+ * export contract the handler and the frontend both read.
+ *
+ * `sourceOperationIdentifier` is what makes the export re-runnable AS the listing: the handler
+ * resolves that operation and dispatches it, rather than re-deriving a query.
+ */
+export type ResourceConfiguration_GeneratedCollectionExportOperationMetadata = {
+    kind: ResourceGeneratedOperationKind.GENERATED_COLLECTION_EXPORT;
+    /** The LIST/SEARCH operation whose result set this exports. */
+    sourceOperationIdentifier: string;
+    /** Which core verb the source is, so the handler knows which service call to make. */
+    sourceCoreOperation: CoreResourceOperation.LIST | CoreResourceOperation.SEARCH;
+    export: ResourceCollectionExportConfig;
+};
+export type ResourceConfiguration_GeneratedOperationMetadata = ResourceConfiguration_GeneratedFileRegenerateOperationMetadata | ResourceConfiguration_GeneratedCollectionExportOperationMetadata;
+/**
+ * Authored acknowledgement that an operation variant is DECLARED but knowingly NOT IMPLEMENTED.
+ *
+ * ## Why this exists
+ *
+ * A custom operation whose `requestDto` no implementation consumes does not fail — it falls
+ * through to the generic core path, which persists only fields the resource schema declares.
+ * A DTO such as `{ newRole, reason }` names none, so the framework validates the body, writes
+ * nothing, and answers **HTTP 200**. On 2026-08-01 a hostile e2e probe caught
+ * `organizationMembers | promote` doing exactly that, and a catalogue sweep found the shape in
+ * 41 routed operations — 8 CRITICAL, 11 HIGH, including `users | impersonate`,
+ * `organizations | suspend` and `applications | transfer`. A "successful" demotion that never
+ * happened is an operational-safety and audit-integrity defect: every runbook, script, and UI
+ * that trusts the 2xx is wrong.
+ *
+ * ## What it does
+ *
+ * Presence is a fail-closed declaration with TWO effects, never one without the other:
+ *
+ *  1. **Startup is allowed to proceed.** Without it, an unserviceable operation is a startup
+ *     ERROR (`ApplicationStartupConfigValidatorService`), so a new one cannot ship silently.
+ *  2. **The request fails closed.** The dispatcher refuses the operation before any persistence
+ *     with `ErrorType.CONFIGURATION` /
+ *     `ErrorCustomMessageReference.RESOURCE_OPERATION_CUSTOM_IMPLEMENTATION_NOT_IMPLEMENTED`.
+ *     Acknowledging a gap must never preserve the 2xx — that would document the defect instead
+ *     of closing it.
+ *
+ * The guard is BIDIRECTIONAL: an acknowledgement on an operation that IS serviceable is also a
+ * startup error, so a stale marker can never brick an operation someone has since implemented.
+ *
+ * ## This is a stop-gap, not a resting place
+ *
+ * The right end states are to implement the operation (see the organization-units
+ * MOVE/ARCHIVE pattern — a `prefixCoreOperations` hook returning the field patch the core
+ * write persists) or to remove the declaration. Reach for this only to keep a known gap
+ * honest while it is scheduled.
+ *
+ * assurance-control: WILDO.OPERATIONS.EXECUTION_INTEGRITY — an interface must not report success for an
+ * action it did not perform; monitoring and incident response depend on the response being
+ * truthful.
+ */
+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. */
+    trackingRef: string;
+};
+/**
+ * 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";
+/**
+ * Acknowledge an engine operation as a known, fail-closed implementation gap.
+ *
+ * Requires a SPECIFIC reason: "not implemented" is what the marker already says, so a reason
+ * 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.
+ */
+export declare const acknowledgeUnimplementedEngineOperation: (reason: string) => ResourceOperation_UnimplementedAcknowledgement;
+/**
+ * Declarative control over this variant's audit emission.
+ *
+ * **The baseline needs no declaration.** Every `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.
+ */
+export type ResourceOperation_AuditableEvent = {
+    /**
+     * Emit for this variant even though its `riskLevel` is below the automatic floor.
+     *
+     * For a `MEDIUM` / `LOW` verb whose danger is not proportional to its blast radius — the risk
+     * level answers "how alarming is the UI affordance", which is a related but not identical
+     * question to "is this evidence an auditor needs".
+     */
+    auditBelowRiskFloor?: boolean;
+};
 type ResourceConfiguration_OperationVariant_Base<TMainSchema extends z.ZodTypeAny = z.ZodAny> = {
     variantType: ResourceOperationVariantType;
     resourceOperationLike?: CoreResourceOperation;
+    generatedOperation?: ResourceConfiguration_GeneratedOperationMetadata;
     /**
      * Feature gating for this operation variant.
      * Shorthand: `string[]` auto-normalized by factory to `{ features: [...], mode: 'OR' }`.
@@ -310,6 +1036,226 @@ type ResourceConfiguration_OperationVariant_Base<TMainSchema extends z.ZodTypeAn
     variantKey?: string;
     riskLevel: ResourceOperationRiskLevel;
     roles: Roles[];
+    /**
+     * Per-foreign-key policy for REFERENCE fields this variant writes — the TARGET-side counterpart of
+     * `roles` above (which gates the CALLER).
+     *
+     * A relationship that declares `scopeMembership` already guarantees the baseline: the referenced row
+     * must be linked to the writing row's scope through a junction (that is tenant isolation, and it
+     * applies to every variant). This map TIGHTENS that baseline for THIS variant, keyed by foreign-key
+     * field — require an `ACTIVE` membership, an `ORG_ADMIN` assignee, a typed partnership — or `false`
+     * to disable it for one foreign key on one variant.
+     *
+     * Omit entirely (the common case): the relationship's baseline membership applies unchanged.
+     *
+     * @example an "assign reviewer" variant whose assignee must be an ACTIVE org admin
+     * referenceConstraints: {
+     *   assignedToUserId: {
+     *     qualifyingStatuses: ['ACTIVE'],
+     *     requiredRoles: { scope: ResourcePrimaryScope.ORGANIZATIONS, roles: [CORE_ORG_ROLES.ORG_ADMIN] },
+     *   },
+     * }
+     */
+    referenceConstraints?: ReferenceConstraints;
+    /**
+     * Declares this variant a KNOWN, fail-closed implementation gap.
+     * See {@link ResourceOperation_UnimplementedAcknowledgement} — presence both unblocks
+     * startup and makes the request refuse, so an acknowledged operation never answers 2xx.
+     */
+    unimplementedAcknowledgement?: ResourceOperation_UnimplementedAcknowledgement;
+    /**
+     * Declarative control over this variant's audit emission — see
+     * {@link ResourceOperation_AuditableEvent}. Omit it: `HIGH` / `CRITICAL` variants are audited
+     * automatically, and everything else is deliberately not.
+     */
+    auditableEvent?: ResourceOperation_AuditableEvent;
+    /**
+     * Demand a FRESH proof of identity for this specific operation, regardless of how recently the
+     * caller authenticated.
+     *
+     * The framework's baseline step-up is a per-USER-TYPE policy (`UserTypeAuthPolicy.stepUpAuth`):
+     * opt-in, defaulting to `enabled: false`, and *freshness*-based — it challenges only once the
+     * session's `lastAuthenticatedAt` is older than `maxAgeSeconds` (default 300). That is the right
+     * shape for "this tenant wants periodic re-proof across the board", and the wrong shape for a
+     * single irreversible action: a caller who signed in two minutes ago destroys the resource with
+     * no credential proof at all, and an application that never configures `stepUpAuth` is never
+     * challenged for anything.
+     *
+     * Setting this to `true` makes the challenge UNCONDITIONAL for this operation. The caller must
+     * present a valid single-use `REAUTH` consumable token (minted by `POST /auth/reauth`, carried in
+     * `X-Reauth-Token`); otherwise the request is refused with `STEP_UP_REQUIRED` (HTTP 403). The
+     * frontend HTTP client already completes this loop — it catches the 403, runs the registered
+     * step-up handler to obtain a token, and replays the request — so declaring the flag is the whole
+     * integration.
+     *
+     * FAIL-CLOSED by design: an operation that declares this is challenged even when the user type
+     * has NO `stepUpAuth` policy at all. Deriving the requirement from `riskLevel` was rejected —
+     * `riskLevel` is a UI/observability signal (danger-zone placement, typed confirmation, MCP
+     * destructive hints), read today by no authorization code, and silently promoting it to a security
+     * control would change the behaviour of every existing `CRITICAL` operation at once.
+     *
+     * Applies only to principals whose identity can be re-proved: user requests that are not
+     * sub-calls. Machine principals, internal calls and worker executions are exempt exactly as they
+     * are for the baseline policy — there is no interactive credential to re-present.
+     *
+     * ⚠️ **Check who can actually satisfy it before declaring it.**
+     * `AuthMethodManagementBackendService.reAuthenticate` proves identity by PASSWORD only today
+     * (`AuthMethod.PASSKEY` is declared and explicitly refused as not yet supported), and it requires
+     * a real `passwordHash` on the principal's credential row — a user-type policy that merely enables
+     * `PASSWORD` is necessary but NOT sufficient.
+     *
+     * Two populations therefore cannot satisfy this gate:
+     *
+     *  - a user type whose `authMethodsEnabled` excludes `PASSWORD` (SSO-only, passkey-only) — note
+     *    this is also reachable through a per-ORGANIZATION `authMethodsEnabled` override, so an
+     *    app-level policy is not the whole answer;
+     *  - **directory-managed (SCIM) users**, whose `passwordHash` AND passkeys the framework
+     *    DELIBERATELY DESTROYS as a compliance control
+     *    (`_reconcileLocalCredentialsForDirectoryManaged` — a local first factor would survive IdP
+     *    deprovisioning). Their TOTP is intentionally preserved, but re-auth cannot use it yet.
+     *
+     * For those principals the operation is permanently refused. That is fail-closed rather than
+     * unsafe, and the refusal is diagnosable (the step-up round-trip ends in an explicit "No password
+     * set for this account") — but it is a product decision, not a detail. Do not declare this flag on
+     * an operation those populations are expected to perform until re-authentication covers a factor
+     * they hold.
+     *
+     * 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
+     * contract. A `{ password }` field cannot adapt to any of the above.
+     *
+     * assurance-control: WILDO.IDENTITY.STEP_UP_AUTHENTICATION — re-authentication before a high-impact action.
+     */
+    /**
+     * 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.
+     *
+     * ## Why this exists, and why it is per-variant rather than global
+     *
+     * `validateParentScopeAccess` authorizes an organization-scoped operation by finding an
+     * organization-WIDE `initiatorRoles` entry whose `relatedResourceId` is the target organization. A
+     * platform super-administrator holds an APPLICATION-scope entry and therefore matches nothing — so
+     * 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`.
+     *
+     * 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
+     * repair it only from a higher authorized tier. This flag is that higher-tier
+     * exception and nothing else.
+     *
+     * **It is deliberately NOT a global super-admin bypass.** Adding one to the authorization layer
+     * would grant cross-tenant reach to EVERY org-scoped operation whose gate a super-admin's role
+     * chain satisfies — an enormous, silent widening of tenant isolation. Instead each variant opts in
+     * explicitly, so the admitted surface is enumerable by grep and empty by default.
+     *
+     * ## Conditions, all required
+     *
+     * - The caller must hold `APP_ADMIN_SUPER_ADMIN` at **APPLICATION** scope. An organization-scoped
+     *   role string that merely spells the same name confers nothing: `getRoleHierarchy` partitions the
+     *   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.
+     *
+     * 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.
+     *
+     * assurance-control: WILDO.ACCESS.CROSS_TENANT_ADMINISTRATION — an explicitly enumerated,
+     * platform-tier admission across a tenant boundary that is otherwise absolute.
+     */
+    admitsCrossTenantPlatformAdministration?: boolean;
+    /**
+     * Admits this variant to address a USER other than the caller — the USER_SELF-scope sibling of
+     * {@link admitsCrossTenantPlatformAdministration}, and it follows that flag's doctrine exactly:
+     * per-variant, empty by default, enumerable by grep.
+     *
+     * ## Why it is needed
+     *
+     * `authorizeUserSelf` authorizes a USER_SELF-scoped operation by requiring the addressed row to BE
+     * the caller. On `USERS` — whose `resourcePrimaryScope` IS `USER_SELF`, because the resource is a
+     * self-anchor scope root — that made the entire administrative surface self-only: `assign_roles`,
+     * `revoke_roles`, `suspend_user`, `unsuspend_user`, `force_password_reset`, the admin READ and the
+     * core UPDATE/DELETE all refused `authorizations_access_denied` against another user, while the
+     * specification documents every one of them as acting on "another user's record" and the admin UI
+     * surfaces them as per-row actions.
+     *
+     * ## Why it is PER-VARIANT and not per-resource
+     *
+     * This is the whole reason a resource-level declaration cannot serve. Within `USERS` the two READ
+     * variants need OPPOSITE answers:
+     *
+     *  - the DEFAULT read is gated `APP_USER`. Admitting cross-subject addressing there would let ANY
+     *    authenticated user read ANY other user's row — `email`, `appRoles`, `status` — a privacy and
+     *    enumeration regression far worse than the bug being fixed.
+     *  - the `admin` read is gated `APP_ADMIN_VIEWER` and is precisely the surface that SHOULD address
+     *    others.
+     *
+     * One resource, one field identifier, two required answers. Only the variant can carry it.
+     *
+     * ## What still protects the surface
+     *
+     * This flag relaxes WHOSE row may be addressed. It does not touch 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; this decides whose. Declare it only where the
+     * operation's PURPOSE is administering another person, and expect each one to justify itself.
+     *
+     * assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — an administrative action on another principal
+     * is authorized by the caller's ROLE, never by caller and subject being the same person.
+     */
+    admitsCrossSubjectUserAdministration?: boolean;
+    requiresStepUpAuthentication?: boolean;
+    /**
+     * Default **frontend surface** for this operation when no app preset declares
+     * one (see {@link ResourceOperationFrontendSurface}). Lets the framework mark
+     * an operation headless-by-default (`API_ONLY`) — e.g. system/workflow/signup
+     * -driven creates — so apps don't re-author `apiOnly()` per app. An app preset
+     * that surfaces the operation (`addressable()`/`notAddressable()`/`apiOnly()`)
+     * always wins; this is only the fallback. When unset, an unsurfaced operation
+     * resolves to `API_ONLY` (the safe default — callable, no UI). Display-only:
+     * never affects authorization.
+     */
+    defaultFrontendPosture?: ResourceOperationFrontendSurface;
+    /**
+     * @wildo_source:part:start saas.models.resource-config.operation-mcp-exposure facet:layer:shared facet:family:resource-config
+     *
+     * MCP (Model Context Protocol) exposure for this operation. Set `exposed: true` to
+     * surface the operation as an MCP tool that authenticated machine / agent callers can
+     * discover (`tools/list`) and invoke (`tools/call`). Import path: `@wildo-ai/saas-models`
+     * — 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.
+     *
+     * `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
+     * specification's `purpose` / `whenToUse`, then to a synthesized default; keep an authored
+     * `description` reconciled with the spec.
+     *
+     * Exposure is a DISCOVERY gate ONLY. Every `tools/call` still re-runs the operation's own
+     * role authorization against the CALLER's roles before dispatch, so exposing an operation can
+     * never widen who is allowed to perform it.
+     *
+     * `servers` selects WHICH named MCP server(s) carry this tool when the app declares more than one
+     * (each server is a separate endpoint + audience, so a token for one is rejected at another). OMIT it
+     * for the DEFAULT server — the plain `/mcp` endpoint every app has. When PRESENT it must name at least
+     * one declared server: an EMPTY array is a startup error, not a silent fallback, so the field always
+     * reads as "exactly these" (the same omitted-vs-present rule an A2A agent's `actorSystemRefs` follows).
+     * Naming a server the app does not declare is likewise a startup error (fail-closed), so a typo can
+     * never conjure a phantom surface.
+     *
+     * Membership is EXCLUSIVE: an operation naming a server LEAVES the default `/mcp` catalog rather than
+     * appearing on both, so curation is always a deliberate move and never an accidental duplication.
+     */
+    mcp?: {
+        exposed?: boolean;
+        description?: string;
+        servers?: string[];
+    };
+    /** @wildo_source:part:end saas.models.resource-config.operation-mcp-exposure */
     requestDto?: z.ZodSchema<any>;
     /**
      * RepositoryDto for repository projection.
@@ -323,8 +1269,45 @@ type ResourceConfiguration_OperationVariant_Base<TMainSchema extends z.ZodTypeAn
      * Can optionally specify needsObjectContext/needsUserContext flags:
      * basicPrefixOperation.needsObjectContext = true
      * basicPrefixOperation.needsUserContext = true
+     *
+     * Returns a PATCH, not a replacement: the service MERGES the result onto the payload
+     * (`coreInput = { ...coreInput, ...result }`) and whitelists the keys the hook ADDED into
+     * `preserveServerInjectedFields`, so they survive the repository's strict re-parse. Naming
+     * 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.
      */
-    basicPrefixOperation?: ResourceConfiguration_FunctionWithContextNeeds<(params: ResourceConfiguration_OperationVariant_CustomImplementation_FunctionParameters<TMainSchema>) => MainSchemaInfer<TMainSchema>>;
+    basicPrefixOperation?: ResourceConfiguration_FunctionWithContextNeeds<(params: ResourceConfiguration_OperationVariant_CustomImplementation_FunctionParameters<TMainSchema>) => Partial<MainSchemaInfer<TMainSchema>>>;
+    /**
+     * Fields whose value this operation's {@link basicPrefixOperation} OWNS.
+     *
+     * Declare a field here when the hook must set it EVEN IF the caller also supplied it. The
+     * "keys the hook ADDED" inference described above is derived from a snapshot of the payload
+     * taken at the SERVICE tier, after a LOOSE parse (`z.looseObject`) that passes unknown keys
+     * through. A caller that reaches that tier with the field already present — MCP `callTool`
+     * forwards its arguments with no strict parse — puts the key into the snapshot, so the hook's
+     * own value stops being treated as injected, the repository's strict re-parse drops it, and the
+     * 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.
+     *
+     * 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
+     * need to, because a caller could not have supplied it under a strict contract anyway.
+     *
+     * Typed `readonly string[]` rather than `keyof MainSchemaInfer<TMainSchema>`: this type is shared
+     * by the authoring parameters AND the built operation, and the built side is assembled behind a
+     * type-erased generic where `keyof` collapses to `never`. The stronger check lives at BOOT
+     * instead — `collectResourceOperationAuthoritativeFieldIssues` refuses startup when a declared
+     * name is not a persisted field of the resource. That guard is strictly better than the
+     * compile-time one would have been, because it also covers custom-implementation registrations,
+     * whose declarations are plain strings with no schema generic to check against. A typo must fail
+     * loudly: silently declaring nothing would restore the exact no-op this contract prevents.
+     */
+    authoritativeFields?: readonly string[];
 };
 type ResourceConfiguration_OperationVariant_ApiCall_BuilderParameters<TMainSchema extends z.ZodTypeAny = z.ZodAny> = ResourceConfiguration_OperationVariant_Base<TMainSchema> & {
     variantType: ResourceOperationVariantType.API_CALL;
@@ -338,6 +1321,30 @@ type ResourceConfiguration_OperationVariant_ApiCall_BuilderParameters<TMainSchem
     /** Declarative token revocation config — revokes tokens before the core operation (e.g., on DELETE) */
     tokenRevocation?: TokenRevocationConfig;
     customResponseDto?: z.ZodSchema<any>;
+    /**
+     * Per-endpoint rate-limit policy.
+     *
+     * When present, the resource controller's pre-flight check enforces this
+     * policy BEFORE execution-context creation, request validation, and
+     * authorization (via `RateLimitBackendService.checkPolicyForVariant`). At
+     * that seam the authenticated identity is not yet known, so the client
+     * identifier is the IP address (`getClientIpFromRequest`).
+     *
+     * When absent, only the global HTTP rate-limit
+     * (`RuntimeConfig.httpServerConfiguration.rateLimiting`) gates this route
+     * — that limiter is the safety net for endpoints with no per-endpoint
+     * policy.
+     *
+     * Multiple windows AND together (most restrictive wins). On 429 the
+     * `X-RateLimit-*` headers report the **tightest active window** (fewest
+     * remaining slots), while `Retry-After` / `retryAfterSeconds` reports
+     * the **latest tripped window** because declared windows are AND-ed.
+     * These can be different windows when multiple trip simultaneously.
+     *
+     * The declared policy is surfaced through standard rate-limit response
+     * headers and retry guidance, so callers see the same request budget.
+     */
+    rateLimit?: RateLimitConfiguration;
     /**
      * Function to determine if operation variant is enabled.
      * Available in both frontend and backend.
@@ -359,6 +1366,15 @@ type ResourceConfiguration_OperationVariant_ApiCallWithCallback_BuilderParameter
     /** Declarative token revocation config — revokes tokens before the core operation (e.g., on DELETE) */
     tokenRevocation?: TokenRevocationConfig;
     customResponseDto?: z.ZodSchema<any>;
+    /**
+     * Per-endpoint rate-limit policy. Same semantics as on the API_CALL
+     * variant — enforced pre-flight by the resource controller before EC
+     * creation, validation, and authorization.
+     *
+     * The declared policy is surfaced through standard rate-limit response
+     * headers and retry guidance, so callers see the same request budget.
+     */
+    rateLimit?: RateLimitConfiguration;
     /**
      * Function to determine if operation variant is enabled.
      * Available in both frontend and backend.
@@ -374,6 +1390,18 @@ type ResourceConfiguration_OperationVariant_ApiCallWithCallback_BuilderParameter
 type ResourceConfiguration_OperationVariant_CronJob_BuilderParameters = ResourceConfiguration_OperationVariant_Base & {
     variantType: ResourceOperationVariantType.CRON_JOB;
     cronExpression: string;
+    /**
+     * Explicit response contract for a CRON_JOB custom operation whose return shape
+     * is NOT the resource row implied by `resourceOperationLike`. A scheduled
+     * generator/sweeper (e.g. a recurring-occurrence generator) borrows a core verb
+     * (UPDATE/CREATE) for its repo/DTO semantics but returns a RUN SUMMARY, not an
+     * occurrence. The factory already reads `customResponseDto` off any variant
+     * params (`resources-config.shared.factory.ts`) and warns when a borrowed-verb
+     * custom op omits it — this exposes it on the CRON_JOB params so the cron op can
+     * declare its true return shape instead of inheriting the verb's occurrence
+     * -shaped envelope (which the executor would reject the summary against).
+     */
+    customResponseDto?: z.ZodSchema<any>;
 };
 type ResourceConfiguration_OperationVariant_BatchJob_BuilderParameters = ResourceConfiguration_OperationVariant_Base & {
     variantType: ResourceOperationVariantType.BATCH_JOB;
@@ -385,9 +1413,13 @@ type ResourceConfiguration_OperationVariant_RepositoryOnly_BuilderParameters = R
     variantType: ResourceOperationVariantType.REPOSITORY_ONLY;
 };
 /**
+ * @wildo_source:part:start saas.models.resource-config.operation-base facet:layer:shared facet:family:resource-config
+ *
  * Base operation configuration type.
  * NOTE: TDatabaseSchema has been removed. Backend-only fields are now marked with
  * the isBackendOnly decorator in mainSchema and are stripped at the service layer.
+ *
+ * @remarks Import from `@wildo-ai/saas-models`. App `resources-config` fills these per operation variant.
  */
 export type ResourceConfiguration_Operation_Base<TCustomOperationEnum extends EnumLikeType | undefined, TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined, TMainSchema extends z.ZodTypeAny = z.ZodAny> = ResourceConfiguration_OperationVariant_Base<TMainSchema> & {
     isDisabled: boolean;
@@ -400,8 +1432,16 @@ export type ResourceConfiguration_Operation_Base<TCustomOperationEnum extends En
     operationIdentifier: TCustomOperationEnum | TCoreOperationEnum;
     isOperationDefault: boolean;
     serviceRuntimeMode: ResourceOperation_ServiceRuntimeMode;
+    generatedOperation?: ResourceConfiguration_GeneratedOperationMetadata;
     requestDto?: z.ZodSchema<any>;
     responseDto?: z.ZodSchema<any>;
+    /** Set by factory when an explicit `requestDto` was provided in variant params.
+     * Allows the DTO builder to skip heuristic comparison and trust the flag:
+     * `true` ⇒ preserve the supplied schema verbatim; `false` ⇒ the requestDto is
+     * the factory's auto-derived temporary placeholder, so always use the
+     * inheritance-rebuilt DTO (a discriminated union for inheritance resources).
+     * Absent only on legacy/hand-authored operations that predate the flag. */
+    hasCustomRequestDto?: boolean;
     /** Set by factory when `customResponseDto` was explicitly provided in variant params.
      * Allows the DTO builder to skip heuristic comparison and always preserve the custom schema. */
     hasCustomResponseDto?: boolean;
@@ -436,6 +1476,7 @@ export type ResourceConfiguration_Operation_Base<TCustomOperationEnum extends En
     userNotifications: UserNotificationDefinition[];
     m2mNotifications: M2MNotificationDefinitionWithoutIdentifier[];
 };
+/** @wildo_source:part:end saas.models.resource-config.operation-base */
 /**
  * Base operation type - explicitly extracted for better type checking performance.
  * TypeScript can cache this more efficiently when it's a named type alias.
@@ -455,6 +1496,14 @@ export type ResourceConfiguration_Operation_InternalCall<TCustomOperationEnum ex
 export type ResourceConfiguration_Operation_RepositoryOnly<TCustomOperationEnum extends EnumLikeType | undefined, TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined, TMainSchema extends z.ZodTypeAny = z.ZodAny> = ResourceConfiguration_Operation_Base<TCustomOperationEnum, TCoreOperationEnum, TMainSchema> & {
     variantType: ResourceOperationVariantType.REPOSITORY_ONLY;
 };
+/**
+ * @wildo_source:part:start saas.models.resource-config.operation-api-call facet:layer:shared facet:family:resource-config
+ *
+ * HTTP API surface for an operation: URL templates, method, tokens,
+ * enabledCondition, and per-endpoint rate-limit policy (`rateLimit?`).
+ *
+ * @remarks Import from `@wildo-ai/saas-models`.
+ */
 export type ResourceConfiguration_Operation_UrlParameterInfo = {
     fieldIdentifier: string;
     resourceType: ResourceType;
@@ -464,6 +1513,17 @@ export type ResourceConfiguration_Operation_UrlParameterInfo = {
      * undefined for default parent relationships.
      */
     relationshipField?: string;
+    /**
+     * Scope-via-junction tag, propagated from the synthetic scope-anchored parent
+     * edge (`ResourceRelationship.scopeViaJunction`). When set, this param scopes
+     * the (target) resource's SEARCH/LIST through the named junction `J` rather
+     * than via a direct column the resource owns — e.g. on
+     * `/organizations/{organizationId}/users/search`, `organizationId` carries
+     * `scopeViaJunction: 'organizationMembers'`. The backend contextual filter +
+     * authorization read this off the runtime relationship context. Absent on
+     * normal parent params.
+     */
+    scopeViaJunction?: ResourceType;
 };
 export type ResourceConfiguration_Operation_UrlInitiatorInfo = {
     url: string;
@@ -479,6 +1539,22 @@ export type ResourceConfiguration_Operation_ApiCall<TCustomOperationEnum extends
     tokenAuthentication?: TokenAuthenticationConfig;
     tokenGeneration?: TokenGenerationConfig;
     tokenRevocation?: TokenRevocationConfig;
+    /**
+     * Resolved per-endpoint rate-limit policy (forwarded by the resource
+     * configuration factory from the variant builder parameters). Read at
+     * runtime by `RateLimitBackendService.checkPolicyForVariant` at the
+     * controller pre-flight seam (`controller-resource.backend.service.ts`
+     * → `doOperation`).
+     *
+     * Auto-variants (`SUMMARY` / `CONTEXT` for READ/LIST) inherit this
+     * field from their default URL-bearing variant (`API_CALL` or
+     * `API_CALL_WITH_CALLBACK`) — a single declaration on the default variant
+     * covers all derived auto-variants by design.
+     *
+     * The declaration is inherited by derived variants so every route for this
+     * operation presents one consistent request budget.
+     */
+    rateLimit?: RateLimitConfiguration;
     /**
      * Function to determine if operation variant is enabled.
      * Available in both frontend and backend.
@@ -488,6 +1564,7 @@ export type ResourceConfiguration_Operation_ApiCall<TCustomOperationEnum extends
      */
     enabledCondition?: ResourceConfiguration_FunctionWithContextNeeds<(params: ResourceConfiguration_OperationVariant_CustomImplementation_FunctionParameters<TMainSchema>) => boolean>;
 };
+/** @wildo_source:part:end saas.models.resource-config.operation-api-call */
 export type ResourceConfiguration_Operation_ApiCallWithCallback<TCustomOperationEnum extends EnumLikeType | undefined, TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined, TMainSchema extends z.ZodTypeAny = z.ZodAny> = ResourceConfiguration_Operation_Base<TCustomOperationEnum, TCoreOperationEnum, TMainSchema> & {
     variantType: ResourceOperationVariantType.API_CALL_WITH_CALLBACK;
     httpVerb: HttpMethod;
@@ -497,6 +1574,14 @@ export type ResourceConfiguration_Operation_ApiCallWithCallback<TCustomOperation
     tokenAuthentication?: TokenAuthenticationConfig;
     tokenGeneration?: TokenGenerationConfig;
     tokenRevocation?: TokenRevocationConfig;
+    /**
+     * Resolved per-endpoint rate-limit policy. Same semantics as on the
+     * API_CALL variant.
+     *
+     * The declaration is inherited by derived variants so every route for this
+     * operation presents one consistent request budget.
+     */
+    rateLimit?: RateLimitConfiguration;
     /**
      * Function to determine if operation variant is enabled.
      * Available in both frontend and backend.
@@ -511,6 +1596,8 @@ export type ResourceConfiguration_Operation_ApiCallWithCallback<TCustomOperation
 };
 export type ResourceConfiguration_OperationVariant_BuilderParameters<TMainSchema extends z.ZodTypeAny = z.ZodAny> = ResourceConfiguration_OperationVariant_ApiCall_BuilderParameters<TMainSchema> | ResourceConfiguration_OperationVariant_ApiCallWithCallback_BuilderParameters<TMainSchema> | ResourceConfiguration_OperationVariant_CronJob_BuilderParameters | ResourceConfiguration_OperationVariant_BatchJob_BuilderParameters | ResourceConfiguration_OperationVariant_InternalCall_BuilderParameters | ResourceConfiguration_OperationVariant_RepositoryOnly_BuilderParameters;
 /**
+ * @wildo_source:part:start saas.models.resource-config.operation-variant-for-key facet:layer:shared facet:family:resource-config
+ *
  * Variant builder type that distributes operation-specific fields based on the operation key.
  *
  * Collection-view fields are intersected with the **full** variant union — not restricted to
@@ -523,7 +1610,11 @@ export type ResourceConfiguration_OperationVariant_BuilderParameters<TMainSchema
  * explicitly through custom operation identifiers plus variant/runtime config,
  * not through a special core operation.
  */
-export type OperationVariant_ForKey<K, TMainSchema extends z.ZodTypeAny = z.ZodAny> = K extends CoreResourceOperation.LIST ? ResourceConfiguration_OperationVariant_BuilderParameters<TMainSchema> & CollectionViewFields_List : K extends CoreResourceOperation.SEARCH ? ResourceConfiguration_OperationVariant_BuilderParameters<TMainSchema> & CollectionViewFields_Search : ResourceConfiguration_OperationVariant_BuilderParameters<TMainSchema>;
+export type OperationVariant_ForKey<K, TMainSchema extends z.ZodTypeAny = z.ZodAny> = K extends CoreResourceOperation.LIST ? ResourceConfiguration_OperationVariant_BuilderParameters<TMainSchema> & CollectionViewFields_List : K extends CoreResourceOperation.SEARCH ? ResourceConfiguration_OperationVariant_BuilderParameters<TMainSchema> & CollectionViewFields_Search : K extends CoreResourceOperation ? ResourceConfiguration_OperationVariant_BuilderParameters<TMainSchema> : ResourceConfiguration_OperationVariant_BuilderParameters<TMainSchema> | (ResourceConfiguration_OperationVariant_BuilderParameters<TMainSchema> & {
+    resourceOperationLike: CoreResourceOperation.LIST;
+} & CollectionViewFields_List) | (ResourceConfiguration_OperationVariant_BuilderParameters<TMainSchema> & {
+    resourceOperationLike: CoreResourceOperation.SEARCH;
+} & CollectionViewFields_Search);
 /**
  * Operation config with variant type narrowed by operation key.
  * Distributes at the operation-config level; collection-view fields live on the variant.
@@ -542,7 +1633,19 @@ export type OperationConfig_ForKey<K, TMainSchema extends z.ZodTypeAny = z.ZodAn
     }[];
     m2mNotifications?: M2MNotificationDefinitionWithoutIdentifier[];
 };
+/** @wildo_source:part:end saas.models.resource-config.operation-variant-for-key */
+/**
+ * @wildo_source:part:start saas.models.resource-config.operation-union facet:layer:shared facet:family:resource-config
+ *
+ * Discriminated union of resolved operation configuration shapes (variant discriminant).
+ */
 export type ResourceConfiguration_Operation<TCustomOperationEnum extends EnumLikeType | undefined, TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined, TMainSchema extends z.ZodTypeAny = z.ZodAny> = ResourceConfiguration_Operation_ApiCall<TCustomOperationEnum, TCoreOperationEnum, TMainSchema> | ResourceConfiguration_Operation_ApiCallWithCallback<TCustomOperationEnum, TCoreOperationEnum, TMainSchema> | ResourceConfiguration_Operation_CronJob<TCustomOperationEnum, TCoreOperationEnum, TMainSchema> | ResourceConfiguration_Operation_BatchJob<TCustomOperationEnum, TCoreOperationEnum, TMainSchema> | ResourceConfiguration_Operation_InternalCall<TCustomOperationEnum, TCoreOperationEnum, TMainSchema> | ResourceConfiguration_Operation_RepositoryOnly<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>;
+/** @wildo_source:part:end saas.models.resource-config.operation-union */
+/**
+ * @wildo_source:part:start saas.models.resource-config.operation-path facet:layer:shared facet:family:resource-config
+ *
+ * Path key for routing: resource, operation, variant, optional variantKey / bulk.
+ */
 export type ResourceConfiguration_OperationPath<TCustomOperationEnum extends EnumLikeType | undefined, TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined> = {
     resourceIdentifier: ResourceType;
     operationIdentifier: TCustomOperationEnum | TCoreOperationEnum;
@@ -551,6 +1654,7 @@ export type ResourceConfiguration_OperationPath<TCustomOperationEnum extends Enu
     isBulkOperation?: boolean;
     variantKey?: string;
 };
+/** @wildo_source:part:end saas.models.resource-config.operation-path */
 export type ResourceConfiguration_OperationRepositoryPath = {
     resourceIdentifier: ResourceType;
     operationIdentifier: CoreResourceOperation;
@@ -593,7 +1697,232 @@ export type ResourceConfiguration_Operation_BuilderParameters<TMainSchema extend
     }[];
     m2mNotifications?: M2MNotificationDefinitionWithoutIdentifier[];
 };
+/**
+ * @wildo_source:part:start saas.models.resource-config.builder-parameters facet:layer:shared facet:family:resource-config
+ *
+ * Valid operation keys from core + custom enums, and builder params for `createResourceConfiguration`.
+ */
 export type ValidOperationKeys<TCustomOperationEnum extends EnumLikeType | undefined, TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined> = (TCustomOperationEnum extends EnumLikeType ? EnumValues<TCustomOperationEnum> : never) | (TCoreOperationEnum extends Partial<CoreResourceOperation> ? TCoreOperationEnum : never);
+/**
+ * @wildo_source:part:start saas.models.resource-config.system-access-policy facet:layer:shared facet:family:resource-config
+ *
+ * Access mode for the ACL-bypassing system-context reads
+ * (`SystemAccessBackendService.readAsSystem` / `listAsSystem`, from
+ * `@wildo-ai/saas-backend-lib`).
+ *
+ * Those primitives run with a synthesised super-admin execution context and
+ * therefore SKIP the caller's scope and role checks entirely. A resource is
+ * readable that way ONLY if its resource configuration opts the verb in. Any
+ * verb left undeclared defaults to `FORBIDDEN`: a system read of a resource
+ * that has not opted in throws `ErrorType.CONFIGURATION` — the framework is
+ * fail-closed here by construction.
+ */
+export declare enum ResourceSystemAccessMode {
+    /** The verb's system-context primitive is rejected for this resource (default). */
+    FORBIDDEN = "FORBIDDEN",
+    /** The verb's system-context primitive is permitted for this resource. */
+    ALLOWED = "ALLOWED"
+}
+/**
+ * Per-resource opt-in policy for the ACL-bypassing system-context primitives
+ * on `SystemAccessBackendService`: the reads (`readAsSystem` / `listAsSystem`)
+ * and the trusted writes (`createAsSystem` / `updateAsSystem` /
+ * `updateManyAsSystem`).
+ *
+ * A system-context call does not REMOVE the authorization decision — it
+ * RELOCATES it from the resource ACL onto the calling service, which MUST
+ * enforce an explicit alternative check (e.g. consumable-token or
+ * email-ownership matching). Declaring this policy is the data owner's
+ * statement that such a bypass is permissible at all, and for which verb. An
+ * absent policy — or a verb set to (or left defaulting to) `FORBIDDEN` — makes
+ * the primitive throw.
+ *
+ * The WRITE verbs additionally let a trusted in-process caller persist the
+ * fields the client-shaped request DTO strips — `.isBackendOnly()` material
+ * (e.g. a credential `passwordHash`) and the context-auto-populated FKs (e.g.
+ * `userId` on a system resource that has no HTTP surface to seed it) — by
+ * re-attaching exactly those fields after the strict parse. They are the
+ * sanctioned path for engine flows like registration that must write system
+ * resources directly; opting a verb in is the data owner's acknowledgement that
+ * a super-admin-context mutation of this resource is legitimate.
+ *
+ * Caveats a system-context call inherits (it runs as super-admin), to weigh
+ * before opting in:
+ *  - a READ returns the FULL record — every field, including ones a normal
+ *    caller's role / field-visibility would hide — so never forward the result
+ *    verbatim to an under-privileged caller; project only what is safe.
+ *  - a WRITE bypasses the caller's scope + role ACL, so the calling service
+ *    owns the authorization decision (only trusted engine code can reach the
+ *    primitive — it is never exposed to an HTTP payload).
+ *  - feature flags do not gate it (it is an internal request).
+ *  - the policy is RESOURCE-LEVEL: for a polymorphic resource it is shared by
+ *    every scope variant (declare it once on the shared config).
+ *
+ * Intentionally DISTINCT from `isSystemResource`: marking a resource as
+ * framework infrastructure does NOT imply that an ACL bypass is acceptable
+ * for its data. Keep the two concepts separate.
+ */
+export type ResourceSystemAccessPolicy = {
+    /** Governs `readAsSystem`. Omitted ⇒ FORBIDDEN. */
+    read?: ResourceSystemAccessMode;
+    /** Governs `listAsSystem`. Omitted ⇒ FORBIDDEN. */
+    list?: ResourceSystemAccessMode;
+    /** Governs `createAsSystem`. Omitted ⇒ FORBIDDEN. */
+    create?: ResourceSystemAccessMode;
+    /** Governs `updateAsSystem`. Omitted ⇒ FORBIDDEN. */
+    update?: ResourceSystemAccessMode;
+    /** Governs `updateManyAsSystem`. Omitted ⇒ FORBIDDEN. */
+    updateMany?: ResourceSystemAccessMode;
+    /**
+     * Governs the impersonalization see-through reads (`readRetainedAsSystem` /
+     * `listRetainedAsSystem`) — the privileged, audited path that reveals
+     * `retentionStatus = RETAINED` rows hidden-by-default. Omitted ⇒ FORBIDDEN.
+     * Auto-derived to `ALLOWED` by the factory when a resource opts into
+     * `retentionPolicy`; never authored by hand in the common case.
+     *
+     * **LIVE.** `readRetainedAsSystem` / `listRetainedAsSystem` exist and are enforced: the verb is
+     * asserted fail-closed, a privileged human role is required, and every reveal emits a
+     * human-attributed `RETAINED_DATA_ACCESS` audit event. (This block previously said the primitives
+     * were "wired in a later phase" — false since the M5b work landed.)
+     */
+    seeRetained?: ResourceSystemAccessMode;
+    /**
+     * May this resource's rows be swept into a SUBJECT EXPORT bundle (GDPR Art. 15 / Art. 20)?
+     *
+     * Fail-closed by omission, like every other verb here. A subject export reads across the whole
+     * child-direction graph of its subject, so without an explicit opt-in a resource could be
+     * disclosed to a data subject because it merely sits on an edge — nobody having decided that its
+     * contents are appropriate to hand over.
+     *
+     * **The refusal is LOUD, not a silent skip.** When an edge the classifier marked for inclusion
+     * belongs to a resource that has not opted in, the export REFUSES and names it. Silently dropping
+     * it would produce an access bundle that is incomplete without saying so — a disclosure failure
+     * wearing the appearance of a successful response, which is the same class of lie as the routed
+     * export operations this capability replaced. Refusing is a one-line fix per resource; a silent
+     * omission is undetectable.
+     *
+     * NOT derived from `portabilityPolicy`: declaring where fields came from (Art. 20 scoping) and
+     * consenting to be disclosed at all are different decisions, and a resource may legitimately want
+     * the first without the second.
+     */
+    exportSubject?: ResourceSystemAccessMode;
+};
+/** @wildo_source:part:end saas.models.resource-config.system-access-policy */
+/**
+ * Resource-level opt-in to the **impersonalization-on-erasure** capability: on erasure the
+ * resource is impersonalized-and-retained (personal fields scrubbed, row kept for a legal/audit
+ * obligation) instead of hard-deleted. When set, the factory injects a `retentionStatus` marker
+ * and derives the `updateMany` + `seeRetained` system-access grants.
+ *
+ * RESOURCE-level (intrinsic, trigger-agnostic). The per-EDGE trigger is
+ * `onParentDelete.strategy = IMPERSONALIZE_AND_RETAIN`; the per-FIELD scrub is `.impersonalizeWith()`.
+ *
+ * **LIVE — opting in has real effect today.** The marker + derived grants, the in-place scrub writer,
+ * the `IMPERSONALIZE_AND_RETAIN` cascade mode and the hidden-by-default read filter all exist and are
+ * enforced. A RETAINED row is invisible to reads, lists, counts and CHART aggregates, and immutable
+ * to ordinary writes, on BOTH persistence adapters; the only door is the audited see-through path.
+ *
+ * Runtime-proven, not asserted — and scoped precisely, because an earlier revision of this block
+ * over-claimed it. Against a real MongoDB, the erasure orchestrator reaches its terminal path and its
+ * receipt is truthful over a registered subset of resources
+ * (`subject-erasure-completion.mongo.integration.test.ts`); the retention OUTCOME and a SECOND erasure
+ * are observed (`subject-impersonalization-retention-outcome.mongo.integration.test.ts`); and a
+ * retained row is absent from a real application chart over real HTTP
+ * (Wonder Todos `e2e/chart-retention-hide.e2e.ts`).
+ *
+ * What is NOT proven: that an erasure completes over the FULL `onParentDelete` closure, and that
+ * external (provider-side) effects run. The completion lane deliberately requires
+ * `declinedEdges.length > 0`, so it asserts a state in which some edges were NOT executed, and
+ * `externalEffects` is stubbed empty. Do not read "runtime-proven" here as end-to-end completeness.
+ *
+ * (This block previously read "Contract only in this phase … No record is impersonalized-and-retained
+ * yet." That was true when written and became false without being revisited — it is the public
+ * authoring contract an app developer reads before declaring this policy, so it is corrected here
+ * rather than left to mislead.)
+ *
+ * ⚠️ NOT the anonymous-user concept (`isAnonymizable` is pre-auth ownership transposition — the
+ * opposite direction). Reuse of that mechanism, never its name.
+ */
+/**
+ * WHO a row of this resource is with respect to an erasure, and where that person's session lives.
+ * The companion of {@link ResourceRetentionPolicy}: retention says what happens to the ROW and whether
+ * the row holds personal data at all; this says **whose SESSION an erasure of it must end**.
+ *
+ * The two are independent, and reading this one as "is the row about a person" is the mistake that
+ * cost `NO_PRINCIPAL` its previous name — see {@link ResourceDataSubjectKind}. A CRM contact holds
+ * personal data (`RETAIN_AND_IMPERSONALIZE`) and has no session (`NO_PRINCIPAL`); an invoice holds
+ * none (`RETAIN_ONLY`) and also has no session. Same value here, opposite compliance meaning, and the
+ * retention mode is what tells them apart.
+ *
+ * Required on every resource declaring a {@link ResourceRetentionPolicy}, because those are exactly
+ * the resources that can be passed to `eraseSubjectAsSystem` as a subject (the orchestrator refuses a
+ * subject with no retention policy). Undeclared fails at config build rather than defaulting: the safe
+ * default is unknowable — guessing `NO_PRINCIPAL` silently drops a real person's revocation, and
+ * guessing a linked principal revokes the wrong people. See {@link ResourceDataSubjectKind} for why
+ * the linkage can never be inferred from the presence of a user foreign key.
+ */
+export interface ResourceDataSubjectPolicy {
+    /** Whose login session an erasure of this row must end — never whether the row is about a person. */
+    kind: ResourceDataSubjectKind;
+    /**
+     * The field naming the `USERS` row whose session an erasure of this row must end.
+     *
+     * REQUIRED when {@link kind} is `LINKED_PRINCIPAL`, and FORBIDDEN otherwise — under
+     * `SELF_PRINCIPAL` the row's own id is the principal, and under `NO_PRINCIPAL` there is no
+     * principal at all, so a field there would be a contradiction rather than redundancy. Both
+     * directions are enforced at config build.
+     */
+    sessionPrincipalField?: string;
+}
+export interface ResourceRetentionPolicy {
+    /**
+     * WHAT happens to a row of this resource when its subject is erased.
+     *
+     * Both modes retain the row (kept, marked `RETAINED`, hidden from normal reads and immutable,
+     * readable only through the audited see-through path). They differ on whether the row's own FIELDS
+     * additionally need scrubbing — which is a genuinely separate question, because a record can be
+     * legally retainable while holding no personal data of its own (a financial row that merely POINTS
+     * at a person). Fusing the two forced such a resource to either invent a fake scrub or forgo
+     * retention entirely; keeping them distinct is what makes "retain, nothing to scrub" expressible.
+     */
+    mode: ErasureRetentionMode;
+}
+/**
+ * Resource-level DEFAULT for where this resource's field values came from — the axis that decides
+ * GDPR Art. 20 (portability) scope. Per-field overrides are `.portabilityProvenance()`.
+ *
+ * ## Why a resource-level default exists at all
+ *
+ * Art. 20 is intrinsically a per-FIELD question: one row routinely mixes data the subject supplied
+ * (`firstName`) with data the controller produced about them (a computed score, a server-assigned
+ * status). But requiring a decorator on EVERY field of every resource would make the capability
+ * unadoptable, and an unadopted disclosure capability is worse than a coarse one — it means
+ * portability requests cannot be answered at all.
+ *
+ * So the declaration is two-level: this default carries the resource's common case in one line, and
+ * only fields that DIFFER from it need a decorator. A `USER_PROFILES` resource is
+ * `SUBJECT_PROVIDED` by default with a handful of derived exceptions; an `AUDIT_LOGS` resource is
+ * `DERIVED` throughout with none.
+ *
+ * ## Why it is optional, and what happens without it
+ *
+ * Omitting it entirely is legitimate: **Art. 15 (access) never consults provenance**, so an
+ * application can answer access requests in full before annotating anything. Only an Art. 20
+ * portability export needs the axis, and for a resource where neither the field nor this default
+ * declares one, that export REFUSES rather than guessing — see
+ * `SubjectExportFieldScope.UNDECLARED` for why neither guess is the safe one.
+ *
+ * ⚠️ NOT `retentionPolicy`. That says what happens to a value on ERASURE (destroy vs retain-and-
+ * scrub); this says where the value ORIGINATED, for a DISCLOSURE decision. A field is commonly
+ * `SUBJECT_PROVIDED` here and masked on erasure there — orthogonal axes on the same value.
+ */
+export interface ResourcePortabilityPolicy {
+    /**
+     * The provenance every field of this resource is assumed to carry unless its own
+     * `.portabilityProvenance()` says otherwise.
+     */
+    defaultProvenance: DataPortabilityProvenance;
+}
 /**
  * Builder parameters for creating a resource configuration.
  * NOTE: databaseSchema has been removed. Backend-only fields are now marked with
@@ -608,15 +1937,101 @@ export type ResourceConfiguration_BuilderParameters<TCustomOperationEnum extends
     inheritenceSchemaDefinition?: ResourceConfiguration_InheritanceSchemaDefinition<EnumLikeType, TMainSchema>;
     /**
      * Persistence adapter (database type) for this resource.
-     * - `mongodb`: MongoDB with Mongoose ORM (default)
+     * - `mongodb`: MongoDB with Mongoose ORM
      * - `postgresql`: PostgreSQL (SQL adapter)
      *
-     * If not specified, uses `appConfig.database.defaultAdapter`.
+     * If not specified, uses `appConfig.database.defaultAdapter` — which is the normal case and
+     * should stay the normal case.
      *
-     * @see DATABASE_AGNOSTIC_REPOSITORY_ANALYSIS.md Section 18.3
+     * **Declaring a value that DISAGREES with the application default is refused at registration
+     * unless {@link ResourceConfiguration_BuilderParameters.persistenceAdapterIsolation} is also
+     * declared.** An application is wholly one adapter by default because two adapters cannot
+     * share a native transaction; the isolation declaration is the only way past that refusal,
+     * and it is a claim about this resource's write topology rather than a way to silence the
+     * error. Declaring an adapter that AGREES with the default is always fine and needs nothing.
      */
     persistenceAdapter?: PersistenceAdapterType;
+    /**
+     * This resource's declared relationship to cross-adapter atomic write boundaries.
+     *
+     * Required — and only meaningful — when {@link
+     * ResourceConfiguration_BuilderParameters.persistenceAdapter} disagrees with
+     * `appConfig.database.defaultAdapter`. Without it, the resources registry refuses the
+     * application at startup; with it, the registry admits the resource and LOGS the admitted
+     * set, so a mixed configuration is always named and never ambient.
+     *
+     * Read {@link ResourcePersistenceAdapterIsolation} before declaring one: the member is an
+     * assertion about the resource's design that the persistence unit of work will still enforce
+     * at every real boundary.
+     */
+    persistenceAdapterIsolation?: ResourcePersistenceAdapterIsolationType;
+    /**
+     * REQUIRED companion declaration when `persistenceAdapter` is `HTTP_API`; forbidden otherwise.
+     *
+     * Carries everything the external repository needs that the platform does not own: provider
+     * reference (credentials resolve through `ExternalProvidersRegistryBackendService`), transport
+     * dialect, remote entity, ordered key declaration (id synthesis), identity mode, tenancy
+     * stance, erasure stance, and remote-call semantics. The factory enforces presence/absence
+     * coherence and content-validates the declaration.
+     */
+    httpApiBinding?: HttpApiResourceBinding;
+    /** REQUIRED when `persistenceAdapter` is INTROSPECTION; meaningless otherwise. */
+    introspectionBinding?: IntrospectionResourceBinding;
+    /**
+     * OPTIONAL inbound ETL pipeline on an ordinary LOCAL resource — "some resources local, some
+     * remote, ETL between them" (partial-resource coverage, model v3; PR-3). FORBIDDEN on an
+     * HTTP_API-adapter resource: a virtual resource IS the remote side. The factory
+     * content-validates the declaration and every mainSchema-dependent coherence rule (the
+     * remote-key field is a declared `.isBusinessKey()` + excludeFromCreate/Update STRING; mapped
+     * targets exist, accept null unless `required`, and are excludeFromCreate/Update; CLOSED
+     * population refuses caller CREATE operations).
+     */
+    externalDataPipeline?: ExternalDataPipelineDeclaration;
     isSystemResource?: boolean;
+    /**
+     * Does this resource's OWN primary-key URL segment name the CALLER, or the SUBJECT?
+     *
+     * Default `true` (the segment names the caller) — deliberately the SAFE default, so a resource
+     * whose author has not considered the question keeps the identity-coherence guard rather than
+     * silently losing it.
+     *
+     * ## Why this cannot be inferred
+     *
+     * The W3.6 identity-coherence guard (`handleUserJwtAuthentication` →
+     * `AUTHORIZATION_USER_ID_MISMATCH`) refuses a request whose URL `userId` differs from the JWT
+     * subject. That is exactly right for `USER_SELF` (`/user-self/{userId}` — the segment IS the
+     * caller, pinned by the horizontal-IDOR probes) and for child routes under a user
+     * (`/users/{userId}/draft-notes` — a PARENT segment naming whose rows these are).
+     *
+     * It is exactly WRONG for `USERS`, whose own `resourceFieldIdentifier` is also `userId` but whose
+     * segment names the TARGET of an administrative action. Both resources are keyed on the same
+     * field name, so no structural rule can tell them apart — the framework already had to add
+     * `coreResourceShared_FieldIdentifierPriority` to disambiguate the very same collision for FK
+     * resolution. This declaration is that disambiguation for IDENTITY.
+     *
+     * ## What it does and does not change
+     *
+     * Setting `false` relaxes ONLY the coherence refusal. It does not touch:
+     *  - `initiatorIds.userId`, which is taken from the JWT and spread LAST precisely so a URL can
+     *    never spoof the caller (see the `W3.6` comment at that assignment) — so permitting the
+     *    mismatch cannot produce impersonation;
+     *  - the contextual-field map, which legitimately carries the ADDRESSED resource's id;
+     *  - authorization, which still decides whether this caller may run this operation at all.
+     *
+     * Set `false` only for an administrative resource whose primary key is a person/tenant identifier
+     * that a privileged caller is MEANT to address on someone else's behalf.
+     */
+    primaryKeyIdentifiesInitiator?: boolean;
+    /**
+     * Opt-in policy for the ACL-bypassing system-context primitives
+     * (`readAsSystem` / `listAsSystem` and the trusted writes `createAsSystem` /
+     * `updateAsSystem` / `updateManyAsSystem`). Omitted ⇒ EVERY verb FORBIDDEN
+     * (fail-closed): a system-context call on this resource throws unless the
+     * matching verb is explicitly set to ALLOWED. Declare ONLY the verb(s) that
+     * genuinely need a system bypass, and ensure the calling service enforces an
+     * explicit alternative authorization.
+     */
+    systemAccessPolicy?: ResourceSystemAccessPolicy;
     coreOperations: TCoreOperationEnum[];
     customOperation?: TCustomOperationEnum;
     operationsConfiguration: {
@@ -641,8 +2056,42 @@ export type ResourceConfiguration_BuilderParameters<TCustomOperationEnum extends
      * Defaults to ADD (simple ownership reassignment).
      */
     transpositionPolicy?: ResourceTranspositionPolicy;
+    /**
+     * Opt in to impersonalization-on-erasure (retain + scrub instead of hard-delete). When set, the
+     * factory injects a `retentionStatus` marker and derives the `updateMany` / `seeRetained`
+     * system-access grants. Per-field scrub is `.impersonalizeWith()`; the per-edge trigger is the
+     * `IMPERSONALIZE_AND_RETAIN` cascade mode.
+     *
+     * **LIVE.** Marker injection, grant derivation, the scrub writer, the cascade mode and the
+     * hidden-by-default read filter are all enforced today — see `ResourceRetentionPolicy` for the
+     * runtime evidence. Declaring this changes behaviour; it is not a forward declaration.
+     *
+     * Declaring this also REQUIRES {@link dataSubjectPolicy}: a retention-governed resource is exactly
+     * one that can be handed to `eraseSubjectAsSystem` as a subject, so it must say whether its rows are
+     * a person — and if so, whose session an erasure ends.
+     */
+    retentionPolicy?: ResourceRetentionPolicy;
+    /**
+     * WHO a row of this resource is with respect to an erasure — and, when it is a person, which field
+     * names the `USERS` row whose session that erasure must end.
+     *
+     * Mandatory for any resource declaring a {@link retentionPolicy}; meaningless (and rejected) without
+     * one, since a resource with no retention policy can never be an erasure subject. See
+     * {@link ResourceDataSubjectPolicy}.
+     */
+    dataSubjectPolicy?: ResourceDataSubjectPolicy;
+    /**
+     * Resource-level DEFAULT provenance for GDPR Art. 20 (portability) scoping; per-field overrides
+     * are `.portabilityProvenance()`. Optional — Art. 15 (access) never consults provenance, so an
+     * application can answer access requests without declaring this. See
+     * {@link ResourcePortabilityPolicy}.
+     */
+    portabilityPolicy?: ResourcePortabilityPolicy;
 };
+/** @wildo_source:part:end saas.models.resource-config.builder-parameters */
 /**
+ * @wildo_source:part:start saas.models.resource-config.resource-relationships-buckets facet:layer:shared facet:family:resource-config
+ *
  * Categorized resource relationships produced by `transformResourceRelationships()`.
  *
  * All relationships — including conditional ones (those with `discriminator` or `condition`) —
@@ -668,6 +2117,7 @@ export type ResourceConfiguration_ResourceRelationships = {
     childRelationships: ResourceRelationship[];
     selfRelationships: ResourceRelationship[];
 };
+/** @wildo_source:part:end saas.models.resource-config.resource-relationships-buckets */
 /**
  * Returns all relationships where this resource acts as a child (has a parent).
  * Merges `childRelationships` with `selfRelationships` — self-refs are both
@@ -682,6 +2132,8 @@ export declare function getChildDirectionRelationships(rels: ResourceConfigurati
  */
 export declare function getParentDirectionRelationships(rels: ResourceConfiguration_ResourceRelationships): ResourceRelationship[];
 /**
+ * @wildo_source:part:start saas.models.resource-config.resource-configuration facet:layer:shared facet:family:resource-config
+ *
  * Full resource configuration type.
  * NOTE: databaseSchema has been removed. Backend-only fields are now marked with
  * the isBackendOnly decorator in mainSchema and are stripped at the service layer.
@@ -704,9 +2156,52 @@ export type ResourceConfiguration<TCustomOperationEnum extends EnumLikeType | un
      * Resolved at runtime from:
      * 1. This field (if specified)
      * 2. `appConfig.database.defaultAdapter` (fallback)
+     *
+     * A value disagreeing with the application default is admitted at registration ONLY when
+     * {@link ResourceConfiguration.persistenceAdapterIsolation} is declared beside it.
      */
     persistenceAdapter?: PersistenceAdapterType;
+    /**
+     * This resource's declared relationship to cross-adapter atomic write boundaries; see the
+     * authoring-side declaration and {@link ResourcePersistenceAdapterIsolation} for the full
+     * rationale.
+     *
+     * Carried through to the resolved config UNMATERIALISED (no default is substituted) because
+     * absence is semantically load-bearing here: the registry's admission asks whether the author
+     * MADE the claim, and a materialised default would answer that question for them.
+     */
+    persistenceAdapterIsolation?: ResourcePersistenceAdapterIsolationType;
+    /**
+     * The external HTTP-API binding — present exactly when `persistenceAdapter` is `HTTP_API`
+     * (factory-enforced both ways). See the authoring-side declaration for the full contract.
+     */
+    httpApiBinding?: HttpApiResourceBinding;
+    /** REQUIRED when `persistenceAdapter` is INTROSPECTION; meaningless otherwise. */
+    introspectionBinding?: IntrospectionResourceBinding;
+    /**
+     * The inbound ETL pipeline, when this LOCAL resource declared one — parsed + coherence-checked
+     * by the factory (see the authoring-side declaration for the full contract).
+     */
+    externalDataPipeline?: ExternalDataPipelineDeclaration;
     isSystemResource: boolean;
+    /**
+     * Whether this resource's own primary-key URL segment names the CALLER (see the authoring-side
+     * declaration for the full rationale).
+     *
+     * Materialised by the factory to a concrete boolean, defaulting to `true`, so the consuming guard
+     * never has to distinguish "declared true" from "not declared" — an un-migrated or hand-built
+     * config keeps the identity-coherence refusal.
+     */
+    primaryKeyIdentifiesInitiator: boolean;
+    /**
+     * Opt-in policy gating the ACL-bypassing `readAsSystem` / `listAsSystem`
+     * primitives for this resource. Optional on the resolved config so that
+     * non-factory-built configs (mocks/tests) need not declare it; the factory
+     * always materialises a concrete value (defaulting both verbs to FORBIDDEN
+     * when unauthored). The system-read primitives treat an absent policy — or
+     * any verb not explicitly ALLOWED — as forbidden and throw.
+     */
+    systemAccessPolicy?: ResourceSystemAccessPolicy;
     /**
      * 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.
@@ -717,17 +2212,80 @@ export type ResourceConfiguration<TCustomOperationEnum extends EnumLikeType | un
      * Only meaningful when isAnonymizable is true. Defaults to ADD.
      */
     transpositionPolicy: ResourceTranspositionPolicy;
+    /** Resolved impersonalization opt-in (undefined when the resource did not opt into `retentionPolicy`). */
+    retentionPolicy?: ResourceRetentionPolicy;
+    /**
+     * Resolved data-subject declaration. Present exactly when `retentionPolicy` is (the factory refuses
+     * a retention-governed resource that declares no `dataSubjectPolicy`, and refuses a
+     * `dataSubjectPolicy` on a resource with no `retentionPolicy`), so a consumer that has one may read
+     * the other without a second existence check.
+     */
+    dataSubjectPolicy?: ResourceDataSubjectPolicy;
+    /** Resolved portability default (undefined when the resource declared no `portabilityPolicy` — an
+     *  Art. 15 export is unaffected, an Art. 20 export refuses on any field that also lacks its own
+     *  `.portabilityProvenance()`). */
+    portabilityPolicy?: ResourcePortabilityPolicy;
     operations: ResourceConfiguration_Operation<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>[];
 };
+/** @wildo_source:part:end saas.models.resource-config.resource-configuration */
 export type ResourceConfiguration_InitializationFactory<TCustomOperationEnum extends EnumLikeType | undefined, TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined, TMainSchema extends z.ZodTypeAny> = (resourcesRelationships: ResourceRelationship[]) => ResourceConfiguration<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>;
+/**
+ * The factory map accepted by the RUNTIME REGISTRY initializers
+ * (`ResourcesRegistryBackendService.initialize`, `ResourceRegistry_InitializerParameters`).
+ *
+ * ⚠️ The leading `TResourceType extends undefined` conditional is DISTRIBUTIVE, and it must stay
+ * that way. A registry initializer takes this map at a position whose type argument is INFERRED
+ * from the argument, and inference only reaches the mapped-type branch through that distributive
+ * chain. Prefixing the chain with a non-distributive guard (`[TResourceType] extends [never] ? …`)
+ * stops the inference dead: every such parameter falls back to its `= undefined` default, so a
+ * perfectly good map is reported as `not assignable to parameter of type 'undefined'`. That
+ * shipped on 2026-08-26 and failed the compile of BOTH `platform-apps-manager` and
+ * `platform-crontabs-batches-manager` — the only two runtimes that pass a typed custom map
+ * positionally — while every other consumer stayed green because it passes `undefined` or a value
+ * already widened by a cast.
+ *
+ * The consequence of the distribution is that a union `TResourceType` yields a UNION of
+ * single-key maps rather than one complete map. That is weaker than it looks, and it is why a
+ * module's OWN map uses {@link ResourceConfiguration_ModuleInitializationFactoryMap} instead —
+ * including for the empty-module case (`never`), which this type deliberately does not model:
+ * distributing over `never` yields `never`, and no ordering of distributive branches can change
+ * that.
+ */
 export type ResourceConfiguration_InitializationFactoryMap<TResourceType extends ResourceType | undefined = undefined> = TResourceType extends undefined ? undefined : [TResourceType] extends [undefined] ? undefined : TResourceType extends ResourceType ? {
     [key in TResourceType]: ResourceConfiguration_InitializationFactory<any, any, any>;
 } : {
     [key: string]: ResourceConfiguration_InitializationFactory<any, any, any>;
 };
+/**
+ * The factory map a MODULE declares for its OWN resources: exactly one entry per member of that
+ * module's resource-type enum — no missing entry, no key the enum does not declare.
+ *
+ * This is a plain mapped type, with no conditional in front of it, and both of its properties
+ * follow from that:
+ *
+ * - a union of enum members produces ONE complete map (not the union of single-key maps that
+ *   {@link ResourceConfiguration_InitializationFactoryMap} produces), which is the truthful
+ *   contract for a module: it owns all of its resources;
+ * - a FRESHLY SCAFFOLDED module, whose resource enum has no members yet, produces the empty map
+ *   `{}`. A memberless enum is numeric by default, so the scaffold writes
+ *   `<Module>_ResourceType & string`, which is `never` until the first string member arrives —
+ *   and a mapped type over `never` is `{}`, so the empty declaration type-checks without any
+ *   `never` special case.
+ *
+ * The value is assignable to every consumer that takes the registry-facing map, so a module can be
+ * merged into an application registry unchanged.
+ */
+export type ResourceConfiguration_ModuleInitializationFactoryMap<TResourceType extends ResourceType> = {
+    [key in TResourceType]: ResourceConfiguration_InitializationFactory<any, any, any>;
+};
 export type AnyResourceConfiguration = ResourceConfiguration<any, // TCustomOperationEnum - allow any custom operations
 any, // TCoreOperationEnum - allow any subset of core operations
 any>;
+/**
+ * @wildo_source:part:start saas.models.resource-config.resources-registry facet:layer:shared facet:family:resource-config
+ *
+ * Aggregated registry passed to app bootstrap (relationships + per-resource configs + FK maps).
+ */
 export type ResourcesRegistry = {
     notificationBadgeDefinitions: NotificationBadgeDefinition[];
     additionalUserNotificationDefinitions: UserNotificationDefinition[];
@@ -735,6 +2293,20 @@ export type ResourcesRegistry = {
     resourceConfigurations: {
         [key: ResourceType]: AnyResourceConfiguration;
     };
+    /**
+     * The resource types the APPLICATION registered — its own, never the engine's.
+     *
+     * The registry composes app and core factory maps into one `resourceConfigurations`, which is what
+     * every runtime consumer wants. This is the one place the two are still distinguishable, so the
+     * split is recorded HERE rather than re-derived by each consumer from a core key set — which would
+     * be a second enumeration of a population this file already knows.
+     *
+     * Its consumer today is the personal-data declaration report, which asks a question only an
+     * application author can act on: the engine declares its own posture on ~85 resources, and putting
+     * those in front of a reader of a report about THEIR application is how a diagnostic channel stops
+     * being read.
+     */
+    applicationResourceTypes: ResourceType[];
     /**
      * Map of ResourceType to its standard field identifier (e.g., USERS -> userId).
      * Used for FK field resolution without string manipulation.
@@ -745,7 +2317,30 @@ export type ResourcesRegistry = {
      * Used for quick lookup of resource type from a FK field name.
      */
     fieldIdentifierToResourceType: Record<string, ResourceType>;
+    /**
+     * Scope-required reference-search junctions, keyed by `${target}|${scope}`.
+     * When a foreign key targets `T` from a resource whose primary scope is `S`,
+     * and `T ↔ S` is a MANY-to-MANY relationship via junction `J`, a reference
+     * people-picker searches `T` scoped to the caller's current `S` through `J`
+     * (rather than enumerating every `T`). Derived from the registered M:N
+     * relationships at registry init.
+     */
+    manyToManyScopeJunctions: ManyToManyScopeJunctionMap;
+    /**
+     * Resources narrowed by ORGANIZATION UNIT, keyed by resource type — the engine's opt-ins merged
+     * with the application's, validated at boot against the authorization-plane containment rule.
+     *
+     * Opting a resource in means: a principal whose authority for it comes ONLY from a unit grant is
+     * admitted by the operation gate and then confined to the rows of those units. Narrowing is
+     * ADDITIVE — an organization-wide grant that already satisfies the operation is never narrowed —
+     * so opting in can only widen who can reach the resource, never shrink an existing result set.
+     *
+     * Empty for an application that declares none, which is the default: narrowing is never inferred
+     * from the presence of a unit field. See `OrganizationUnitNarrowingDeclaration`.
+     */
+    organizationUnitNarrowing: Readonly<Partial<Record<ResourceType, OrganizationUnitNarrowingDeclaration>>>;
 };
+/** @wildo_source:part:end saas.models.resource-config.resources-registry */
 export type ResourceRegistry_InitializerParameters<TResourceType extends ResourceType | undefined = undefined> = [
     TResourceType
 ] extends [undefined] ? {