@classytic/arc 2.41.1 → 2.44.0

package/dist/{index-D4u76eQW.d.mts → index-Beg3aNnK.d.mts}

@@ -1,8 +1,8 @@
 
 import { i as RequestScope } from "./types-Ddl9OjmE.mjs";
-import { l as PermissionCheck, t as AnyRecord } from "./base-CxrV1LmG.mjs";
-import { C as RequestContext, Et as ActionDefinition, F as FastifyWithDecorators, Fn as IControllerResponse, H as CrudController, In as IRequestContext, L as RequestWithExtras, Pn as IController, T as CrudRouterOptions, U as ResourceConfig, V as ResourceDefinition, et as RouteSchemaOptions, jt as RouteMcpConfig, tt as ArcFieldRule, ut as AggregationConfig } from "./index-DHbyPo5j.mjs";
-import "./fastify-augmentation-Cq2nHVaW.mjs";
+import { l as PermissionCheck, t as AnyRecord } from "./base-CZyixEQR.mjs";
+import { A as RequestWithExtras, Dt as RouteMcpConfig, F as ResourceDefinition, Hn as IRequestContext, I as CrudController, L as ResourceConfig, O as FastifyWithDecorators, St as ActionDefinition, Vn as IControllerResponse, X as RouteSchemaOptions, Z as ArcFieldRule, g as RequestContext, ot as AggregationConfig, v as CrudRouterOptions } from "./index-WH7xgvxS.mjs";
+import "./fastify-augmentation-DRlCIWE9.mjs";
 import { Filter } from "@classytic/repo-core/filter";
 import { FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";
 import { z } from "zod";
@@ -42,6 +42,8 @@ declare const DEFAULT_ID_FIELD: "_id";
 declare const DEFAULT_TENANT_FIELD: "organizationId";
 /** Default HTTP method for update routes */
 declare const DEFAULT_UPDATE_METHOD: "PATCH";
+/** Default version field under `concurrency: {}` (optimistic concurrency) */
+declare const DEFAULT_VERSION_FIELD: "__v";
 /** System-managed fields that cannot be set via request body */
 declare const SYSTEM_FIELDS: readonly ["_id", "__v", "createdAt", "updatedAt", "deletedAt"];
 /** Maximum regex pattern length (ReDoS mitigation) */
@@ -95,9 +97,8 @@ declare function defineAggregation(config: AggregationConfig): AggregationConfig
  */
 declare function createCrudRouter<TDoc = unknown>(fastify: FastifyWithDecorators, controller: CrudController<TDoc> | undefined, options?: CrudRouterOptions): void;
 /**
- * Build a permission middleware from a PermissionCheck — useful when hosts
- * register their own routes outside the resource system but still want to
- * evaluate permissions through the shared applicator.
+ * Build a permission middleware from a PermissionCheck, for host routes
+ * registered outside the resource system.
  */
 declare function createPermissionMiddleware(permission: PermissionCheck, resourceName: string, action: string): RouteHandlerMethod | null;
 //#endregion
@@ -123,6 +124,8 @@ interface DefineActionConfig<TSchema extends z.ZodTypeAny | undefined = undefine
   id?: boolean;
   /** MCP tool generation flag — `false` to skip, object for explicit overrides. */
   mcp?: boolean | RouteMcpConfig;
+  /** `{ required: true }`: a call of this action needs an idempotency key. See `ActionDefinition`. */
+  idempotency?: ActionDefinition["idempotency"];
   /**
    * Typed handler. `data` is inferred from `schema` — declare both and
    * the compiler catches `data.stagId` typos at the use site.
@@ -266,90 +269,33 @@ type VariantsResult<TDoc, V extends VariantsMap<TDoc>> = { [K in keyof V]: Resou
  * @returns A record where each key from `variants` maps to a real
  *          `ResourceDefinition` ready for `.toPlugin()` registration.
  */
-declare function defineResourceVariants<TDoc extends AnyRecord = AnyRecord, V extends VariantsMap<TDoc> = VariantsMap<TDoc>>(base: Omit<ResourceConfig<TDoc>, "name" | "prefix">, variants: V): VariantsResult<TDoc, V>;
-//#endregion
-//#region src/core/entityHelpers.d.ts
-/**
- * Read the resource's configured `idField` for the current request.
- * Falls back to the framework default (`_id`) when the route hasn't
- * bound an idField — keeps handlers safe to author without checking
- * the resource config.
- */
-declare function getEntityIdField(req: RequestWithExtras): string;
-/**
- * Read the URL `:id` path param value as the resource handle.
- * Returns `undefined` when the route has no `:id` segment (collection
- * routes) — handlers that need the entity must be on row routes.
- */
-declare function getEntityId(req: RequestWithExtras): string | undefined;
-/**
- * Compose a `findOne` filter that resolves the current request's
- * entity, regardless of whether the resource binds `_id` or a custom
- * field. Idiomatic shape for arc action handlers.
- *
- * ```ts
- * const doc = await Model.findOne(getEntityQuery(req));
- * ```
- *
- * Returns `{}` when the route has no entity context (collection routes
- * or tests bypassing the router) — caller decides what that means.
- */
-declare function getEntityQuery(req: RequestWithExtras): Record<string, string>;
+declare function defineResourceVariants<TDoc extends object = AnyRecord, V extends VariantsMap<TDoc> = VariantsMap<TDoc>>(base: Omit<ResourceConfig<TDoc>, "name" | "prefix">, variants: V): VariantsResult<TDoc, V>;
 //#endregion
 //#region src/core/fastifyAdapter.d.ts
 /**
- * Project `FastifyRequest` into the curated `IRequestContext` shape that
- * arc's controllers receive. This is a developer-facing facade, not a
- * portability boundary — arc is Fastify-only. The projection lifts the
- * fields tenant-scoped controllers reach for (`organizationId`,
- * `teamId`, `scope`, `context`, server accessor) onto a flat, typed
- * surface so handler code doesn't have to dig through Fastify's
- * decorator surface or `req.metadata._scope` internals.
+ * Project `FastifyRequest` into the `IRequestContext` controllers receive,
+ * lifting scope, context, and a server accessor onto a flat, typed surface.
  */
 declare function createRequestContext(req: FastifyRequest): IRequestContext;
 /**
- * Get typed auth context from an IRequestContext.
- * Use this in controller overrides to access request context.
- *
- * For org scope, use `getControllerScope(req)` instead.
+ * Typed auth context from an IRequestContext, for controller overrides.
+ * For org scope, use `getControllerScope(req)`.
  */
 declare function getControllerContext(req: IRequestContext): RequestContext;
-/**
- * Get request scope from an IRequestContext.
- * Returns the RequestScope set by auth adapters.
- */
+/** The RequestScope set by auth adapters (`PUBLIC_SCOPE` when absent). */
 declare function getControllerScope(req: IRequestContext): RequestScope;
 /**
- * Send a controller's `IControllerResponse` through Fastify's reply.
- *
- * The `IControllerResponse<T>` envelope is arc's internal pipeline
- * contract — it's how custom `status`, `meta`, `headers`, and field
- * permissions thread from a handler through interceptors to the wire
- * without each step having to touch `reply` directly. Not a portability
- * abstraction (arc is Fastify-only); a pipeline-internal one.
+ * Send a controller's `IControllerResponse` envelope (status, meta, headers)
+ * through Fastify's reply, applying field masks and field read permissions.
  *
- * **Auto-envelope of bare returns.** Custom route handlers are
- * expected to return the envelope shape so this function can apply
- * field permissions, attach `fieldCaps`, and flatten paginated lists.
- * A handler that returns raw `T` (array, plain object, primitive) used
- * to silently produce a broken response — `response.data` was
- * `undefined`, the body sent was `undefined`, and any declared
- * `fields:` permission map was bypassed (the leak shape mentora
- * flagged). 2.17 detects bare returns and wraps them into
- * `{ data: response, status: 200 }` before the field-permission
- * pipeline runs, so `fields:` applies to ALL custom routes whether the
- * handler envelopes its return value or not. The envelope shape is
- * still the canonical contract — auto-wrapping is a safety net, not
- * an invitation to drop the envelope.
+ * A bare return (no `data` key) is wrapped as `{ data, status: 200 }` so
+ * `fields:` permissions still apply — otherwise restricted fields would leak.
+ * The envelope remains the canonical contract.
  */
 declare function sendControllerResponse<T>(reply: FastifyReply, response: IControllerResponse<T>, request?: FastifyRequest): void;
 /**
- * Bridge an `IController` method (`(ctx: IRequestContext) => Promise<IControllerResponse<T>>`)
- * into a Fastify route handler. Translates between arc's curated request
- * context surface and Fastify's request/reply, and routes the envelope
- * through `sendControllerResponse` so the pipeline applies field
- * permissions, status, and meta uniformly. Internal plumbing, not a
- * portability layer — arc is Fastify-only.
+ * Bridge an `IController` method into a Fastify route handler, sending the
+ * envelope through `sendControllerResponse`.
  *
  * @example
  * ```typescript
@@ -359,30 +305,6 @@ declare function sendControllerResponse<T>(reply: FastifyReply, response: IContr
  * ```
  */
 declare function createFastifyHandler<T>(controllerMethod: (req: IRequestContext) => Promise<IControllerResponse<T>>): (req: FastifyRequest, reply: FastifyReply) => Promise<FastifyReply>;
-/**
- * Create Fastify adapters for all CRUD methods of an IController
- *
- * Returns Fastify-compatible handlers for each CRUD operation
- *
- * @example
- * ```typescript
- * const controller = new BaseController(repository);
- * const handlers = createCrudHandlers(controller);
- *
- * fastify.get('/', handlers.list);
- * fastify.get('/:id', handlers.get);
- * fastify.post('/', handlers.create);
- * fastify.patch('/:id', handlers.update);
- * fastify.delete('/:id', handlers.delete);
- * ```
- */
-declare function createCrudHandlers<TDoc>(controller: IController<TDoc>): {
-  list: (req: FastifyRequest, reply: FastifyReply) => Promise<FastifyReply>;
-  get: (req: FastifyRequest, reply: FastifyReply) => Promise<FastifyReply>;
-  create: (req: FastifyRequest, reply: FastifyReply) => Promise<FastifyReply>;
-  update: (req: FastifyRequest, reply: FastifyReply) => Promise<FastifyReply>;
-  delete: (req: FastifyRequest, reply: FastifyReply) => Promise<FastifyReply>;
-};
 //#endregion
 //#region src/core/fieldRulePredicates.d.ts
 /**
@@ -446,4 +368,4 @@ declare function formatValidationErrors(resourceName: string, result: Validation
  */
 declare function assertValidConfig(config: ResourceConfig, options?: ValidateOptions): void;
 //#endregion
-export { CRUD_OPERATIONS as A, HookOperation as B, SeamedResourceConfig as C, createCrudRouter as D, defineAction as E, DEFAULT_SORT as F, MUTATION_OPERATIONS as G, MAX_FILTER_DEPTH as H, DEFAULT_TENANT_FIELD as I, SYSTEM_FIELDS as J, MutationOperation as K, DEFAULT_UPDATE_METHOD as L, DEFAULT_ID_FIELD as M, DEFAULT_LIMIT as N, createPermissionMiddleware as O, DEFAULT_MAX_LIMIT as P, HOOK_OPERATIONS as R, ResourceSeams as S, DefineActionConfig as T, MAX_REGEX_LENGTH as U, HookPhase as V, MAX_SEARCH_LENGTH as W, getEntityId as _, formatValidationErrors as a, defineResourceVariants as b, nativePolicyFilter as c, createCrudHandlers as d, createFastifyHandler as f, sendControllerResponse as g, getControllerScope as h, assertValidConfig as i, CrudOperation as j, defineAggregation as k, collectReadBlockedFields as l, getControllerContext as m, ValidateOptions as n, validateResourceConfig as o, createRequestContext as p, RESERVED_QUERY_PARAMS as q, ValidationResult as r, NativePolicyFilter as s, ConfigError as t, isFieldReadable as u, getEntityIdField as v, mergeResourceConfig as w, AdapterLike as x, getEntityQuery as y, HOOK_PHASES as z };
+export { CrudOperation as A, HookOperation as B, mergeResourceConfig as C, createPermissionMiddleware as D, createCrudRouter as E, DEFAULT_TENANT_FIELD as F, MUTATION_OPERATIONS as G, MAX_FILTER_DEPTH as H, DEFAULT_UPDATE_METHOD as I, SYSTEM_FIELDS as J, MutationOperation as K, DEFAULT_VERSION_FIELD as L, DEFAULT_LIMIT as M, DEFAULT_MAX_LIMIT as N, defineAggregation as O, DEFAULT_SORT as P, HOOK_OPERATIONS as R, SeamedResourceConfig as S, defineAction as T, MAX_REGEX_LENGTH as U, HookPhase as V, MAX_SEARCH_LENGTH as W, VariantsMap as _, formatValidationErrors as a, AdapterLike as b, nativePolicyFilter as c, createFastifyHandler as d, createRequestContext as f, VariantOverride as g, sendControllerResponse as h, assertValidConfig as i, DEFAULT_ID_FIELD as j, CRUD_OPERATIONS as k, collectReadBlockedFields as l, getControllerScope as m, ValidateOptions as n, validateResourceConfig as o, getControllerContext as p, RESERVED_QUERY_PARAMS as q, ValidationResult as r, NativePolicyFilter as s, ConfigError as t, isFieldReadable as u, VariantsResult as v, DefineActionConfig as w, ResourceSeams as x, defineResourceVariants as y, HOOK_PHASES as z };

package/dist/{preloadResources-CjS2OfpU.d.mts → index-BkV55WlV.d.mts}

@@ -1,16 +1,16 @@
 
-import { It as Authenticator } from "./index-DHbyPo5j.mjs";
+import { Mt as Authenticator } from "./index-WH7xgvxS.mjs";
 import { r as CacheStore } from "./interface-BOk3YnTz.mjs";
-import { n as ElevationOptions } from "./elevation-BXCfVcNG.mjs";
-import { a as EventTransport } from "./EventTransport-CbUKDzZZ.mjs";
+import { n as ElevationOptions } from "./elevation-BW2J3tNj.mjs";
+import { a as EventTransport } from "./EventTransport-CiicKz2Z.mjs";
 import { t as ExternalOpenApiPaths } from "./externalPaths-CmGOxOtD.mjs";
-import { r as QueryCachePluginOptions } from "./queryCachePlugin-BzqxconG.mjs";
+import { r as QueryCachePluginOptions } from "./queryCachePlugin-C2lZjTxk.mjs";
 import { t as ErrorHandlerOptions } from "./errorHandler--4rSMMvq.mjs";
-import { l as ResourceLike, m as SchedulesPluginOptions, n as ArcModuleInput, v as HealthOptions } from "./types-DfVDvkdP.mjs";
-import "./index-CFfLKMH4.mjs";
-import { t as EventPluginOptions } from "./eventPlugin-B52abJ8W.mjs";
-import { b as GracefulShutdownOptions, g as CachingOptions, o as MetricsOptions, p as SSEOptions, t as VersioningOptions, u as RealtimeOptions } from "./versioning-D6JIK8Tk.mjs";
-import { r as IdempotencyStore } from "./interface-DEWNOMza.mjs";
+import { S as SchedulesPluginOptions, T as HealthOptions, _ as ResourceLike, o as ArcPorts, r as ArcModuleInput } from "./types-BJ-2XqVF.mjs";
+import { H as ModuleGraphOptions } from "./index-CUJvoyw3.mjs";
+import { t as EventPluginOptions } from "./eventPlugin-BtmA4-3P.mjs";
+import { a as MetricsOptions, c as RealtimeOptions, f as CachingOptions, h as GracefulShutdownOptions, t as VersioningOptions, u as SSEOptions } from "./versioning-Bsb51gGT.mjs";
+import { i as IdempotencyStore } from "./interface-JJzwH4Ro.mjs";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, FastifyServerOptions } from "fastify";
 //#region src/factory/types/assets.d.ts
 /**
@@ -399,6 +399,8 @@ interface RateLimitPlanConfig {
 }
 //#endregion
 //#region src/factory/types/app-options.d.ts
+/** Releases what `beforeBoot` acquired — see `CreateAppOptions.beforeBoot`. */
+type BootDisposer = () => void | Promise<void>;
 /**
  * Configuration for `createApp()`.
  *
@@ -425,8 +427,9 @@ interface CreateAppOptions {
    */
   mountRoutes?: boolean;
   /**
-   * Runtime profile for store backends.
-   * - 'memory' (default): Uses in-memory stores. Suitable for single-instance deployments.
+   * Runtime profile for store backends — the deployment's TOPOLOGY. REQUIRED under
+   * `preset: 'production'` (boot fails without it); defaults to 'memory' elsewhere.
+   * - 'memory': Uses in-memory stores. Correct for exactly ONE instance.
    * - 'distributed': Requires durable adapters for events, and for any enabled
    *   shared subsystems such as caching/queryCache/rate limiting.
    *   Idempotency remains per-resource opt-in: memory-backed stores are rejected,
@@ -808,7 +811,7 @@ interface CreateAppOptions {
    * - `'number'` — LOSSY above `Number.MAX_SAFE_INTEGER` (2^53-1). Only for
    *   an audited, bounded range.
    */
