@wildo-ai/saas-models 1.1.1 → 1.1.3

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

@@ -7,13 +7,13 @@ import { z } from 'zod';
 import { EnumLikeType, EnumValues, PrimitiveZodType } from '@wildo-ai/zod-decorators';
 import { ErasureRetentionMode, ResourceDataSubjectKind } from '../compliance/privacy/impersonalization.shared.schemas';
 import type { DataPortabilityProvenance } from '../compliance/privacy/subject-export.shared.schemas';
-import type { HttpApiResourceBinding } from '../http-api-binding/http-api-binding.shared.schemas';
-import type { ExternalDataPipelineDeclaration } from '../external-data/external-data-pipeline.shared.schemas';
+import type { HttpApiResourceBinding, HttpApiResourceBindingAuthored } from '../http-api-binding/http-api-binding.shared.schemas';
+import type { ExternalDataPipelineDeclaration, ExternalDataPipelineDeclarationAuthored } from '../external-data/external-data-pipeline.shared.schemas';
 import { HttpMethod } from '../requests/http-requests.shared';
 import { Roles } from '../security/authorizations/roles.shared.schemas';
 import { TokenAuthenticationConfig, TokenGenerationConfig, TokenRevocationConfig } from '../security/authentications/consumable-token.shared.schemas';
 import { ResourceOperation_ServiceRuntimeMode, ResourceOperationVariantType, ResourceOperationRiskLevel, ResourceOperationFrontendSurface, ResourcePrimaryScope, ResourceTranspositionPolicy, ResourceOperation_CustomServiceImplementationMode, ResourceRelationship, ResourceRelationshipAccessScopeStrategy, ManyToManyScopeJunctionMap, type ReferenceConstraints } from './resources.shared.schemas';
-import { NotificationBadgeIdentifier, NotificationBadgeOperation } from '../notifications/notification-badges.schemas';
+import { NotificationBadgeKey, NotificationBadgeOperation } from '../notifications/notification-badges.schemas';
 import { M2MNotificationDefinition, UserNotificationDefinition } from '../notifications/notifications.shared.schemas';
 import { NotificationBadgeDefinition } from '../notifications/notification-badges.schemas';
 import { CoreResourceOperation, ResourceFieldIdentifier, ResourceType } from './resources.shared.core.definitions';
@@ -42,7 +42,7 @@ export declare function createPaginationResponseMetadataSchema(maxLimit?: number
     totalPages: z.ZodNumber;
 }>;
 /** The default-bounded response metadata. Prefer {@link createPaginationResponseMetadataSchema} where the ceiling is known. */
