@ultimat3/query 22.9.1 → 22.11.0

package/CLAUDE.md

@@ -38,7 +38,8 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 
 ## Invariants — the read path
 
-- Every surface goes through `sourceFor`: parse input, evaluate policy, build the source. A second
+- Every surface goes through `sourceFor`: the policy's actor half (`guardBeforeInput`), parse input,
+  evaluate policy, build the source. A second
   read path is the one unforgivable change here.
 - **An explicit `ctx` is INSTALLED, never merely passed** — the ambient context (which
   `@ultimat3/entity`'s tenant guard reads) must be the identity `guard()` decided about.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/query",
-  "version": "22.9.1",
+  "version": "22.11.0",
   "description": "The query primitive: a policy-checked read, optionally live, with cursor pagination and an incremental matcher",
   "license": "MIT",
   "type": "module",
@@ -36,11 +36,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "22.9.1",
-    "@ultimat3/core": "22.9.1",
-    "@ultimat3/entity": "22.9.1",
-    "@ultimat3/http": "22.9.1",
-    "@ultimat3/policy": "22.9.1",
-    "@ultimat3/schema": "22.9.1"
+    "@ultimat3/cache": "22.11.0",
+    "@ultimat3/core": "22.11.0",
+    "@ultimat3/entity": "22.11.0",
+    "@ultimat3/http": "22.11.0",
+    "@ultimat3/policy": "22.11.0",
+    "@ultimat3/schema": "22.11.0"
   }
 }

package/src/errors.ts

@@ -1,5 +1,5 @@
 /** Every failure @ultimat3/query can produce, one subclass per stable code. */
-import { assertNever, registerErrorCodes, UltimateError } from '@ultimat3/core';
+import { assertNever, deniedCallerFix, registerErrorCodes, UltimateError } from '@ultimat3/core';
 import type { SurfaceDenial } from '@ultimat3/policy';
 
 // No `docs:` on the classes below.
@@ -87,6 +87,7 @@ export class QueryDeniedError extends UltimateError {
       code,
       cause: `${query} denied: ${denialReason(denial)}`,
       fix: `x policy explain ${query} --json   # shows which clause decided and why`,
+      callerFix: deniedCallerFix(),
     });
     this.denial = denial;
   }

package/src/index.ts

@@ -129,6 +129,7 @@ export {
   actorOf,
   admitsAnonymous,
   guard,
+  guardBeforeInput,
   policyCapability,
   policyPermissions,
 } from './policy-gate';
@@ -142,6 +143,7 @@ export type {
   QueryListFilterOp,
   QueryListParams,
   QueryMcp,
+  QueryMcpAnnotations,
   QueryOptions,
   QueryRateLimit,
   SourceOptions,

package/src/policy-gate.ts

@@ -9,6 +9,7 @@ import { assertNever, isAnonymous } from '@ultimat3/core';
 import type { Policy, Surface as PolicySurface } from '@ultimat3/policy';
 import {
   enforce,
+  enforceBeforeInput,
   policyPermissions as flattenedPermissions,
   admitsAnonymous as policyAdmitsAnonymous,
 } from '@ultimat3/policy';
@@ -42,6 +43,23 @@ export function guard(policy: QueryPolicy, subject: QuerySubject, surface: Query
   if (denial !== undefined) throw new QueryDeniedError(subject.query, denial);
 }
 
+/**
+ * The actor-only half of `guard`, run BEFORE the input is parsed — the twin of
+ * `@ultimat3/action`'s. A reader the policy refuses whatever they send is answered 403 (or 401),
+ * never `X_INPUT_INVALID` with the read's input schema in it. Undecided passes to `guard`.
+ */
+export function guardBeforeInput(
+  policy: QueryPolicy,
+  subject: Omit<QuerySubject, 'input' | 'row'>,
+  surface: QuerySurface,
+): void {
+  const denial = enforceBeforeInput(policySurface(surface), policy, {
+    actor: subject.actor,
+    ctx: subject.ctx,
+  });
+  if (denial !== undefined) throw new QueryDeniedError(subject.query, denial);
+}
+
 /** A direct server read is the job surface: no request, no socket to close. */
 function policySurface(surface: QuerySurface): PolicySurface {
   switch (surface) {

package/src/query.ts

@@ -62,6 +62,21 @@ export interface QueryMcp {
    * implements them; `manage_resource` refuses anything outside the whitelist before it runs.
    */
   readonly listParams?: QueryListParams;
+  /** The tool's display name in an MCP client. See `ActionMcp.title`. */
+  readonly title?: string;
+  /**
+   * MCP tool annotations, overriding the derived `readOnlyHint: true` key by key — `openWorldHint:
+   * true` for a read that reaches outside the app. See `ActionMcp.annotations`.
+   */
+  readonly annotations?: QueryMcpAnnotations;
+}
+
+/** Structural twin of `@ultimat3/action`'s `McpAnnotationHints` (siblings cannot import). */
+export interface QueryMcpAnnotations {
+  readonly readOnlyHint?: boolean;
+  readonly destructiveHint?: boolean;
+  readonly idempotentHint?: boolean;
+  readonly openWorldHint?: boolean;
 }
 
 /** One comparison a list filter accepts. A filter key is `<field><op>`: `status_eq`. */

package/src/read.ts

@@ -29,7 +29,7 @@ import {
   readThrough,
 } from './cache';
 import { QueryForeignError, QueryInputInvalidError, QueryUnregisteredError } from './errors';
-import { actorOf, guard } from './policy-gate';
+import { actorOf, guard, guardBeforeInput } from './policy-gate';
 import type { AnyQuery, AnyQueryDef, Query, QueryOptions, SourceOptions } from './query';
 import type { SqlSource } from './source';
 
@@ -204,8 +204,17 @@ async function buildSource(
 ): Promise<SqlSource<object>> {
   const def = defOf(target);
   const name = queryName(target);
-  const input = await validate(def.input, raw, name);
   const unenforced = options.unenforced;
+  // The actor half of the policy first, exactly as `invoke` does it: a reader refused whatever
+  // they send learns nothing about this read's input schema from an `X_INPUT_INVALID`.
+  if (unenforced === undefined) {
+    guardBeforeInput(
+      def.policy,
+      { actor: actorOf(ctx), ctx, query: name },
+      options.surface ?? 'server',
+    );
+  }
+  const input = await validate(def.input, raw, name);
   if (unenforced === undefined) {
     guard(
       def.policy,