@getstrata/core 2.1.0 → 2.2.1

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @getstrata/core changelog
 
+## 2.2.1
+
+F02 — complete queue durability. Queues have leased reservations, recovery and fenced acknowledgement, but still use Redis lists. Persisted retry schedules, execution deadlines, cancellation and the planned Streams migration remain unfinished. Retries currently wait inside the running worker.
+F10 — production public-route tenancy. Separate anonymous access from development tenant headers, support a trusted-host resolver, reject unknown hosts, and accept forwarded hosts only through configured trusted proxies. The shop still lacks the approved-domain mapping.
+F12 — initial administrator provisioning and migration guidance. Automatic demo seeding is fixed. Secure initial-admin provisioning and a consolidated upgrade/operations guide remain.
+Distributed qualification. Cache generations/fill leases, scheduler ownership, OpenTelemetry, body limits and lifecycle controls now exist. Their implementation should no longer be described as entirely pending, but broader failure and capacity qualification is still required.
+
+## 2.2.0
+
+Consistent model scopes.
+Changed-field model writes.
+Awaited provider startup.
+Shared cache correctness.
+Native HTTP controls and body limits.
+Graceful lifecycle.
+Validated async discovery.
+Stronger model input types.
+OpenTelemetry tracing.
+Distributed scheduler ownership.
+App-owned quota policy.
+Bounded memory throttling.
+
+## Unreleased
+
+- Coordinate scheduled minute occurrences with renewable Redis ownership, overlap exclusion, completion retention and lease-loss cancellation. Production defaults to Redis without local fallback; direct task callbacks now accept ownership context. Share appSchedule across root/subpath imports. See SCHEDULER.md for explicit local mode and replay limits.
+
+- Use maintained OpenTelemetry tracing with W3C propagation, consistent identities/epoch timestamps, bounded batching, sampling, error status and lifecycle-owned flush/shutdown. Raw URL/exception secrets are omitted; debug x-trace-id no longer overrides identity.
+
+- Strengthen declared model write/filter/identifier contracts and add typed plain-record projections with model casts and existing scope/RLS semantics. Source compatibility: use `query().select(...)` instead of partial selects on model-returning helpers, `whereDynamic` for qualified/dynamic predicates, and `newFromTrustedRecord` for deliberate partial driver hydration. Database defaults and mass-assignment rules remain runtime concerns.
+
+- Accept awaited provider hooks and explicit cleanup registration; expose optional closure of owned Redis cache/queue clients.
+
+- Persist only changed attributes on existing model saves, skip no-op updates and unchanged write casts, and restore retryable snapshots after transaction/savepoint rollback.
+
+- Apply related target model scopes and composed filters to lazy/eager/existence/count reads; retain batched connection reuse, isolate morph targets by type and ID, and use dialect-aware through/pivot read parameters.
+
+- Compose repeated query predicates and protect global model scopes from caller OR branches; preserve scopes in chunks/cursor pages and intersect cursor bounds with existing filters.
+
+- Add typed `defineModel(table)` bases and two-phase model startup; preserve explicit repository overrides and share model identity across package import paths.
+
 ## 2.1.0
 
 - refactor(starter): reuse shared config and base repositories - fix(database): await password casts before model writes - fix(database): preserve concrete model types in query results

package/dist/core/cache/createCacheStore.d.ts