-  serializeBigInt?: boolean | "number" | "string";
+  serializeBigInt?: false | "number" | "string";
   /**
    * Domain modules — one entry per self-contained domain package.
    *
@@ -819,6 +822,19 @@ interface CreateAppOptions {
    * always before the app-level entry for that phase. See [[modules]].
    */
   modules?: ReadonlyArray<ArcModuleInput>;
+  /**
+   * Host collaborators modules declare in `requires.ports` (a connection, an outbox, a
+   * calendar…). Every `'required'` port of every active module is checked before any module
+   * boots — all gaps in one error — and each module's setup phases receive only the ports it
+   * declared, as `context.ports`. Nothing is defaulted.
+   */
+  ports?: ArcPorts;
+  /**
+   * The module graph check. `events: 'strict'` fails boot when an event has two owners, is
+   * published outside its module's namespace, or is consumed with no active publisher and no
+   * `externalEvents` entry. Default `'off'`. The graph is always on `fastify.arc.moduleGraph`.
+   */
+  moduleGraph?: ModuleGraphOptions;
   /**
    * Resources to register. An ARRAY is resolved at module import, so every
    * adapter must be constructible synchronously. A FACTORY (sync or async,
@@ -939,9 +955,15 @@ interface CreateAppOptions {
    * ```
    *
    * Runs after option validation (config bugs fail fast without touching
-   * the DB). Cleanup stays host-owned — pair with `onClose`.
+   * the DB). Return a disposer to hand cleanup to arc: it runs once, on
+   * `app.close()` after every plugin's `onClose`, AND on a boot that fails —
+   * including one that fails before Fastify exists, where no `onClose` can.
+   *
+   * ```ts
+   * beforeBoot: async () => { await mongoose.connect(uri); return () => mongoose.disconnect(); },
+   * ```
    */
