@web-ts-toolkit/access-router 0.60.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.
@@ -1024,8 +1054,19 @@ declare const documentAuthorizationBrand: unique symbol;
1024
1054
  * row/call/access or pre-/post-write stages cannot establish validity and reject.
1025
1055
  * A list/read handle with its server unsafeSkipListDocumentSnapshotChecks or
1026
1056
  * unsafeSkipReadDocumentSnapshotChecks flag enabled retains that weakened source-
1027
- * mutation policy; output mutation/ownership checks still apply. Turning a setting
1057
+ * mutation policy; independent output-value/ownership checks still apply. Turning a setting
1028
1058
  * off affects new calls, not an existing handle or captured read-to-list retry.
1059
+ * Independent unsafeSkipListOutputSnapshotChecks / unsafeSkipReadOutputSnapshotChecks
1060
+ * can also retain weakened output-value checks (graph identities still checked).
1061
+ * unsafeSkipListNestedDocumentSnapshotChecks / unsafeSkipReadNestedDocumentSnapshotChecks
1062
+ * retain weakened source checks on query descendants, using the initiating model's
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.
1029
1070
  */
1030
1071
  interface DocumentAuthorization {
1031
1072
  readonly [documentAuthorizationBrand]: true;
@@ -1099,6 +1140,11 @@ type AllowedOutputFieldOptions<TModel = unknown, TVirtuals extends object = Reco
1099
1140
  readonly purpose: 'output';
1100
1141
  };
1101
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
+
1102
1148
  /** Package-private D2 validation/capture. Terminal persisted inputs, never output grants or target I/O. */
1103
1149
 