@@ -1,3 +1,4 @@
+import { type RedisCacheOptions } from "./redisCacheStore";
 import type { CacheStore } from "./store";
 type CacheDriver = "array" | "redis";
 interface CreateCacheStoreOptions {
@@ -5,7 +6,8 @@ interface CreateCacheStoreOptions {
     ttlMs: number;
     maxEntries: number;
     redisUrl?: string;
+    redis?: RedisCacheOptions;
 }
 declare function createCacheStore(options: CreateCacheStoreOptions): CacheStore;
-export type { CacheDriver, CreateCacheStoreOptions };
+export type { CacheDriver, CreateCacheStoreOptions, RedisCacheOptions };
 export { createCacheStore };

package/dist/core/cache/redisCacheStore.d.ts

@@ -1,23 +1,36 @@
 import type { CacheStore } from "./store";
+type RedisCacheOptions = {
+    commandTimeoutMs?: number;
+    leaseMs?: number;
+    fillTimeoutMs?: number;
+    waitTimeoutMs?: number;
+    pollMs?: number;
+    metadataTtlMs?: number;
+    metadataLimit?: number;
+};
 declare class RedisCacheStore implements CacheStore {
     private readonly ttlMs;
     private readonly maxEntries;
     private readonly client;
-    private readonly inflight;
-    private readonly keyTags;
-    constructor(redisUrl: string, ttlMs: number, maxEntries: number);
+    private readonly keys;
+    private readonly options;
+    private readonly fills;
+    private closed;
+    constructor(redisUrl: string, ttlMs: number, maxEntries: number, options?: RedisCacheOptions);
+    close(): void;
     get<T>(key: string): Promise<T | undefined>;
     set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
-    getOrSet<T>(key: string, loader: () => Promise<T>, ttlMs?: number): Promise<T>;
+    getOrSet<T>(key: string, loader: (signal?: AbortSignal) => Promise<T>, ttlMs?: number): Promise<T>;
+    getOrSetTagged<T>(key: string, loader: (signal?: AbortSignal) => Promise<T>, tags: string[], ttlMs?: number): Promise<T>;
     attachTags(key: string, tags: string[]): Promise<void>;
     flushTags(tags: string[]): Promise<number>;
     invalidate(key: string): Promise<boolean>;
     invalidateByPrefix(prefix: string): Promise<number>;
     clear(): Promise<void>;
     size(): Promise<number>;
-    private storageKey;
-    private tagKey;
-    private detachKeyFromTags;
-    private enforceMaxEntries;
+    private fill;
+    private serialize;
+    private execute;
 }
+export type { RedisCacheOptions };
 export default RedisCacheStore;

package/dist/core/cache/repository.d.ts

@@ -3,12 +3,13 @@ import TaggedCache from "./taggedCache";
 declare class CacheRepository {
     private readonly store;
     constructor(store: CacheStore);
+    close(): Promise<void>;
     get<T>(key: string): Promise<T | undefined>;
-    remember<T>(key: string, callback: () => Promise<T>, ttlMs?: number): Promise<T>;
+    remember<T>(key: string, callback: (signal?: AbortSignal) => Promise<T>, ttlMs?: number): Promise<T>;
     forget(key: string): Promise<boolean>;
     flush(): Promise<void>;
     tags(...names: string[]): TaggedCache;
-    getOrSet<T>(key: string, loader: () => Promise<T>, ttlMs?: number): Promise<T>;
+    getOrSet<T>(key: string, loader: (signal?: AbortSignal) => Promise<T>, ttlMs?: number): Promise<T>;
     invalidate(key: string): Promise<boolean>;
     invalidateByPrefix(prefix: string): Promise<number>;
     clear(): Promise<void>;

package/dist/core/cache/store.d.ts

@@ -1,7 +1,10 @@
 interface CacheStore {
+    close?(): void | Promise<void>;
     get<T>(key: string): Promise<T | undefined>;
     set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
-    getOrSet<T>(key: string, loader: () => Promise<T>, ttlMs?: number): Promise<T>;
+    getOrSet<T>(key: string, loader: (signal?: AbortSignal) => Promise<T>, ttlMs?: number): Promise<T>;
+    /** Shared stores can bind tags before starting a fill. */
+    getOrSetTagged?<T>(key: string, loader: (signal?: AbortSignal) => Promise<T>, tags: string[], ttlMs?: number): Promise<T>;
     attachTags(key: string, tags: string[]): Promise<void>;
     flushTags(tags: string[]): Promise<number>;
     invalidate(key: string): Promise<boolean>;

package/dist/core/cache/taggedCache.d.ts

@@ -3,7 +3,7 @@ declare class TaggedCache {
     private readonly store;
     private readonly tags;
     constructor(store: CacheStore, tags: string[]);
-    remember<T>(key: string, callback: () => Promise<T>, ttlMs?: number): Promise<T>;
+    remember<T>(key: string, callback: (signal?: AbortSignal) => Promise<T>, ttlMs?: number): Promise<T>;
     flush(): Promise<number>;
 }
 export default TaggedCache;

package/dist/core/contracts/di.d.ts

@@ -13,11 +13,13 @@ interface ProviderContext {
     container: ServiceContainer;
     config: ConfigStore;
     dependencies: MutableAppDependencies;
+    /** Register owned resources immediately; flush precedes close, each in reverse order. */
+    onCleanup(handler: () => void | Promise<void>, phase?: "drain" | "flush" | "close"): void;
 }
 interface ServiceProvider {
     name: string;
-    register?(context: ProviderContext): void;
-    boot?(context: ProviderContext): void;
+    register?(context: ProviderContext): void | Promise<void>;
+    boot?(context: ProviderContext): void | Promise<void>;
 }
 interface AppContext {
     container: ServiceContainer;

package/dist/core/contracts/serviceTokens.d.ts

@@ -1,6 +1,12 @@
 import type { AbilityChecker } from "../auth/abilityChecker";
+import type { ThrottleQuotaPolicy } from "../http/throttleMiddleware";
+import type { PublicTenancyOptions, TenantResolver } from "../tenant/tenantMiddleware";
 import type { AuthUserDirectory } from "./authUserDirectory";
 import type { ServiceContainerLike } from "./container";
+declare const CORE_THROTTLE_QUOTA_POLICY_TOKEN: import("./container").ServiceToken<ThrottleQuotaPolicy>;
+declare const CORE_PUBLIC_TENANCY_TOKEN: import("./container").ServiceToken<PublicTenancyOptions>;
+declare const CORE_TENANT_RESOLVER_TOKEN: import("./container").ServiceToken<TenantResolver>;
+declare const CORE_HTTP_CLEANUP_TOKEN: import("./container").ServiceToken<(cleanup: () => void) => void>;
 declare const CORE_CONFIG_TOKEN = "core.config";
 declare const CORE_CACHE_TOKEN = "core.cache";
 declare const CORE_QUEUE_TOKEN = "core.queue";
@@ -14,4 +20,4 @@ declare function isAbilityChecker(value: unknown): value is AbilityChecker;
 declare function isAuthUserDirectory(value: unknown): value is AuthUserDirectory;
 declare function resolveAbilityChecker(container: ServiceContainerLike): AbilityChecker;
 declare function resolveAuthUserDirectory(container: ServiceContainerLike): AuthUserDirectory | null;
-export { CORE_ABILITY_CHECKER_TOKEN, CORE_AUTH_TOKEN, CORE_AUTH_USER_DIRECTORY_TOKEN, CORE_CACHE_TOKEN, CORE_CONFIG_TOKEN, CORE_EVENT_BUS_TOKEN, CORE_POLICY_GATE_TOKEN, CORE_QUEUE_TOKEN, CORE_TOKEN_SERVICE_TOKEN, isAbilityChecker, isAuthUserDirectory, resolveAbilityChecker, resolveAuthUserDirectory, };
+export { CORE_ABILITY_CHECKER_TOKEN, CORE_AUTH_TOKEN, CORE_AUTH_USER_DIRECTORY_TOKEN, CORE_CACHE_TOKEN, CORE_CONFIG_TOKEN, CORE_EVENT_BUS_TOKEN, CORE_HTTP_CLEANUP_TOKEN, CORE_POLICY_GATE_TOKEN, CORE_PUBLIC_TENANCY_TOKEN, CORE_QUEUE_TOKEN, CORE_TENANT_RESOLVER_TOKEN, CORE_THROTTLE_QUOTA_POLICY_TOKEN, CORE_TOKEN_SERVICE_TOKEN, isAbilityChecker, isAuthUserDirectory, resolveAbilityChecker, resolveAuthUserDirectory, };

package/dist/core/database/baseRepository.d.ts

@@ -73,7 +73,6 @@ declare class BaseRepository<TEntity extends object, PrimaryKey extends keyof TE
     loadHasManyForParents<TParent extends object, LocalKey extends keyof TParent & string, ForeignKey extends keyof TEntity & string>(parents: readonly TParent[], relation: HasManyRelation<TParent, TEntity, LocalKey, ForeignKey>, options?: Omit<QueryOptions<TEntity>, "where">): Promise<Map<TParent[LocalKey], TEntity[]>>;
     findHasManyThrough<TParent extends object, LocalKey extends keyof TParent & string, FirstKey extends string, SecondLocalKey extends string, SecondKey extends keyof TEntity & string>(parentId: unknown, relation: HasManyThroughRelation<TParent, TEntity, LocalKey, FirstKey, SecondLocalKey, SecondKey>, options?: QueryOptions<TEntity>): Promise<TEntity[]>;
     loadHasManyThroughForParents<TParent extends object, LocalKey extends keyof TParent & string, FirstKey extends string, SecondLocalKey extends string, SecondKey extends keyof TEntity & string>(parents: readonly TParent[], relation: HasManyThroughRelation<TParent, TEntity, LocalKey, FirstKey, SecondLocalKey, SecondKey>, options?: QueryOptions<TEntity>): Promise<Map<TParent[LocalKey], TEntity[]>>;
-    private throughSoftDeleteClause;
     private buildThroughWhere;
     loadBelongsToForParents<TChild extends object, TParent extends object, ForeignKey extends keyof TChild & string, OwnerKey extends keyof TParent & string>(children: readonly TChild[], relation: BelongsToRelation<TChild, TParent, ForeignKey, OwnerKey>, parentRepository: BaseRepository<TParent, OwnerKey>, options?: Omit<QueryOptions<TParent>, "where">): Promise<Map<TChild[ForeignKey], TParent>>;
     loadMorphManyForParents<TParent extends object, LocalKey extends keyof TParent & string, MorphTypeKey extends keyof TEntity & string, MorphIdKey extends keyof TEntity & string>(parents: readonly TParent[], relation: MorphManyRelation<TParent, TEntity, LocalKey, MorphTypeKey, MorphIdKey>, options?: Omit<QueryOptions<TEntity>, "where">): Promise<Map<TParent[LocalKey], TEntity[]>>;

package/dist/core/database/index.d.ts

@@ -9,7 +9,7 @@ export { mapDatabaseError, withDatabaseErrorHandling } from "./errors.ts";
 export { Factory } from "./factory.ts";
 export { foreignKeyFromTable, pivotTableName, singularize } from "./inflection.ts";
 export type { CastType, GlobalScopeFn, ModelConstructor } from "./model.ts";
-export { applyCasts, BelongsToManyRelationQuery, BelongsToRelationQuery, dehydrateValue, filterMassAssignable, HasManyRelationQuery, HasManyThroughRelationQuery, HasOneRelationQuery, hydrateValue, Model, ModelQuery, MorphManyRelationQuery, MorphOneRelationQuery, MorphToRelationQuery, registerModelClass, registerModelRepository, } from "./model.ts";
+export { applyCasts, BelongsToManyRelationQuery, BelongsToRelationQuery, bootModels, defineModel, dehydrateValue, filterMassAssignable, HasManyRelationQuery, HasManyThroughRelationQuery, HasOneRelationQuery, hydrateValue, Model, ModelQuery, MorphManyRelationQuery, MorphOneRelationQuery, MorphToRelationQuery, registerModelClass, registerModelRepository, } from "./model.ts";
 export type { MysqlConnection, MysqlExecutable, MysqlPool } from "./mysqlConnection.ts";
 export { createMysqlConnection, createMysqlConnectionFromPool, createMysqlPool, } from "./mysqlConnection.ts";
 export type { NamedConnectionEntry } from "./namedConnections.ts";

package/dist/core/database/model.d.ts

@@ -1,9 +1,10 @@
-import type BaseRepository from "./baseRepository.ts";
+import BaseRepository from "./baseRepository.ts";
 import type { AnyRelationQuery, RelatedModelClass } from "./relationQuery.ts";
 import { BelongsToManyRelationQuery, BelongsToRelationQuery, HasManyRelationQuery, HasManyThroughRelationQuery, HasOneRelationQuery, MorphManyRelationQuery, MorphOneRelationQuery, MorphToRelationQuery } from "./relationQuery.ts";
 import type { BelongsToManyRelation, BelongsToRelation, HasManyRelation, HasOneRelation } from "./relationships.ts";
 import type { RepositoryQuery } from "./repositoryQuery.ts";
-import type { QueryOptions, QueryWhere } from "./types.ts";
+import type { TableDefinition } from "./table.ts";
+import type { ModelWhere, ModelWriteValues, QueryOptions, QueryWhere } from "./types.ts";
 type CastType = "date" | "datetime" | "json" | "bool" | "boolean" | "integer" | "int" | "hashed";
 type LoadedAttributes = Record<string, unknown>;
 type ModelCasts = Partial<Record<string, CastType>>;
@@ -16,6 +17,9 @@ type AnyModel = Model<Record<string, unknown>, "id">;
 type ModelAttributes<TModel> = TModel extends {
     toObject(): infer TRecord extends object;
 } ? TRecord : Record<string, unknown>;
+type ModelIdentifier<TModel> = TModel extends {
+    readonly id: infer TKey;
+} ? TKey : unknown;
 type WithModelCount<TModel, TCount extends string> = {
     toObject(): Omit<ModelAttributes<TModel>, TCount> & Record<TCount, unknown>;
     get<K extends keyof (Omit<ModelAttributes<TModel>, TCount> & Record<TCount, unknown>)>(key: K): (Omit<ModelAttributes<TModel>, TCount> & Record<TCount, unknown>)[K];
@@ -34,6 +38,10 @@ type ModelObserver = {
     deleting?: (model: AnyModel) => unknown;
     deleted?: (model: AnyModel) => unknown;
 };
+/** Typed model base with a lazily created framework repository and active connection. */
+declare function defineModel<TEntity extends object, PrimaryKey extends keyof TEntity & string>(table: TableDefinition<TEntity, PrimaryKey>): typeof Model<TEntity, PrimaryKey>;
+/** Register all relationship names before initializing any model's boot hooks. */
+declare function bootModels(models: readonly object[]): void;
 /** Alias for `hasMany("Name")` when `Name` is not `constructor.name` or `$morphClass`. */
 declare function registerModelClass(name: string, model: object): void;
 declare function hydrateValue(value: unknown, cast: CastType): unknown;
@@ -44,21 +52,31 @@ declare function filterMassAssignable(fillable: readonly string[] | undefined, g
 declare function applyCasts(values: LoadedAttributes, casts: ModelCasts, direction: "hydrate"): LoadedAttributes;
 declare function applyCasts(values: LoadedAttributes, casts: ModelCasts, direction: "dehydrate"): Promise<LoadedAttributes>;
 declare function applyCasts(values: LoadedAttributes, casts: ModelCasts, direction: "hydrate" | "dehydrate"): LoadedAttributes | Promise<LoadedAttributes>;
+/** Read-only plain records; partial selection never acquires model mutation methods. */
+declare class ModelProjection<TEntity extends object, K extends keyof TEntity & string> {
+    private readonly load;
+    constructor(load: (limit?: number) => Promise<Array<Pick<TEntity, K>>>);
+    get(): Promise<Array<Pick<TEntity, K>>>;
+    first(): Promise<Pick<TEntity, K> | null>;
+}
 declare class ModelQuery<TModel extends object = AnyModel, TCounts extends string = never> {
     private readonly modelClass;
     readonly query: RepositoryQuery<Record<string, unknown>, "id">;
     private readonly eager;
     constructor(modelClass: object, query: RepositoryQuery<Record<string, unknown>, "id">);
     with(...relations: RelationNameInput[]): this;
-    where(input: QueryWhere<object> | ((builder: import("./whereBuilder.ts").WhereBuilder<object>) => void)): this;
-    orWhere(input: QueryWhere<object> | ((builder: import("./whereBuilder.ts").WhereBuilder<object>) => void)): this;
-    orderBy(orderBy: QueryOptions<object>["orderBy"]): this;
+    where(input: ModelWhere<ModelAttributes<TModel>> | ((builder: import("./whereBuilder.ts").WhereBuilder<ModelAttributes<TModel>, ModelWhere<ModelAttributes<TModel>>>) => void)): this;
+    orWhere(input: ModelWhere<ModelAttributes<TModel>> | ((builder: import("./whereBuilder.ts").WhereBuilder<ModelAttributes<TModel>, ModelWhere<ModelAttributes<TModel>>>) => void)): this;
+    /** Qualified/dynamic filters retain existing SQL semantics through an explicit escape hatch. */
+    whereDynamic(input: QueryWhere<object>): this;
+    select<K extends keyof ModelAttributes<TModel> & string>(...columns: readonly K[]): ModelProjection<ModelAttributes<TModel>, K>;
+    orderBy(orderBy: QueryOptions<ModelAttributes<TModel>>["orderBy"]): this;
     limit(limit: number): this;
     offset(offset: number): this;
-    whereNull(column: string): this;
-    whereNotNull(column: string): this;
-    whereIn(column: string, values: readonly unknown[]): this;
-    whereNotIn(column: string, values: readonly unknown[]): this;
+    whereNull(column: keyof ModelAttributes<TModel> & string): this;
+    whereNotNull(column: keyof ModelAttributes<TModel> & string): this;
+    whereIn<K extends keyof ModelAttributes<TModel> & string>(column: K, values: readonly ModelAttributes<TModel>[K][]): this;
+    whereNotIn<K extends keyof ModelAttributes<TModel> & string>(column: K, values: readonly ModelAttributes<TModel>[K][]): this;
     groupBy(groupBy: QueryOptions<object>["groupBy"]): this;
     having(having: QueryWhere<object>): this;
     join(left: `${string}.${string}`, right: `${string}.${string}`): this;
@@ -92,8 +110,8 @@ declare class ModelQuery<TModel extends object = AnyModel, TCounts extends strin
     pluck(column: string): Promise<unknown[]>;
     pluck(column: string, keyBy: string): Promise<Map<unknown, unknown>>;
     value(column: string): Promise<unknown>;
-    find(id: unknown): Promise<ModelQueryResult<TModel, TCounts> | null>;
-    findOrFail(id: unknown, errorFactory?: (id: unknown) => Error): Promise<ModelQueryResult<TModel, TCounts>>;
+    find(id: ModelIdentifier<TModel>): Promise<ModelQueryResult<TModel, TCounts> | null>;
+    findOrFail(id: ModelIdentifier<TModel>, errorFactory?: (id: unknown) => Error): Promise<ModelQueryResult<TModel, TCounts>>;
     then(onfulfilled?: ((value: ModelQueryResult<TModel, TCounts>[]) => unknown) | null, onrejected?: ((reason: unknown) => unknown) | null): Promise<unknown>;
     withCount<TName extends string, TAlias extends string = `${TName}_count`>(name: TName, alias?: TAlias): ModelQuery<TModel, TCounts | TAlias>;
     private constrainExists;
@@ -110,11 +128,13 @@ declare class Model<TEntity extends object, PrimaryKey extends keyof TEntity & s
     static $appends?: readonly string[];
     static $morphClass?: string;
     private _exists;
+    private originalAttributes;
     private readonly loadedRelations;
     private hiddenOverrides;
     private visibleOverrides;
     private appended;
     constructor(attributes: TEntity, repository: BaseRepository<TEntity, PrimaryKey>, exists?: boolean);
+    private acceptPersistedAttributes;
     getRepository(): BaseRepository<TEntity, PrimaryKey>;
     get $exists(): boolean;
     get<K extends keyof TEntity>(key: K): TEntity[K];
@@ -134,15 +154,24 @@ declare class Model<TEntity extends object, PrimaryKey extends keyof TEntity & s
     static observe(this: object, observer: ModelObserver): void;
     static addGlobalScope<TEntity extends object, PrimaryKey extends keyof TEntity & string>(this: object, _name: string, scope: GlobalScopeFn<TEntity, PrimaryKey>): void;
     static repository<TEntity extends object, PrimaryKey extends keyof TEntity & string>(this: object): BaseRepository<TEntity, PrimaryKey>;
+    /** Apply this model's global filters to a query with an explicitly selected connection. */
+    static scopeQuery<TEntity extends object, PrimaryKey extends keyof TEntity & string>(this: object, query: RepositoryQuery<TEntity, PrimaryKey>): RepositoryQuery<TEntity, PrimaryKey>;
     static query<TModel extends object>(this: {
         prototype: TModel;
     }): ModelQuery<TModel>;
     static newFromRecord<TModel extends object>(this: {
         prototype: TModel;
+    }, record: NoInfer<ModelWriteValues<ModelAttributes<TModel>>>, exists: false): TModel;
+    static newFromRecord<TModel extends object>(this: {
+        prototype: TModel;
+    }, record: NoInfer<ModelAttributes<TModel>>, exists?: boolean): TModel;
+    /** Trusted SQL/driver/partial-record hydration. Callers own shape and completeness. */
+    static newFromTrustedRecord<TModel extends object>(this: {
+        prototype: TModel;
     }, record: object, exists?: boolean): TModel;
     static create<TModel extends object>(this: {
         prototype: TModel;
-    }, attributes: Record<string, unknown>, forced?: Record<string, unknown>): Promise<TModel>;
+    }, attributes: NoInfer<ModelWriteValues<ModelAttributes<TModel>>>, forced?: NoInfer<ModelWriteValues<ModelAttributes<TModel>>>): Promise<TModel>;
     static with<TModel extends object>(this: {
         prototype: TModel;
     }, ...relations: RelationNameInput[]): ModelQuery<TModel>;
@@ -183,32 +212,32 @@ declare class Model<TEntity extends object, PrimaryKey extends keyof TEntity & s
     }, name: string, constrain?: (query: AnyRelationQuery) => void): ModelQuery<TModel>;
     static find<TModel extends object>(this: {
         prototype: TModel;
-    }, id: unknown): Promise<TModel | null>;
+    }, id: NoInfer<ModelIdentifier<TModel>>): Promise<TModel | null>;
     static findOrFail<TModel extends object>(this: {
         prototype: TModel;
-    }, id: unknown, errorFactory?: (id: unknown) => Error): Promise<TModel>;
+    }, id: NoInfer<ModelIdentifier<TModel>>, errorFactory?: (id: unknown) => Error): Promise<TModel>;
     static all<TModel extends object>(this: {
         prototype: TModel;
-    }, options?: Omit<QueryOptions<object>, "where">): Promise<TModel[]>;
+    }, options?: Omit<QueryOptions<ModelAttributes<TModel>>, "where" | "select">): Promise<TModel[]>;
     static where<TModel extends object>(this: {
         prototype: TModel;
-    }, where: QueryWhere<object>): ModelQuery<TModel>;
+    }, where: NoInfer<ModelWhere<ModelAttributes<TModel>>>): ModelQuery<TModel>;
     static count(this: object): Promise<number>;
     static pluck(this: object, column: string): Promise<unknown[]>;
     static pluck(this: object, column: string, keyBy: string): Promise<Map<unknown, unknown>>;
     static value(this: object, column: string): Promise<unknown>;
     static firstWhere<TModel extends object>(this: {
         prototype: TModel;
-    }, where: QueryWhere<object>, options?: Omit<QueryOptions<object>, "where">): Promise<TModel | null>;
+    }, where: NoInfer<ModelWhere<ModelAttributes<TModel>>>, options?: Omit<QueryOptions<ModelAttributes<TModel>>, "where" | "select">): Promise<TModel | null>;
     static firstOrNew<TModel extends object>(this: {
         prototype: TModel;
-    }, where: QueryWhere<object>, values?: Record<string, unknown>): Promise<TModel>;
+    }, where: NoInfer<ModelWhere<ModelAttributes<TModel>>>, values?: NoInfer<ModelWriteValues<ModelAttributes<TModel>>>): Promise<TModel>;
     static firstOrCreate<TModel extends object>(this: {
         prototype: TModel;
-    }, where: QueryWhere<object>, values?: Record<string, unknown>): Promise<TModel>;
+    }, where: NoInfer<ModelWhere<ModelAttributes<TModel>>>, values?: NoInfer<ModelWriteValues<ModelAttributes<TModel>>>): Promise<TModel>;
     static updateOrCreate<TModel extends object>(this: {
         prototype: TModel;
-    }, where: QueryWhere<object>, values?: Record<string, unknown>): Promise<TModel>;
+    }, where: NoInfer<ModelWhere<ModelAttributes<TModel>>>, values?: NoInfer<ModelWriteValues<ModelAttributes<TModel>>>): Promise<TModel>;
     save(): Promise<this>;
     update(changes: Partial<TEntity>): Promise<this>;
     delete(): Promise<boolean>;
