@wildo-ai/saas-backend-lib 1.1.2 → 1.1.4

package/dist/esm/flows-actors/models/function-tools.backend.definitions.js

@@ -1,6 +1,25 @@
 import { z } from 'zod';
-import { CoreResourceOperation } from '@wildo-ai/saas-models';
+import { CoreResourceOperation, ErrorType, ResourceOperationVariantType, ResourcesConfig_OperationPathUtils, isWildoBackendError, } from '@wildo-ai/saas-models';
 import { toResponseSafeToolOutput } from '../../base-classes/services/controllers/utils/operation-response-serializer.backend.utils.js';
+import { resolveDeclaredPolicySubjectKey } from '../../security/authentications/services/utils/external-turn-rate-limit.backend.utils.js';
+/** @wildo_source:part:end saas.backend.flows-actors.function-tool */
+/**
+ * The name a `functionRef` is exposed to the model under.
+ *
+ * Provider tool names must be identifier-safe and a `functionRef` uses dots, so the two differ for
+ * every tool. ONE definition, because the mapping is used in opposite directions by two sites: the
+ * turn BUILDS the tool set from refs, and a resume that re-signs a modified approval must find the
+ * FunctionTool behind a name it reads back out of the model SDK's own message array. A second copy
+ * of this expression would make an approval unmodifiable for exactly the refs the two spelled
+ * differently.
+ *
+ * Not injective by construction (`a.b` and `a_b` collapse), and deliberately not made so: the
+ * forward direction is what the model sees, and a reverse lookup resolves against ONE agent's
+ * declared refs, where a collision would already be an authoring defect.
+ */
+export function modelToolNameForFunctionRef(functionRef) {
+    return functionRef.replace(/[^a-zA-Z0-9_-]/g, '_');
+}
 /** Normalize a handler list/search result (array or paginated) to the tool result shape. */
 function toReadResult(result, limit) {
     if (Array.isArray(result)) {
@@ -12,6 +31,327 @@ function toReadResult(result, limit) {
     }
     return { data: [] };
 }
+/**
+ * Resolve the operation a tool DISPATCHES for `(resourceType, operationIdentifier)`: the
+ * URL-BEARING default, and nothing else.
+ *
+ * ## The defect this closes — `authorize ≡ advertise ≡ execute`
+ *
+ * Both factories used to resolve through `getServiceOperationPathDefault`, and they dispatched
+ * through the `ServicesRegistryHandlerBackendService` convenience verbs (`create` / `update` /
+ * `list` / `search`), which re-resolve the same way. That resolver PREFERS an `INTERNAL_CALL`
+ * default over the URL-bearing one — deliberately, because it is the SERVICE layer's native
+ * transport and the trusted internal callers it was written for want exactly that. This plane is
+ * not one of them: it faces an external principal and advertises a public operation to a model.
+ *
+ * So for a resource declaring BOTH defaults, the tool advertised one operation and executed
+ * another — a different `requestDto` validating the model's arguments, a different response DTO,
+ * a different `roles` declaration, and different prefix / postfix / custom-impl side effects.
+ *
+ * **Measured 2026-09-08, and exactly one resource declares both: `organizations` CREATE.** The
+ * divergence there is not cosmetic. Its `INTERNAL_CALL` default is the transport registration owns,
+ * so the shared CREATE prefix treats that path as registration-managed and SKIPS the
+ * `org_type_creation_restricted` guard that confines creation-policy-managed organization types to
+ * the registration flow; and the founding-owner postfix is registered on the DEFAULT `API_CALL`
+ * variant ONLY, so the internal path writes no owner membership. An agent tool wired to
+ * `resourceWriteTool(ORGANIZATIONS, CREATE)` therefore created a tenant with no owner — precisely
+ * the stranded state `administrative-continuity-floors.md` exists to prevent — while also reaching
+ * a restricted organization type. The MCP tool plane had already made this exact decision and wrote
+ * down the reasoning (`McpServerBackendService.callTool`); this plane simply had not.
+ *
+ * ## Why "no URL-bearing default" now REFUSES, and why that is the safe direction
+ *
+ * This is a behaviour change, and it is intended. A resource whose only default for an identifier
+ * is `INTERNAL_CALL` has NO HTTP surface, and its author reasoned from exactly that: `users` LIST
+ * declares `roles: []` and says in as many words that the empty set "is inert here precisely
+ * because it is not URL-bearing". A tool that dispatched it made a route-less, deliberately
+ * unexposed operation reachable by an external agent — the opposite of what the declaration
+ * assumed. Refusing is fail-closed, and the refusal names the resource and the operation so an app
+ * author who genuinely wants that surface exposed can declare a URL-bearing default for it.
+ *
+ * @returns the URL-bearing default operation, or `undefined` when the resource declares none.
+ */
+function resolveDispatchableOperation(ctx, resourceType, operationIdentifier) {
+    const { resourcesRegistry } = ctx.services;
+    // Non-throwing probe FIRST: `getOperationPathDefault` mints an alert-grade INTERNAL error on its
+    // miss path, and merely CONSTRUCTING a Wildo error fires its backend actions (LOG / ALERT /
+    // METRICS) before any `catch` could downgrade them. A resource with no URL-bearing default for
+    // this identifier is an ordinary, expected shape here — not an incident.
+    if (!resourcesRegistry.hasOperationPathDefault(resourceType, operationIdentifier)) {
+        return undefined;
+    }
+    return resourcesRegistry.getOperationFromPath(resourcesRegistry.getOperationPathDefault(resourceType, operationIdentifier));
+}
+/** {@link resolveDispatchableOperation}, refusing rather than returning `undefined`. */
+function requireDispatchableOperation(ctx, resourceType, operationIdentifier) {
+    const operation = resolveDispatchableOperation(ctx, resourceType, operationIdentifier);
+    if (!operation) {
+        throw new Error(`Agent function tool for "${resourceType}.${operationIdentifier}": the resource declares no default URL-bearing `
+            + 'variant for this operation, so there is no publicly-advertised operation for the tool to dispatch. Declare an '
+            + 'API_CALL default for it, or expose a different operation.');
+    }
+    return operation;
+}
+/**
+ * Apply the dispatched operation's OWN `roles` ACL — the gate this plane was missing entirely.
+ *
+ * ## What was broken
+ *
+ * A function tool dispatches a resource operation through
+ * `ServicesRegistryHandlerBackendService`, i.e. it enters at the SERVICE tier. The service tier
+ * applies the repository's contextual filter (tenancy, FK narrowing, unit narrowing, the anonymous
+ * guard, the retention row-hide — all fail-closed) and the whole operation pipeline (Zod, enabled
+ * conditions, custom impl, hooks). It applies NO role check, and that is deliberate and
+ * load-bearing: its dominant population is authentication, SCIM provisioning, webhook routing and
+ * sweeps, which run BEFORE a role-bearing principal exists. Enforcing declared roles there would
+ * deny the reads that ESTABLISH identity.
+ *
+ * `AuthorizationsBackendService.authorizeInController` is therefore the ONLY place an operation's
+ * declared `roles` are checked, and it is mounted at the CONTROLLER tier — the boundary, because
+ * that is where an untrusted principal names an operation.
+ *
+ * **This plane is that boundary and did not ask.** A tool call arrives from an external principal
+ * (an A2A agent's token, or a user's own WebSocket) naming an operation on their own authority, and
+ * dispatched it with the role ACL unread. A caller whose roles the operation refuses, but whose
+ * tenancy admits the row, succeeded — so `roles: [ORG_MEMBER]` on Wonder Todos' todos CREATE, and
+ * `roles: [APP_USER]` on the organizations self-service CREATE, were both statements about the HTTP
+ * door only. Worse, the factories' own JSDoc, the app's registration comment and
+ * `authenticateExternalToken`'s contract all asserted the opposite, so the gap read as closed.
+ *
+ * The MCP plane, which faces the same class of caller through a different transport, has always run
+ * this gate (`McpServerBackendService.callTool`). This is the same call, on the sibling plane.
+ *
+ * ## Collection vs row
+ *
+ * `idOrIds` is `undefined` for CREATE / LIST / SEARCH (collection: roles + parent scope) and the
+ * addressed record id for UPDATE (row: additionally FK reachability and per-row access). Passing a
+ * value in the row's place for a collection call would authorize a READ of a row whose id happens
+ * to be a scope id — a question nobody asked, failing for the wrong reason.
+ *
+ * Refusals are recorded by the authorizer's own denial-audit funnel, so a tool call denied here
+ * produces the same `RESOURCE_OPERATION_DENIED` evidence a denied HTTP request produces.
+ *
+ * assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — an external caller reaching a resource operation
+ * off the HTTP plane is held to that operation's own declared authority, through the same predicate.
+ *
+ * @throws AUTHORIZATION — surfaced to the model as a tool error, so the agent can say it was refused.
+ */
+async function authorizeToolDispatch(ctx, executionContext, idOrIds) {
+    await ctx.services.authorizer.authorizeInController(idOrIds, executionContext);
+}
+/**
+ * Charge ONE dispatch against the operation's own authored `rateLimit?` policy, before the
+ * dispatch happens.
+ *
+ * ## What was broken
+ *
+ * `rateLimit?` is authored on an `API_CALL` / `API_CALL_WITH_CALLBACK` variant and had exactly
+ * two consumers: `RateLimitBackendService.checkPolicyForVariant` at the HTTP controller
+ * pre-flight, and `McpServerBackendService.assertOperationRateLimitPolicy` on the MCP tool plane.
+ * The factories below dispatch the SAME operations through the SAME service pipeline while
+ * bypassing Express entirely, so the identical operation was throttled over REST, throttled over
+ * MCP, and unthrottled as an agent tool.
+ *
+ * The exposure is larger here than on either of those planes, which is why this is not merely a
+ * consistency fix. A2A's blanket per-principal cap (`A2A_EXTERNAL_TURN_RATE_MAX`) bounds TURNS,
+ * and one turn's tool loop may issue arbitrarily many tool calls — so an operation declaring
+ * `requestsPerMinute: 5` could be dispatched far more than five times a minute by an external
+ * caller spending a single turn. MCP has no such multiplier: one `tools/call` is one dispatch, so
+ * its transport cap bounds dispatches 1:1.
+ *
+ * ## The policy is read off the operation actually being DISPATCHED — which is now the right one
+ *
+ * This guard originally re-resolved the URL-bearing default for itself, because the factories
+ * dispatched the `INTERNAL_CALL` default and `rateLimit?` does not exist on that variant at all —
+ * so reading the dispatched operation would have made the guard permanently inert for precisely
+ * the resources that declare both. That divergence is gone: {@link resolveDispatchableOperation}
+ * makes the URL-bearing default the dispatched operation, and this function takes it as an
+ * argument. Policy-source and dispatch-target are now the same object rather than two resolutions
+ * that agreed by discipline — which is what stops them separating again.
+ *
+ * Reading a single declaration as the OPERATION's budget is the framework's own established
+ * reading of the field, not an invention: `resources-config.shared.factory.ts` projects
+ * `rateLimit: defaultApiCallVariant.rateLimit` onto every derived auto-variant, stating that "a
+ * single declaration on the default URL-bearing variant covers all derived auto-variants".
+ *
+ * ## Subject: the CREDENTIAL, not the tenant
+ *
+ * See {@link resolveDeclaredPolicySubjectKey} for the full argument. In short, an authored
+ * `requestsPerMinute` has always meant "per CLIENT" — the HTTP seam keys on the source IP — so
+ * the faithful translation onto a plane whose callers are credentials is the credential, then the
+ * delegated user, then the owning scope. Keying on the tenant would silently make the same
+ * declared number several times stricter here than over REST for any tenant running more than one
+ * agent. Every branch reads a SERVER-VERIFIED field of the caller's auth; nothing here may ever be
+ * sourced from a tool argument, or the throttle becomes opt-out by a model choosing a fresh bucket.
+ *
+ * ## Scope: a THIRD bucket, deliberately
+ *
+ * `agent-tool:resource:<resource>:<operation>`, distinct from the HTTP seam's
+ * `resource:<resource>:<operation>` and MCP's `mcp:resource:<resource>:<operation>`. The three
+ * count different SUBJECTS (an IP, a credential, a credential on a different transport); one
+ * shared bucket would mix identity spaces and let a browser's traffic spend an agent's budget.
+ *
+ * ## Ordering: AFTER authorization
+ *
+ * Reversed 2026-09-08, when the role gate landed beside it, and MCP's argument is adopted verbatim:
+ * a caller who may not run the operation at all must be refused with AUTHORIZATION rather than told
+ * how much of a budget they have, and must not consume a slot of a budget that is not theirs —
+ * which would let an unauthorized caller exhaust an authorized one's quota. The HTTP seam orders
+ * these the other way round because it has no choice (`checkPolicyForVariant` runs pre-flight,
+ * before the execution context authorization needs exists); here the identity is already resolved,
+ * so the safer order is available and is taken.
+ *
+ * ## Postures
+ *
+ * - **No declared policy, or a non-HTTP default** -> no-op, zero Redis traffic. The overwhelmingly
+ *   common case: most operations declare nothing.
+ * - **Unkeyable subject with a policy declared** -> REFUSE. This diverges from MCP's
+ *   proceed-and-log, and the reason is the tool-loop multiplier described above: there, an
+ *   unkeyed call is still bounded 1:1 by the transport's per-principal cap, so proceeding costs a
+ *   bounded amount; here an unkeyed turn could drive an uncounted, unbounded loop against an
+ *   endpoint whose author asked for a budget. The branch is structurally unreachable — a tool runs
+ *   only inside an authenticated turn, and an authenticated principal always carries one of the
+ *   four identity fields — so the refusal costs nothing today and cannot decay into a silent hole.
+ * - **Limiter outage** -> propagates, exactly as it does over HTTP and MCP for the same declared
+ *   policy. An authored budget must not quietly become "unlimited" on one plane while it is a 500
+ *   on the others. (Contrast `assertExternalTurnWithinRate`, the framework-default abuse throttle,
+ *   which fails OPEN because nobody declared it.)
+ *
+ * ## Call-site enumeration, so the next reader does not re-derive it
+ *
+ * The invariant is "a resource operation dispatched on behalf of an external CLIENT is charged
+ * against its declared budget". Enumerated 2026-09-08 over every caller of the generic service
+ * dispatch (`doByOperationPath` and the `ServicesRegistryHandlerBackendService` verbs):
+ *
+ * | Plane | Verdict |
+ * |---|---|
+ * | REST route (`ControllerResourceBackendService.doOperation`) | charged — `checkPolicyForVariant`, IP-keyed |
+ * | MCP `tools/call` (`McpServerBackendService`) | charged — `checkPolicyForSubject`, credential-keyed |
+ * | Agent function tool (here; reachable over A2A and the app WebSocket) | charged — this function |
+ * | Queue job executor (`job-executor.backend.service.ts`) | **N/A** — a REPLAY of an operation already authorized, and already charged, at enqueue time (`isWorkerExecution: true`). Charging again would double-count one client request and throttle a background worker against a client's budget |
+ * | Minion-scoped handler (`saas-minions-lib`) | **N/A** — same worker plane, one scope deeper |
+ * | Custom controllers (SCIM, charts, flows-actors) | **N/A** — the separate authoring surface: they declare their own policy and call `checkPolicy` inline (SCIM does, with its own scope key) rather than inheriting a resource operation's |
+ * | Engine-internal collaborators (auth, org, RAG, seeding, retention) | **N/A** — not client-driven; reached from a plane that already charged, or from a system path with no client at all |
+ *
+ * The rule that generalises: a NEW plane that dispatches a resource operation on a client's behalf
+ * owes its own `checkPolicyForSubject` call — AND its own `authorizeInController`. Nothing
+ * structural forces either; both fields are simply unread where nobody reads them, which is how
+ * both the MCP plane and this one shipped unthrottled, and how this one shipped unauthorized.
+ *
+ * @throws RATE_LIMIT (429) carrying `context.retryAfterSeconds` — the same envelope the HTTP and
+ *   MCP seams throw, so one refusal vocabulary covers all three planes. The AI SDK surfaces it to
+ *   the model as a tool error, so the agent can tell the user it is being throttled.
+ */
+async function assertDeclaredOperationRateLimit(ctx, operation, resourceType, operationIdentifier) {
+    // Defensive: `resolveDispatchableOperation` already filters to URL-bearing variants, so this
+    // narrow exists to reach `rateLimit` on the union rather than to exclude a reachable case.
+    if (operation.variantType !== ResourceOperationVariantType.API_CALL
+        && operation.variantType !== ResourceOperationVariantType.API_CALL_WITH_CALLBACK) {
+        return;
+    }
+    const policy = operation.rateLimit;
+    if (!policy) {
+        return;
+    }
+    const subjectKey = resolveDeclaredPolicySubjectKey(ctx.auth?.initiatorIds);
+    if (!subjectKey) {
+        throw new Error(`Agent function tool for "${resourceType}.${operationIdentifier}": the operation declares a rateLimit policy but the `
+            + 'caller carries no server-verified identity to count it against, so the declared budget cannot be honoured.');
+    }
+    await ctx.services.rateLimitService.checkPolicyForSubject(policy, `agent-tool:resource:${resourceType}:${operationIdentifier}`, subjectKey, ctx.organizationId);
+}
+/**
+ * Dispatch a resource operation from a function tool, carrying BOTH gates the service tier skips.
+ *
+ * ## What this exists to prevent (#556)
+ *
+ * A `FunctionTool` enters at the SERVICE tier. It never passes through Express, so two
+ * controller-tier gates are simply absent from its path — the operation's declared `roles` ACL and
+ * its declared `rateLimit?`. That skip is CORRECT for the service tier's intended caller (the
+ * authentication reads that run before a role-bearing principal exists) and wrong for this plane,
+ * whose caller is an external principal naming an operation on their own authority.
+ *
+ * The failure is quiet, which is what makes it worth a seam. Tenancy still applies — the
+ * repository's contextual filter runs regardless — so an unauthorized tool returns the caller's own
+ * tenant's rows and LOOKS like it works. Nothing throws and nothing logs. What is missing is only
+ * the row-level `roles` ACL: a caller whose roles the operation refuses, but whose tenancy admits
+ * the row, succeeds.
+ *
+ * Until this existed the two gates were applied by hand at three sites in this file, and both helpers
+ * were module-private — so an application author writing their own tool could not discharge the
+ * obligation even after reading about it. The engine's own rule
+ * (`invariant-call-site-enumeration.md`) asks for the opposite: prefer making the invariant
+ * unbypassable over applying it N times. **This is the shortest path to a dispatch, so the correct
+ * path is also the easy one.**
+ *
+ * ## The order is authorize → charge → dispatch, and it is not arbitrary
+ *
+ * Authorization first, so an unauthorized caller cannot spend an authorized caller's quota. The
+ * charge before the dispatch, so a refused budget costs no work. This is the same order the MCP
+ * plane uses, deliberately — one refusal vocabulary across every plane that enters here.
+ *
+ * ## One id, two uses, and why that is safer than two parameters
+ *
+ * `recordId` addresses the row AND is the authorization subject, because at every existing call site
+ * those are the same value: an UPDATE passes the id to both, a CREATE/LIST/SEARCH passes it to
+ * neither. Splitting them into two parameters would make it possible to authorize a collection call
+ * while dispatching a row call — a question nobody asked, failing for the wrong reason. A bulk
+ * operation addressed by a FILTER passes `dispatchFilter` instead, which is never an authorization
+ * subject because a filter-addressed operation IS a collection call.
+ *
+ * assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — an external caller reaching a resource operation
+ * off the HTTP plane is held to that operation's own declared authority, through the same predicate.
+ *
+ * @throws AUTHORIZATION when the operation's roles refuse the caller — surfaced to the model as a
+ *   tool error, so the agent can say it was refused. Recorded by the authorizer's own denial-audit
+ *   funnel, so the evidence matches a denied HTTP request.
+ * @throws RATE_LIMIT (429) carrying `context.retryAfterSeconds`, the same envelope the HTTP and MCP
+ *   seams throw.
+ * @throws NOT_FOUND when the resource declares no dispatchable operation under that identifier.
+ */
+export async function dispatchResourceOperationAsTool(input) {
+    const { ctx, resourceType, operationIdentifier, recordId, dispatchFilter, contextIds, data, options } = input;
+    const operation = requireDispatchableOperation(ctx, resourceType, operationIdentifier);
+    // Rebuild a scoped ExecutionContext from the CALLER's verified auth for THIS operation. Never
+    // reuse one built for another operation: the scope it resolves is operation-specific.
+    const executionContext = await ctx.services.executionContextCreator.buildContextFromSocketAuth(ctx.auth, operation, contextIds);
+    await authorizeToolDispatch(ctx, executionContext, recordId);
+    await assertDeclaredOperationRateLimit(ctx, operation, resourceType, operationIdentifier);
+    const operationPath = ResourcesConfig_OperationPathUtils.extractOperationPath(operation);
+    const subject = recordId ?? dispatchFilter;
+    /*
+     * The trailing `options` is OMITTED rather than passed as `undefined` when absent, so this seam
+     * calls the dispatcher with exactly the arity each site used before it existed.
+     *
+     * Behaviourally the two are identical for an optional parameter. What differs is what a test can
+     * see: the authorization and write pins here assert the dispatch with `toHaveBeenCalledWith`,
+     * which is arity-exact, so a uniform five-argument call would have required editing four tests
+     * that guard an authorization path. Preserving the shape proves the refactor changed nothing,
+     * which is the property that matters most for the one seam every tool dispatch now goes through.
+     */
+    return options === undefined
+        ? ctx.services.servicesRegistryHandler.doByOperationPath(operationPath, executionContext, subject, data)
+        : ctx.services.servicesRegistryHandler.doByOperationPath(operationPath, executionContext, subject, data, options);
+}
+/**
+ * Is this a REFUSAL the read tool must never launder into a different operation?
+ *
+ * Exists for exactly one reason: the read tool's SEARCH branch degrades to a scoped LIST on any
+ * throw, and a refusal swallowed there would silently become an UNGATED LIST — the guard present
+ * and inert, which is worse than absent because it reads as enforced. Two refusal kinds qualify:
+ *
+ *  - **RATE_LIMIT** — a declared budget is an application's statement about the endpoint, not a
+ *    reason to reach for a different one.
+ *  - **AUTHORIZATION** — stronger still. A denial has already been RECORDED by the authorizer's
+ *    audit funnel, so proceeding would leave a `RESOURCE_OPERATION_DENIED` row beside a request
+ *    that then succeeded, making the access trail describe something that did not happen.
+ *
+ * A genuine "this resource has no URL-bearing SEARCH operation" still degrades, unchanged.
+ */
+function isNonDegradableRefusal(error) {
+    return isWildoBackendError(error)
+        && (error.type === ErrorType.RATE_LIMIT || error.type === ErrorType.AUTHORIZATION);
+}
 /**
  * @wildo_source:part:start saas.backend.flows-actors.resource-read-tool facet:layer:backend facet:family:flows-actors
  *
@@ -21,9 +361,16 @@ function toReadResult(result, limit) {
  * it per resource an agent should be able to read (e.g. `resourceReadTool(TODOS)`),
  * making any registered resource agent-readable without hand-writing a tool.
  *
- * The tool reads through the normal service path under a user `ExecutionContext`
- * rebuilt from the caller's socket auth, so the framework's contextual filter +
- * role ACL apply exactly as for the user's own request. Identity is NEVER taken
+ * The tool dispatches the resource's PUBLIC, URL-bearing default LIST / SEARCH — the same
+ * operation a REST client reaches — under a user `ExecutionContext` rebuilt from the caller's
+ * socket auth, and applies that operation's own declared `roles` ACL through
+ * `AuthorizationsBackendService.authorizeInController` before dispatching it. So the framework's
+ * contextual filter AND the role ACL apply exactly as for the user's own request. (The role gate
+ * is named explicitly because it does NOT come free with the service path: the service tier
+ * applies tenancy and the operation pipeline and no role check, so a tool that merely dispatched
+ * would run with the ACL unread — which is what this factory did until 2026-09-08.) A resource
+ * that declares no URL-bearing default for the operation is REFUSED rather than served through its
+ * route-less internal variant. Identity is NEVER taken
  * from the model — only the `searchQuery` / `limit` args are. Its `functionRef`
  * defaults to `resource.<resourceType>.read` — reference that exact string from
  * your agent's `capabilities.tools.functionRefs`. Import path:
@@ -51,14 +398,14 @@ export function resourceReadTool(resourceType, options) {
             limit: z.number().int().min(1).max(maxLimit).optional(),
         }),
         execute: async (args, ctx) => {
-            const { resourcesRegistry, servicesRegistryHandler, executionContextCreator } = ctx.services;
+            const { servicesRegistryHandler, executionContextCreator } = ctx.services;
             const limit = typeof args?.limit === 'number' ? Math.min(args.limit, maxLimit) : defaultLimit;
             const searchQuery = typeof args?.searchQuery === 'string' && args.searchQuery.trim().length > 0 ? args.searchQuery.trim() : undefined;
             const contextIds = ctx.organizationId ? { organizationId: ctx.organizationId } : {};
-            // Prefer SEARCH when a query is supplied AND the resource supports it; fall
-            // back to a scoped LIST. Both run as the user (no ACL bypass).
+            // Prefer SEARCH when a query is supplied AND the resource EXPOSES it; fall back to a scoped
+            // LIST. Both run as the user, under the operation's own role ACL (no bypass).
             if (searchQuery) {
-                // The fallback catch covers ONLY op-resolution + the search call — a resource may have no
+                // The fallback catch covers ONLY op-resolution + the search call — a resource may expose no
                 // SEARCH operation, in which case we degrade to a scoped LIST. It deliberately does NOT wrap
                 // the response-DTO projection below: a projection failure there is a real server contract
                 // violation (a record that violates its own response DTO) and must surface as a tool error,
@@ -66,12 +413,31 @@ export function resourceReadTool(resourceType, options) {
                 let searchOp;
                 let searchResult;
                 try {
-                    searchOp = resourcesRegistry.getOperationFromPath(resourcesRegistry.getServiceOperationPathDefault(resourceType, CoreResourceOperation.SEARCH));
-                    const searchEc = await executionContextCreator.buildContextFromSocketAuth(ctx.auth, searchOp, contextIds);
-                    searchResult = await servicesRegistryHandler.search(resourceType, searchEc, searchQuery);
+                    // Non-throwing: a resource with no URL-bearing SEARCH default has nothing to expose here,
+                    // which is the documented degradation rather than a refusal.
+                    searchOp = resolveDispatchableOperation(ctx, resourceType, CoreResourceOperation.SEARCH);
+                    if (searchOp) {
+                        // The seam authorizes, charges and dispatches in that order. It sits inside this try
+                        // because that is where the dispatch is; the catch below re-throws either refusal so
+                        // neither can be laundered into an ungated LIST. The operation is resolved twice — once
+                        // above to decide whether SEARCH is even available, once inside the seam — and that is
+                        // deliberate: the availability question is this factory's, the gates are the seam's.
+                        searchResult = await dispatchResourceOperationAsTool({
+                            ctx,
+                            resourceType,
+                            operationIdentifier: CoreResourceOperation.SEARCH,
+                            contextIds,
+                            data: { searchQuery, filter: undefined },
+                        });
+                    }
                 }
-                catch {
-                    searchOp = undefined; // Resource has no SEARCH operation (or it failed to resolve) — fall through to LIST.
+                catch (error) {
+                    // A declared budget, or a role refusal, is a statement about THIS endpoint — not a reason
+                    // to reach for a different one. Degrading here would answer the model with LIST results
+                    // the caller was just refused: enforcement that reports success.
+                    if (isNonDegradableRefusal(error))
+                        throw error;
+                    searchOp = undefined; // SEARCH failed to resolve or dispatch — fall through to LIST.
                 }
                 if (searchOp !== undefined) {
                     // Project through the SEARCH operation's response DTO + JSON wire step, exactly as the
@@ -80,12 +446,22 @@ export function resourceReadTool(resourceType, options) {
                     return toReadResult(safeSearchResult, limit);
                 }
             }
-            const listOp = resourcesRegistry.getOperationFromPath(resourcesRegistry.getServiceOperationPathDefault(resourceType, CoreResourceOperation.LIST));
-            const listEc = await executionContextCreator.buildContextFromSocketAuth(ctx.auth, listOp, contextIds);
+            // LIST is a distinct operation with its own ACL and its own declared budget, so it is
+            // authorized and charged separately. A call that resolved SEARCH and then degraded to LIST
+            // does both twice — two operations were attempted, exactly as two HTTP requests would be, and
+            // that path is only reached when the search dispatch failed for a reason that is not a refusal.
+            const listOp = requireDispatchableOperation(ctx, resourceType, CoreResourceOperation.LIST);
             // `paginated: true` yields the `{ data, pagination }` envelope the LIST response DTO expects
             // (the same shape the HTTP controller requests) — a bare array would fail the wrapper-DTO
             // projection in `toResponseSafeToolOutput` below.
-            const listResult = await servicesRegistryHandler.list(resourceType, listEc, undefined, { page: 1, limit }, { paginated: true });
+            const listResult = await dispatchResourceOperationAsTool({
+                ctx,
+                resourceType,
+                operationIdentifier: CoreResourceOperation.LIST,
+                contextIds,
+                data: { filter: undefined, page: 1, limit },
+                options: { paginated: true },
+            });
             const safeListResult = await toResponseSafeToolOutput(listOp, listResult);
             return toReadResult(safeListResult, limit);
         },
@@ -98,10 +474,22 @@ export function resourceReadTool(resourceType, options) {
  * Produces a {@link FunctionTool} that lets an agent CREATE or UPDATE ONE resource
  * type **as the calling user**, under the caller's own `ExecutionContext` rebuilt
  * from their verified socket auth — no `systemAccessPolicy` bypass, and identity is
- * NEVER taken from the model. The resource's own CREATE / UPDATE `accessControl`
- * (roles + parent scope) is enforced by the service tier exactly as for the user's
- * own HTTP request, so authorization is **fail-closed**: a caller lacking the
- * operation's role gets a thrown authz error, not a silent write. Owner FKs and
+ * NEVER taken from the model. It dispatches the resource's PUBLIC, URL-bearing default CREATE /
+ * UPDATE — the same operation a REST client reaches, with the same request DTO validating the
+ * model's arguments and the same prefix / postfix side effects — and applies that operation's own
+ * `accessControl` (roles + parent scope, plus per-row access on UPDATE) through
+ * `AuthorizationsBackendService.authorizeInController` before the write. Authorization is therefore
+ * **fail-closed**: a caller lacking the operation's role gets a thrown authz error, not a silent
+ * write.
+ *
+ * Both halves of that are load-bearing and neither came free, so do not simplify them away. The
+ * service tier applies tenancy and the operation pipeline and NO role check, and the service
+ * layer's own default resolver PREFERS a route-less `INTERNAL_CALL` variant over the public one —
+ * so before 2026-09-08 this factory dispatched a different operation from the one it advertises,
+ * with the ACL unread. On `organizations` CREATE that combination created ownerless tenants.
+ *
+ * A resource that declares no URL-bearing default for the operation is REFUSED rather than written
+ * through its internal variant. Owner FKs and
  * other server-set fields are EC-injected / `excludeFromCreate`, so the model can
  * never spoof ownership through the tool arguments.
  *
@@ -140,25 +528,39 @@ export function resourceWriteTool(resourceType, op, options) {
                 : `Update an existing "${resourceType}" record the current user owns. Pass the record "id" plus only the fields to change.`),
         inputSchema: options.inputSchema,
         execute: async (args, ctx) => {
-            const { resourcesRegistry, servicesRegistryHandler, executionContextCreator } = ctx.services;
+            const { servicesRegistryHandler, executionContextCreator } = ctx.services;
             const contextIds = ctx.organizationId ? { organizationId: ctx.organizationId } : {};
-            // Rebuild a scoped ExecutionContext from the CALLER's verified auth for this
-            // operation. The service tier then enforces the op's role + scope ACL against
-            // this EC (fail-closed) — the write runs as the user, never with an ACL bypass.
-            const operation = resourcesRegistry.getOperationFromPath(resourcesRegistry.getServiceOperationPathDefault(resourceType, op));
-            const ec = await executionContextCreator.buildContextFromSocketAuth(ctx.auth, operation, contextIds);
-            if (op === CoreResourceOperation.CREATE) {
-                const created = await servicesRegistryHandler.create(resourceType, ec, args);
+            // UPDATE addresses a row; CREATE does not. Split FIRST, before anything is resolved: this is
+            // a check on the tool AUTHOR's own `inputSchema`, independent of the registry, and surfacing
+            // it ahead of a resolution failure keeps the actionable message the actionable one.
+            // `authorizeInController` then takes the addressed id and runs the row-scoped phases only
+            // when there is one.
+            const isUpdate = op === CoreResourceOperation.UPDATE;
+            const { id, ...patch } = args;
+            if (isUpdate && (typeof id !== 'string' || id.length === 0)) {
+                throw new Error(`resourceWriteTool(${resourceType}, update): the "id" argument is required — declare it in the tool's inputSchema.`);
+            }
+            // The operation the tool ADVERTISES is the resource's public, URL-bearing default; dispatch
+            // that exact one rather than re-resolving through the service layer's INTERNAL-preferred
+            // resolver. See `resolveDispatchableOperation` for what diverged and what it cost.
+            const operation = requireDispatchableOperation(ctx, resourceType, op);
+            const operationPath = ResourcesConfig_OperationPathUtils.extractOperationPath(operation);
+            // Rebuild a scoped ExecutionContext from the CALLER's verified auth for this operation, then
+            // apply the operation's own role + scope ACL against it (fail-closed) before anything is
+            // written. The write runs as the user, never with an ACL bypass.
+            if (!isUpdate) {
+                // The seam authorizes as a COLLECTION call (no row addressed), charges the operation's own
+                // budget after authorization so an unauthorized caller cannot spend an authorized one's, and
+                // writes as the user — never with an ACL bypass.
+                const created = await dispatchResourceOperationAsTool({ ctx, resourceType, operationIdentifier: op, contextIds, data: args });
                 // Return the same JSON-safe, response-DTO-projected record the REST endpoint would, so no
                 // `Date`/backend-only/secret reaches the model and the tool-loop CONTINUATION step validates.
                 return toResponseSafeToolOutput(operation, created);
             }
-            // UPDATE: the record "id" addresses the row; the remaining fields are the patch.
-            const { id, ...patch } = args;
-            if (typeof id !== 'string' || id.length === 0) {
-                throw new Error(`resourceWriteTool(${resourceType}, update): the "id" argument is required — declare it in the tool's inputSchema.`);
-            }
-            const updated = await servicesRegistryHandler.update(resourceType, ec, id, patch);
+            // UPDATE: the record "id" addresses the row AND is the authorization subject — the seam takes
+            // one value for both, which is what makes authorizing a collection call while dispatching a
+            // row call unrepresentable.
+            const updated = await dispatchResourceOperationAsTool({ ctx, resourceType, operationIdentifier: op, recordId: id, contextIds, data: patch });
             return toResponseSafeToolOutput(operation, updated);
         },
     };