@ultimat3/query 7.0.0 → 9.0.0

package/CLAUDE.md

@@ -145,6 +145,20 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
   authz stage deciding first would be a second authz system holding raw strings — and would
   demand an `authorize` hook to decide at all. `http.test.ts` drives both over the real pipeline
   with no hook wired and counts the evaluations: exactly one.
+- **`meta.auth` is derived from a WALK of the policy tree**, never from the root combinator.
+  `target.policy.kind === 'allow'` answered `'required'` for `or(allow(), can('x:y'))`, so the
+  pipeline's `auth` stage 401'd an anonymous caller the policy itself ALLOWS — while the MCP tool
+  and a direct server read let that caller through the same object. One policy, a different answer
+  per surface. `'public'` here is `meta.auth` only: the read is still `cache: no-store` and
+  `runQuery` still evaluates the policy per caller.
+  **`admitsAnonymous` is `@ultimat3/policy`'s** (`policy.ts`, beside `policyPermissions`) and
+  reaches this package through `policy-gate.ts` like every other authz question — never a copy
+  here. It cannot be one: `@ultimat3/action` needs the identical answer and is the same tier, so a
+  copy in either is a second answer for the other. It is EXACT rather than heuristic — with
+  `actor === null`, `can()` short-circuits before its predicate and `allow()`/`deny()` ignore their
+  arguments, so the tree alone decides. `packages/policy/src/policy.test.ts` asserts it against
+  `policy.run({ actor: null })` itself, case for case; `http.test.ts` proves this projection reads
+  the answer, over the real pipeline.
 - `registry.ts` announces `registerQueries` in core's registrar table at import. That is how
   `defineApi({ queries })` in `@ultimat3/action` registers a read without importing this package
   sideways. Never remove the announcement: `defineApi` would then throw `X_REGISTRAR_MISSING`.

package/package.json

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

package/src/http.ts

@@ -14,7 +14,7 @@ import type { Deprecation } from './deprecation';
 import { applyHeaders, recordDeprecatedCall, renderDeprecation } from './deprecation';
 import { QueryDeprecationInvalidError } from './errors';
 import { derivePath } from './naming';
-import { policyCapability } from './policy-gate';
+import { admitsAnonymous, policyCapability } from './policy-gate';
 import type { AnyQuery } from './query';
 import { queryName, runQuery } from './read';
 
@@ -58,9 +58,12 @@ export function toQueryRoute(target: AnyQuery): Route {
 
   const meta: RouteMeta = {
     name,
-    // `allow(...)` is the only way a read is public, and saying so explicitly is what
-    // keeps "forgot the policy" from ever looking like "meant to be readable".
-    auth: target.policy.kind === 'allow' ? 'public' : 'required',
+    // Derived from a WALK of the policy tree, never from the root combinator alone.
+    // `policy.kind === 'allow'` answered `required` for `or(allow(), can('x:y'))`, so the pipeline
+    // 401'd an anonymous caller the policy itself allows — while the MCP tool and a direct server
+    // read let the same caller through the same object. `public` here is not "unguarded":
+    // `enforcedBy: 'handler'` below means `runQuery` still evaluates the policy for every read.
+    auth: admitsAnonymous(target.policy) ? 'public' : 'required',
     policy: policyCapability(target.policy),
     // `runQuery` is this route's one evaluation and it decides from the PARSED input the
     // rule reads (`ownsOrg(actor, input.orgId)`); the stage would decide the same policy

package/src/index.ts

@@ -70,8 +70,19 @@ export { derivePath, toKebabCase } from './naming';
  */
 export type { Page, PaginateArgs } from './pagination';
 export type { QueryPolicy, QuerySubject, QuerySurface } from './policy-gate';
-/** `policyCapability` is the display label; `policyPermissions` is what a report MATCHES on. */
-export { actorOf, guard, policyCapability, policyPermissions } from './policy-gate';
+/**
+ * `policyCapability` is the display label; `policyPermissions` is what a report MATCHES on.
+ * `admitsAnonymous` is `@ultimat3/policy`'s, re-exported here beside them: it is what
+ * `toQueryRoute` derives `meta.auth` from, so a plain `route` sets that field from the same walk
+ * rather than re-reading the root combinator.
+ */
+export {
+  actorOf,
+  admitsAnonymous,
+  guard,
+  policyCapability,
+  policyPermissions,
+} from './policy-gate';
 export type {
   AnyQuery,
   Query,

package/src/policy-gate.ts

@@ -7,7 +7,11 @@
 import type { Actor, Ctx } from '@ultimat3/core';
 import { assertNever, isAnonymous } from '@ultimat3/core';
 import type { Policy, Surface as PolicySurface } from '@ultimat3/policy';
-import { enforce, policyPermissions as flattenedPermissions } from '@ultimat3/policy';
+import {
+  enforce,
+  policyPermissions as flattenedPermissions,
+  admitsAnonymous as policyAdmitsAnonymous,
+} from '@ultimat3/policy';
 import { QueryDeniedError } from './errors';
 
 /** Policies are opaque here: we evaluate them, we never introspect their rules. */
@@ -75,3 +79,16 @@ export function policyCapability(policy: QueryPolicy): string {
 export function policyPermissions(policy: QueryPolicy): readonly string[] {
   return flattenedPermissions(policy);
 }
+
+/**
+ * Whether a policy admits an ANONYMOUS caller — `@ultimat3/policy`'s answer, re-exported here so
+ * `http.ts` reads it through this file like every other authz question. `toQueryRoute` derives
+ * `meta.auth` from it, never from `policy.kind === 'allow'`: that read looked at the ROOT
+ * combinator only, so `or(allow(), can('x:y'))` was 401'd by the pipeline before `runQuery` ran
+ * while the MCP tool and a direct server read allowed it. `true` is `meta.auth` only — the read is
+ * still `no-store` and `runQuery` still evaluates the policy per caller. Declared once in
+ * `policy.ts`, exactly as `policyPermissions` is: the answer is a property of the combinators.
+ */
+export function admitsAnonymous(policy: QueryPolicy): boolean {
+  return policyAdmitsAnonymous(policy);
+}