@@ -234,5 +263,5 @@ declare class Model<TEntity extends object, PrimaryKey extends keyof TEntity & s
 /** Binds a Model class to its table/connection and names it for `hasMany("User")`. */
 declare function registerModelRepository<TModelClass>(model: TModelClass, repository: object): TModelClass;
 export { BelongsToManyRelationQuery, BelongsToRelationQuery, HasManyRelationQuery, HasManyThroughRelationQuery, HasOneRelationQuery, MorphManyRelationQuery, MorphOneRelationQuery, MorphToRelationQuery, } from "./relationQuery.ts";
-export type { CastType, GlobalScopeFn, ModelClassType, ModelConstructor };
-export { applyCasts, dehydrateValue, filterMassAssignable, hydrateValue, Model, ModelQuery, registerModelClass, registerModelRepository, };
+export type { CastType, GlobalScopeFn, ModelAttributes, ModelClassType, ModelConstructor, ModelProjection, };
+export { applyCasts, bootModels, defineModel, dehydrateValue, filterMassAssignable, hydrateValue, Model, ModelQuery, registerModelClass, registerModelRepository, };

package/dist/core/database/repositoryQuery.d.ts

@@ -10,8 +10,11 @@ declare class RepositoryQuery<TEntity extends object, PrimaryKey extends keyof T
     private queryOptions;
     private readonly eagerLoads;
     private readonly whereNodes;