-export declare const Resouces_PaginationResponseMetadataSchema: z.ZodObject<{
+export declare const Resources_PaginationResponseMetadataSchema: z.ZodObject<{
     page: z.ZodDefault<z.ZodNumber>;
     limit: z.ZodDefault<z.ZodNumber>;
     total: z.ZodNumber;
@@ -64,16 +64,16 @@ export declare function createPaginationRequestSchema(maxLimit?: number): z.ZodO
     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<{
+export declare const Resources_PaginationRequestSchema: z.ZodObject<{
     page: z.ZodDefault<z.ZodNumber>;
     limit: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 export type ResourcePaginatedResponseResultSchema<T extends z.ZodTypeAny> = {
     data: SchemaArrayInfer<T>;
-    pagination: z.infer<typeof Resouces_PaginationResponseMetadataSchema>;
+    pagination: z.infer<typeof Resources_PaginationResponseMetadataSchema>;
 };
-export type Resources_PaginationMetadata = z.infer<typeof Resouces_PaginationResponseMetadataSchema>;
-export type Resources_PaginationRequest = z.infer<typeof Resouces_PaginationRequestSchema>;
+export type Resources_PaginationMetadata = z.infer<typeof Resources_PaginationResponseMetadataSchema>;
+export type Resources_PaginationRequest = z.infer<typeof Resources_PaginationRequestSchema>;
 export type Resources_PaginatedResult<T> = {
     data: T[];
     pagination: Resources_PaginationMetadata;
@@ -134,6 +134,27 @@ export declare enum IntrospectionTenancyStance {
      * story, and nobody would be asked to notice.
      */
     APPLICATION_STRUCTURE = "application-structure",
+    /**
+     * The rows are the DEVELOPMENT COMPANION'S OWN RUNTIME PROJECTIONS for the one application it
+     * serves — the playbook eligibility board, the build plan, the run write-register, the execution
+     * traces. Like `APPLICATION_STRUCTURE` they carry no tenant dimension and no scope predicate can
+     * apply; UNLIKE it, they are not derived from the application's source, and the tenancy stance is
+     * where that difference must stay visible (added 2026-09-01, creation-board resources plan):
+     *
+     * - `APPLICATION_STRUCTURE`'s public-read posture (`APP_PUBLIC` variants on the workbench's
+     *   structural projections) rests on the rows being the application's OWN source, which anyone
+     *   with the working tree can already read. That argument does NOT extend to runtime state, so a
+     *   resource declaring this stance is expected to gate its variants on an authenticated role —
+     *   never `APP_PUBLIC`.
+     * - Row-level tenant-anchor checks are bypassed for this stance exactly as for
+     *   `APPLICATION_STRUCTURE` (the rows carry no anchor BY CONTRACT); authorization comes from the
+     *   session and the operation's role gate.
+     *
+     * Fusing this into `APPLICATION_STRUCTURE` was rejected for the enum's own founding reason: an
+     * unstated distinction is indistinguishable from an overlooked one, and the next decision site
+     * keyed off the stance would inherit a claim nobody checked.
+     */
+    APPLICATION_RUNTIME = "application-runtime",
     /**
      * The rows carry a tenant dimension and a scope predicate must be pushed into the source.
      *
@@ -224,10 +245,15 @@ export declare enum PersistenceAdapter {
      * "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.
+     * is the COMPANION's decision per behavior (amended 2026-09-01): the app-import behaviors run a
+     * SUBPROCESS that imports the target application's built modules — seconds per read, requiring
+     * that application's `dist`, failing as a thrown behavior — while the creation-plane behaviors
+     * are IN-PROCESS projections of the companion's own runtime services (playbook eligibility,
+     * build plan, write register, traces). Both reach the engine through the same
+     * `IntrospectionResourceSourceBackendPort`; the adapter never encodes the mechanism, which is
+     * exactly why a behavior id is an engine-opaque string. Collapsing this into `HTTP_API` would
+     * still be wrong for the original reason: its failure mode is a source throwing rather than a
+     * row being absent, and nothing here is reached over a network API.
      *
      * ## What every adapter decision site must honor
      *
@@ -438,11 +464,11 @@ export declare enum SortOrder {
     ASC = "asc",
     DESC = "desc"
 }
-export declare const Resouces_Filter_DateRangeSchema: z.ZodObject<{
+export declare const Resources_Filter_DateRangeSchema: z.ZodObject<{
     startDate: z.ZodOptional<z.ZodDate>;
     endDate: z.ZodOptional<z.ZodDate>;
 }, z.core.$strip>;
-export declare const Resouces_Filter_BaseSchema: z.ZodObject<{
+export declare const Resources_Filter_BaseSchema: z.ZodObject<{
     searchRequest: z.ZodOptional<z.ZodString>;
     createdAt: z.ZodOptional<z.ZodObject<{
         startDate: z.ZodOptional<z.ZodDate>;
@@ -453,7 +479,7 @@ export declare const Resouces_Filter_BaseSchema: z.ZodObject<{
         endDate: z.ZodOptional<z.ZodDate>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-export declare const Resouces_FilterRequestSchema: z.ZodObject<{
+export declare const Resources_FilterRequestSchema: z.ZodObject<{
     searchRequest: z.ZodOptional<z.ZodString>;
     createdAt: z.ZodOptional<z.ZodObject<{
         startDate: z.ZodOptional<z.ZodDate>;
@@ -464,17 +490,17 @@ export declare const Resouces_FilterRequestSchema: z.ZodObject<{
         endDate: z.ZodOptional<z.ZodDate>;
     }, z.core.$strip>>;
 }, z.core.$catchall<z.ZodOptional<z.ZodAny>>>;
-export declare const Resouces_SortingFieldSchema: z.ZodObject<{
+export declare const Resources_SortingFieldSchema: z.ZodObject<{
     field: z.ZodString;
     order: z.ZodDefault<z.ZodEnum<typeof SortOrder>>;
     priority: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
-export declare const Resouces_SortingRequestSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodObject<{
+export declare const Resources_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>>>>;
-export declare const Resouces_SearchQueryRequestSchema: z.ZodObject<{
+export declare const Resources_SearchQueryRequestSchema: z.ZodObject<{
     pagination: z.ZodOptional<z.ZodObject<{
         page: z.ZodDefault<z.ZodNumber>;
         limit: z.ZodDefault<z.ZodNumber>;
@@ -497,9 +523,9 @@ export declare const Resouces_SearchQueryRequestSchema: z.ZodObject<{
     }, 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>;
-    filters: z.ZodOptional<typeof Resouces_Filter_BaseSchema>;
+    pagination: z.ZodOptional<typeof Resources_PaginationRequestSchema>;
+    sorting: z.ZodOptional<typeof Resources_SortingRequestSchema>;
+    filters: z.ZodOptional<typeof Resources_Filter_BaseSchema>;
 }>;
 export type Ressources_RequestSortPriority<T extends EnumLikeType> = {
     [K in keyof T as T[K]]: number;
@@ -803,7 +829,7 @@ export type CollectionViewFields_Search = CollectionViewFields_Shared & {
  * validates away to nothing, and then fails as "`_ids` is required" — which is exactly what every
  * frontend bulk surface did until 2026-08-29.
  */
-export declare const Resouces_BulkOperationBaseSchema: z.ZodObject<{
+export declare const Resources_BulkOperationBaseSchema: z.ZodObject<{
     _ids: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
 /**
@@ -867,6 +893,36 @@ export type ResourceConfiguration_FunctionContextNeeds = {
     needsUserContext?: boolean;
 };
 /**
+ * @wildo_source:part:start saas.models.resource-config.required-features facet:layer:shared facet:audience:app-developer
+ *
+ * Gating an operation or a view on a FEATURE the customer has — a plan entitlement, a boolean
+ * capability, or a usage limit.
+ *
+ * Declared as `requiredFeatures` on a resource operation variant or on a view. The shorthand form is
+ * a plain `string[]` of feature identifiers, auto-normalized to `{ features, mode: 'OR' }`; the full
+ * form adds `mode: 'AND'` and `limitChecks`.
+ *
+ * ## ⚠️ The screen gate is NOT the security boundary
+ *
+ * Declaring the requirement on a VIEW decides what a screen looks like. It does not stop the
+ * operation running. A capability that must not be REACHABLE needs the requirement declared on the
+ * OPERATION as well — the backend gate is what refuses, and it is the only thing that does.
+ *
+ * Two consequences of the interface half that follow from this, and are not defects:
+ *
+ * - **While the resolved feature set is still loading, everything is treated as AVAILABLE.** That
+ *   avoids a flash of locked interface, and it means a gate can briefly show content the backend
+ *   would refuse. Correct behaviour; not something to design around on the screen.
+ * - A hidden or prompted control is a presentation choice, so anyone who reaches the endpoint
+ *   directly is decided by the operation's own declaration.
+ *
+ * ## Limit checks measure, they do not merely check presence
+ *
+ * `features` is a PRESENCE check on boolean capabilities. `limitChecks` is different: each entry
+ * names a LIMIT-type feature and an increment, and the gate measures current usage through that
+ * feature definition's own `counting` config before allowing the operation. Use `limitChecks` for
+ * "up to N of these", never a boolean feature.
+ *
  * Limit check entry: references a LIMIT-type feature and specifies the increment.
  * The gate uses the feature definition's `counting` config to measure current usage.
  */
@@ -907,6 +963,7 @@ export type RequiredFeaturesConfig = string[] | RequiredFeaturesFullConfig;
  * Normalized required features (always the full form, after factory processing).
  */
 export type RequiredFeaturesNormalized = RequiredFeaturesFullConfig;
+/** @wildo_source:part:end saas.models.resource-config.required-features */
 /**
  * Wrapper type for functions that can optionally require context.
  * Stores both the function and metadata about its context needs.
@@ -984,6 +1041,66 @@ export type ResourceOperation_UnimplementedAcknowledgement = {
     /** Where the gap is tracked — a plan path, issue id, or equivalent durable reference. */
     trackingRef: string;
 };
+/**
+ * Whether a declared operation is actually SERVICED — the verdict a shared predicate answers with.
+ *
+ * MOVED HERE FROM `saas-backend-lib` on 2026-09-02, and the reason is a layering one rather than
+ * tidiness. These are closed VOCABULARIES, not backend behaviour: the resolvers that compute them
+ * stay in the backend, but the answers they produce are what other layers must be able to name.
+ * `saas-specifications` could not attest `WILDO.OPERATIONS.EXECUTION_INTEGRITY` in its assurance
+ * authority basis while the vocabulary lived in a package it must not depend on — the control was
+ * real, well-marked and unnameable from the layer obliged to describe it (#207).
+ *
+ * The single-resolver contract is unchanged and still lives with the resolvers: startup validation
+ * and request-time refusal must consume the SAME predicate, because an operation blessed at boot
+ * that can still answer 2xx on the first request is precisely the state that module ended.
+ *
+ * The defect behind all of this: a custom operation declaring a `requestDto` no implementation
+ * consumes falls through to the generic core path, which persists only fields the resource schema
+ * declares. A DTO such as `{ newRole, reason }` names none of them, so the framework validates the
+ * body, writes nothing, and answers HTTP 200 with the unchanged row. A 2026-08-01 hostile probe
+ * caught `organizationMembers | promote` doing exactly that, and a catalogue sweep found 41 routed
+ * operations sharing the shape. Nothing escalates; the destructive direction is the dangerous one —
+ * an admin demotes a compromised account, is told 200 OK, and the account keeps its privileges.
+ *
+ * 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 truthful responses.
+ */
+export declare enum ResourceOperationImplementationCoverage {
+    /** Something consumes the declared contract: a custom implementation, a declarative side effect, or the core path itself. */
+    SERVICEABLE = "serviceable",
+    /** Nothing does. Left alone, the operation answers 2xx having performed nothing. */
+    UNSERVICEABLE = "unserviceable",
+    /** Outside this guard's remit — a core operation, or a variant the service tier never enters. */
+    NOT_APPLICABLE = "not_applicable"
+}
+/**
+ * Why an operation was judged {@link ResourceOperationImplementationCoverage.UNSERVICEABLE}.
+ * Surfaced verbatim in the startup error so the fix is obvious without re-deriving the analysis.
+ */
+export declare enum ResourceOperationUnserviceableReason {
+    /** Write-like: no declared request field is a persisted resource-schema field, so the write is empty. */
+    NO_REQUEST_FIELD_IS_PERSISTED = "no_request_field_is_persisted",
+    /** READ-like: the core read addresses the row by id and consumes no request field, so the declared verb never happens. */
+    READ_CONSUMES_NO_REQUEST_FIELD = "read_consumes_no_request_field",
+    /** Collection-like: no declared request field is a collection parameter the core path reads. */
+    NO_REQUEST_FIELD_IS_COLLECTION_PARAMETER = "no_request_field_is_collection_parameter"
+}
+/**
+ * Whether a custom write-like verb authored the request contract it exposes, or silently inherited
+ * the resource's whole create/update contract.
+ *
+ * Moved here with {@link ResourceOperationImplementationCoverage}, for the same reason.
+ *
+ * assurance-control: WILDO.OPERATIONS.EXECUTION_INTEGRITY — a named verb must not silently widen
+ * into an unconstrained write over fields its resource never exposed for update.
+ */
+export declare enum ResourceOperationRequestContractBreadth {
+    /** The operation authored its own request contract, or its family cannot inherit one. */
+    AUTHORED = "authored",
+    /** A write-like custom verb inherited the resource's whole create/update contract. */
+    OVERBROAD_INHERITED_FULL_CONTRACT = "overbroad_inherited_full_contract"
+}
 /**
  * Where the engine's own inherited implementation gaps are tracked — the 2026-08-01 catalogue
  * sweep that found 41 routed operations answering a success status having performed nothing.
@@ -1001,6 +1118,8 @@ export declare const UNIMPLEMENTED_ENGINE_OPERATION_BACKLOG_REF = ".claude/plans
  */
 export declare const acknowledgeUnimplementedEngineOperation: (reason: string) => ResourceOperation_UnimplementedAcknowledgement;
 /**
+ * @wildo_source:part:start saas.models.resource-config.operation-auditable-event facet:layer:shared facet:audience:app-developer
+ *
  * Declarative control over this variant's audit emission.
  *
  * **The baseline needs no declaration.** Every `HIGH` / `CRITICAL` variant emits
@@ -1022,6 +1141,7 @@ export type ResourceOperation_AuditableEvent = {
      */
     auditBelowRiskFloor?: boolean;
 };
+/** @wildo_source:part:end saas.models.resource-config.operation-auditable-event */
 type ResourceConfiguration_OperationVariant_Base<TMainSchema extends z.ZodTypeAny = z.ZodAny> = {
     variantType: ResourceOperationVariantType;
     resourceOperationLike?: CoreResourceOperation;
@@ -1035,6 +1155,39 @@ type ResourceConfiguration_OperationVariant_Base<TMainSchema extends z.ZodTypeAn
     isDefault?: boolean;
     variantKey?: string;
     riskLevel: ResourceOperationRiskLevel;
+    /**
+     * @wildo_source:part:start saas.models.resource-config.operation-variant-client-timeout facet:layer:shared facet:family:resource-config
+     *
+     * Frontend HTTP timeout for THIS variant, in milliseconds — declare it on any operation whose
+     * synchronous round trip legitimately outlives the frontend client's 30-second default (an
+     * operation that calls a model and waits for the answer, a long import, a blocking generation).
+     *
+     * The frontend resources client applies it as the per-request timeout on every dispatch shape
+     * (api-call, api-call-with-callback, search). An explicit caller-supplied
+     * `RequestOptions.timeout` still wins; omitting the field keeps the client default.
+     *
+     * Why it matters: without it, a long-running operation's request is aborted CLIENT-side while
+     * the server work succeeds — the caller renders a network error, and the operation-success
+     * refresh chain never fires, so lists keep showing the pre-operation world. Declare the
+     * expectation on the variant (the operation knows it is long-running); do not hard-code
+     * timeouts in consumer hooks, which duplicates that knowledge at every call site.
+     *
+     * This is a TRANSPORT expectation only — not a UI/observability signal (that is `riskLevel`)
+     * and not a server-side bound: the backend is free to answer sooner or be cut off by its own
+     * limits.
+     *
+     * @example a custom operation that generates a document before answering
+     * variants: [{
+     *   variantType: ResourceOperationVariantType.API_CALL,
+     *   roles: [CORE_ORG_ROLES.ORG_MEMBER],
+     *   riskLevel: ResourceOperationRiskLevel.MEDIUM,
+     *   clientRequestTimeoutMs: 300_000, // five minutes — the generation is synchronous
+     *   requestDto: GenerateReportRequest_Schema,
+     *   customResponseDto: GenerateReportOutcome_Schema,
+     * }]
+     */
+    clientRequestTimeoutMs?: number;
+    /** @wildo_source:part:end saas.models.resource-config.operation-variant-client-timeout */
     roles: Roles[];
     /**
      * Per-foreign-key policy for REFERENCE fields this variant writes — the TARGET-side counterpart of
@@ -1069,63 +1222,6 @@ type ResourceConfiguration_OperationVariant_Base<TMainSchema extends z.ZodTypeAn
      * 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.
@@ -1175,7 +1271,7 @@ type ResourceConfiguration_OperationVariant_Base<TMainSchema extends z.ZodTypeAn
      * `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
+     * `revoke_roles`, `suspend_user`, `unsuspend_user`, `reactivate_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.
@@ -1204,7 +1300,74 @@ type ResourceConfiguration_OperationVariant_Base<TMainSchema extends z.ZodTypeAn
      * is authorized by the caller's ROLE, never by caller and subject being the same person.
      */
     admitsCrossSubjectUserAdministration?: boolean;
+    /**
+     * @wildo_source:part:start saas.models.resource-config.operation-step-up facet:layer:shared facet:audience:app-developer
+     *
+     * 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` accepts THREE factors — `PASSWORD`, `TOTP`
+     * (a code or a backup code, through the same anti-replay authority login uses) and `PASSKEY` (a
+     * WebAuthn assertion produced under {@link PasskeyAuthenticationCeremony.STEP_UP}, which pins user
+     * verification to REQUIRED and uses a challenge key a login assertion cannot redeem). A principal
+     * satisfies this gate if they hold ANY of the three.
+     *
+     * That was not always true, and the earlier text here is worth knowing because it inverted the
+     * advice: until TOTP and passkey re-auth landed, this said the gate was PASSWORD-only and told
+     * authors not to declare the flag on operations SSO-only, passkey-only or directory-managed users
+     * perform. Both populations can satisfy it now.
+     *
+     *  - **directory-managed (SCIM) users** in particular. The framework deliberately destroys their
+     *    `passwordHash` AND passkeys as a compliance control
+     *    (`_reconcileLocalCredentialsForDirectoryManaged` — a local first factor would survive IdP
+     *    deprovisioning) and deliberately PRESERVES their TOTP, which sits on top of the IdP first
+     *    factor. TOTP re-auth is what makes that preserved factor usable, and it is why an ORG_ADMIN
+     *    of a directory-managed tenant can now start a teardown they were once locked out of.
+     *
+     * A principal holding NONE of the three still cannot satisfy the gate, and is still refused
+     * fail-closed with a diagnosable message. Check the user type's `authMethodsEnabled` — and any
+     * per-ORGANIZATION override of it, since an app-level policy is not the whole answer — before
+     * declaring this flag on an operation that population must perform.
+     *
+     * 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.
+     *
+     * ⚠️ **Read-shaped operations are SKIPPED, so the flag is inert on them.** `READ`, `LIST`,
+     * `SEARCH` and `COUNT` never reach the gate — declaring it there configures cleanly and enforces
+     * nothing. Step-up guards an ACT, not a look; to restrict who may read, use the operation's
+     * `roles`.
+     */
     requiresStepUpAuthentication?: boolean;
+    /** @wildo_source:part:end saas.models.resource-config.operation-step-up */
     /**
      * Default **frontend surface** for this operation when no app preset declares
      * one (see {@link ResourceOperationFrontendSurface}). Lets the framework mark
@@ -1330,6 +1493,18 @@ type ResourceConfiguration_OperationVariant_ApiCall_BuilderParameters<TMainSchem
      * that seam the authenticated identity is not yet known, so the client
      * identifier is the IP address (`getClientIpFromRequest`).
      *
+     * **The declaration binds every plane that dispatches the operation, not only
+     * HTTP.** An agent reaching the same operation as an MCP tool (`tools/call`)
+     * or as a Wildo function tool (`resourceReadTool` / `resourceWriteTool`)
+     * bypasses Express, so each of those planes enforces this policy itself
+     * through `RateLimitBackendService.checkPolicyForSubject`. Two consequences to
+     * expect: each plane counts into its OWN bucket, so an agent's traffic cannot
+     * spend a browser's budget or the reverse; and off HTTP the counted subject is
+     * the caller's CREDENTIAL rather than an IP, which is the closest available
+     * reading of "per client" where there is no socket. A number authored here
+     * therefore means the same thing on every plane — per client, per plane —
+     * rather than one shared total across all three.
+     *
      * 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
@@ -1469,12 +1644,27 @@ export type ResourceConfiguration_Operation_Base<TCustomOperationEnum extends En
      * Calculated at factory execution time.
      */
     repositoryDto?: z.ZodSchema<any>;
+    /**
+     * `EVENT_COUNTER` badge writes this operation performs after it succeeds.
+     *
+     * `badgeRef` is a badge KEY (`<scope>:<identifier>`), NOT a bare identifier, and it is what
+     * decides which badge is written — including at WHICH SCOPE. The scope used to be inferred from
+     * this operation's own `resourcePrimaryScope`, which meant an operation on a user-scoped
+     * resource wrote a user-scoped counter even when the definition it named lived at organization
+     * scope: a row no definition declared, that no screen could render, reported nowhere.
+     *
+     * Every `badgeRef` is resolved against the registered `notificationBadgeDefinitions` at
+     * CONFIGURATION time and the application refuses to start when one does not resolve. Only the
+     * scopeId — whose badge — is left to the request.
+     */
     notificationBadgeOperations: {
-        identifier: NotificationBadgeIdentifier;
+        badgeRef: NotificationBadgeKey;
         operation: NotificationBadgeOperation;
     }[];
     userNotifications: UserNotificationDefinition[];
     m2mNotifications: M2MNotificationDefinitionWithoutIdentifier[];
+    /** Authored metered-usage recording for this operation; `undefined` when it consumes nothing. */
+    recordsUsage?: MeteredUsageRecordingDefinition;
 };
 /** @wildo_source:part:end saas.models.resource-config.operation-base */
 /**
@@ -1542,9 +1732,20 @@ export type ResourceConfiguration_Operation_ApiCall<TCustomOperationEnum extends
     /**
      * 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
+     * runtime by three enforcers, one per plane that can dispatch this
+     * operation: `RateLimitBackendService.checkPolicyForVariant` at the
      * controller pre-flight seam (`controller-resource.backend.service.ts`
-     * → `doOperation`).
+     * → `doOperation`), `McpServerBackendService.assertOperationRateLimitPolicy`
+     * on the MCP tool plane, and `assertDeclaredOperationRateLimit` on the agent
+     * function-tool plane (`function-tools.backend.definitions.ts`). Only the
+     * first is IP-keyed; the other two count the caller's credential, because
+     * there is no socket to key on.
+     *
+     * **A new plane that dispatches a resource operation off HTTP owes its own
+     * call to `checkPolicyForSubject`.** Nothing structural enforces that — the
+     * field is simply not read where nobody reads it — which is how the MCP and
+     * function-tool planes each shipped unthrottled for the operations that
+     * declare a budget.
      *
      * Auto-variants (`SUMMARY` / `CONTEXT` for READ/LIST) inherit this
      * field from their default URL-bearing variant (`API_CALL` or
@@ -1628,12 +1829,71 @@ export type OperationConfig_ForKey<K, TMainSchema extends z.ZodTypeAny = z.ZodAn
     }[];
     userNotifications?: UserNotificationDefinitionWithoutPrimaryScopeAndIdentifier[];
     notificationBadgeOperations?: {
-        identifier: NotificationBadgeIdentifier;
+        badgeRef: NotificationBadgeKey;
         operation: NotificationBadgeOperation;
     }[];
     m2mNotifications?: M2MNotificationDefinitionWithoutIdentifier[];
+    recordsUsage?: MeteredUsageRecordingDefinition;
 };
 /** @wildo_source:part:end saas.models.resource-config.operation-variant-for-key */
+/**
+ * @wildo_source:part:start saas.models.resource-config.metered-usage-recording facet:layer:shared facet:family:resource-config
+ *
+ * Declares that a successful operation CONSUMES a metered product, so the engine records usage
+ * against the caller's billing account (#415).
+ *
+ * Before this existed, `UsageMeteringBackendService.recordUsage` had no caller anywhere: a product
+ * could be declared METERED, priced and synced to the billing provider, and nothing in the framework
+ * ever wrote a usage row. An application could only meter by reaching into a backend service by hand
+ * from a custom implementation, which is not an authoring surface — it is a workaround.
+ *
+ * Declared per OPERATION, beside `userNotifications` and `m2mNotifications`, because it is the same
+ * kind of thing: an authored consequence of an operation succeeding, expressed where the operation is
+ * expressed rather than buried in a handler.
+ *
+ * @example
+ * // One unit per successful export, whatever the export contains.
+ * [CoreResourceOperation.CREATE]: {
+ *   variants: [ ... ],
+ *   recordsUsage: { productKey: 'report_exports' },
+ * }
+ *
+ * @example
+ * // Usage that VARIES per operation, read from the row that was written.
+ * [Reports_Operations.RENDER]: {
+ *   variants: [ ... ],
+ *   recordsUsage: { productKey: 'rendered_pages', quantityFromResultField: 'pageCount' },
+ * }
+ */
+export interface MeteredUsageRecordingDefinition {
+    /**
+     * The METERED product's key.
+     *
+     * Convention, unchanged from the flush: the product key IS the provider's meter event name. Usage
+     * is only recorded when the caller's billing account holds an ACTIVE or TRIALING subscription
+     * containing a METERED product with this key — an operation declared against a product nobody has
+     * bought records nothing, and warns.
+     */
+    productKey: string;
+    /**
+     * Fixed units per successful operation. Defaults to 1.
+     *
+     * Mutually exclusive with {@link quantityFromResultField}: a usage amount has one source, and
+     * letting both apply would make "which one wins" a rule nobody could read off the declaration.
+     */
+    quantity?: number;
+    /**
+     * Dot path to a NUMERIC field on the written row, for usage that varies per operation — pages
+     * rendered, bytes stored, rows exported.
+     *
+     * Read from the operation's RESULT rather than its input, deliberately: the input is what was
+     * asked for and the result is what happened, and only the second is what a customer should be
+     * billed for. A path that resolves to a non-number records nothing and warns, rather than
+     * defaulting to 1 — silently billing the wrong amount is worse than billing nothing and saying so.
+     */
+    quantityFromResultField?: string;
+}
+/** @wildo_source:part:end saas.models.resource-config.metered-usage-recording */
 /**
  * @wildo_source:part:start saas.models.resource-config.operation-union facet:layer:shared facet:family:resource-config
  *
@@ -1692,10 +1952,11 @@ export type ResourceConfiguration_Operation_BuilderParameters<TMainSchema extend
     }[];
     userNotifications?: UserNotificationDefinitionWithoutPrimaryScopeAndIdentifier[];
     notificationBadgeOperations?: {
-        identifier: NotificationBadgeIdentifier;
+        badgeRef: NotificationBadgeKey;
         operation: NotificationBadgeOperation;
     }[];
     m2mNotifications?: M2MNotificationDefinitionWithoutIdentifier[];
+    recordsUsage?: MeteredUsageRecordingDefinition;
 };
 /**
  * @wildo_source:part:start saas.models.resource-config.builder-parameters facet:layer:shared facet:family:resource-config
@@ -1780,10 +2041,22 @@ export type ResourceSystemAccessPolicy = {
      * 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.)
+     * **LIVE, and REACHABLE.** `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.
+     *
+     * "Reachable" is the half that was missing until #490, and the distinction is worth keeping. The
+     * primitives were correct and enforced from the day M5b landed — and had **no caller**, so the only
+     * route an operator actually had to a retained record was a database console: the unaudited path
+     * they were built to replace. `users | read_retained` is the operator surface that closes it, an
+     * authenticated `APP_ADMIN_SUPER_ADMIN` operation carrying a mandatory justification.
+     *
+     * A resource that derives this grant and exposes no such operation is reachable by nothing. That
+     * is a defensible state — not every retention resource needs an operator door — but it should be a
+     * decision rather than an oversight, and `retained-see-through-operator-surface.test.ts` is what
+     * makes it one.
+     *
+     * (This block previously said the primitives were "wired in a later phase" — false since M5b.)
      */
     seeRetained?: ResourceSystemAccessMode;
     /**
@@ -1974,7 +2247,7 @@ export type ResourceConfiguration_BuilderParameters<TCustomOperationEnum extends
      * stance, erasure stance, and remote-call semantics. The factory enforces presence/absence
      * coherence and content-validates the declaration.
      */
-    httpApiBinding?: HttpApiResourceBinding;
+    httpApiBinding?: HttpApiResourceBindingAuthored;
     /** REQUIRED when `persistenceAdapter` is INTROSPECTION; meaningless otherwise. */
     introspectionBinding?: IntrospectionResourceBinding;
     /**
@@ -1986,7 +2259,7 @@ export type ResourceConfiguration_BuilderParameters<TCustomOperationEnum extends
      * targets exist, accept null unless `required`, and are excludeFromCreate/Update; CLOSED
      * population refuses caller CREATE operations).
      */
-    externalDataPipeline?: ExternalDataPipelineDeclaration;
+    externalDataPipeline?: ExternalDataPipelineDeclarationAuthored;
     isSystemResource?: boolean;
     /**
      * Does this resource's OWN primary-key URL segment name the CALLER, or the SUBJECT?
@@ -2250,8 +2523,38 @@ export type ResourceConfiguration_InitializationFactory<TCustomOperationEnum ext
  * 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.
+ *
+ * ## The `undefined` arms produce the OPEN MAP, and that is the fix for #44
+ *
+ * Both of them used to produce `undefined` itself. Since the type parameter DEFAULTS to
+ * `undefined`, that made the BARE `ResourceConfiguration_InitializationFactoryMap` — written with
+ * no type argument — resolve to `undefined`, and every package here compiles with
+ * `strictNullChecks` off, where `undefined` is assignable in both directions. So roughly 34 bare
+ * annotations across engine, platform and examples described nothing at all: a wrong factory, a
+ * misspelled key or an unrelated object were accepted identically. It had reached
+ * `ResourcesRegistryService.initialize`, whose two configuration-map parameters use the bare form,
+ * making the engine's own registry initializer typed `(configurations: undefined, …)`.
+ *
+ * **Only the RESULT of those two branches changed. The chain's STRUCTURE is untouched**, which is
+ * what the warning above requires: the leading conditional is still the distributive
+ * `TResourceType extends undefined`, so inference at a positional argument still reaches the
+ * mapped-type branch. Verified rather than assumed — `platform-apps-manager` and
+ * `platform-crontabs-batches-manager`, the two runtimes the 2026-08-26 regression broke and the
+ * only two that pass a typed custom map positionally, both typecheck at 0 errors.
+ *
+ * Note the fix #44 itself proposed — leading with a NON-distributive `[TResourceType] extends
+ * [undefined]` — is precisely the shape that regression had, so it was not taken.
+ *
+ * Passing `undefined` explicitly stays legal, which every application registry relies on and
+ * `resource-configuration-factory-map-types.test.ts` pins. It is legal today because
+ * `strictNullChecks` is off; if this package is ever made strict, these parameters need an explicit
+ * `| undefined` rather than a type that collapses to it.
  */
-export type ResourceConfiguration_InitializationFactoryMap<TResourceType extends ResourceType | undefined = undefined> = TResourceType extends undefined ? undefined : [TResourceType] extends [undefined] ? undefined : TResourceType extends ResourceType ? {
+export type ResourceConfiguration_InitializationFactoryMap<TResourceType extends ResourceType | undefined = undefined> = TResourceType extends undefined ? {
+    [key: string]: ResourceConfiguration_InitializationFactory<any, any, any>;
+} : [TResourceType] extends [undefined] ? {
+    [key: string]: ResourceConfiguration_InitializationFactory<any, any, any>;
+} : TResourceType extends ResourceType ? {
     [key in TResourceType]: ResourceConfiguration_InitializationFactory<any, any, any>;
 } : {
     [key: string]: ResourceConfiguration_InitializationFactory<any, any, any>;