-  beforeBoot?: () => void | Promise<void>;
+  beforeBoot?: () => void | BootDisposer | Promise<void | BootDisposer>;
   /**
    * Custom plugin registration — runs after Arc core (security, auth, events)
    * but before `bootstrap` and `resources`.
@@ -987,27 +1009,4 @@ interface CreateAppOptions {
   onClose?: (fastify: FastifyInstance) => void | Promise<void>;
 }
 //#endregion
-//#region src/factory/preloadResources.d.ts
-/** Eager glob result: `{ '/path/to/file.ts': resourceModule }` */
-type EagerGlobResult = Record<string, unknown>;
-/** Lazy glob result: `{ '/path/to/file.ts': () => Promise<unknown> }` */
-type LazyGlobResult = Record<string, () => Promise<unknown>>;
-/**
- * Normalize an eager `import.meta.glob` result into a `ResourceLike[]`.
- *
- * Accepts either:
- * - `{ import: 'default' }` form: values are the resource directly
- * - default form: values are the full module — picks first export with `toPlugin()`
- *
- * Throws if any module doesn't yield a valid `ResourceLike`.
- */
-declare function preloadResources(globResult: EagerGlobResult): ResourceLike[];
-/**
- * Normalize a lazy `import.meta.glob` result into a `Promise<ResourceLike[]>`.
- *
- * Use this when resources depend on prior bootstrap (e.g., engine init) and
- * cannot be evaluated at import time of the preload file.
- */
-declare function preloadResourcesAsync(globResult: LazyGlobResult): Promise<ResourceLike[]>;
-//#endregion
-export { RawBodyOptions as a, BetterAuthOption as c, JwtAuthOption as d, MultipartOptions as i, CustomAuthenticatorOption as l, preloadResourcesAsync as n, UnderPressureOptions as o, CreateAppOptions as r, AuthOption as s, preloadResources as t, CustomPluginAuthOption as u };
+export { UnderPressureOptions as a, CustomAuthenticatorOption as c, RawBodyOptions as i, CustomPluginAuthOption as l, CreateAppOptions as n, AuthOption as o, MultipartOptions as r, BetterAuthOption as s, BootDisposer as t, JwtAuthOption as u };