+    private readonly protectedWhere;
     constructor(repository: BaseRepository<TEntity, PrimaryKey>, whereClause?: QueryWhere<TEntity>, queryOptions?: Omit<QueryOptions<TEntity>, "where">);
     where(input: QueryWhere<TEntity> | ((builder: WhereBuilder<TEntity>) => void)): this;
+    /** Preserve completed scope predicates separately from subsequent caller OR conditions. */
+    protectWhere(): this;
     orWhere(input: QueryWhere<TEntity> | ((builder: WhereBuilder<TEntity>) => void)): this;
     orderBy(orderBy: QueryOptions<TEntity>["orderBy"]): this;
     limit(limit: number): this;
@@ -31,7 +34,7 @@ declare class RepositoryQuery<TEntity extends object, PrimaryKey extends keyof T
     withBelongsTo<TParent extends object, ForeignKey extends keyof TEntity & string, OwnerKey extends keyof TParent & string, Alias extends string>(as: Alias, relation: BelongsToRelation<TEntity, TParent, ForeignKey, OwnerKey>, parentRepository: BaseRepository<TParent, OwnerKey>, options?: Omit<QueryOptions<TParent>, "where">): this;
     withMorphMany<TChild extends object, LocalKey extends keyof TEntity & string, MorphTypeKey extends keyof TChild & string, MorphIdKey extends keyof TChild & string, Alias extends string>(as: Alias, relation: MorphManyRelation<TEntity, TChild, LocalKey, MorphTypeKey, MorphIdKey>, childRepository: BaseRepository<TChild, keyof TChild & string>, options?: Omit<QueryOptions<TChild>, "where">): this;
     withMorphOne<TChild extends object, LocalKey extends keyof TEntity & string, MorphTypeKey extends keyof TChild & string, MorphIdKey extends keyof TChild & string, Alias extends string>(as: Alias, relation: MorphOneRelation<TEntity, TChild, LocalKey, MorphTypeKey, MorphIdKey>, childRepository: BaseRepository<TChild, keyof TChild & string>, options?: Omit<QueryOptions<TChild>, "where">): this;
