@getstrata/core 2.0.9 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @getstrata/core changelog
 
+## 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
+
 ## 2.0.9
 
 - fix(starter): remove demo credentials from public login defaults

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/container.d.ts

@@ -1,19 +1,37 @@
+declare const serviceTokenType: unique symbol;
+/** Invariant service identity; its runtime value remains the existing string key. */
+type ServiceToken<T> = string & {
+    readonly [serviceTokenType]: (value: T) => T;
+};
+/** Prevent a typed token from falling back to an unchecked legacy overload. */
+type LegacyServiceKey = string & {
+    readonly [serviceTokenType]?: never;
+};
+declare function createServiceToken<T>(key: string): ServiceToken<T>;
 type ServiceFactory<T> = (container: ServiceContainer) => T;
 interface ServiceContainerLike {
     has(key: string): boolean;
-    resolve<T>(key: string): T;
+    resolve<T>(key: ServiceToken<T>): T;
+    resolve<T>(key: LegacyServiceKey): T;
 }
 declare class ServiceContainer implements ServiceContainerLike {
     private readonly services;
     private readonly singletonFactories;
     private readonly bindings;
-    set<T>(key: string, value: T): T;
-    singleton<T>(key: string, factory: ServiceFactory<T>): void;
-    bind<T>(key: string, factory: ServiceFactory<T>): void;
-    get<T>(key: string): T;
-    resolve<T>(key: string): T;
-    make<T>(key: string): T;
-    instance<T>(key: string, value: T): T;
+    set<T>(key: ServiceToken<T>, value: NoInfer<T>): T;
+    set<T>(key: LegacyServiceKey, value: T): T;
+    singleton<T>(key: ServiceToken<T>, factory: ServiceFactory<NoInfer<T>>): void;
+    singleton<T>(key: LegacyServiceKey, factory: ServiceFactory<T>): void;
+    bind<T>(key: ServiceToken<T>, factory: ServiceFactory<NoInfer<T>>): void;
+    bind<T>(key: LegacyServiceKey, factory: ServiceFactory<T>): void;
+    get<T>(key: ServiceToken<T>): T;
+    get<T>(key: LegacyServiceKey): T;
+    resolve<T>(key: ServiceToken<T>): T;
+    resolve<T>(key: LegacyServiceKey): T;
+    make<T>(key: ServiceToken<T>): T;
+    make<T>(key: LegacyServiceKey): T;
+    instance<T>(key: ServiceToken<T>, value: NoInfer<T>): T;
+    instance<T>(key: LegacyServiceKey, value: T): T;
     has(key: string): boolean;
 }
 interface ConfigStoreLike {
@@ -28,5 +46,5 @@ declare class ConfigStore implements ConfigStoreLike {
     require<T>(key: string): T;
     has(key: string): boolean;
 }
-export type { ConfigStoreLike, ServiceContainerLike, ServiceFactory };
-export { ConfigStore, ServiceContainer };
+export type { ConfigStoreLike, LegacyServiceKey, ServiceContainerLike, ServiceFactory, ServiceToken, };
+export { ConfigStore, createServiceToken, ServiceContainer };

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

@@ -1,6 +1,6 @@
 import type { CacheLike } from "../../types/services";
 import type { StorageManager } from "../storage/storage";
-import type { ConfigStore, ConfigStoreLike, ServiceContainer, ServiceFactory } from "./container";
+import type { ConfigStore, ConfigStoreLike, LegacyServiceKey, ServiceContainer, ServiceFactory, ServiceToken } from "./container";
 type AppRouteMap = Record<string, any>;
 type CachedJson = <T>(cacheKey: string, loader: () => Promise<T>, tags?: string[], request?: Request) => Promise<Response>;
 interface AppDependencies {
@@ -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;
@@ -26,6 +28,7 @@ interface AppContext {
 }
 declare function getRequiredDependency<K extends keyof AppDependencies>(dependencies: Partial<AppDependencies>, key: K): AppDependencies[K];
 declare function assertAppDependenciesComplete(dependencies: MutableAppDependencies): asserts dependencies is AppDependencies;
-declare function resolveService<T>(dependencies: AppDependencies, token: string): T;
+declare function resolveService<T>(dependencies: AppDependencies, token: ServiceToken<T>): T;
+declare function resolveService<T>(dependencies: AppDependencies, token: LegacyServiceKey): T;
 export type { AppContext, AppDependencies, AppRouteMap, CachedJson, MutableAppDependencies, ProviderContext, ServiceFactory, ServiceProvider, };
 export { assertAppDependenciesComplete, getRequiredDependency, resolveService };

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

@@ -1,6 +1,11 @@
 import type { AbilityChecker } from "../auth/abilityChecker";
+import type { ThrottleQuotaPolicy } from "../http/throttleMiddleware";
+import type { 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_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 +19,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_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>>;
@@ -13,6 +14,17 @@ interface ModelConstructor<TEntity extends object, PrimaryKey extends keyof TEnt
     new (attributes: TEntity, repository: BaseRepository<TEntity, PrimaryKey>, exists?: boolean): TModel;
 }
 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];
+} & TModel;
+type ModelQueryResult<TModel, TCounts extends string> = [TCounts] extends [never] ? TModel : WithModelCount<TModel, TCounts>;
 type RelatedRef<TRelated extends object, RelatedKey extends keyof TRelated & string> = RelatedModelClass<TRelated, RelatedKey> | string | (() => RelatedModelClass<TRelated, RelatedKey>);
 type RelationNameInput = string | readonly string[];
 type ModelObserver = {
@@ -26,27 +38,45 @@ 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;
+declare function dehydrateValue(value: unknown, cast: "hashed"): Promise<unknown>;
+declare function dehydrateValue(value: unknown, cast: Exclude<CastType, "hashed">): unknown;
 declare function dehydrateValue(value: unknown, cast: CastType): unknown;
 declare function filterMassAssignable(fillable: readonly string[] | undefined, guarded: readonly string[] | true | undefined, input: LoadedAttributes): LoadedAttributes;
-declare function applyCasts(values: LoadedAttributes, casts: ModelCasts, direction: "hydrate" | "dehydrate"): LoadedAttributes;
-declare class ModelQuery {
+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;
@@ -55,7 +85,7 @@ declare class ModelQuery {
         page: number;
         perPage: number;
     }): Promise<{
-        data: Array<Model<Record<string, unknown>, "id">>;
+        data: ModelQueryResult<TModel, TCounts>[];
         meta: Awaited<ReturnType<RepositoryQuery<Record<string, unknown>, "id">["paginate"]>>["meta"];
     }>;
     whereExists(sql: string, params?: readonly unknown[]): this;
@@ -73,17 +103,17 @@ declare class ModelQuery {
     withHasManyThrough(...args: Parameters<RepositoryQuery<Record<string, unknown>, "id">["withHasManyThrough"]>): this;
     withTrashed(): this;
     onlyTrashed(): this;
-    get(): Promise<Array<Model<Record<string, unknown>, "id">>>;
+    get(): Promise<ModelQueryResult<TModel, TCounts>[]>;
     private hydrateRows;
-    first(): Promise<Model<Record<string, unknown>, "id"> | null>;
+    first(): Promise<ModelQueryResult<TModel, TCounts> | null>;
     count(): Promise<number>;
     pluck(column: string): Promise<unknown[]>;
     pluck(column: string, keyBy: string): Promise<Map<unknown, unknown>>;
     value(column: string): Promise<unknown>;
-    find(id: unknown): Promise<Model<Record<string, unknown>, "id"> | null>;
-    findOrFail(id: unknown, errorFactory?: (id: unknown) => Error): Promise<Model<Record<string, unknown>, "id">>;
-    then(onfulfilled?: ((value: Array<Model<Record<string, unknown>, "id">>) => unknown) | null, onrejected?: ((reason: unknown) => unknown) | null): Promise<unknown>;
-    withCount(name: string, alias?: string): this;
+    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;
 }
 declare class Model<TEntity extends object, PrimaryKey extends keyof TEntity & string> {
@@ -98,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];
@@ -116,24 +148,49 @@ declare class Model<TEntity extends object, PrimaryKey extends keyof TEntity & s
     protected primaryKey(): PrimaryKey;
     protected static primaryKeyField(this: object): string;
     protected static hydrateAttributes<TEntity extends object>(this: object, attributes: TEntity): TEntity;
-    protected static dehydrateAttributes(this: object, attributes: LoadedAttributes): LoadedAttributes;
+    protected static dehydrateAttributes(this: object, attributes: LoadedAttributes): LoadedAttributes | Promise<LoadedAttributes>;
     protected static fromRecord<TEntity extends object, PrimaryKey extends keyof TEntity & string>(this: object, record: TEntity, repository: BaseRepository<TEntity, PrimaryKey>, exists?: boolean): Model<TEntity, PrimaryKey>;
     static boot(): void;
     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>;
-    static query(this: object): ModelQuery;
-    static newFromRecord(this: object, record: object, exists?: boolean): Model<Record<string, unknown>, "id">;
-    static create(this: object, attributes: Record<string, unknown>, forced?: Record<string, unknown>): Promise<Model<Record<string, unknown>, "id">>;
-    static with(this: object, ...relations: RelationNameInput[]): ModelQuery;
-    static withTrashed(this: object): ModelQuery;
-    static onlyTrashed(this: object): ModelQuery;
-    static chunk(this: object, count: number, callback: (models: Array<Model<Record<string, unknown>, "id">>) => Promise<boolean | void>): Promise<void>;
-    static cursorPaginate(this: object, options: {
+    /** 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: NoInfer<ModelWriteValues<ModelAttributes<TModel>>>, forced?: NoInfer<ModelWriteValues<ModelAttributes<TModel>>>): Promise<TModel>;
+    static with<TModel extends object>(this: {
+        prototype: TModel;
+    }, ...relations: RelationNameInput[]): ModelQuery<TModel>;
+    static withTrashed<TModel extends object>(this: {
+        prototype: TModel;
+    }): ModelQuery<TModel>;
+    static onlyTrashed<TModel extends object>(this: {
+        prototype: TModel;
+    }): ModelQuery<TModel>;
+    static chunk<TModel extends object>(this: {
+        prototype: TModel;
+    }, count: number, callback: (models: TModel[]) => Promise<boolean | void>): Promise<void>;
+    static cursorPaginate<TModel extends object>(this: {
+        prototype: TModel;
+    }, options: {
         perPage: number;
         cursor?: unknown;
     }): Promise<{
-        data: Array<Model<Record<string, unknown>, "id">>;
+        data: TModel[];
         meta: {
             per_page: number;
             next_cursor: unknown;
@@ -141,22 +198,46 @@ declare class Model<TEntity extends object, PrimaryKey extends keyof TEntity & s
             has_more: boolean;
         };
     }>;
-    static whereHas(this: object, name: string, constrain?: (query: AnyRelationQuery) => void): ModelQuery;
-    static has(this: object, name: string): ModelQuery;
-    static doesntHave(this: object, name: string): ModelQuery;
-    static whereDoesntHave(this: object, name: string, constrain?: (query: AnyRelationQuery) => void): ModelQuery;
-    static find(this: object, id: unknown): Promise<Model<Record<string, unknown>, "id"> | null>;
-    static findOrFail(this: object, id: unknown, errorFactory?: (id: unknown) => Error): Promise<Model<Record<string, unknown>, "id">>;
-    static all(this: object, options?: Omit<QueryOptions<object>, "where">): Promise<Array<Model<Record<string, unknown>, "id">>>;
-    static where(this: object, where: QueryWhere<object>): ModelQuery;
+    static whereHas<TModel extends object>(this: {
+        prototype: TModel;
+    }, name: string, constrain?: (query: AnyRelationQuery) => void): ModelQuery<TModel>;
+    static has<TModel extends object>(this: {
+        prototype: TModel;
+    }, name: string): ModelQuery<TModel>;
+    static doesntHave<TModel extends object>(this: {
+        prototype: TModel;
+    }, name: string): ModelQuery<TModel>;
+    static whereDoesntHave<TModel extends object>(this: {
+        prototype: TModel;
+    }, name: string, constrain?: (query: AnyRelationQuery) => void): ModelQuery<TModel>;
+    static find<TModel extends object>(this: {
+        prototype: TModel;
+    }, id: NoInfer<ModelIdentifier<TModel>>): Promise<TModel | null>;
+    static findOrFail<TModel extends object>(this: {
+        prototype: TModel;
+    }, id: NoInfer<ModelIdentifier<TModel>>, errorFactory?: (id: unknown) => Error): Promise<TModel>;
+    static all<TModel extends object>(this: {
+        prototype: TModel;
+    }, options?: Omit<QueryOptions<ModelAttributes<TModel>>, "where" | "select">): Promise<TModel[]>;
+    static where<TModel extends object>(this: {
+        prototype: 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(this: object, where: QueryWhere<object>, options?: Omit<QueryOptions<object>, "where">): Promise<Model<Record<string, unknown>, "id"> | null>;
-    static firstOrNew(this: object, where: QueryWhere<object>, values?: Record<string, unknown>): Promise<Model<Record<string, unknown>, "id">>;
-    static firstOrCreate(this: object, where: QueryWhere<object>, values?: Record<string, unknown>): Promise<Model<Record<string, unknown>, "id">>;
-    static updateOrCreate(this: object, where: QueryWhere<object>, values?: Record<string, unknown>): Promise<Model<Record<string, unknown>, "id">>;
+    static firstWhere<TModel extends object>(this: {
+        prototype: TModel;
+    }, where: NoInfer<ModelWhere<ModelAttributes<TModel>>>, options?: Omit<QueryOptions<ModelAttributes<TModel>>, "where" | "select">): Promise<TModel | null>;
+    static firstOrNew<TModel extends object>(this: {
+        prototype: TModel;
+    }, where: NoInfer<ModelWhere<ModelAttributes<TModel>>>, values?: NoInfer<ModelWriteValues<ModelAttributes<TModel>>>): Promise<TModel>;
+    static firstOrCreate<TModel extends object>(this: {
+        prototype: TModel;
+    }, where: NoInfer<ModelWhere<ModelAttributes<TModel>>>, values?: NoInfer<ModelWriteValues<ModelAttributes<TModel>>>): Promise<TModel>;
+    static updateOrCreate<TModel extends object>(this: {
+        prototype: 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>;
@@ -182,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;