package/dist/{index-BHdZD8zK.d.mts → index-Bxriq3so.d.mts}

@@ -1,7 +1,8 @@
 
 import { i as RequestScope, n as Mandate } from "./types-Ddl9OjmE.mjs";
-import { l as PermissionCheck, s as AuthorizationDecision, u as PermissionContext } from "./base-CxrV1LmG.mjs";
+import { c as DataPolicy, l as PermissionCheck, s as AuthorizationDecision, u as PermissionContext } from "./base-CZyixEQR.mjs";
 import { r as CacheStore, t as CacheLogger } from "./interface-BOk3YnTz.mjs";
+import "./resourceRateLimit-Wf6d6FL9.mjs";
 import { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 //#region src/permissions/agent.d.ts
 /**
@@ -194,16 +195,6 @@ declare function normalizeToDecision(result: PermissionCheckReturn): Authorizati
  * nuance lives in {@link evaluateAndApplyPermission}, not here.
  */
 declare function evaluatePermissionDecision(check: PermissionCheck, context: PermissionContext): Promise<AuthorizationDecision>;
-/**
- * Minimal shape of a Fastify request that can receive permission side-effects.
- * We avoid depending on the full augmented `FastifyRequest` type here because
- * `_policyFilters` / `scope` are declared via ambient module augmentation in
- * multiple places and the unaugmented interface is what the core routers see.
- */
-type RequestSink = FastifyRequest & {
-  _policyFilters?: Record<string, unknown>;
-  scope?: RequestScope;
-};
 /**
  * Apply an allowed {@link AuthorizationDecision} to a Fastify request — conjoins
  * the decision's row-level `policy` into `_policyFilters` and conditionally
@@ -222,7 +213,7 @@ type RequestSink = FastifyRequest & {
  * This is the enforcement point (PEP) — the ONE place scope + data policy are
  * installed (and the obligation seam lives).
  */
-declare function applyAuthorizationDecision(decision: AuthorizationDecision, request: RequestSink): void;
+declare function applyAuthorizationDecision(decision: AuthorizationDecision, req: FastifyRequest): void;
 //#endregion
 //#region src/permissions/context.d.ts
 /**
@@ -251,17 +242,72 @@ declare function allow(extra?: Omit<AuthorizationDecision, "effect">): Authoriza
  */
 declare function deny(reason?: string): AuthorizationDecision;
 /**
- * Allow public access (no authentication required).
+ * The row policy an `allowPublic` gate applies to the callers it admits: a
+ * filter, or a function of the request that returns one.
+ *
+ * The function form is the scope-aware one — it sees the caller, so anonymous
+ * visitors, the row's author and staff can each get a different filter from ONE
+ * gate. Return `{}` to admit a caller unrestricted (e.g. staff); returning
+ * nothing is treated as a bug, not as "no filter" (see {@link allowPublic}).
+ */
+type PublicPolicy<TDoc = Record<string, unknown>> = DataPolicy | ((ctx: PermissionContext<TDoc>) => DataPolicy | Promise<DataPolicy>);
+/** Options for {@link allowPublic}. */
+interface AllowPublicOptions<TDoc = Record<string, unknown>> {
+  /**
+   * Narrow what anyone admitted by this gate can read or write. Enforced where
+   * every other row policy is: ANDed into the repository query for `list`, into
+   * the compound lookup for `get` / `update` / `delete`, into aggregations, and
+   * per event on realtime feeds. A caller cannot widen it with a query
+   * parameter — `?status=hidden` is conjoined with the policy, not substituted
+   * for it.
+   */
+  policy?: PublicPolicy<TDoc>;
+}
+/**
+ * Allow public access (no authentication required) — optionally row-filtered.
+ *
+ * Without options, anyone passes and sees everything the query asks for.
+ *
+ * With `policy`, anyone still passes, but only the rows the policy admits are
+ * readable (or writable). This is the declarative form of a check that returns
+ * `allow({ policy })`, and it exists because the hand-written form has a trap:
+ * a check function is treated as PROTECTED unless it carries `_isPublic`, so a
+ * custom "public, but only published rows" check that forgets to set the flag
+ * answers every anonymous visitor with a 401 — the public page silently
+ * becomes a login wall. `allowPublic({ policy })` sets it for you.
+ *
+ * Fail-closed on both ends:
+ *  - a STATIC policy must be a non-empty object — `{}` filters nothing and is
+ *    almost certainly a mistake, so it throws at definition time (use
+ *    `allowPublic()` for an unrestricted gate);
+ *  - a RESOLVER that returns anything but an object throws per request, which
+ *    arc answers as a 403 for everyone. A forgotten branch that falls off the
+ *    end of the function must not quietly mean "no filter". Return `{}` when a
+ *    caller genuinely should be unrestricted.
+ *
+ * Composing: inside `anyOf`, the FIRST granting branch wins, and a public
+ * branch grants everyone — so `anyOf(allowPublic({ policy }), requireRoles("admin"))`
+ * filters admins too. Put the privileged branch first, or use the resolver
+ * form and return `{}` for staff.
  *
  * @example
  * ```typescript
- * permissions: {
- *   list: allowPublic(),
- *   get: allowPublic(),
- * }
+ * // Strangers see only published reviews, whatever filter they send.
+ * list: allowPublic({ policy: { status: { $in: ["published", "flagged"] } } }),
+ *
+ * // Scope-aware: the author also sees their own pending review; staff see all.
+ * list: allowPublic({
+ *   policy: (ctx) => {
+ *     const scope = scopeOf(ctx);
+ *     if (isElevated(scope)) return {};
+ *     const visible = { status: { $in: ["published", "flagged"] } };
+ *     const userId = getUserId(scope);
+ *     return userId ? { $or: [visible, { authorId: userId }] } : visible;
+ *   },
+ * }),
  * ```
  */
-declare function allowPublic(): PermissionCheck;
+declare function allowPublic<TDoc = Record<string, unknown>>(options?: AllowPublicOptions<TDoc>): PermissionCheck<TDoc>;
 /**
  * Require authentication (any authenticated user).
  *
@@ -549,12 +595,23 @@ declare function createDynamicPermissionMatrix(config: DynamicPermissionMatrixCo
  *   aren't, so a consumer that holds the caller's scope (a FE that knows the
  *   active branch's role) can decide it client-side — the piece a flat `roles`
  *   requirement could not express.
+ * - `member` — any MEMBER of the caller's active organization passes
+ *   (`requireOrgMembership()`), or a holder of one of `roles` when it is an `anyOf`
+ *   with role branches. Membership is a fact the client holds, so it is decidable.
  * - `authenticated` — the check reads request-time facts (custom auth, service
  *   scope, ownership, grants) that no static analysis can decide; the definitive
  *   answer is computed per request. Treat as "server decides".
  */
 type PermissionRequirement = {
   readonly kind: "public";
+  /**
+   * `true` for `allowPublic({ policy })`: anyone passes the gate, but a row
+   * policy narrows what they can read or write. Absent for a plain
+   * `allowPublic()`, which exposes every row the query asks for. The access
+   * DECISION is the same (allow); the exposure is not, and an audit of the
+   * public surface needs to tell them apart.
+   */
+  readonly rowFiltered?: true;
 } | {
   readonly kind: "roles";
   readonly roles: readonly string[];
@@ -573,6 +630,10 @@ type PermissionRequirement = {
   readonly roles?: readonly string[];
   /** See `roles.conditional` — the composite also has an opaque/contradictory branch. */
   readonly conditional?: boolean;
+} | {
+  readonly kind: "member";
+  /** Roles that ALSO grant without membership (the role branches of an `anyOf`). */
+  readonly roles?: readonly string[];
 } | {
   readonly kind: "authenticated";
 } |
@@ -620,6 +681,8 @@ declare function explainAccess(check: PermissionCheck, principal?: {
   orgRoles?: readonly string[];
   /** The caller's scope-context values (e.g. `{ branchRole: "head_office" }`) — supply to decide a `scoped` gate. */
   scope?: Readonly<Record<string, string | undefined>>;
+  /** Whether the caller is a member of the active organization — supply to decide a `member` gate. */
+  member?: boolean;
 }): AccessExplanation;
 /**
  * Introspect a whole permission map (`{ list, get, create, ... }` or any
@@ -922,7 +985,7 @@ declare function requireOrgInScope<TDoc = Record<string, unknown>>(target: strin
  */
 declare function requireTeamMembership<TDoc = Record<string, unknown>>(): PermissionCheck<TDoc>;
 declare namespace presets_d_exports {
-  export { adminOnly, authenticated, fullPublic, ownerWithAdminBypass, permissionMatrix, publicRead, publicReadAdminWrite, readOnly };
+  export { PermissionOverrides, adminOnly, authenticated, fullPublic, ownerWithAdminBypass, permissionMatrix, publicRead, publicReadAdminWrite, readOnly };
 }
 /**
  * ResourcePermissions shape — matches the type in types/index.ts
@@ -1017,7 +1080,7 @@ declare function readOnly<TDoc = Record<string, unknown>>(overrides?: Permission
  * A CLIENT MUST treat an unrecognised type as DENIED, never as permitted — the
  * next type added here will otherwise read as "allowed" on every older client.
  */
-type PermissionEntryType = "public" | "authenticated" | "roles" | "scoped" | "denied";
+type PermissionEntryType = "public" | "authenticated" | "roles" | "scoped" | "member" | "denied";
 interface PermissionEntry {
   type: PermissionEntryType;
   roles: string[];
@@ -1095,4 +1158,4 @@ declare function introspectModule(mod: Record<string, unknown>): Record<string,
 declare function introspectRegistry(registry: PermissionMatrixRegistry): Record<string, Record<string, PermissionEntry>>;
 declare function buildPermissionMatrix(options?: PermissionMatrixOptions): PermissionMatrix;
 //#endregion
-export { requireAuth as $, RequireGrantOptions as A, ConnectEventsOptions as B, requireServiceScope as C, GRANT_MODES as D, createRoleHierarchy as E, PermissionRequirement as F, createOrgPermissions as G, DynamicPermissionMatrixConfig as H, collectPublicSurface as I, allowPublic as J, allOf as K, describePermission as L, requireGrant as M, conjoinPolicyFilters as N, GrantMode as O, AccessExplanation as P, not as Q, describePermissionMap as R, requireScopeContext as S, RoleHierarchy as T, PermissionEventBus as U, DynamicPermissionMatrix as V, createDynamicPermissionMatrix as W, deny as X, anyOf as Y, denyAll as Z, publicReadAdminWrite as _, PermissionMatrixRegistry as a, scopeOf as at, requireOrgMembership as b, introspectModule as c, evaluatePermissionDecision as ct, authenticated as d, RequireMandateOptions as dt, requireOwnership as et, fullPublic as f, requireAgentScope as ft, publicRead as g, presets_d_exports as h, PermissionMatrixOptions as i, when as it, modeSatisfies as j, GrantResolution as k, introspectRegistry as l, normalizeToDecision as lt, permissionMatrix as m, requireMandate as mt, PermissionEntryType as n, requireRoles as nt, buildPermissionMatrix as o, PermissionCheckReturn as ot, ownerWithAdminBypass as p, requireDPoP as pt, allow as q, PermissionMatrix as r, roles as rt, introspectCheck as s, applyAuthorizationDecision as st, PermissionEntry as t, requirePlatformRole as tt, adminOnly as u, RequireAgentScopeOptions as ut, readOnly as v, requireTeamMembership as w, requireOrgRole as x, requireOrgInScope as y, explainAccess as z };
+export { deny as $, GrantResolution as A, explainAccess as B, requireScopeContext as C, createRoleHierarchy as D, RoleHierarchy as E, AccessExplanation as F, createDynamicPermissionMatrix as G, DynamicPermissionMatrix as H, PermissionRequirement as I, PublicPolicy as J, createOrgPermissions as K, collectPublicSurface as L, modeSatisfies as M, requireGrant as N, GRANT_MODES as O, conjoinPolicyFilters as P, anyOf as Q, describePermission as R, requireOrgRole as S, requireTeamMembership as T, DynamicPermissionMatrixConfig as U, ConnectEventsOptions as V, PermissionEventBus as W, allow as X, allOf as Y, allowPublic as Z, publicRead as _, requireMandate as _t, PermissionMatrixRegistry as a, requireRoles as at, requireOrgInScope as b, introspectModule as c, scopeOf as ct, adminOnly as d, evaluatePermissionDecision as dt, denyAll as et, authenticated as f, normalizeToDecision as ft, presets_d_exports as g, requireDPoP as gt, permissionMatrix as h, requireAgentScope as ht, PermissionMatrixOptions as i, requirePlatformRole as it, RequireGrantOptions as j, GrantMode as k, introspectRegistry as l, PermissionCheckReturn as lt, ownerWithAdminBypass as m, RequireMandateOptions as mt, PermissionEntryType as n, requireAuth as nt, buildPermissionMatrix as o, roles as ot, fullPublic as p, RequireAgentScopeOptions as pt, AllowPublicOptions as q, PermissionMatrix as r, requireOwnership as rt, introspectCheck as s, when as st, PermissionEntry as t, not as tt, PermissionOverrides as u, applyAuthorizationDecision as ut, publicReadAdminWrite as v, requireServiceScope as w, requireOrgMembership as x, readOnly as y, describePermissionMap as z };