-    withMorphTo<TParent extends object, MorphTypeKey extends keyof TEntity & string, MorphIdKey extends keyof TEntity & string, Alias extends string>(as: Alias, relation: MorphToRelation<TEntity, MorphTypeKey, MorphIdKey>, repositoriesByType: ReadonlyMap<string, BaseRepository<TParent, keyof TParent & string>>, options?: Omit<QueryOptions<TParent>, "where">): this;
+    withMorphTo<TParent extends object, MorphTypeKey extends keyof TEntity & string, MorphIdKey extends keyof TEntity & string, Alias extends string>(as: Alias, relation: MorphToRelation<TEntity, MorphTypeKey, MorphIdKey>, repositoriesByType: ReadonlyMap<string, BaseRepository<TParent, keyof TParent & string>>, options?: Omit<QueryOptions<TParent>, "where">, optionsByType?: ReadonlyMap<string, QueryOptions<TParent>>): this;
     withBelongsToMany<TRelated extends object, Pivot extends object, ParentKey extends keyof TEntity & string, RelatedKey extends keyof TRelated & string, ForeignPivotKey extends keyof Pivot & string, RelatedPivotKey extends keyof Pivot & string, Alias extends string>(as: Alias, relation: BelongsToManyRelation<TEntity, TRelated, Pivot, ParentKey, RelatedKey, ForeignPivotKey, RelatedPivotKey>, relatedRepository: BaseRepository<TRelated, RelatedKey>, options?: Omit<QueryOptions<TRelated>, "where">): this;
     withHasManyThrough<TFar extends object, LocalKey extends keyof TEntity & string, SecondKey extends keyof TFar & string, Alias extends string>(as: Alias, relation: HasManyThroughRelation<TEntity, TFar, LocalKey, string, string, SecondKey>, farRepository: BaseRepository<TFar, keyof TFar & string>, options?: Omit<QueryOptions<TFar>, "where">): this;
     withTrashed(): this;
