@web-ts-toolkit/access-router 0.61.0 → 0.62.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,5 +1,6 @@
1
1
  import { z } from 'zod';
2
- import mongoose, { Model, Schema } from 'mongoose';
2
+ import * as mongoose from 'mongoose';
3
+ import mongoose__default, { Model, Schema } from 'mongoose';
3
4
  import express from 'express';
4
5
 
5
6
  interface BooleanObject {
@@ -168,7 +169,7 @@ type WithDefaultId<T> = T extends object ? T & {
168
169
  */
169
170
  type WithVirtuals<TModel, TVirtuals extends object = Record<never, never>> = TModel & Partial<TVirtuals>;
170
171
  type PublicOutput<T, TVirtuals extends object = Record<never, never>> = WithVirtuals<T, TVirtuals> extends object ? WithVirtuals<T, TVirtuals> & Record<string, unknown> : Record<string, unknown>;
171
- type ModelDocument<TModel = unknown> = mongoose.Document & TModel;
172
+ type ModelDocument<TModel = unknown> = mongoose__default.Document & TModel;
172
173
  type TrimLeft<S extends string> = S extends ` ${infer Rest}` ? TrimLeft<Rest> : S;
173
174
  type TrimRight<S extends string> = S extends `${infer Rest} ` ? TrimRight<Rest> : S;
174
175
  type Trim<S extends string> = TrimLeft<TrimRight<S>>;
@@ -324,6 +325,21 @@ type CorrelatedInclude = CorrelatedReadByIdInclude | CorrelatedReadByFilterInclu
324
325
  type Include = LegacyInclude | CorrelatedInclude;
325
326
  type FindAccess = 'list' | 'read';
326
327
  type PopulateAccess = 'list' | 'read';
328
+ /**
329
+ * Ordinary public population intent, not model/authorization configuration.
330
+ * Static string refs resolve on the source model's connection and must match the
331
+ * exact target registered/configured in the owning runtime with an effective object
332
+ * permissionSchema. Explicit Model-valued schema refs can cross connections when
333
+ * that exact instance is configured in the same runtime. Missing/mismatched targets
334
+ * fail before target I/O or initiating writes; the validated model is pinned in flight.
335
+ * Dynamic callback/refPath refs cannot be statically bound before I/O and reject
336
+ * with a controlled configuration diagnostic.
337
+ * The actual target's requireOperationAccessForPopulateQueries controls only operation
338
+ * admission. Fields, document grants, rows, original selection, match and reference IDs
339
+ * remain enforced; direct/root target guards stay independent. Callers cannot supply
340
+ * a model or either populate policy flag here. Private dependsOnPopulate declarations
341
+ * have a narrower one-hop static-string ObjectId/same-connection contract.
342
+ */
327
343
  interface Populate {
328
344
  path: string;
329
345
  select?: Projection;
@@ -420,8 +436,10 @@ type ModelVirtualDoc<TModel = unknown> = IsUnknownVirtual<TModel> extends true ?
420
436
  * and traversal through target refs are rejected. `_id` is included unless excluded.
421
437
  * Static string refs must bind the actual same-connection ObjectId model; register
422
438
  * its model instance AND options first. Validation is eager/atomic, including setters.
439
+ * Model-valued/cross-connection refs supported by ordinary population are outside
440
+ * this private declaration's static-string, same-connection limit.
423
441
  * This bypasses source/target input-field permissions, not the virtual's own output
424
- * authorization. GlobalOptions.requireOperationAccessForPopulateDependencies defaults
442
+ * authorization. The target model's requireOperationAccessForPopulateDependencies defaults
425
443
  * to true, requiring the captured caller's target base operationAccess.read for private
426
444
  * loading. Only literal false bypasses that gate; private-only loading then adds no
427
445
  * operation check solely for the fetch. Target overrideFilter.read/baseFilter.read and
@@ -432,9 +450,11 @@ type ModelVirtualDoc<TModel = unknown> = IsUnknownVirtual<TModel> extends true ?
432
450
  * admitted ordinary population owns the slot (then its original public mask/miss applies).
433
451
  * Strict private denial, row/query/getter failure and deferred virtual denial cannot hide
434
452
  * permitted IDs. Only source unselection/field denial omits them; there is no extra target
435
- * base-read visibility gate. GlobalOptions.requireOperationAccessForPopulateQueries
436
- * independently controls ordinary target operation admission. Both flags and source/target
437
- * policy are captured before awaits; registration and an effective object permissionSchema
453
+ * base-read visibility gate. The target model's requireOperationAccessForPopulateQueries
454
+ * independently controls ordinary target operation admission. Each target resolves its
455
+ * override → captured runtime model default → true; undefined restores inheritance.
456
+ * Source flags do not propagate: Document's private User ref uses User's dependency flag.
457
+ * Both flags and source/target policy are captured before awaits; registration and an effective object permissionSchema
438
458
  * remain mandatory. Private inputs never implicitly enter hooks, handles or metadata.
439
459
  */
440
460
  interface ModelVirtualPopulateDependency<TModel = unknown> {
@@ -645,6 +665,8 @@ declare class AccessRuntime {
645
665
  private readonly globalOptions;
646
666
  private readonly defaultModelOptions;
647
667
  private readonly modelOptions;
668
+ private readonly modelOptionOverrides;
669
+ private pendingSnapshotWarnings?;
648
670
  private readonly modelJsonSchemas;
649
671
  private readonly dataOptions;
650
672
  private readonly modelRefs;
@@ -653,9 +675,9 @@ declare class AccessRuntime {
653
675
  private readonly modelInstances;
654
676
  private readonly openApiRegistry;
655
677
  private openApiPathPrefix;
656
- registerModelInstance<TModel>(modelName: string, model: mongoose.Model<TModel>): void;
678
+ registerModelInstance<TModel>(modelName: string, model: mongoose__default.Model<TModel>): void;
657
679
  hasModelInstance(modelName: string): boolean;
658
- getModelInstance<TModel = unknown>(modelName: string): mongoose.Model<TModel> | null;
680
+ getModelInstance<TModel = unknown>(modelName: string): mongoose__default.Model<TModel> | null;
659
681
  registerOpenApiRoute(route: OpenApiRouteDescriptor): void;
660
682
  /**
661
683
  * Compose OpenAPI paths while synchronously constructing mounted routers.
@@ -699,8 +721,9 @@ declare class AccessRuntime {
699
721
  globalOptions: GlobalOptions;
700
722
  defaultModelOptions: DefaultModelRouterOptions;
701
723
  modelOptions: Record<string, ModelRouterOptions>;
724
+ modelOptionOverrides: Record<string, ModelRouterOptions>;
702
725
  dataOptions: Record<string, DataRouterOptions>;
703
- modelInstances: Record<string, mongoose.Model<unknown>>;
726
+ modelInstances: Record<string, mongoose__default.Model<unknown>>;
704
727
  modelJsonSchemas: Record<string, Record<string, unknown>>;
705
728
  modelRefs: Record<string, ModelReferenceMap>;
706
729
  modelSubs: Record<string, string[]>;
@@ -716,15 +739,22 @@ declare class AccessRuntime {
716
739
  setGlobalOption<K extends keyof GlobalOptions>(key: K, value: GlobalOptions[K]): void;
717
740
  getGlobalOptions(): GlobalOptions;
718
741
  getGlobalOption<K extends keyof GlobalOptions>(key: K, defaultValue?: GlobalOptions[K]): GlobalOptions[K];
719
- /** Update model starting defaults shallowly; already-stored model values are not broadcast-replaced. */
742
+ /** Update inherited model defaults shallowly. Explicit model values and captured calls are unchanged. */
720
743
  setDefaultModelOptions(options: DefaultModelRouterOptions): void;
721
744
  setDefaultModelOption<K extends keyof ExtendedDefaultModelRouterOptions>(key: K, value: ExtendedDefaultModelRouterOptions[K]): void;
722
745
  getDefaultModelOptions(): DefaultModelRouterOptions<unknown>;
723
746
  getDefaultModelOption<K extends keyof ExtendedDefaultModelRouterOptions>(key: K, defaultValue?: ExtendedDefaultModelRouterOptions[K]): ExtendedDefaultModelRouterOptions<unknown>[K];
747
+ private resolveModelOptions;
748
+ private validateModelOptions;
749
+ private publishDefaultModelOptions;
750
+ private warnSnapshotFlag;
751
+ private deferSnapshotWarnings;
752
+ private initialOutputCopyModes;
724
753
  private createModelOptions;
725
754
  private getOrCreateModelOptions;
726
755
  /**
727
- * Assign `{ ...modelDefaults, ...storedOptions, ...options }` shallowly. A supplied
756
+ * Update explicit model overrides shallowly; undefined restores default inheritance
757
+ * (operationAccess preserves its existing exact-key-only default fallback). A supplied
728
758
  * operationAccess/defaults object replaces that whole value. Defaults accept only
729
759
  * query/presentation settings; virtual configuration is validated before assignment.
730
760
  * Existing router.options remains its construction-time snapshot. Fresh model-service
@@ -732,7 +762,7 @@ declare class AccessRuntime {
732
762
  */
733
763
  setModelOptions<TModel = unknown, TVirtuals extends object = Record<never, never>>(modelName: string, options: ModelRouterOptions<TModel, TVirtuals>): void;
734
764
  setModelOption<K extends keyof ExtendedModelRouterOptions<TModel, TVirtuals>, TModel = unknown, TVirtuals extends object = Record<never, never>>(modelName: string, key: K, value: ExtendedModelRouterOptions<TModel, TVirtuals>[K]): void;
735
- /** Frozen stored snapshot, not fully resolved per-path defaults. Read again for current configuration. */
765
+ /** Frozen model/default snapshot; populate flags remain raw overrides. Read again for current values. */
736
766
  getModelOptions<TModel = unknown, TVirtuals extends object = Record<never, never>>(modelName: string): ModelRouterOptions<TModel, TVirtuals>;
737
767
  /**
738
768
  * Generic stored exact → parent.default → parent lookup; only undefined falls through.
@@ -1031,6 +1061,12 @@ declare const documentAuthorizationBrand: unique symbol;
1031
1061
  * unsafeSkipListNestedDocumentSnapshotChecks / unsafeSkipReadNestedDocumentSnapshotChecks
1032
1062
  * retain weakened source checks on query descendants, using the initiating model's
1033
1063
  * mode. In-place value mutations can therefore reuse stale grants/decisions.
1064
+ * unsafeSkipListInitialOutputSnapshotCopy / unsafeSkipReadInitialOutputSnapshotCopy
1065
+ * additionally omit eligible initial output snapshots only when the corresponding
1066
+ * output-value comparison skip is enabled. They retain bounded structural admission
1067
+ * and exact graph ownership, but omit this pass's native/BSON normalization and
1068
+ * validation observations. Source/callback/grant copies remain detached; unproven
1069
+ * graphs or open ownership bindings fall back to copying. Retained handles keep this mode.
1034
1070
  */
1035
1071
  interface DocumentAuthorization {
1036
1072
  readonly [documentAuthorizationBrand]: true;
@@ -1104,6 +1140,11 @@ type AllowedOutputFieldOptions<TModel = unknown, TVirtuals extends object = Reco
1104
1140
  readonly purpose: 'output';
1105
1141
  };
1106
1142
 
1143
+ /** Package-private model-default capture. Never use a source model's resolved flags as defaults. */
1144
+
1145
+ /** Function identity survives authorization snapshot copying, retaining one owner capture. */
1146
+ type PopulatePolicyDefaultsToken = () => void;
1147
+
1107
1148
  /** Package-private D2 validation/capture. Terminal persisted inputs, never output grants or target I/O. */
1108
1149
 
1109
1150
  interface VirtualPopulateTarget {
@@ -1171,11 +1212,15 @@ interface AuthorizationConfiguration {
1171
1212
  readonly unsafeSkipReadOutputSnapshotChecks?: boolean;
1172
1213
  readonly unsafeSkipListNestedDocumentSnapshotChecks?: boolean;
1173
1214
  readonly unsafeSkipReadNestedDocumentSnapshotChecks?: boolean;
1215
+ readonly unsafeSkipListInitialOutputSnapshotCopy?: boolean;
1216
+ readonly unsafeSkipReadInitialOutputSnapshotCopy?: boolean;
1174
1217
  /** Opaque terminal private-input capture. Never related authority or public document metadata. */
1175
1218
  readonly virtualPopulateSnapshot?: VirtualPopulateSnapshotToken;
1176
- /** Runtime-owned private input admission mode, not public output/related authority. */
1219
+ /** Held runtime model defaults, distinct from this model's resolved flags. */
1220
+ readonly populatePolicyDefaults?: PopulatePolicyDefaultsToken;
1221
+ /** Target-owned private input admission mode, not public output/related authority. */
1177
1222
  readonly requireOperationAccessForPopulateDependencies?: boolean;
1178
- /** Independent ordinary-populate operation admission from the same global snapshot. */
1223
+ /** Independent target-owned ordinary-populate operation admission. */
1179
1224
  readonly requireOperationAccessForPopulateQueries?: boolean;
1180
1225
  readonly documentPermissionField?: string;
1181
1226
  /** Captured permission schema, virtual descriptors, always-select and metadata posture. */
@@ -1186,6 +1231,8 @@ interface AuthorizationRelatedTarget {
1186
1231
  readonly path: string;
1187
1232
  readonly modelName: string;
1188
1233
  readonly configuration: AuthorizationConfiguration;
1234
+ /** Actual source-ref target or include receiver, captured with this runtime's configuration. */
1235
+ readonly model?: mongoose.Model<unknown>;
1189
1236
  /** Effective include args/options, resolved with that target's captured defaults. */
1190
1237
  readonly queryIntent?: ModelServiceIntent;
1191
1238
  /** Existing include operation gate, resolved synchronously with its target. */
@@ -2341,7 +2388,7 @@ interface Change {
2341
2388
  }
2342
2389
  interface ModelHookContext {
2343
2390
  modelName: string;
2344
- mongooseModel: mongoose.Model<unknown>;
2391
+ mongooseModel: mongoose__default.Model<unknown>;
2345
2392
  operation?: string;
2346
2393
  originalDocumentSnapshot?: Record<string, unknown>;
2347
2394
  finalDocumentSnapshot?: Record<string, unknown>;
@@ -3149,9 +3196,12 @@ interface AccessRouterLogger {
3149
3196
  isLevelEnabled?: (level: string) => boolean;
3150
3197
  }
3151
3198
  /**
3152
- * Runtime-wide request initialization, populate operation policies and resource settings, configured with
3199
+ * Runtime-wide request initialization and resource settings, configured with
3153
3200
  * api.setGlobalOptions / api.setGlobalOption. These are not model options or wire
3154
3201
  * options. Object assignment is shallow; nested requestComplexity replaces as a unit.
3202
+ * Populate operation flags belong to the actual target's ModelRouterOptions or
3203
+ * DefaultModelRouterOptions. Stale global setters (including api.set) reject them
3204
+ * with migration guidance to setModelOptions / setDefaultModelOptions.
3155
3205
  */
3156
3206
  interface GlobalOptions {
3157
3207
  /** Request grant-storage property (default `_permissions`), distinct from documentPermissionField. */
@@ -3165,57 +3215,6 @@ interface GlobalOptions {
3165
3215
  * context. Generated routers do not authenticate client claims for this hook.
3166
3216
  */
3167
3217
  globalPermissions?: (this: AccessRouterRequest, req: AccessRouterRequest) => MaybePromise<GlobalPermissionValue>;
3168
- /**
3169
- * Require the caller's effective target operation (`read`, supported `list` or trusted
3170
- * custom access) for ordinary query population (default `true`). Only literal `false`
3171
- * skips that admission gate; source entry/field authorization, target field/document
3172
- * grants, row/base/transform policies, original selection, match and mandatory reference
3173
- * IDs still constrain output. Denied population retains selected/permitted original
3174
- * source IDs; admitted population misses return null/filtered arrays, not restored IDs.
3175
- * Targets always require an actual Mongoose model and ACL configuration with an
3176
- * effective object permissionSchema in this runtime; `{}` closes business fields.
3177
- * Runtime-owned and captured before awaits, independently of private dependency
3178
- * admission. A configuration-only Document needs no HTTP routes. Its denied direct/root
3179
- * read/list operations stay denied. No per-model/query/client override.
3180
- */
3181
- requireOperationAccessForPopulateQueries?: boolean;
3182
- /**
3183
- * Require the original caller's target base `operationAccess.read` before loading
3184
- * declared private `dependsOnPopulate` inputs (default `true`). Only literal boolean
3185
- * `false` bypasses that operation gate; undefined/malformed JS values normalize to
3186
- * `true`. Source/target input-field permissions are already bypassed by the server
3187
- * declaration; the virtual's own output authorization still applies. Target request-mode
3188
- * `baseFilter.read`, `overrideFilter.read` and retained reference IDs always constrain rows.
3189
- * Captured with source/target policy and query intent before the first await, including
3190
- * nested output scopes. In-flight calls retain their mode; later calls see updates.
3191
- * Runtime-isolated server configuration only: no caller/query or per-model override.
3192
- *
3193
- * Neither mode changes ordinary reference shape: selected/permitted parent fields keep
3194
- * exact original IDs (including array order, duplicates, missing IDs and nulls) when no
3195
- * admitted ordinary population owns them. Private denial, row/query/getter failure or
3196
- * deferred virtual denial cannot hide those IDs. Omit only for parent unselection/field
3197
- * denial; admitted public DTO/null/filtered-array results retain their original masks.
3198
- * There is no additional target-base-read reference-visibility gate. False-mode loading
3199
- * adds no operation check solely for its private fetch. Private fourth-argument inputs
3200
- * never implicitly enter DTOs, hooks, handles, snapshots or permission metadata.
3201
- * An actual registered model, effective object permissionSchema and static declarations
3202
- * remain mandatory, independently of requireOperationAccessForPopulateQueries.
3203
- *
3204
- * @example
3205
- * ```ts
3206
- * import { createAccessRuntime, type GlobalOptions } from '@web-ts-toolkit/access-router';
3207
- * const api = createAccessRuntime();
3208
- * const policy = {
3209
- * requireOperationAccessForPopulateQueries: true,
3210
- * requireOperationAccessForPopulateDependencies: false,
3211
- * } satisfies GlobalOptions;
3212
- * api.setGlobalOptions(policy); // private computation; denied public population retains permitted IDs
3213
- * const snapshot: GlobalOptions = api.getGlobalOptions();
3214
- * api.setGlobalOption('requireOperationAccessForPopulateDependencies', true);
3215
- * void snapshot; // stored snapshot; read again to observe the setter
3216
- * ```
3217
- */
3218
- requireOperationAccessForPopulateDependencies?: boolean;
3219
3218
  logger?: AccessRouterLogger;
3220
3219
  /** Request budgets and separate hook/persistence pools; concurrency limits are captured on first owner use. */
3221
3220
  requestComplexity?: RequestComplexityOptions;
@@ -3346,8 +3345,9 @@ type HydrationMode = 'lean' | 'hydrated';
3346
3345
  * Set through ModelRouterOptions/DefaultModelRouterOptions and their whole-record
3347
3346
  * or exact hydration.<method> setters (including existing model/default decorators).
3348
3347
  * A supplied record replaces the previous record shallowly; omitted/undefined
3349
- * members use built-ins, not an older/default record. Whole-record undefined clears
3350
- * it. Invalid records/keys/modes throw before publication. Fresh calls observe owner
3348
+ * members use built-ins, not an older/default record. Whole-model-record undefined
3349
+ * restores default-model inheritance; default-record undefined clears that default.
3350
+ * Invalid records/keys/modes throw before publication. Fresh calls observe owner
3351
3351
  * updates; in-flight calls retain their captured configuration.
3352
3352
  * Includes stay fixed lean; raw parents/lifecycle stages stay hydrated; subdocument
3353
3353
  * post-save visibility stays lean. Populate inherits its parent query; $$sq uses
@@ -3369,7 +3369,17 @@ interface ModelHydrationOptions {
3369
3369
  /** Internal findById defaults to hydrated; does not inherit findOne's setting. */
3370
3370
  findById?: HydrationMode;
3371
3371
  }
3372
- /** Model starting defaults; data/root routers do not inherit these. Nested values assign shallowly. */
3372
+ /**
3373
+ * Inherited model defaults; data/root routers do not inherit these. Unspecified model
3374
+ * options follow later default updates for new calls. Explicit values (including false,
3375
+ * null, empty objects/arrays) win; setting a model option to undefined restores inheritance.
3376
+ * Exception: explicitly cleared operationAccess retains its exact-key-only default fallback;
3377
+ * a runtime catch-all/default guard is not an exact fallback in that mode.
3378
+ * Nested objects replace shallowly. Existing calls/handles and router.options keep their
3379
+ * captured snapshots; changing defaults does not rebuild already-mounted route paths.
3380
+ * The two populate operation flags retain raw override values in model snapshots;
3381
+ * their effective policy is resolved separately against the captured model defaults.
3382
+ */
3373
3383
  interface DefaultModelRouterOptions<TModel = unknown> {
3374
3384
  /**
3375
3385
  * Default business-field policy when a model's permissionSchema is undefined.
@@ -3379,6 +3389,85 @@ interface DefaultModelRouterOptions<TModel = unknown> {
3379
3389
  permissionSchema?: PermissionSchema<AccessRouterFieldKey<TModel>>;
3380
3390
  /** Server-owned fetch choices, captured per call. Not a per-call or method-default option. */
3381
3391
  hydration?: ModelHydrationOptions;
3392
+ /**
3393
+ * This target model requires the caller's effective operation (`read`, supported
3394
+ * `list` or trusted custom access) for ordinary query population (built-in default `true`).
3395
+ * Only literal `false` skips that admission gate; source entry/field authorization,
3396
+ * target field/document grants, row/base/transform policies, original selection,
3397
+ * match and mandatory reference IDs still constrain output. Denied population retains
3398
+ * permitted original IDs; admitted population misses return null/filtered arrays.
3399
+ * Targets always require an actual registered Mongoose model and an effective object permissionSchema;
3400
+ * `{}` closes business fields. A configuration-only Document needs no HTTP routes;
3401
+ * denied direct/root read/list operations stay denied.
3402
+ * Static string refs resolve on the source connection and must match that runtime's
3403
+ * configured instance. Explicit Model-valued ordinary refs can cross connections
3404
+ * when that exact model is registered/configured in the same runtime. The validated
3405
+ * model stays pinned through in-flight population; callers cannot supply a model.
3406
+ *
3407
+ * Target override → captured runtime model default → true. Explicit undefined clears
3408
+ * the override and restores inheritance; omission preserves it. Malformed non-undefined
3409
+ * JavaScript values become true. Defaults are captured before source/target option
3410
+ * reads and the first await; later top-level calls observe changes. getModelOptions and
3411
+ * router.options retain raw flag overrides; getModelOption reads the live default.
3412
+ * Source/sibling flags cannot relax
3413
+ * this target. Configure with setModelOptions/setDefaultModelOptions, never global,
3414
+ * per-query, service.defaults or client controls. Independent of private dependencies.
3415
+ */
3416
+ requireOperationAccessForPopulateQueries?: boolean;
3417
+ /**
3418
+ * This target model requires the original caller's base `operationAccess.read` before
3419
+ * loading declared private `dependsOnPopulate` inputs (built-in default `true`). Only
3420
+ * literal boolean `false` bypasses that operation gate. Target override → captured
3421
+ * runtime model default → true; explicit undefined clears the override to inherit,
3422
+ * omission preserves it, and malformed JS values other than undefined normalize true.
3423
+ * Runtime-isolated server configuration on the actual target, not the source model;
3424
+ * set runtime defaults with setDefaultModelOptions. Global setters reject these keys.
3425
+ * Captured with source/target policy before the first await; nested stages retain the
3426
+ * capture and later top-level calls refresh. No caller/query or service.defaults control.
3427
+ * Project refs to Document use Document's flags; Document's own private User ref
3428
+ * uses User's dependency flag, never Project's or Document's bypass.
3429
+ * Source/target input-field permissions are bypassed only by the declaration; the
3430
+ * virtual's output authorization still applies. Target request-mode `baseFilter.read`,
3431
+ * `overrideFilter.read` and retained reference IDs always constrain rows.
3432
+ *
3433
+ * Neither mode changes ordinary reference shape: selected/permitted parent fields keep
3434
+ * exact original IDs (including order, duplicates, missing IDs and nulls) when no admitted
3435
+ * ordinary population owns them. Private denial, row/query/getter failure or deferred
3436
+ * virtual denial cannot hide those IDs. There is no additional target-base-read reference-visibility gate.
3437
+ * Private fourth-argument inputs never implicitly enter DTOs, hooks, handles or metadata.
3438
+ * An actual registered model, effective object permissionSchema and static declarations
3439
+ * remain mandatory, independently of requireOperationAccessForPopulateQueries.
3440
+ *
3441
+ * @example
3442
+ * ```ts
3443
+ * import mongoose from 'mongoose';
3444
+ * import { createAccessRuntime, type DefaultModelRouterOptions } from '@web-ts-toolkit/access-router';
3445
+ * const api = createAccessRuntime();
3446
+ * const defaults = {
3447
+ * requireOperationAccessForPopulateQueries: true,
3448
+ * requireOperationAccessForPopulateDependencies: true,
3449
+ * } satisfies DefaultModelRouterOptions;
3450
+ * api.setDefaultModelOptions(defaults);
3451
+ * const Document = mongoose.model('Document', new mongoose.Schema({ name: String }));
3452
+ * const User = mongoose.model('User', new mongoose.Schema({ name: String }));
3453
+ * api.registerModelInstance(Document.modelName, Document);
3454
+ * api.registerModelInstance(User.modelName, User);
3455
+ * api.setModelOptions(Document.modelName, {
3456
+ * operationAccess: { read: false, list: false }, permissionSchema: { name: true },
3457
+ * requireOperationAccessForPopulateQueries: false,
3458
+ * requireOperationAccessForPopulateDependencies: false,
3459
+ * });
3460
+ * api.setModelOptions(User.modelName, {
3461
+ * operationAccess: { read: false, list: false }, permissionSchema: {},
3462
+ * requireOperationAccessForPopulateQueries: true,
3463
+ * requireOperationAccessForPopulateDependencies: true,
3464
+ * });
3465
+ * api.setModelOption(Document.modelName, 'requireOperationAccessForPopulateDependencies', undefined); // inherit again
3466
+ * // Administrative default changes apply to later calls on existing unoverridden models.
3467
+ * api.setDefaultModelOption('requireOperationAccessForPopulateDependencies', false);
3468
+ * ```
3469
+ */
3470
+ requireOperationAccessForPopulateDependencies?: boolean;
3382
3471
  /** Maximum returned list rows (default 1000), independent of exact match/count totals. */
3383
3472
  listHardLimit?: number;
3384
3473
  /**
@@ -3483,7 +3572,7 @@ interface DefaultModelRouterOptions<TModel = unknown> {
3483
3572
  * trusted non-mutating hooks, measure before rollout and restore `false` promptly.
3484
3573
  * Embedded/related source stages use separate nested flags. Writes (including
3485
3574
  * read-like output) and fresh helpers stay strict. Warns per model/flag transition.
3486
- * Server model or model-starting-default configuration only; never method defaults
3575
+ * Server model or inherited model-default configuration only; never method defaults
3487
3576
  * or wire options.
3488
3577
  */
3489
3578
  unsafeSkipReadDocumentSnapshotChecks?: boolean;
@@ -3492,9 +3581,10 @@ interface DefaultModelRouterOptions<TModel = unknown> {
3492
3581
  * top-level LIST responses and their embedded/populated/included descendants.
3493
3582
  * Exact output associations, graph identities, bindings and permission rules remain;
3494
3583
  * scalar/native in-place mutations can now reuse stale decisions and expose data.
3495
- * Source checks are independent. Initial snapshots and detached copies remain.
3584
+ * Source checks and detached callback/grant/output copies remain. Initial output
3585
+ * snapshots also remain unless unsafeSkipListInitialOutputSnapshotCopy is active.
3496
3586
  * Captured before awaits; handles keep this mode after rollback. Only literal `true`
3497
- * in server model/starting-default configuration enables it and warns on transition.
3587
+ * in server model/default configuration enables it and warns on effective transition.
3498
3588
  * READ/retries use unsafeSkipReadOutputSnapshotChecks; writes and fresh helpers stay
3499
3589
  * strict. Never set from request/per-call/method defaults. Revisit/remove promptly.
3500
3590
  */
@@ -3505,7 +3595,7 @@ interface DefaultModelRouterOptions<TModel = unknown> {
3505
3595
  * embedded/populated/included outputs. Uses the initiating READ model's captured
3506
3596
  * setting, not LIST or target-model settings. Value mutations may reuse stale
3507
3597
  * decisions; exact ownership/graph identities and permissions still run. Server
3508
- * model/starting-default literal `true` only; warns on enablement. Retained handles
3598
+ * model/default literal `true` only; warns on effective enablement. Retained handles
3509
3599
  * keep their mode. Writes/fresh helpers stay strict. Revisit/remove promptly.
3510
3600
  */
3511
3601
  unsafeSkipReadOutputSnapshotChecks?: boolean;
@@ -3515,8 +3605,8 @@ interface DefaultModelRouterOptions<TModel = unknown> {
3515
3605
  * The initiating model's captured setting applies recursively, not target-model
3516
3606
  * flags. Parent source and all output-value checks remain independently configured;
3517
3607
  * parent snapshots still include nested values. Permission rules, exact binding,
3518
- * initial snapshots and detached copies remain. Child mutation can leave stale
3519
- * grants/decisions and expose data. Only server model/starting-default literal `true`
3608
+ * initial source snapshots and detached copies remain. Child mutation can leave stale
3609
+ * grants/decisions and expose data. Only server model/default literal `true`
3520
3610
  * enables it; warns on transition. Rollback affects new calls, not captured descendants
3521
3611
  * or handles. READ uses its own flag; writes, dedicated subdocument operations and
3522
3612
  * fresh helpers stay strict. Never derive from requests. Revisit/remove promptly.
@@ -3529,11 +3619,37 @@ interface DefaultModelRouterOptions<TModel = unknown> {
3529
3619
  * initiating READ model's captured setting, independently of LIST, root source
3530
3620
  * and output-value flags. Parent comparisons may still observe child mutation.
3531
3621
  * Stale grants/decisions can expose data; permissions, identities and detached copies
3532
- * remain. Server model/starting-default literal `true` only; warns on enablement.
3622
+ * remain. Server model/default literal `true` only; warns on effective enablement.
3533
3623
  * Writes/dedicated subdocument operations/fresh helpers stay strict; retained handles
3534
3624
  * keep their mode after rollback. Never set from requests. Revisit/remove promptly.
3535
3625
  */
3536
3626
  unsafeSkipReadNestedDocumentSnapshotChecks?: boolean;
3627
+ /**
3628
+ * TEMPORARY UNSAFE (default `false`): omit the initial output-association snapshot
3629
+ * copy for eligible LIST outputs and their authenticated descendants. Active only
3630
+ * with unsafeSkipListOutputSnapshotChecks=true; otherwise dormant (warns).
3631
+ * Skips this pass's native/BSON normalization and validation observations, which
3632
+ * can change exceptions, side effects and permission outcomes. Exact ownership,
3633
+ * bounded shape admission and graph identities remain; proxies/Map/Set and open
3634
+ * ownership bindings use the original copy fallback. Source snapshots and detached
3635
+ * hook/grant/response copies remain. Not a general clone bypass. Server model/default literal true
3636
+ * only; warns on activation. Captured before awaits; retained handles keep their
3637
+ * mode after rollback. READ/retries use their own flag; writes/fresh helpers stay
3638
+ * strict. Restore false promptly; never select from requests or method defaults.
3639
+ */
3640
+ unsafeSkipListInitialOutputSnapshotCopy?: boolean;
3641
+ /**
3642
+ * TEMPORARY UNSAFE (default `false`): READ equivalent of
3643
+ * unsafeSkipListInitialOutputSnapshotCopy, including READ-to-list retries and
3644
+ * authenticated embedded/populated/included outputs. Requires the independent
3645
+ * unsafeSkipReadOutputSnapshotChecks=true. Uses the initiating READ model's
3646
+ * captured setting, not LIST/target flags. Omits initial native normalization
3647
+ * observations; ownership/bounds/identities and detached callback/source copies
3648
+ * remain. Proxies/Map/Set fall back to copying. Server model/default literal true
3649
+ * only; warns on activation/dormancy. Writes/fresh helpers stay strict. Captured
3650
+ * handles do not change on rollback. Never derive from requests; restore false.
3651
+ */
3652
+ unsafeSkipReadInitialOutputSnapshotCopy?: boolean;
3537
3653
  }
3538
3654
  interface ExtendedDefaultModelRouterOptions<TModel = unknown> extends DefaultModelRouterOptions<TModel> {
3539
3655
  'hydration.publicList'?: HydrationMode;
@@ -3573,6 +3689,8 @@ interface ExtendedDefaultModelRouterOptions<TModel = unknown> extends DefaultMod
3573
3689
  * named method query/presentation defaults. Trusted service authorization is per-call.
3574
3690
  * Router setters update live behavior shallowly; router.options retains its frozen
3575
3691
  * construction-time snapshot. Route-shape options require constructing a new router.
3692
+ * Populate flags govern this model when it is the actual target, not refs leaving it.
3693
+ * Their model snapshots retain raw overrides; operation capture resolves live defaults.
3576
3694
  */
3577
3695
  interface ModelRouterOptions<TModel = unknown, TVirtuals extends object = Record<never, never>> extends DefaultModelRouterOptions<TModel> {
3578
3696
  modelName?: string;
@@ -3611,13 +3729,13 @@ interface ModelRouterOptions<TModel = unknown, TVirtuals extends object = Record
3611
3729
  * that getter's fourth argument. Annotate ModelVirtualDescriptor<Source, Value,
3612
3730
  * { ref: Target }> separately, then assign here; persisted/write/public types
3613
3731
  * stay unchanged. Register target models/options first in this runtime. Source
3614
- * refs are retained automatically. GlobalOptions.requireOperationAccessForPopulateDependencies
3732
+ * refs are retained automatically. The actual target's requireOperationAccessForPopulateDependencies
3615
3733
  * defaults to true; false bypasses only private target-operation admission, never
3616
3734
  * request read-row filters/retained IDs. Neither mode changes ordinary reference
3617
3735
  * shape: admitted population keeps its original authorized mask/miss; otherwise
3618
3736
  * selected/permitted parent fields keep exact original IDs, even on private failure.
3619
3737
  * Only unselected/field-denied source refs are omitted. Query operation admission is
3620
- * independently controlled by GlobalOptions.requireOperationAccessForPopulateQueries.
3738
+ * independently controlled by that target's requireOperationAccessForPopulateQueries.
3621
3739
  *
3622
3740
  * @example Shortest typed happy-path (persisted model lacks `fullAddress`):
3623
3741
  * ```ts