@web-ts-toolkit/access-router 0.44.0 → 0.45.0

package/llms.txt

@@ -78,6 +78,22 @@ const conservative: CopyAndDepopulateOutput = copyAndDepopulate({ items: [{ _id:
 void [typed, conservative];
 ```
 
+Correlated includes: besides legacy `localField`/`foreignField` joins,
+`include` entries accept `mode: 'correlated'` with `{ "$parent": "<field>" }`
+markers in filter value positions (or as the whole `id`). Each entry runs per
+parent against the immediate parent snapshot: reads attach doc-or-`null`,
+lists attach per-parent paginated arrays, counts attach numbers (missing/null
+refs attach `null`/`[]`/`0` with no query). Plain `'$special'` strings stay
+literal; match literal `{ "$parent": "x" }` objects with
+`{ "$escape": { "$parent": "x" } }`. Identifier behavior, per-op target
+authorization (denials fail the whole request with zero target queries), and
+bounds (`maxIncludeCount`, revalidated `maxNodes`/`maxDepth`/`maxInValues`/
+`maxLogicalClauses`, `maxCorrelatedQueries` default 100,
+`maxCorrelatedDepth` default 5) follow the README "Correlated Includes"
+section. Wire types (`ParentRef`, `CorrelatedInclude`, `Include`) are
+available from `@web-ts-toolkit/access-router/advanced` without deep
+imports.
+
 ## Gotchas
 
 - peer dependencies: `express >= 5` and `mongoose >= 8`

package/package.json

@@ -2,7 +2,7 @@
   "name": "@web-ts-toolkit/access-router",
   "description": "ACL-aware Express routers and in-memory data services for Mongoose-backed APIs",
   "homepage": "https://web-ts-toolkit.pages.dev/docs/packages/access-router",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "sideEffects": [
     "./**/index.js",
     "./**/index.mjs",
@@ -57,8 +57,8 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@web-ts-toolkit/express-json-router": "0.44.0",
-    "@web-ts-toolkit/utils": "0.44.0",
+    "@web-ts-toolkit/express-json-router": "0.45.0",
+    "@web-ts-toolkit/utils": "0.45.0",
     "just-diff": "^6.0.2",
     "mongoose-schema-jsonschema": "^4.0.1",
     "sift": "^17.1.3",

package/{parsers-B5dbVmjm.d.mts → parsers-DppKW-Fd.d.mts}

@@ -65,6 +65,13 @@ declare class Service<TModel = unknown> extends Base<TModel> {
     protected authorizeDistinctField(field: string): Promise<ErrorResult | null>;
     distinct(field: string, args?: DistinctArgs<TModel>): Promise<ListResult<unknown> | ErrorResult>;
     count(filter: Filter<TModel>, access?: BaseFilterAccess): Promise<SingleResult<number> | ErrorResult>;
+    /**
+     * Trusted count for correlated includes (ACI-03): the caller already
+     * resolved parent references, revalidated expanded operands, and applied
+     * explicit `count` access via `genFilter`. This skips client-filter
+     * validation and subquery parsing so substituted parent data stays inert.
+     */
+    countTrusted(authorizedFilter: Filter<TModel>): Promise<SingleResult<number> | ErrorResult>;
     countByFieldValues(foreignField: string, values: unknown[], filter?: Filter<TModel>, access?: BaseFilterAccess): Promise<SingleResult<Map<string, Set<string>>> | ErrorResult>;
     getDocPermissions(doc: unknown): Record<string, unknown>;
     private resolveFindOneArgs;
@@ -442,6 +449,8 @@ interface RequestComplexityOptions {
     maxSubQueryCount?: number;
     maxBulkConcurrency?: number;
     maxHookConcurrency?: number;
+    maxCorrelatedQueries?: number;
+    maxCorrelatedDepth?: number;
 }
 
 declare class RequestConcurrencyScheduler {
@@ -452,6 +461,10 @@ declare class RequestConcurrencyScheduler {
 }
 
 type CrossResourceModelOperation = 'list' | 'read' | 'count';
+interface CorrelatedExecState {
+    totalQueries: number;
+    scheduler: RequestConcurrencyScheduler;
+}
 declare class Base<TModel = unknown> {
     protected req: ModelRequest;
     protected modelName: string;
@@ -488,9 +501,11 @@ declare class Base<TModel = unknown> {
     protected throwClientRequestError(code: ErrorResult['code'], detail: string): never;
     protected getAuthorizedTargetService(modelName: string, op: CrossResourceModelOperation): Promise<PublicService<unknown>>;
     protected processInclude(include: Include | Include[]): {
-        includes: Include[];
+        includes: LegacyInclude[];
+        correlatedIncludes: CorrelatedInclude[];
         includeLocalFields: string[];
         includePaths: string[];
+        correlatedReferenceFields: string[];
     };
     private getForeignKeyValues;
     private getForeignKey;
@@ -503,6 +518,13 @@ declare class Base<TModel = unknown> {
     private includeDocsRead;
     private includeDocsList;
     private includeDocsCount;
+    protected getCorrelatedExecState(): CorrelatedExecState;
+    protected claimCorrelatedQuerySlot(): void;
+    private sanitizeCorrelatedArgs;
+    protected includeCorrelatedDocs<TDoc>(docs: TDoc[], correlatedIncludes: CorrelatedInclude[], snapshots?: unknown[], depth?: number): Promise<TDoc[]>;
+    private includeCorrelatedRead;
+    private includeCorrelatedList;
+    private includeCorrelatedCount;
     protected parseClientData<TValue>(filter: TValue, scheduler?: RequestConcurrencyScheduler, scheduled?: boolean): Promise<TValue>;
     private handleSubQuery;
     private handleDate;
@@ -839,7 +861,8 @@ type TypedFilterObject<T> = {
 };
 type TypedFilter<T> = false | TypedFilterObject<WithDefaultId<T>>;
 type Filter<T = unknown> = IsUnknown<T> extends true ? LooseFilter : TypedFilter<T>;
-interface Include {
+interface LegacyInclude {
+    mode?: 'legacy';
     model: string;
     op: 'list' | 'read' | 'count';
     path: string;
@@ -849,6 +872,56 @@ interface Include {
     args?: unknown;
     options?: unknown;
 }
+/**
+ * Explicit structural marker referencing a field of the immediate parent
+ * document (ACI-01 D2.1). Recognized only in filter/id value positions of
+ * correlated includes; magic `$field` strings are never markers.
+ */
+interface ParentRef {
+    $parent: string;
+}
+/** Filter template for correlated includes; values may carry {@link ParentRef} markers. */
+type CorrelatedFilter = Record<string, unknown>;
+interface CorrelatedIncludeArgs {
+    select?: Projection;
+    sort?: Sort;
+    skip?: number | string;
+    limit?: number | string;
+    page?: number | string;
+    pageSize?: number | string;
+    include?: Include | Include[];
+}
+interface CorrelatedIncludeBase {
+    mode: 'correlated';
+    model: string;
+    op: 'list' | 'read' | 'count';
+    path: string;
+    args?: CorrelatedIncludeArgs;
+    options?: Record<string, never>;
+}
+/** Identifier read: exactly one of `id` / `filter` must be present. */
+interface CorrelatedReadByIdInclude extends CorrelatedIncludeBase {
+    op: 'read';
+    id: string | ParentRef;
+    filter?: never;
+}
+interface CorrelatedReadByFilterInclude extends CorrelatedIncludeBase {
+    op: 'read';
+    filter: CorrelatedFilter;
+    id?: never;
+}
+interface CorrelatedListInclude extends CorrelatedIncludeBase {
+    op: 'list';
+    filter: CorrelatedFilter;
+    id?: never;
+}
+interface CorrelatedCountInclude extends CorrelatedIncludeBase {
+    op: 'count';
+    filter: CorrelatedFilter;
+    id?: never;
+}
+type CorrelatedInclude = CorrelatedReadByIdInclude | CorrelatedReadByFilterInclude | CorrelatedListInclude | CorrelatedCountInclude;
+type Include = LegacyInclude | CorrelatedInclude;
 type FindAccess = 'list' | 'read';
 type PopulateAccess = 'list' | 'read';
 interface Populate {
@@ -1056,10 +1129,11 @@ interface SubQueryEntry {
         compact?: boolean;
     };
 }
+type TaskType = 'COPY_AND_DEPOPULATE' | 'COPY' | 'MOVE' | 'SLICE' | 'COUNT' | 'MASK' | string;
 interface Task {
-    type: string;
+    type: TaskType;
     args: unknown;
-    options: Record<string, unknown>;
+    options?: Record<string, unknown>;
 }
 interface AccessRouterBaseRequest extends AccessRouterRequest {
     query: Record<'skip' | 'limit' | 'page' | 'page_size' | 'try_list' | 'skim' | 'include_permissions' | 'include_count' | 'include_extra_headers' | 'returning_all', string>;
@@ -1575,4 +1649,4 @@ declare function fromIoTs<TValue = unknown>(decoder: IoTsDecoderLike<TValue>): R
 declare function fromSuperstruct<TStruct, TOutput = unknown>(struct: TStruct, validate: SuperstructValidateLike): RequestSchemaValidator<TOutput>;
 declare function fromVine<TValue = unknown>(validator: VineValidatorLike<TValue>): RequestSchemaValidator<TValue>;
 
-export { type ExtendedModelRouterOptions as $, type AccessRouterBaseRequest as A, type BaseFilterAccess as B, type Change as C, DATA_MIDDLEWARE as D, type DataFindOneArgs as E, type DataFindOneOptions as F, type DataFindOptions as G, type DataHook as H, type DataHookContext as I, type DataIdentifierHook as J, type DataListHook as K, type DataOverrideFilterHook as L, type DataRequest as M, type DataRequestSchemas as N, type DataRouterOptions as O, type DecorateAccess as P, type DecorateAllAccess as Q, type DeepFieldPath as R, type DefaultModelRouterOptions as S, type Defaults as T, type DistinctArgs as U, type DistinctBody as V, type DocPermissionsAccess as W, type ErrorResult as X, type ExistsOptions as Y, type ExtendedDataRouterOptions as Z, type ExtendedDefaultModelRouterOptions as _, type AccessRouterFieldKey as a, type RequestSchemaAdapter as a$, type Filter as a0, FilterOperator as a1, type FindAccess as a2, type FindArgs as a3, type FindByIdArgs as a4, type FindByIdOptions as a5, type FindOneArgs as a6, type FindOneOptions as a7, type FindOptions as a8, type GlobalOptions as a9, type ModelRouterOptions as aA, type ModelValidateHook as aB, PERMISSIONS as aC, PERMISSION_KEYS as aD, type PathValue as aE, type PermissionSchema as aF, type Populate as aG, type PopulateAccess as aH, type PrepareAccess as aI, type Projection as aJ, type PublicCreateArgs as aK, type PublicCreateOptions as aL, type PublicErrorResult as aM, type PublicListArgs as aN, type PublicListOptions as aO, type PublicListResult as aP, type PublicOutput as aQ, type PublicReadArgs as aR, type PublicReadOptions as aS, type PublicServiceResult as aT, type PublicSingleResult as aU, type PublicUpdateArgs as aV, type PublicUpdateOptions as aW, type PublicUpsertArgs as aX, type PublicUpsertOptions as aY, type ReadQueryInput as aZ, type Request as a_, type GlobalPermissionValue as aa, type GuardHook as ab, type IdentifierHook as ac, type Include as ad, type IoTsContextEntryLike as ae, type IoTsDecodeErrorLike as af, type IoTsDecoderLike as ag, type JoiSchemaLike as ah, type JoiValidationErrorDetailLike as ai, type KeyValueProjection as aj, type ListQueryInput as ak, type ListResult as al, MIDDLEWARE as am, type MaybePromise as an, type ModelBaseFilterHook as ao, type ModelChangeHook as ap, type ModelDeleteHook as aq, type ModelDocPermissionsHook as ar, type ModelDocument as as, type ModelDocumentHook as at, type ModelHook as au, type ModelHookContext as av, type ModelIdentifierHook as aw, type ModelListHook as ax, type ModelOverrideFilterHook as ay, type ModelRequest as az, type AccessRouterLogger as b, type SubdocumentReadOptions as b$, type RequestSchemaFailure as b0, type RequestSchemaIssue as b1, type RequestSchemaLike as b2, type RequestSchemaOptions as b3, type RequestSchemaResult as b4, type RequestSchemaSuccess as b5, type RequestSchemaValidator as b6, type RequestSchemas as b7, type RootDataListQueryEntry as b8, type RootDataOperation as b9, type SelectedPopulatedPublicOutput as bA, type SelectedPublicOutput as bB, type ServiceResult as bC, type SingleResult as bD, type Sort as bE, type SortOrder as bF, type StandardSchemaFailure as bG, type StandardSchemaInferOutput as bH, type StandardSchemaIssue as bI, type StandardSchemaPathSegment as bJ, type StandardSchemaResult as bK, type StandardSchemaSuccess as bL, type StandardSchemaV1 as bM, StatusCodes as bN, type SubListBody as bO, type SubPopulate as bP, type SubQueryEntry as bQ, type SubReadBody as bR, type SubdocumentBulkRecord as bS, type SubdocumentBulkUpdateInput as bT, type SubdocumentCreateInput as bU, type SubdocumentCreateOptions as bV, type SubdocumentId as bW, type SubdocumentListOptions as bX, type SubdocumentName as bY, type SubdocumentParentArgs as bZ, type SubdocumentParentOptions as b_, type RootDataReadByFilterQueryEntry as ba, type RootDataReadByIdQueryEntry as bb, type RootModelCountQueryEntry as bc, type RootModelCreateQueryEntry as bd, type RootModelDeleteQueryEntry as be, type RootModelDistinctQueryEntry as bf, type RootModelListQueryEntry as bg, type RootModelNewQueryEntry as bh, type RootModelOperation as bi, type RootModelReadByFilterQueryEntry as bj, type RootModelReadByIdQueryEntry as bk, type RootModelSubBulkUpdateQueryEntry as bl, type RootModelSubCreateQueryEntry as bm, type RootModelSubDeleteQueryEntry as bn, type RootModelSubListQueryEntry as bo, type RootModelSubReadQueryEntry as bp, type RootModelSubUpdateQueryEntry as bq, type RootModelUpdateQueryEntry as br, type RootModelUpsertQueryEntry as bs, type RootOperationResult as bt, type RootQueryEntry as bu, type RootRouterOptions as bv, type RootSubOperation as bw, type RootTarget as bx, type RouteGuardAccess as by, type SelectAccess as bz, type AccessRouterRequest as c, type SubdocumentRecord as c0, type SuperstructFailureLike as c1, type SuperstructValidateLike as c2, type Task as c3, type TransformAccess as c4, type TypedFilter as c5, type UpdateByIdArgs as c6, type UpdateByIdOptions as c7, type UpdateOneArgs as c8, type UpdateOneOptions as c9, fromYup as cA, fromZod as cB, parseBody as cC, parseBodyWithSchema as cD, parseNestedBodyWithSchema as cE, parsePathParam as cF, parseQuery as cG, DataService as cH, Service as cI, PublicService as cJ, type AccessRouterPermissionMap as cK, type AccessRouterPermissions as cL, type Permissions as cM, type UpdateQueryInput as ca, type UpsertArgs as cb, type UpsertOptions as cc, type UpsertQueryInput as cd, type ValibotIssueLike as ce, type ValibotPathItemLike as cf, type ValibotSafeParseLike as cg, type ValibotSafeParseResult as ch, type ValidateAccess as ci, type ValidateRule as cj, type Validation as ck, type ValidationError as cl, type VineValidationErrorLike as cm, type VineValidationMessageLike as cn, type VineValidatorLike as co, type YupSchemaLike as cp, type YupValidationErrorLike as cq, defineRequestSchema as cr, fromAjv as cs, fromArkType as ct, fromIoTs as cu, fromJoi as cv, fromStandardSchema as cw, fromSuperstruct as cx, fromValibot as cy, fromVine as cz, type AccessRouterRequestExtensions as d, type AdvancedCreateBody as e, type AdvancedListBody as f, type AdvancedReadBody as g, type AdvancedReadFilterBody as h, type AdvancedUpdateBody as i, type AdvancedUpsertBody as j, type AfterPersistAccess as k, type AjvErrorObjectLike as l, type AjvValidationErrorLike as m, type AjvValidatorLike as n, type ArkTypeErrorsLike as o, type ArkTypeLike as p, type ArkTypeProblemLike as q, Codes as r, type CountBody as s, type CreateArgs as t, type CreateOptions as u, type CreateQueryInput as v, CustomHeaders as w, type DataBaseFilterHook as x, type DataFilter as y, type DataFindArgs as z };
+export { type DistinctArgs as $, type AccessRouterBaseRequest as A, type BaseFilterAccess as B, type Change as C, type CreateArgs as D, type CreateOptions as E, type CreateQueryInput as F, CustomHeaders as G, DATA_MIDDLEWARE as H, type DataBaseFilterHook as I, type DataFilter as J, type DataFindArgs as K, type DataFindOneArgs as L, type DataFindOneOptions as M, type DataFindOptions as N, type DataHook as O, type DataHookContext as P, type DataIdentifierHook as Q, type DataListHook as R, type DataOverrideFilterHook as S, type DataRequest as T, type DataRequestSchemas as U, type DataRouterOptions as V, type DecorateAccess as W, type DecorateAllAccess as X, type DeepFieldPath as Y, type DefaultModelRouterOptions as Z, type Defaults as _, type AccessRouterFieldKey as a, type PublicReadOptions as a$, type DistinctBody as a0, type DocPermissionsAccess as a1, type ErrorResult as a2, type ExistsOptions as a3, type ExtendedDataRouterOptions as a4, type ExtendedDefaultModelRouterOptions as a5, type ExtendedModelRouterOptions as a6, type Filter as a7, FilterOperator as a8, type FindAccess as a9, type ModelDocument as aA, type ModelDocumentHook as aB, type ModelHook as aC, type ModelHookContext as aD, type ModelIdentifierHook as aE, type ModelListHook as aF, type ModelOverrideFilterHook as aG, type ModelRequest as aH, type ModelRouterOptions as aI, type ModelValidateHook as aJ, PERMISSIONS as aK, PERMISSION_KEYS as aL, type ParentRef as aM, type PathValue as aN, type PermissionSchema as aO, type Populate as aP, type PopulateAccess as aQ, type PrepareAccess as aR, type Projection as aS, type PublicCreateArgs as aT, type PublicCreateOptions as aU, type PublicErrorResult as aV, type PublicListArgs as aW, type PublicListOptions as aX, type PublicListResult as aY, type PublicOutput as aZ, type PublicReadArgs as a_, type FindArgs as aa, type FindByIdArgs as ab, type FindByIdOptions as ac, type FindOneArgs as ad, type FindOneOptions as ae, type FindOptions as af, type GlobalOptions as ag, type GlobalPermissionValue as ah, type GuardHook as ai, type IdentifierHook as aj, type Include as ak, type IoTsContextEntryLike as al, type IoTsDecodeErrorLike as am, type IoTsDecoderLike as an, type JoiSchemaLike as ao, type JoiValidationErrorDetailLike as ap, type KeyValueProjection as aq, type LegacyInclude as ar, type ListQueryInput as as, type ListResult as at, MIDDLEWARE as au, type MaybePromise as av, type ModelBaseFilterHook as aw, type ModelChangeHook as ax, type ModelDeleteHook as ay, type ModelDocPermissionsHook as az, type AccessRouterLogger as b, type SubdocumentBulkRecord as b$, type PublicServiceResult as b0, type PublicSingleResult as b1, type PublicUpdateArgs as b2, type PublicUpdateOptions as b3, type PublicUpsertArgs as b4, type PublicUpsertOptions as b5, type ReadQueryInput as b6, type Request as b7, type RequestSchemaAdapter as b8, type RequestSchemaFailure as b9, type RootModelUpdateQueryEntry as bA, type RootModelUpsertQueryEntry as bB, type RootOperationResult as bC, type RootQueryEntry as bD, type RootRouterOptions as bE, type RootSubOperation as bF, type RootTarget as bG, type RouteGuardAccess as bH, type SelectAccess as bI, type SelectedPopulatedPublicOutput as bJ, type SelectedPublicOutput as bK, type ServiceResult as bL, type SingleResult as bM, type Sort as bN, type SortOrder as bO, type StandardSchemaFailure as bP, type StandardSchemaInferOutput as bQ, type StandardSchemaIssue as bR, type StandardSchemaPathSegment as bS, type StandardSchemaResult as bT, type StandardSchemaSuccess as bU, type StandardSchemaV1 as bV, StatusCodes as bW, type SubListBody as bX, type SubPopulate as bY, type SubQueryEntry as bZ, type SubReadBody as b_, type RequestSchemaIssue as ba, type RequestSchemaLike as bb, type RequestSchemaOptions as bc, type RequestSchemaResult as bd, type RequestSchemaSuccess as be, type RequestSchemaValidator as bf, type RequestSchemas as bg, type RootDataListQueryEntry as bh, type RootDataOperation as bi, type RootDataReadByFilterQueryEntry as bj, type RootDataReadByIdQueryEntry as bk, type RootModelCountQueryEntry as bl, type RootModelCreateQueryEntry as bm, type RootModelDeleteQueryEntry as bn, type RootModelDistinctQueryEntry as bo, type RootModelListQueryEntry as bp, type RootModelNewQueryEntry as bq, type RootModelOperation as br, type RootModelReadByFilterQueryEntry as bs, type RootModelReadByIdQueryEntry as bt, type RootModelSubBulkUpdateQueryEntry as bu, type RootModelSubCreateQueryEntry as bv, type RootModelSubDeleteQueryEntry as bw, type RootModelSubListQueryEntry as bx, type RootModelSubReadQueryEntry as by, type RootModelSubUpdateQueryEntry as bz, type AccessRouterRequest as c, type SubdocumentBulkUpdateInput as c0, type SubdocumentCreateInput as c1, type SubdocumentCreateOptions as c2, type SubdocumentId as c3, type SubdocumentListOptions as c4, type SubdocumentName as c5, type SubdocumentParentArgs as c6, type SubdocumentParentOptions as c7, type SubdocumentReadOptions as c8, type SubdocumentRecord as c9, type YupValidationErrorLike as cA, defineRequestSchema as cB, fromAjv as cC, fromArkType as cD, fromIoTs as cE, fromJoi as cF, fromStandardSchema as cG, fromSuperstruct as cH, fromValibot as cI, fromVine as cJ, fromYup as cK, fromZod as cL, parseBody as cM, parseBodyWithSchema as cN, parseNestedBodyWithSchema as cO, parsePathParam as cP, parseQuery as cQ, DataService as cR, Service as cS, PublicService as cT, type AccessRouterPermissionMap as cU, type AccessRouterPermissions as cV, type Permissions as cW, type SuperstructFailureLike as ca, type SuperstructValidateLike as cb, type Task as cc, type TaskType as cd, type TransformAccess as ce, type TypedFilter as cf, type UpdateByIdArgs as cg, type UpdateByIdOptions as ch, type UpdateOneArgs as ci, type UpdateOneOptions as cj, type UpdateQueryInput as ck, type UpsertArgs as cl, type UpsertOptions as cm, type UpsertQueryInput as cn, type ValibotIssueLike as co, type ValibotPathItemLike as cp, type ValibotSafeParseLike as cq, type ValibotSafeParseResult as cr, type ValidateAccess as cs, type ValidateRule as ct, type Validation as cu, type ValidationError as cv, type VineValidationErrorLike as cw, type VineValidationMessageLike as cx, type VineValidatorLike as cy, type YupSchemaLike as cz, type AccessRouterRequestExtensions as d, type AdvancedCreateBody as e, type AdvancedListBody as f, type AdvancedReadBody as g, type AdvancedReadFilterBody as h, type AdvancedUpdateBody as i, type AdvancedUpsertBody as j, type AfterPersistAccess as k, type AjvErrorObjectLike as l, type AjvValidationErrorLike as m, type AjvValidatorLike as n, type ArkTypeErrorsLike as o, type ArkTypeLike as p, type ArkTypeProblemLike as q, Codes as r, type CorrelatedCountInclude as s, type CorrelatedFilter as t, type CorrelatedInclude as u, type CorrelatedIncludeArgs as v, type CorrelatedListInclude as w, type CorrelatedReadByFilterInclude as x, type CorrelatedReadByIdInclude as y, type CountBody as z };

package/{parsers-B5dbVmjm.d.ts → parsers-DppKW-Fd.d.ts}

@@ -65,6 +65,13 @@ declare class Service<TModel = unknown> extends Base<TModel> {
     protected authorizeDistinctField(field: string): Promise<ErrorResult | null>;
     distinct(field: string, args?: DistinctArgs<TModel>): Promise<ListResult<unknown> | ErrorResult>;
     count(filter: Filter<TModel>, access?: BaseFilterAccess): Promise<SingleResult<number> | ErrorResult>;
+    /**
+     * Trusted count for correlated includes (ACI-03): the caller already
+     * resolved parent references, revalidated expanded operands, and applied
+     * explicit `count` access via `genFilter`. This skips client-filter
+     * validation and subquery parsing so substituted parent data stays inert.
+     */
+    countTrusted(authorizedFilter: Filter<TModel>): Promise<SingleResult<number> | ErrorResult>;
     countByFieldValues(foreignField: string, values: unknown[], filter?: Filter<TModel>, access?: BaseFilterAccess): Promise<SingleResult<Map<string, Set<string>>> | ErrorResult>;
     getDocPermissions(doc: unknown): Record<string, unknown>;
     private resolveFindOneArgs;
@@ -442,6 +449,8 @@ interface RequestComplexityOptions {
     maxSubQueryCount?: number;
     maxBulkConcurrency?: number;
     maxHookConcurrency?: number;
+    maxCorrelatedQueries?: number;
+    maxCorrelatedDepth?: number;
 }
 
 declare class RequestConcurrencyScheduler {
@@ -452,6 +461,10 @@ declare class RequestConcurrencyScheduler {
 }
 
 type CrossResourceModelOperation = 'list' | 'read' | 'count';
+interface CorrelatedExecState {
+    totalQueries: number;
+    scheduler: RequestConcurrencyScheduler;
+}
 declare class Base<TModel = unknown> {
     protected req: ModelRequest;
     protected modelName: string;
@@ -488,9 +501,11 @@ declare class Base<TModel = unknown> {
     protected throwClientRequestError(code: ErrorResult['code'], detail: string): never;
     protected getAuthorizedTargetService(modelName: string, op: CrossResourceModelOperation): Promise<PublicService<unknown>>;
     protected processInclude(include: Include | Include[]): {
-        includes: Include[];
+        includes: LegacyInclude[];
+        correlatedIncludes: CorrelatedInclude[];
         includeLocalFields: string[];
         includePaths: string[];
+        correlatedReferenceFields: string[];
     };
     private getForeignKeyValues;
     private getForeignKey;
@@ -503,6 +518,13 @@ declare class Base<TModel = unknown> {
     private includeDocsRead;
     private includeDocsList;
     private includeDocsCount;
+    protected getCorrelatedExecState(): CorrelatedExecState;
+    protected claimCorrelatedQuerySlot(): void;
+    private sanitizeCorrelatedArgs;
+    protected includeCorrelatedDocs<TDoc>(docs: TDoc[], correlatedIncludes: CorrelatedInclude[], snapshots?: unknown[], depth?: number): Promise<TDoc[]>;
+    private includeCorrelatedRead;
+    private includeCorrelatedList;
+    private includeCorrelatedCount;
     protected parseClientData<TValue>(filter: TValue, scheduler?: RequestConcurrencyScheduler, scheduled?: boolean): Promise<TValue>;
     private handleSubQuery;
     private handleDate;
@@ -839,7 +861,8 @@ type TypedFilterObject<T> = {
 };
 type TypedFilter<T> = false | TypedFilterObject<WithDefaultId<T>>;
 type Filter<T = unknown> = IsUnknown<T> extends true ? LooseFilter : TypedFilter<T>;
-interface Include {
+interface LegacyInclude {
+    mode?: 'legacy';
     model: string;
     op: 'list' | 'read' | 'count';
     path: string;
@@ -849,6 +872,56 @@ interface Include {
     args?: unknown;
     options?: unknown;
 }
+/**
+ * Explicit structural marker referencing a field of the immediate parent
+ * document (ACI-01 D2.1). Recognized only in filter/id value positions of
+ * correlated includes; magic `$field` strings are never markers.
+ */
+interface ParentRef {
+    $parent: string;
+}
+/** Filter template for correlated includes; values may carry {@link ParentRef} markers. */
+type CorrelatedFilter = Record<string, unknown>;
+interface CorrelatedIncludeArgs {
+    select?: Projection;
+    sort?: Sort;
+    skip?: number | string;
+    limit?: number | string;
+    page?: number | string;
+    pageSize?: number | string;
+    include?: Include | Include[];
+}
+interface CorrelatedIncludeBase {
+    mode: 'correlated';
+    model: string;
+    op: 'list' | 'read' | 'count';
+    path: string;
+    args?: CorrelatedIncludeArgs;
+    options?: Record<string, never>;
+}
+/** Identifier read: exactly one of `id` / `filter` must be present. */
+interface CorrelatedReadByIdInclude extends CorrelatedIncludeBase {
+    op: 'read';
+    id: string | ParentRef;
+    filter?: never;
+}
+interface CorrelatedReadByFilterInclude extends CorrelatedIncludeBase {
+    op: 'read';
+    filter: CorrelatedFilter;
+    id?: never;
+}
+interface CorrelatedListInclude extends CorrelatedIncludeBase {
+    op: 'list';
+    filter: CorrelatedFilter;
+    id?: never;
+}
+interface CorrelatedCountInclude extends CorrelatedIncludeBase {
+    op: 'count';
+    filter: CorrelatedFilter;
+    id?: never;
+}
+type CorrelatedInclude = CorrelatedReadByIdInclude | CorrelatedReadByFilterInclude | CorrelatedListInclude | CorrelatedCountInclude;
+type Include = LegacyInclude | CorrelatedInclude;
 type FindAccess = 'list' | 'read';
 type PopulateAccess = 'list' | 'read';
 interface Populate {
@@ -1056,10 +1129,11 @@ interface SubQueryEntry {
         compact?: boolean;
     };
 }
+type TaskType = 'COPY_AND_DEPOPULATE' | 'COPY' | 'MOVE' | 'SLICE' | 'COUNT' | 'MASK' | string;
 interface Task {
-    type: string;
+    type: TaskType;
     args: unknown;
-    options: Record<string, unknown>;
+    options?: Record<string, unknown>;
 }
 interface AccessRouterBaseRequest extends AccessRouterRequest {
     query: Record<'skip' | 'limit' | 'page' | 'page_size' | 'try_list' | 'skim' | 'include_permissions' | 'include_count' | 'include_extra_headers' | 'returning_all', string>;
@@ -1575,4 +1649,4 @@ declare function fromIoTs<TValue = unknown>(decoder: IoTsDecoderLike<TValue>): R
 declare function fromSuperstruct<TStruct, TOutput = unknown>(struct: TStruct, validate: SuperstructValidateLike): RequestSchemaValidator<TOutput>;
 declare function fromVine<TValue = unknown>(validator: VineValidatorLike<TValue>): RequestSchemaValidator<TValue>;
 
-export { type ExtendedModelRouterOptions as $, type AccessRouterBaseRequest as A, type BaseFilterAccess as B, type Change as C, DATA_MIDDLEWARE as D, type DataFindOneArgs as E, type DataFindOneOptions as F, type DataFindOptions as G, type DataHook as H, type DataHookContext as I, type DataIdentifierHook as J, type DataListHook as K, type DataOverrideFilterHook as L, type DataRequest as M, type DataRequestSchemas as N, type DataRouterOptions as O, type DecorateAccess as P, type DecorateAllAccess as Q, type DeepFieldPath as R, type DefaultModelRouterOptions as S, type Defaults as T, type DistinctArgs as U, type DistinctBody as V, type DocPermissionsAccess as W, type ErrorResult as X, type ExistsOptions as Y, type ExtendedDataRouterOptions as Z, type ExtendedDefaultModelRouterOptions as _, type AccessRouterFieldKey as a, type RequestSchemaAdapter as a$, type Filter as a0, FilterOperator as a1, type FindAccess as a2, type FindArgs as a3, type FindByIdArgs as a4, type FindByIdOptions as a5, type FindOneArgs as a6, type FindOneOptions as a7, type FindOptions as a8, type GlobalOptions as a9, type ModelRouterOptions as aA, type ModelValidateHook as aB, PERMISSIONS as aC, PERMISSION_KEYS as aD, type PathValue as aE, type PermissionSchema as aF, type Populate as aG, type PopulateAccess as aH, type PrepareAccess as aI, type Projection as aJ, type PublicCreateArgs as aK, type PublicCreateOptions as aL, type PublicErrorResult as aM, type PublicListArgs as aN, type PublicListOptions as aO, type PublicListResult as aP, type PublicOutput as aQ, type PublicReadArgs as aR, type PublicReadOptions as aS, type PublicServiceResult as aT, type PublicSingleResult as aU, type PublicUpdateArgs as aV, type PublicUpdateOptions as aW, type PublicUpsertArgs as aX, type PublicUpsertOptions as aY, type ReadQueryInput as aZ, type Request as a_, type GlobalPermissionValue as aa, type GuardHook as ab, type IdentifierHook as ac, type Include as ad, type IoTsContextEntryLike as ae, type IoTsDecodeErrorLike as af, type IoTsDecoderLike as ag, type JoiSchemaLike as ah, type JoiValidationErrorDetailLike as ai, type KeyValueProjection as aj, type ListQueryInput as ak, type ListResult as al, MIDDLEWARE as am, type MaybePromise as an, type ModelBaseFilterHook as ao, type ModelChangeHook as ap, type ModelDeleteHook as aq, type ModelDocPermissionsHook as ar, type ModelDocument as as, type ModelDocumentHook as at, type ModelHook as au, type ModelHookContext as av, type ModelIdentifierHook as aw, type ModelListHook as ax, type ModelOverrideFilterHook as ay, type ModelRequest as az, type AccessRouterLogger as b, type SubdocumentReadOptions as b$, type RequestSchemaFailure as b0, type RequestSchemaIssue as b1, type RequestSchemaLike as b2, type RequestSchemaOptions as b3, type RequestSchemaResult as b4, type RequestSchemaSuccess as b5, type RequestSchemaValidator as b6, type RequestSchemas as b7, type RootDataListQueryEntry as b8, type RootDataOperation as b9, type SelectedPopulatedPublicOutput as bA, type SelectedPublicOutput as bB, type ServiceResult as bC, type SingleResult as bD, type Sort as bE, type SortOrder as bF, type StandardSchemaFailure as bG, type StandardSchemaInferOutput as bH, type StandardSchemaIssue as bI, type StandardSchemaPathSegment as bJ, type StandardSchemaResult as bK, type StandardSchemaSuccess as bL, type StandardSchemaV1 as bM, StatusCodes as bN, type SubListBody as bO, type SubPopulate as bP, type SubQueryEntry as bQ, type SubReadBody as bR, type SubdocumentBulkRecord as bS, type SubdocumentBulkUpdateInput as bT, type SubdocumentCreateInput as bU, type SubdocumentCreateOptions as bV, type SubdocumentId as bW, type SubdocumentListOptions as bX, type SubdocumentName as bY, type SubdocumentParentArgs as bZ, type SubdocumentParentOptions as b_, type RootDataReadByFilterQueryEntry as ba, type RootDataReadByIdQueryEntry as bb, type RootModelCountQueryEntry as bc, type RootModelCreateQueryEntry as bd, type RootModelDeleteQueryEntry as be, type RootModelDistinctQueryEntry as bf, type RootModelListQueryEntry as bg, type RootModelNewQueryEntry as bh, type RootModelOperation as bi, type RootModelReadByFilterQueryEntry as bj, type RootModelReadByIdQueryEntry as bk, type RootModelSubBulkUpdateQueryEntry as bl, type RootModelSubCreateQueryEntry as bm, type RootModelSubDeleteQueryEntry as bn, type RootModelSubListQueryEntry as bo, type RootModelSubReadQueryEntry as bp, type RootModelSubUpdateQueryEntry as bq, type RootModelUpdateQueryEntry as br, type RootModelUpsertQueryEntry as bs, type RootOperationResult as bt, type RootQueryEntry as bu, type RootRouterOptions as bv, type RootSubOperation as bw, type RootTarget as bx, type RouteGuardAccess as by, type SelectAccess as bz, type AccessRouterRequest as c, type SubdocumentRecord as c0, type SuperstructFailureLike as c1, type SuperstructValidateLike as c2, type Task as c3, type TransformAccess as c4, type TypedFilter as c5, type UpdateByIdArgs as c6, type UpdateByIdOptions as c7, type UpdateOneArgs as c8, type UpdateOneOptions as c9, fromYup as cA, fromZod as cB, parseBody as cC, parseBodyWithSchema as cD, parseNestedBodyWithSchema as cE, parsePathParam as cF, parseQuery as cG, DataService as cH, Service as cI, PublicService as cJ, type AccessRouterPermissionMap as cK, type AccessRouterPermissions as cL, type Permissions as cM, type UpdateQueryInput as ca, type UpsertArgs as cb, type UpsertOptions as cc, type UpsertQueryInput as cd, type ValibotIssueLike as ce, type ValibotPathItemLike as cf, type ValibotSafeParseLike as cg, type ValibotSafeParseResult as ch, type ValidateAccess as ci, type ValidateRule as cj, type Validation as ck, type ValidationError as cl, type VineValidationErrorLike as cm, type VineValidationMessageLike as cn, type VineValidatorLike as co, type YupSchemaLike as cp, type YupValidationErrorLike as cq, defineRequestSchema as cr, fromAjv as cs, fromArkType as ct, fromIoTs as cu, fromJoi as cv, fromStandardSchema as cw, fromSuperstruct as cx, fromValibot as cy, fromVine as cz, type AccessRouterRequestExtensions as d, type AdvancedCreateBody as e, type AdvancedListBody as f, type AdvancedReadBody as g, type AdvancedReadFilterBody as h, type AdvancedUpdateBody as i, type AdvancedUpsertBody as j, type AfterPersistAccess as k, type AjvErrorObjectLike as l, type AjvValidationErrorLike as m, type AjvValidatorLike as n, type ArkTypeErrorsLike as o, type ArkTypeLike as p, type ArkTypeProblemLike as q, Codes as r, type CountBody as s, type CreateArgs as t, type CreateOptions as u, type CreateQueryInput as v, CustomHeaders as w, type DataBaseFilterHook as x, type DataFilter as y, type DataFindArgs as z };
+export { type DistinctArgs as $, type AccessRouterBaseRequest as A, type BaseFilterAccess as B, type Change as C, type CreateArgs as D, type CreateOptions as E, type CreateQueryInput as F, CustomHeaders as G, DATA_MIDDLEWARE as H, type DataBaseFilterHook as I, type DataFilter as J, type DataFindArgs as K, type DataFindOneArgs as L, type DataFindOneOptions as M, type DataFindOptions as N, type DataHook as O, type DataHookContext as P, type DataIdentifierHook as Q, type DataListHook as R, type DataOverrideFilterHook as S, type DataRequest as T, type DataRequestSchemas as U, type DataRouterOptions as V, type DecorateAccess as W, type DecorateAllAccess as X, type DeepFieldPath as Y, type DefaultModelRouterOptions as Z, type Defaults as _, type AccessRouterFieldKey as a, type PublicReadOptions as a$, type DistinctBody as a0, type DocPermissionsAccess as a1, type ErrorResult as a2, type ExistsOptions as a3, type ExtendedDataRouterOptions as a4, type ExtendedDefaultModelRouterOptions as a5, type ExtendedModelRouterOptions as a6, type Filter as a7, FilterOperator as a8, type FindAccess as a9, type ModelDocument as aA, type ModelDocumentHook as aB, type ModelHook as aC, type ModelHookContext as aD, type ModelIdentifierHook as aE, type ModelListHook as aF, type ModelOverrideFilterHook as aG, type ModelRequest as aH, type ModelRouterOptions as aI, type ModelValidateHook as aJ, PERMISSIONS as aK, PERMISSION_KEYS as aL, type ParentRef as aM, type PathValue as aN, type PermissionSchema as aO, type Populate as aP, type PopulateAccess as aQ, type PrepareAccess as aR, type Projection as aS, type PublicCreateArgs as aT, type PublicCreateOptions as aU, type PublicErrorResult as aV, type PublicListArgs as aW, type PublicListOptions as aX, type PublicListResult as aY, type PublicOutput as aZ, type PublicReadArgs as a_, type FindArgs as aa, type FindByIdArgs as ab, type FindByIdOptions as ac, type FindOneArgs as ad, type FindOneOptions as ae, type FindOptions as af, type GlobalOptions as ag, type GlobalPermissionValue as ah, type GuardHook as ai, type IdentifierHook as aj, type Include as ak, type IoTsContextEntryLike as al, type IoTsDecodeErrorLike as am, type IoTsDecoderLike as an, type JoiSchemaLike as ao, type JoiValidationErrorDetailLike as ap, type KeyValueProjection as aq, type LegacyInclude as ar, type ListQueryInput as as, type ListResult as at, MIDDLEWARE as au, type MaybePromise as av, type ModelBaseFilterHook as aw, type ModelChangeHook as ax, type ModelDeleteHook as ay, type ModelDocPermissionsHook as az, type AccessRouterLogger as b, type SubdocumentBulkRecord as b$, type PublicServiceResult as b0, type PublicSingleResult as b1, type PublicUpdateArgs as b2, type PublicUpdateOptions as b3, type PublicUpsertArgs as b4, type PublicUpsertOptions as b5, type ReadQueryInput as b6, type Request as b7, type RequestSchemaAdapter as b8, type RequestSchemaFailure as b9, type RootModelUpdateQueryEntry as bA, type RootModelUpsertQueryEntry as bB, type RootOperationResult as bC, type RootQueryEntry as bD, type RootRouterOptions as bE, type RootSubOperation as bF, type RootTarget as bG, type RouteGuardAccess as bH, type SelectAccess as bI, type SelectedPopulatedPublicOutput as bJ, type SelectedPublicOutput as bK, type ServiceResult as bL, type SingleResult as bM, type Sort as bN, type SortOrder as bO, type StandardSchemaFailure as bP, type StandardSchemaInferOutput as bQ, type StandardSchemaIssue as bR, type StandardSchemaPathSegment as bS, type StandardSchemaResult as bT, type StandardSchemaSuccess as bU, type StandardSchemaV1 as bV, StatusCodes as bW, type SubListBody as bX, type SubPopulate as bY, type SubQueryEntry as bZ, type SubReadBody as b_, type RequestSchemaIssue as ba, type RequestSchemaLike as bb, type RequestSchemaOptions as bc, type RequestSchemaResult as bd, type RequestSchemaSuccess as be, type RequestSchemaValidator as bf, type RequestSchemas as bg, type RootDataListQueryEntry as bh, type RootDataOperation as bi, type RootDataReadByFilterQueryEntry as bj, type RootDataReadByIdQueryEntry as bk, type RootModelCountQueryEntry as bl, type RootModelCreateQueryEntry as bm, type RootModelDeleteQueryEntry as bn, type RootModelDistinctQueryEntry as bo, type RootModelListQueryEntry as bp, type RootModelNewQueryEntry as bq, type RootModelOperation as br, type RootModelReadByFilterQueryEntry as bs, type RootModelReadByIdQueryEntry as bt, type RootModelSubBulkUpdateQueryEntry as bu, type RootModelSubCreateQueryEntry as bv, type RootModelSubDeleteQueryEntry as bw, type RootModelSubListQueryEntry as bx, type RootModelSubReadQueryEntry as by, type RootModelSubUpdateQueryEntry as bz, type AccessRouterRequest as c, type SubdocumentBulkUpdateInput as c0, type SubdocumentCreateInput as c1, type SubdocumentCreateOptions as c2, type SubdocumentId as c3, type SubdocumentListOptions as c4, type SubdocumentName as c5, type SubdocumentParentArgs as c6, type SubdocumentParentOptions as c7, type SubdocumentReadOptions as c8, type SubdocumentRecord as c9, type YupValidationErrorLike as cA, defineRequestSchema as cB, fromAjv as cC, fromArkType as cD, fromIoTs as cE, fromJoi as cF, fromStandardSchema as cG, fromSuperstruct as cH, fromValibot as cI, fromVine as cJ, fromYup as cK, fromZod as cL, parseBody as cM, parseBodyWithSchema as cN, parseNestedBodyWithSchema as cO, parsePathParam as cP, parseQuery as cQ, DataService as cR, Service as cS, PublicService as cT, type AccessRouterPermissionMap as cU, type AccessRouterPermissions as cV, type Permissions as cW, type SuperstructFailureLike as ca, type SuperstructValidateLike as cb, type Task as cc, type TaskType as cd, type TransformAccess as ce, type TypedFilter as cf, type UpdateByIdArgs as cg, type UpdateByIdOptions as ch, type UpdateOneArgs as ci, type UpdateOneOptions as cj, type UpdateQueryInput as ck, type UpsertArgs as cl, type UpsertOptions as cm, type UpsertQueryInput as cn, type ValibotIssueLike as co, type ValibotPathItemLike as cp, type ValibotSafeParseLike as cq, type ValibotSafeParseResult as cr, type ValidateAccess as cs, type ValidateRule as ct, type Validation as cu, type ValidationError as cv, type VineValidationErrorLike as cw, type VineValidationMessageLike as cx, type VineValidatorLike as cy, type YupSchemaLike as cz, type AccessRouterRequestExtensions as d, type AdvancedCreateBody as e, type AdvancedListBody as f, type AdvancedReadBody as g, type AdvancedReadFilterBody as h, type AdvancedUpdateBody as i, type AdvancedUpsertBody as j, type AfterPersistAccess as k, type AjvErrorObjectLike as l, type AjvValidationErrorLike as m, type AjvValidatorLike as n, type ArkTypeErrorsLike as o, type ArkTypeLike as p, type ArkTypeProblemLike as q, Codes as r, type CorrelatedCountInclude as s, type CorrelatedFilter as t, type CorrelatedInclude as u, type CorrelatedIncludeArgs as v, type CorrelatedListInclude as w, type CorrelatedReadByFilterInclude as x, type CorrelatedReadByIdInclude as y, type CountBody as z };

package/processors.d.mts

@@ -47,6 +47,97 @@ interface CopyAndDepopulateOptions {
      */
     idField?: string;
 }
+/**
+ * A path copy operation consumed by {@link copyPaths} and the `COPY` task.
+ * Reuses the same `{ src, dest }` shape as {@link ProcessCopy}.
+ */
+type ProcessPathCopy = ProcessCopy;
+/**
+ * A path move operation consumed by {@link movePaths} and the `MOVE` task.
+ * Reuses the same `{ src, dest }` shape as {@link ProcessCopy}.
+ */
+type ProcessPathMove = ProcessCopy;
+/**
+ * A slice operation consumed by {@link sliceArrays} and the `SLICE` task.
+ */
+interface ProcessSlice {
+    /**
+     * Dotted source path of the array to slice. Intermediate segments fan out
+     * across arrays like {@link copyAndDepopulate}. Missing, null, or
+     * non-array leaves are safe no-ops.
+     */
+    src: string;
+    /**
+     * Dotted destination path (relative to the leaf parent) where the sliced
+     * window is written. When omitted, the slice is applied in place at `src`.
+     * Empty-string destinations are safe no-ops.
+     */
+    dest?: string;
+    /**
+     * Number of leading array members to skip. Defaults to `0`. Must be a
+     * non-negative safe integer when present.
+     */
+    skip?: number;
+    /**
+     * Maximum number of array members to keep from `skip`. When omitted, the
+     * tail from `skip` to the end is kept. When present it is clamped to
+     * `maxSlice` (default `1000`). Must be a non-negative safe integer.
+     */
+    limit?: number;
+}
+/**
+ * A count operation consumed by {@link countPaths} and the `COUNT` task.
+ */
+interface ProcessCount {
+    /**
+     * Dotted source path whose size is measured. Arrays measure length, plain
+     * objects measure key count, present scalars count as `1`, and
+     * null/undefined leaves count as `0`. Missing leaves are safe no-ops.
+     */
+    src: string;
+    /**
+     * Dotted destination path (relative to the leaf parent) where the numeric
+     * count is written. Empty destinations are safe no-ops.
+     */
+    dest: string;
+}
+/**
+ * A mask operation consumed by {@link maskPaths} and the `MASK` task.
+ */
+interface ProcessMask {
+    /**
+     * Dotted source path to redact. Each resolved leaf present on its parent
+     * is replaced with `replacement`. Missing leaves are safe no-ops.
+     */
+    src: string;
+    /**
+     * Replacement value written at `src`. Defaults to `'***'` when the key is
+     * absent. An explicitly provided value (including `null`) is used as-is.
+     */
+    replacement?: unknown;
+}
+/**
+ * Shared mutable/clone option for path processors.
+ */
+interface ProcessorOptions {
+    /**
+     * When `true` (default), `docObject` is mutated in place and returned.
+     * When `false`, a deep clone is produced via `cloneDeep` and the input is
+     * left untouched.
+     */
+    mutable?: boolean;
+}
+/**
+ * Options for {@link sliceArrays}.
+ */
+interface SliceProcessorOptions extends ProcessorOptions {
+    /**
+     * Upper bound applied to a client-requested `limit`. Defaults to `1000`,
+     * matching the `listHardLimit` default. Must be a non-negative safe
+     * integer when present.
+     */
+    maxSlice?: number;
+}
 /**
  * Conservative default output for {@link copyAndDepopulate}.
  *
@@ -90,5 +181,64 @@ type CopyAndDepopulateOutput = Record<string, unknown>;
  * `constructor`, or when a populated record is missing the configured id field.
  */
 declare const copyAndDepopulate: <Output extends object = CopyAndDepopulateOutput>(docObject: object, operations: ProcessCopy[], options?: CopyAndDepopulateOptions) => Output;
+/**
+ * Conservative default output for path processors.
+ */
+type ProcessorOutput = Record<string, unknown>;
+/**
+ * Copy the value at `src` to `dest` without modifying `src`.
+ *
+ * Semantics mirror {@link copyAndDepopulate} traversal: intermediate segments
+ * fan out across arrays, missing/null/scalar intermediates are safe no-ops,
+ * and unsafe (`__proto__`, `prototype`, `constructor`) or empty paths are
+ * handled the same way. The copied value is deep-cloned so later tasks in
+ * the chain cannot alias `src` through `dest`. Copying a path onto itself
+ * is a safe no-op.
+ *
+ * @throws Error when a path contains an unsafe segment.
+ */
+declare const copyPaths: <Output extends object = ProcessorOutput>(docObject: object, operations: ProcessCopy[], options?: ProcessorOptions) => Output;
+/**
+ * Move the value at `src` to `dest` and delete `src`.
+ *
+ * Traversal and safety semantics match {@link copyPaths}. Moving a path onto
+ * itself is a safe no-op. A `dest` nested under the moved leaf (for example
+ * `src: 'a'`, `dest: 'a.b'`) copies without deleting `src` so the freshly
+ * written destination is not removed.
+ *
+ * @throws Error when a path contains an unsafe segment.
+ */
+declare const movePaths: <Output extends object = ProcessorOutput>(docObject: object, operations: ProcessCopy[], options?: ProcessorOptions) => Output;
+/**
+ * Slice the array at `src` to `[skip, skip + limit)` and write the window to
+ * `dest` (default: in place at `src`).
+ *
+ * Missing, null, or non-array leaves are safe no-ops. `skip` defaults to `0`;
+ * an omitted `limit` keeps the tail from `skip`. A present `limit` is clamped
+ * to `maxSlice` (default `1000`) so client-requested windows stay bounded.
+ *
+ * @throws Error when a path contains an unsafe segment or when
+ * `skip`/`limit`/`maxSlice` is not a non-negative safe integer.
+ */
+declare const sliceArrays: <Output extends object = ProcessorOutput>(docObject: object, operations: ProcessSlice[], options?: SliceProcessorOptions) => Output;
+/**
+ * Write the size of `src` to `dest`: array length, plain-object key count,
+ * `0` for null/undefined leaves, and `1` for other present scalars.
+ *
+ * Missing leaves are safe no-ops (no destination is created).
+ *
+ * @throws Error when a path contains an unsafe segment.
+ */
+declare const countPaths: <Output extends object = ProcessorOutput>(docObject: object, operations: ProcessCount[], options?: ProcessorOptions) => Output;
+/**
+ * Replace the value at `src` with `replacement` (default `'***'`).
+ *
+ * Only existing leaves are redacted; missing paths are safe no-ops and no
+ * new keys are created. Intermediate segments fan out across arrays like
+ * {@link copyAndDepopulate}.
+ *
+ * @throws Error when a path contains an unsafe segment.
+ */
+declare const maskPaths: <Output extends object = ProcessorOutput>(docObject: object, operations: ProcessMask[], options?: ProcessorOptions) => Output;
 
-export { type CopyAndDepopulateOptions, type CopyAndDepopulateOutput, type ProcessCopy, copyAndDepopulate };
+export { type CopyAndDepopulateOptions, type CopyAndDepopulateOutput, type ProcessCopy, type ProcessCount, type ProcessMask, type ProcessPathCopy, type ProcessPathMove, type ProcessSlice, type ProcessorOptions, type ProcessorOutput, type SliceProcessorOptions, copyAndDepopulate, copyPaths, countPaths, maskPaths, movePaths, sliceArrays };