@@ -42,11 +45,23 @@ declare class RepositoryQuery<TEntity extends object, PrimaryKey extends keyof T
     pluck<K extends keyof TEntity & string>(column: K): Promise<Array<TEntity[K]>>;
     pluck<K extends keyof TEntity & string, KK extends keyof TEntity & string>(column: K, keyBy: KK): Promise<Map<TEntity[KK], TEntity[K]>>;
     value<K extends keyof TEntity & string>(column: K): Promise<TEntity[K] | null>;
+    /** Plain selected records, never complete entities or hydrated models. */
+    project<K extends keyof TEntity & string>(columns: readonly K[], limit?: number): Promise<Array<Pick<TEntity, K>>>;
     attachToRows(rows: readonly TEntity[]): Promise<Array<TEntity & LoadedRow>>;
     paginate(options: {
         page: number;
         perPage: number;
     }): Promise<PaginatedResult<TEntity>>;
+    chunk(count: number, callback: (rows: Array<TEntity & LoadedRow>) => Promise<boolean | void>): Promise<void>;
+    cursorPaginate(options: {
+        perPage: number;
+        cursor?: TEntity[PrimaryKey];
+    }): Promise<{
+        meta: import("../pagination/index.ts").CursorPaginationMeta<TEntity[PrimaryKey]>;
+        data: (TEntity & LoadedRow)[];
+    }>;
+    /** Compiled query filters for batched relationship loaders. */
+    getOptions(): QueryOptions<TEntity>;
     private buildOptions;
     private addJoin;
     private attach;