1104
1150
  interface VirtualPopulateTarget {
@@ -1162,11 +1208,19 @@ interface AuthorizationConfiguration {
1162
1208
  /** Captured server model option; alone it never issues relaxed document authority. */
1163
1209
  readonly unsafeSkipListDocumentSnapshotChecks?: boolean;
1164
1210
  readonly unsafeSkipReadDocumentSnapshotChecks?: boolean;
1211
+ readonly unsafeSkipListOutputSnapshotChecks?: boolean;
1212
+ readonly unsafeSkipReadOutputSnapshotChecks?: boolean;
1213
+ readonly unsafeSkipListNestedDocumentSnapshotChecks?: boolean;
1214
+ readonly unsafeSkipReadNestedDocumentSnapshotChecks?: boolean;
1215
+ readonly unsafeSkipListInitialOutputSnapshotCopy?: boolean;
1216
+ readonly unsafeSkipReadInitialOutputSnapshotCopy?: boolean;
1165
1217
  /** Opaque terminal private-input capture. Never related authority or public document metadata. */
1166
1218
  readonly virtualPopulateSnapshot?: VirtualPopulateSnapshotToken;
1167
- /** 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. */
1168
1222
  readonly requireOperationAccessForPopulateDependencies?: boolean;
1169
- /** Independent ordinary-populate operation admission from the same global snapshot. */
1223
+ /** Independent target-owned ordinary-populate operation admission. */
1170
1224
  readonly requireOperationAccessForPopulateQueries?: boolean;
1171
1225
  readonly documentPermissionField?: string;
1172
1226
  /** Captured permission schema, virtual descriptors, always-select and metadata posture. */
@@ -1177,6 +1231,8 @@ interface AuthorizationRelatedTarget {
1177
1231
  readonly path: string;
1178
1232
  readonly modelName: string;
1179
1233
  readonly configuration: AuthorizationConfiguration;
1234
+ /** Actual source-ref target or include receiver, captured with this runtime's configuration. */
1235
+ readonly model?: mongoose.Model<unknown>;
1180
1236
  /** Effective include args/options, resolved with that target's captured defaults. */
1181
1237
  readonly queryIntent?: ModelServiceIntent;
1182
1238
  /** Existing include operation gate, resolved synchronously with its target. */
@@ -2332,7 +2388,7 @@ interface Change {
2332
2388
  }
2333
2389
  interface ModelHookContext {
2334
2390
  modelName: string;
2335
- mongooseModel: mongoose.Model<unknown>;
2391
+ mongooseModel: mongoose__default.Model<unknown>;
2336
2392
  operation?: string;
2337
2393
  originalDocumentSnapshot?: Record<string, unknown>;
2338
2394
  finalDocumentSnapshot?: Record<string, unknown>;
@@ -3140,9 +3196,12 @@ interface AccessRouterLogger {
3140
3196
  isLevelEnabled?: (level: string) => boolean;
3141
3197
  }
3142
3198
  /**
3143
- * Runtime-wide request initialization, populate operation policies and resource settings, configured with
3199
+ * Runtime-wide request initialization and resource settings, configured with
3144
3200
  * api.setGlobalOptions / api.setGlobalOption. These are not model options or wire
3145
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.
3146
3205
  */
3147
3206
  interface GlobalOptions {
3148
3207
  /** Request grant-storage property (default `_permissions`), distinct from documentPermissionField. */
@@ -3156,57 +3215,6 @@ interface GlobalOptions {
3156
3215
  * context. Generated routers do not authenticate client claims for this hook.
3157
3216
  */
3158
3217
  globalPermissions?: (this: AccessRouterRequest, req: AccessRouterRequest) => MaybePromise<GlobalPermissionValue>;
3159
- /**
3160
- * Require the caller's effective target operation (`read`, supported `list` or trusted
3161
- * custom access) for ordinary query population (default `true`). Only literal `false`
3162
- * skips that admission gate; source entry/field authorization, target field/document
3163
- * grants, row/base/transform policies, original selection, match and mandatory reference
3164
- * IDs still constrain output. Denied population retains selected/permitted original
3165
- * source IDs; admitted population misses return null/filtered arrays, not restored IDs.
3166
- * Targets always require an actual Mongoose model and ACL configuration with an
3167
- * effective object permissionSchema in this runtime; `{}` closes business fields.
3168
- * Runtime-owned and captured before awaits, independently of private dependency
3169
- * admission. A configuration-only Document needs no HTTP routes. Its denied direct/root
3170
- * read/list operations stay denied. No per-model/query/client override.
3171
- */
3172
- requireOperationAccessForPopulateQueries?: boolean;
3173
- /**
3174
- * Require the original caller's target base `operationAccess.read` before loading
3175
- * declared private `dependsOnPopulate` inputs (default `true`). Only literal boolean
3176
- * `false` bypasses that operation gate; undefined/malformed JS values normalize to
3177
- * `true`. Source/target input-field permissions are already bypassed by the server
3178
- * declaration; the virtual's own output authorization still applies. Target request-mode
3179
- * `baseFilter.read`, `overrideFilter.read` and retained reference IDs always constrain rows.
3180
- * Captured with source/target policy and query intent before the first await, including
3181
- * nested output scopes. In-flight calls retain their mode; later calls see updates.
3182
- * Runtime-isolated server configuration only: no caller/query or per-model override.
3183
- *
3184
- * Neither mode changes ordinary reference shape: selected/permitted parent fields keep
3185
- * exact original IDs (including array order, duplicates, missing IDs and nulls) when no
3186
- * admitted ordinary population owns them. Private denial, row/query/getter failure or
3187
- * deferred virtual denial cannot hide those IDs. Omit only for parent unselection/field
3188
- * denial; admitted public DTO/null/filtered-array results retain their original masks.
3189
- * There is no additional target-base-read reference-visibility gate. False-mode loading
3190
- * adds no operation check solely for its private fetch. Private fourth-argument inputs
3191
- * never implicitly enter DTOs, hooks, handles, snapshots or permission metadata.
3192
- * An actual registered model, effective object permissionSchema and static declarations
3193
- * remain mandatory, independently of requireOperationAccessForPopulateQueries.
3194
- *
3195
- * @example
3196
- * ```ts
3197
- * import { createAccessRuntime, type GlobalOptions } from '@web-ts-toolkit/access-router';
3198
- * const api = createAccessRuntime();
3199
- * const policy = {
3200
- * requireOperationAccessForPopulateQueries: true,
3201
- * requireOperationAccessForPopulateDependencies: false,
3202
- * } satisfies GlobalOptions;
3203
- * api.setGlobalOptions(policy); // private computation; denied public population retains permitted IDs
3204
- * const snapshot: GlobalOptions = api.getGlobalOptions();
3205
- * api.setGlobalOption('requireOperationAccessForPopulateDependencies', true);
3206
- * void snapshot; // stored snapshot; read again to observe the setter
3207
- * ```
3208
- */
3209
- requireOperationAccessForPopulateDependencies?: boolean;
3210
3218
  logger?: AccessRouterLogger;
3211
3219
  /** Request budgets and separate hook/persistence pools; concurrency limits are captured on first owner use. */
3212
3220
  requestComplexity?: RequestComplexityOptions;
@@ -3337,8 +3345,9 @@ type HydrationMode = 'lean' | 'hydrated';
3337
3345
  * Set through ModelRouterOptions/DefaultModelRouterOptions and their whole-record
3338
3346
  * or exact hydration.<method> setters (including existing model/default decorators).
3339
3347
  * A supplied record replaces the previous record shallowly; omitted/undefined
3340
- * members use built-ins, not an older/default record. Whole-record undefined clears
3341
- * 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
3342
3351
  * updates; in-flight calls retain their captured configuration.
3343
3352
  * Includes stay fixed lean; raw parents/lifecycle stages stay hydrated; subdocument
3344
3353
  * post-save visibility stays lean. Populate inherits its parent query; $$sq uses
@@ -3360,7 +3369,17 @@ interface ModelHydrationOptions {
3360
3369
  /** Internal findById defaults to hydrated; does not inherit findOne's setting. */
3361
3370
  findById?: HydrationMode;
3362
3371
  }
3363
- /** 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
+ */
3364
3383
  interface DefaultModelRouterOptions<TModel = unknown> {
3365
3384
  /**
3366
3385
  * Default business-field policy when a model's permissionSchema is undefined.
@@ -3370,6 +3389,85 @@ interface DefaultModelRouterOptions<TModel = unknown> {
3370
3389
  permissionSchema?: PermissionSchema<AccessRouterFieldKey<TModel>>;
3371
3390
  /** Server-owned fetch choices, captured per call. Not a per-call or method-default option. */
3372
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;
3373
3471
  /** Maximum returned list rows (default 1000), independent of exact match/count totals. */
3374
3472
  listHardLimit?: number;
3375
3473
  /**
@@ -3450,9 +3548,10 @@ interface DefaultModelRouterOptions<TModel = unknown> {
3450
3548
  * skips repeated projected-document snapshot comparisons for this model's top-level
3451
3549
  * `find`/public/root list responses. Captured before awaits; list-origin handles keep
3452
3550
  * that mode. Single reads use the independent unsafeSkipReadDocumentSnapshotChecks
3453
- * setting. Writes, embedded/related stages and fresh standalone helpers stay strict.
3551
+ * setting. Embedded/related source stages and output values have separate flags.
3552
+ * Writes and fresh standalone helpers stay strict.
3454
3553
  *
3455
- * Row/field permissions, exact ownership/binding, output provenance/mutation checks
3554
+ * Row/field permissions, exact ownership/binding, independent output-value checks
3456
3555
  * and detached callback/grant copies still run. However, source changes during a
3457
3556
  * callback/await are no longer detected: stale grants/decisions may authorize output.
3458
3557
  * Use only with trusted non-mutating application hooks, measure before rollout, and
@@ -3467,15 +3566,90 @@ interface DefaultModelRouterOptions<TModel = unknown> {
3467
3566
  * this setting, not unsafeSkipListDocumentSnapshotChecks. Captured before awaits;
3468
3567
  * read-origin handles and retries keep that mode. List operations use their own flag.
3469
3568
  *
3470
- * Permission rules, exact ownership/binding, output-mutation/provenance checks and
3569
+ * Permission rules, exact ownership/binding, independent output-value checks and
3471
3570
  * detached callback/grant copies still run. Source changes during callbacks/awaits
3472
3571
  * can leave stale grants/decisions and incorrectly authorized output. Use only with
3473
3572
  * trusted non-mutating hooks, measure before rollout and restore `false` promptly.
3474
- * Writes (including read-like output), embedded/related stages and fresh helpers
3475
- * remain strict. Enabling warns once per model/flag transition. Server model or
3476
- * model-starting-default configuration only; never method defaults or wire options.
3573
+ * Embedded/related source stages use separate nested flags. Writes (including
3574
+ * read-like output) and fresh helpers stay strict. Warns per model/flag transition.
3575
+ * Server model or inherited model-default configuration only; never method defaults
3576
+ * or wire options.
3477
3577
  */
3478
3578
  unsafeSkipReadDocumentSnapshotChecks?: boolean;
3579
+ /**
3580
+ * TEMPORARY UNSAFE (default `false`): skip output VALUE snapshot comparisons in
3581
+ * top-level LIST responses and their embedded/populated/included descendants.
3582
+ * Exact output associations, graph identities, bindings and permission rules remain;
3583
+ * scalar/native in-place mutations can now reuse stale decisions and expose data.
3584
+ * Source checks and detached callback/grant/output copies remain. Initial output
3585
+ * snapshots also remain unless unsafeSkipListInitialOutputSnapshotCopy is active.
3586
+ * Captured before awaits; handles keep this mode after rollback. Only literal `true`
3587
+ * in server model/default configuration enables it and warns on effective transition.
3588
+ * READ/retries use unsafeSkipReadOutputSnapshotChecks; writes and fresh helpers stay
3589
+ * strict. Never set from request/per-call/method defaults. Revisit/remove promptly.
3590
+ */
3591
+ unsafeSkipListOutputSnapshotChecks?: boolean;
3592
+ /**
3593
+ * TEMPORARY UNSAFE (default `false`): READ equivalent of unsafeSkipListOutputSnapshotChecks,
3594
+ * including findOne/findById, public/root reads, read-to-list retries and their
3595
+ * embedded/populated/included outputs. Uses the initiating READ model's captured
3596
+ * setting, not LIST or target-model settings. Value mutations may reuse stale
3597
+ * decisions; exact ownership/graph identities and permissions still run. Server
3598
+ * model/default literal `true` only; warns on effective enablement. Retained handles
3599
+ * keep their mode. Writes/fresh helpers stay strict. Revisit/remove promptly.
3600
+ */
3601
+ unsafeSkipReadOutputSnapshotChecks?: boolean;
3602
+ /**
3603
+ * TEMPORARY UNSAFE (default `false`): skip repeated SOURCE snapshot comparisons for
3604
+ * embedded/populated/included document stages reached from a top-level LIST.
3605
+ * The initiating model's captured setting applies recursively, not target-model
3606
+ * flags. Parent source and all output-value checks remain independently configured;
3607
+ * parent snapshots still include nested values. Permission rules, exact binding,
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`
3610
+ * enables it; warns on transition. Rollback affects new calls, not captured descendants
3611
+ * or handles. READ uses its own flag; writes, dedicated subdocument operations and
3612
+ * fresh helpers stay strict. Never derive from requests. Revisit/remove promptly.
3613
+ */
3614
+ unsafeSkipListNestedDocumentSnapshotChecks?: boolean;
3615
+ /**
3616
+ * TEMPORARY UNSAFE (default `false`): READ equivalent of
3617
+ * unsafeSkipListNestedDocumentSnapshotChecks, including read-to-list retries.
3618
+ * Recursively skips embedded/populated/included SOURCE comparisons using the
3619
+ * initiating READ model's captured setting, independently of LIST, root source
3620
+ * and output-value flags. Parent comparisons may still observe child mutation.
3621
+ * Stale grants/decisions can expose data; permissions, identities and detached copies
3622
+ * remain. Server model/default literal `true` only; warns on effective enablement.
3623
+ * Writes/dedicated subdocument operations/fresh helpers stay strict; retained handles
3624
+ * keep their mode after rollback. Never set from requests. Revisit/remove promptly.
3625
+ */
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;
3479
3653
  }
3480
3654
  interface ExtendedDefaultModelRouterOptions<TModel = unknown> extends DefaultModelRouterOptions<TModel> {
3481
3655
  'hydration.publicList'?: HydrationMode;
@@ -3515,6 +3689,8 @@ interface ExtendedDefaultModelRouterOptions<TModel = unknown> extends DefaultMod
3515
3689
  * named method query/presentation defaults. Trusted service authorization is per-call.
3516
3690
  * Router setters update live behavior shallowly; router.options retains its frozen
3517
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.
3518
3694
  */
3519
3695
  interface ModelRouterOptions<TModel = unknown, TVirtuals extends object = Record<never, never>> extends DefaultModelRouterOptions<TModel> {
3520
3696
  modelName?: string;
@@ -3553,13 +3729,13 @@ interface ModelRouterOptions<TModel = unknown, TVirtuals extends object = Record
3553
3729
  * that getter's fourth argument. Annotate ModelVirtualDescriptor<Source, Value,
3554
3730
  * { ref: Target }> separately, then assign here; persisted/write/public types
3555
3731
  * stay unchanged. Register target models/options first in this runtime. Source
3556
- * refs are retained automatically. GlobalOptions.requireOperationAccessForPopulateDependencies
3732
+ * refs are retained automatically. The actual target's requireOperationAccessForPopulateDependencies
3557
3733
  * defaults to true; false bypasses only private target-operation admission, never
3558
3734
  * request read-row filters/retained IDs. Neither mode changes ordinary reference
3559
3735
  * shape: admitted population keeps its original authorized mask/miss; otherwise
3560
3736
  * selected/permitted parent fields keep exact original IDs, even on private failure.
3561
3737
  * Only unselected/field-denied source refs are omitted. Query operation admission is
3562
- * independently controlled by GlobalOptions.requireOperationAccessForPopulateQueries.
3738
+ * independently controlled by that target's requireOperationAccessForPopulateQueries.
3563
3739
  *
3564
3740
  * @example Shortest typed happy-path (persisted model lacks `fullAddress`):
3565
3741
  * ```ts