package/dist/core/database/types.d.ts

@@ -1,3 +1,4 @@
+import type { WhereNode } from "./whereBuilder.ts";
 type DatabaseComparable = string | number | Date;
 type DatabaseScalar = DatabaseComparable | boolean | null;
 type QueryOperator = {
@@ -15,6 +16,27 @@ type QueryOperator = {
 };
 type QueryFilterValue = DatabaseScalar | readonly DatabaseScalar[] | QueryOperator;
 type QueryWhere<TEntity> = Partial<Record<keyof TEntity & string, QueryFilterValue>> & Partial<Record<string, QueryFilterValue>>;
+/** Ordinary model filters constrain keys and operators to their declared scalar values. */
+type ModelFilterScalar<T> = unknown extends T ? DatabaseScalar : Extract<T, DatabaseScalar>;
+type ModelFilterOperator<T> = {
+    eq?: ModelFilterScalar<T>;
+    ne?: ModelFilterScalar<T>;
+    in?: readonly ModelFilterScalar<T>[];
+    notIn?: readonly ModelFilterScalar<T>[];
+    gt?: Extract<ModelFilterScalar<T>, DatabaseComparable>;
+    gte?: Extract<ModelFilterScalar<T>, DatabaseComparable>;
+    lt?: Extract<ModelFilterScalar<T>, DatabaseComparable>;
+    lte?: Extract<ModelFilterScalar<T>, DatabaseComparable>;
+    isNull?: boolean;
+} & (Extract<T, string> extends never ? unknown : {
+    ilike?: string;
+    tsMatch?: string;
+});
+type ModelWhere<TEntity> = string extends keyof TEntity ? QueryWhere<TEntity> : {
+    [K in keyof TEntity & string]?: ModelFilterScalar<TEntity[K]> | readonly ModelFilterScalar<TEntity[K]>[] | ModelFilterOperator<TEntity[K]>;
+};
+/** Omission stays legal: DB defaults, generated columns and fillable/timestamp policy are runtime concerns. */
+type ModelWriteValues<TEntity> = Partial<TEntity>;
 type QueryOrder<TEntity> = {
     column: keyof TEntity & string;
     direction?: "ASC" | "DESC" | "asc" | "desc";
@@ -56,7 +78,8 @@ type QuerySelectItem = {
     query: string;
     as: string;
 };
-interface QueryOptions<TEntity> {
+interface QueryOptions<TEntity extends object> {
+    whereNodes?: WhereNode<TEntity>[];
     where?: QueryWhere<TEntity>;
     orderBy?: QueryOrder<TEntity> | QueryOrder<TEntity>[] | QueryOrderShorthand<TEntity>;
     limit?: number;
@@ -70,4 +93,4 @@ interface QueryOptions<TEntity> {
 }
 type MutationValues<TEntity> = Partial<TEntity>;
 type UpdateValues<TEntity, PrimaryKey extends keyof TEntity & string = keyof TEntity & string> = Partial<Omit<TEntity, PrimaryKey>>;
-export type { DatabaseComparable, DatabaseScalar, MutationValues, QueryFilterValue, QueryJoin, QueryJoinOn, QueryOperator, QueryOptions, QueryOrder, QuerySelectItem, QueryWhere, UpdateValues, };
+export type { DatabaseComparable, DatabaseScalar, ModelWhere, ModelWriteValues, MutationValues, QueryFilterValue, QueryJoin, QueryJoinOn, QueryOperator, QueryOptions, QueryOrder, QuerySelectItem, QueryWhere, UpdateValues, };

package/dist/core/database/whereBuilder.d.ts

@@ -14,12 +14,12 @@ type WhereNode<TEntity extends object> = {
     kind: "and" | "or";
     exists: ExistsClause;
 };
-declare class WhereBuilder<TEntity extends object> {
+declare class WhereBuilder<TEntity extends object, TWhere extends object = QueryWhere<TEntity>> {
     readonly nodes: WhereNode<TEntity>[];
-    where(where: QueryWhere<TEntity>): this;
-    orWhere(where: QueryWhere<TEntity>): this;
-    whereGroup(fn: (builder: WhereBuilder<TEntity>) => void): this;
-    orWhereGroup(fn: (builder: WhereBuilder<TEntity>) => void): this;
+    where(where: TWhere): this;
+    orWhere(where: TWhere): this;
+    whereGroup(fn: (builder: WhereBuilder<TEntity, TWhere>) => void): this;
+    orWhereGroup(fn: (builder: WhereBuilder<TEntity, TWhere>) => void): this;
 }
 export type { ExistsClause, WhereNode };
 export { WhereBuilder };

package/dist/core/events/deferredModelEvents.d.ts

@@ -1,3 +1,4 @@
 declare function dispatchModelEvent(event: string, payload: unknown): Promise<void>;
 declare function runWithDeferredModelEvents<T>(callback: () => T | Promise<T>): Promise<T>;
-export { dispatchModelEvent, runWithDeferredModelEvents };
+declare function onDeferredModelRollback(callback: () => void): void;
+export { dispatchModelEvent, onDeferredModelRollback, runWithDeferredModelEvents };

package/dist/core/http/loginThrottleMiddleware.d.ts

@@ -1,6 +1,7 @@
-import type { Middleware } from "./middleware";
-import { type RedisThrottleClient } from "./throttleMiddleware";
-interface LoginThrottleOptions {
+import { type MemoryThrottleStorageOptions } from "../runtime/boundedThrottleStore";
+import type { DisposableMemoryThrottle } from "./memoryThrottleMiddleware";
+import { type DisposableThrottle, type RedisThrottleClient } from "./throttleMiddleware";
+interface LoginThrottleOptions extends MemoryThrottleStorageOptions {
     redisUrl?: string;
     maxAttempts: number;
     decaySeconds: number;
@@ -10,8 +11,8 @@ interface LoginThrottleOptions {
 }
 declare function resolveLoginIdentity(request: Request): string;
 declare function resolveLoginEmail(request: Request): Promise<string>;
-declare function createMemoryLoginThrottleMiddleware(options: LoginThrottleOptions): Middleware;
-declare function createLoginThrottleMiddleware(options: LoginThrottleOptions): Middleware;
+declare function createMemoryLoginThrottleMiddleware(options: LoginThrottleOptions): DisposableMemoryThrottle;
+declare function createLoginThrottleMiddleware(options: LoginThrottleOptions): DisposableThrottle;
 declare function resetMemoryLoginThrottleForTests(): void;
 export type { LoginThrottleOptions };
 export { createLoginThrottleMiddleware, createMemoryLoginThrottleMiddleware, resetMemoryLoginThrottleForTests, resolveLoginEmail, resolveLoginIdentity, };

package/dist/core/http/memoryThrottleMiddleware.d.ts

@@ -1,10 +1,18 @@
+import { type MemoryThrottleStats, type MemoryThrottleStorageOptions } from "../runtime/boundedThrottleStore";
 import type { Middleware } from "./middleware";
-interface MemoryThrottleOptions {
+import { type ThrottleQuotaPolicy } from "./throttleMiddleware";
+interface MemoryThrottleOptions extends MemoryThrottleStorageOptions {
     maxAttempts: number;
     decaySeconds: number;
     keyPrefix?: string;
+    quotaPolicy?: ThrottleQuotaPolicy;
 }
-declare function createMemoryThrottleMiddleware(options: MemoryThrottleOptions): Middleware;
+type DisposableMemoryThrottle = Middleware & {
+    dispose(): void;
+    stats(): MemoryThrottleStats;
+};
+declare function createMemoryThrottleMiddleware(options: MemoryThrottleOptions): DisposableMemoryThrottle;
+/** Lazy generation reset avoids retaining middleware instances in a global test registry. */
 declare function resetMemoryThrottleForTests(): void;
-export type { MemoryThrottleOptions };
+export type { DisposableMemoryThrottle, MemoryThrottleOptions, MemoryThrottleStats, MemoryThrottleStorageOptions, };
 export { createMemoryThrottleMiddleware, resetMemoryThrottleForTests };

package/dist/core/http/requestMetaContext.d.ts

@@ -1,5 +1,7 @@
 type RequestMeta = {
     ipAddress: string | null;
+    /** Immediate socket peer recorded by the transport; never a forwarded client header. */
+    peerAddress?: string | null;
     userAgent: string | null;
     request?: Request;
     /** Registered route template; never a URL supplied by the client. */

package/dist/core/http/scimThrottleMiddleware.d.ts

@@ -1,9 +1,18 @@
+import { type MemoryThrottleStorageOptions } from "../runtime/boundedThrottleStore";
 import type { Middleware } from "./middleware";
-interface ScimThrottleOptions {
+import { type RedisThrottleClient } from "./throttleMiddleware";
+interface ScimThrottleOptions extends MemoryThrottleStorageOptions {
     redisUrl?: string;
     maxAttempts: number;
     decaySeconds: number;
+    commandTimeoutMs?: number;
+    redisClient?: RedisThrottleClient;
+    keyPrefix?: string;
 }
-declare function createScimThrottleMiddleware(options: ScimThrottleOptions): Middleware;
+declare function resolveScimIdentity(request: Request): string;
+declare function createScimThrottleMiddleware(options: ScimThrottleOptions): Middleware & {
+    dispose: () => void;
+    stats: () => import("./memoryThrottleMiddleware").MemoryThrottleStats | undefined;
+};
 export type { ScimThrottleOptions };
-export { createScimThrottleMiddleware };
+export { createScimThrottleMiddleware, resolveScimIdentity };