@mayhem93/nexxus-core-lib 0.0.1 → 0.0.3

package/dist-types/common/QueuePayloads.d.ts

@@ -1,4 +1,4 @@
-import { NexxusAppModelType } from '../models/AppModel';
+import { INexxusAppModel } from '../models/AppModel';
 import { NexxusJsonPatchInternal, NexxusJsonPatchMetadata } from '../common/JsonPatch';
 export interface NexxusBaseQueuePayload {
     event: string;
@@ -6,65 +6,87 @@ export interface NexxusBaseQueuePayload {
 }
 export type NexxusModelCreatedPayload = {
     event: 'model_created';
-    data: NexxusAppModelType;
+    data: INexxusAppModel;
 };
 export type NexxusModelUpdatedPayload = {
     event: 'model_updated';
     data: Array<NexxusJsonPatchInternal>;
 };
-export type NexxusModelDeletedData = Pick<NexxusAppModelType, 'id' | 'type' | 'appId' | 'userId'>;
+export type NexxusModelDeletedData = Pick<INexxusAppModel, 'id' | 'type' | 'appId' | 'userId'>;
 export type NexxusModelDeletedPayload = {
     event: 'model_deleted';
     data: NexxusModelDeletedData;
 };
 export type NexxusWriterPayload = NexxusModelCreatedPayload | NexxusModelUpdatedPayload | NexxusModelDeletedPayload;
-export type NexxusTransportManagetJsonPatch = Omit<NexxusJsonPatchInternal, 'metadata'> & {
+export type NexxusTransportManagerJsonPatch = Omit<NexxusJsonPatchInternal, 'metadata'> & {
     metadata: NexxusJsonPatchMetadata & {
-        partialModel: Partial<NexxusAppModelType>;
+        partialModel: Partial<INexxusAppModel>;
     };
 };
 export type NexxusTransportManagerModelUpdatedPayload = {
     event: 'model_updated';
-    data: Array<NexxusTransportManagetJsonPatch>;
+    data: Array<NexxusTransportManagerJsonPatch>;
 };
 export type NexxusTransportManagerPayload = NexxusModelCreatedPayload | NexxusTransportManagerModelUpdatedPayload | NexxusModelDeletedPayload;
-export interface NexxusWebSocketJsonPatchMetadata {
-    id: string;
+/**
+ * Metadata for transport-bound model events (create/update/delete alike).
+ * Carries the channels that matched the subscription router for this device,
+ * so the client can correlate the event with its local subscription containers.
+ */
+export interface NexxusTransportMetadata {
     channels: Array<string>;
 }
 /**
- * JsonPatch type for WebSocket transport workers
+ * Payload for any transport worker - model created
+ */
+export type NexxusTransportModelCreatedPayload = {
+    event: 'model_created';
+    model: INexxusAppModel;
+    metadata: NexxusTransportMetadata;
+};
+/**
+ * Payload for any transport worker - model deleted
  */
-export type NexxusWebSocketJsonPatch = Omit<NexxusJsonPatchInternal, 'metadata'> & {
-    metadata: NexxusWebSocketJsonPatchMetadata;
+export type NexxusTransportModelDeletedPayload = {
+    event: 'model_deleted';
+    model: NexxusModelDeletedData;
+    metadata: NexxusTransportMetadata;
 };
 /**
- * Payload for WebSocket Transport - slim metadata with just channel
+ * Payload for any transport worker - model updated.
+ * All patches in a single event target the same model — its identity is hoisted
+ * into `model`, and the matched channels into top-level `metadata`. Per-patch
+ * metadata is intentionally absent (it was redundant across patches of the same
+ * update event under the previous shape).
  */
-export type NexxusWebSocketModelUpdatedPayload = {
+export type NexxusTransportModelUpdatedPayload = {
     event: 'model_updated';
-    data: Array<NexxusWebSocketJsonPatch>;
+    /**
+     * Includes `version` — the post-update version stamp assigned by the adapter.
+     * Clients use it for gap detection: apply if `model.version === local.version + 1`,
+     * request a fresh GET if there's a gap, ignore if it's already been applied.
+     */
+    model: Pick<INexxusAppModel, 'id' | 'type' | 'appId' | 'userId' | 'version'>;
+    patches: Array<Omit<NexxusJsonPatchInternal, 'metadata'>>;
+    metadata: NexxusTransportMetadata;
 };
-export type NexxusWebsocketPayload = {
+/**
+ * Canonical payload consumed by ALL transport workers (volatile and persistent alike).
+ * The shape is identical across transports; each transport translates the inner `data`
+ * into its own wire format inside its `sendToDevice` implementation.
+ */
+export type NexxusTransportWorkerPayload = {
     event: 'device_message';
     deviceIds: Array<string>;
-    data: NexxusModelCreatedPayload | NexxusWebSocketModelUpdatedPayload | NexxusModelDeletedPayload;
-};
-export type NexxusMqttPayload = {
-    event: 'mqtt_publish';
-    topic: string;
-    payload: Buffer;
-} | {
-    event: 'mqtt_subscribe';
-    topic: string;
+    data: NexxusTransportModelCreatedPayload | NexxusTransportModelUpdatedPayload | NexxusTransportModelDeletedPayload;
 };
 export interface NexxusBuiltInQueuePayloadMap {
     'writer': NexxusWriterPayload;
     'transport-manager': NexxusTransportManagerPayload;
 }
 export interface NexxusDynamicQueuePayloadMap {
-    'websockets-transport': NexxusWebsocketPayload;
-    'mqtt-transport': NexxusMqttPayload;
+    'websockets-transport': NexxusTransportWorkerPayload;
+    'mqtt-transport': NexxusTransportWorkerPayload;
 }
 export type NexxusBuiltInQueueName = keyof NexxusBuiltInQueuePayloadMap;
 export type NexxusDynamicQueueType = keyof NexxusDynamicQueuePayloadMap;

package/dist-types/common/SchemaValidator.d.ts

@@ -1,4 +1,44 @@
-import { NexxusUserDetailSchema } from "../models/User";
+import type { NexxusFieldDef, NexxusModelDef } from './ModelTypes';
+/**
+ * Pure schema-aware validation + normalization for a single value against a
+ * field definition, or for whole-model data against a model definition.
+ *
+ * Returns a normalized copy of the input value (e.g. date strings become
+ * integer timestamps). Throws InvalidSchemaDataException on the first violation.
+ *
+ * Used by:
+ *   - NexxusJsonPatch (per-path validation on patch operations)
+ *   - NexxusAppModel (whole-model validation on construction)
+ *
+ * Required-field checking is intentionally NOT performed here yet; only fields
+ * present in the input are validated.
+ */
 export declare class NexxusSchemaValidator {
-    static validateUserDetails(partialDetails: Record<string, any>, userDetailSchema: NexxusUserDetailSchema): boolean;
+    /**
+     * Validate every present field of `data` against the model definition.
+     * Returns a shallow-merged copy of `data` with each value normalized.
+     * Unknown fields (present in data but not declared in modelDef) are passed
+     * through unchanged.
+     */
+    static validateAgainstSchema(data: Record<string, unknown>, modelDef: NexxusModelDef): Record<string, unknown>;
+    /**
+     * Validate a single value against a field definition. Returns the normalized
+     * value. Throws InvalidSchemaDataException on failure.
+     *
+     * `path` is used only for error messages.
+     */
+    static validateValue(value: unknown, fieldDef: NexxusFieldDef, path: string): unknown;
+    private static validateString;
+    private static validateNumber;
+    private static validateBoolean;
+    /**
+     * Accepts: number (ms timestamp), ISO date string, or numeric string.
+     * Returns: integer ms timestamp.
+     *
+     * This is the single canonical date parser for the system; the previous
+     * inconsistency between `Date.parse()` and `new Date(s).getTime()` is gone.
+     */
+    private static validateDate;
+    private static validateObject;
+    private static validateArray;
 }

package/dist-types/index.d.ts

@@ -3,10 +3,14 @@ export * from "./lib/ConfigProvider";
 export * from "./lib/ConfigManager";
 export * from "./lib/BaseService";
 export * from "./lib/Logger";
+export * from "./lib/ServiceResolver";
 export * from "./common/QueuePayloads";
 export * from "./common/JsonPatch";
 export * from "./common/FilterQuery";
+export * from "./common/InferModel";
+export * from "./common/SchemaValidator";
 export * from "./models/BaseModel";
+export * from "./models/BuiltinModel";
 export * from './common/BuiltinSchemas';
 export * from "./models/AppModel";
 export * from "./models/Application";

package/dist-types/lib/BaseService.d.ts

@@ -1,11 +1,54 @@
 import type { ConfigEnvVars, ConfigCliArgs, AddJsonSchemaDefFuncArg, NexxusConfigManager } from './ConfigManager';
-import type { NexxusBaseLogger } from "./Logger";
+import type { NexxusBaseLogger } from './Logger';
 import { NexxusConfig } from './ConfigProvider';
 export type EventMap = Record<string | symbol, any[]>;
 export interface INexxusBaseServices {
     configManager: NexxusConfigManager;
     logger: NexxusBaseLogger<NexxusConfig>;
 }
+/**
+ * Static-only shape of a Nexxus service class. Anything ConfigManager needs to
+ * register a service's config lives here — `name` (for diagnostics), plus the
+ * three static-config accessors. Constructor visibility is intentionally
+ * absent, so classes that expose an async factory instead of a public
+ * constructor (e.g. `WinstonNexxusLogger.create(...)`) still satisfy the type.
+ *
+ * All `NexxusBaseService` subclasses satisfy this structurally. Downstream code
+ * writing custom services should type against this interface when passing
+ * classes to `ConfigManager.validateServices(...)`.
+ */
+export interface NexxusServiceClass {
+    readonly name: string;
+    schema(): AddJsonSchemaDefFuncArg;
+    envVarConfig(): ConfigEnvVars;
+    cliArgConfig(): ConfigCliArgs;
+}
+/**
+ * `NexxusServiceClass` + a public constructor. This is the default shape for
+ * pluggable adapters — DB, MQ, most anything without async init. Consumers
+ * `new Cls(services)` directly at the bootstrap site.
+ *
+ * If your adapter needs to await something before it's ready (dynamic
+ * imports, remote fetches, warm-up connections), use
+ * `NexxusFactoryServiceClass` instead — that's what `WinstonNexxusLogger`
+ * does for dynamic transports.
+ */
+export interface NexxusConstructableServiceClass extends NexxusServiceClass {
+    new (services: INexxusBaseServices): NexxusBaseService<any, any>;
+}
+/**
+ * `NexxusServiceClass` + a static async factory. For adapters whose
+ * initialization has to await something — dynamic imports, remote handshakes,
+ * schema fetches. The class typically hides its constructor (private) so
+ * consumers must go through `Cls.create(services)`.
+ *
+ * Currently used only for `WinstonNexxusLogger`. Most adapters are fine as
+ * `NexxusConstructableServiceClass`; only reach for this when async init is
+ * actually needed.
+ */
+export interface NexxusFactoryServiceClass extends NexxusServiceClass {
+    create(services: INexxusBaseServices): Promise<NexxusBaseService<any, any>>;
+}
 declare class TypedEventEmitter<E> {
     private emitter;
     constructor();
@@ -18,6 +61,13 @@ export declare abstract class NexxusBaseService<T extends NexxusConfig, Ev exten
     protected config: Readonly<T>;
     protected static envVars: ConfigEnvVars;
     protected static cliArgs: ConfigCliArgs;
+    /**
+     * The top-level key under which this service's configuration sits in the merged
+     * root config (e.g. "logger", "database", "redis", "app"). Required for every
+     * concrete service — ConfigManager uses it as the property name when grafting
+     * the service's schema definition into the root JSON Schema.
+     */
+    protected static configRootKey: string;
     protected static schemaPath: string;
     private static schemaContents;
     constructor(config: Readonly<T>);

package/dist-types/lib/ConfigManager.d.ts

@@ -1,4 +1,4 @@
-import { NexxusBaseService } from './BaseService';
+import { NexxusServiceClass } from './BaseService';
 import { CliArgType, NexxusConfig, INexxusConfigProvider } from "./ConfigProvider";
 import type { JSONSchema7Definition } from "json-schema";
 export type AddJsonSchemaDefFuncArg = {
@@ -9,35 +9,72 @@ export type AddJsonSchemaDefFuncArg = {
 };
 type EnvVarsSpec = {
     name: string;
+    /** Dot-notation path relative to the service's configRootKey (e.g. "host", "auth.jwtSecret"). */
     location: string;
 };
-export type ConfigEnvVars = {
-    source: string;
-    specs: Array<EnvVarsSpec>;
-};
+export type ConfigEnvVars = Array<EnvVarsSpec>;
 type CliArgsSpec = {
     name: string;
+    /** Dot-notation path relative to the service's configRootKey. */
     location: string;
     type: CliArgType;
 };
-export type ConfigCliArgs = {
-    source: string;
-    specs: Array<CliArgsSpec>;
-};
+export type ConfigCliArgs = Array<CliArgsSpec>;
 export declare class NexxusConfigManager {
     private static CONF_FILE_NAME;
+    private static DEFAULT_CONF_PATH;
     private jsonSchema;
     private envVarsSpecs;
     private cliArgsSpecs;
     private data;
     private configProviders;
     private customProviders;
-    constructor(confFile?: string);
+    /**
+     * Names (class.name) of services already registered. Guards against
+     * double-registration when the same class is passed to `registerService`
+     * or `validateServices` more than once — schema, env, and CLI specs each
+     * carry a uniqueness invariant that would otherwise throw on a second pass.
+     */
+    private registeredServices;
+    /**
+     * True until the file + custom providers have been loaded into `this.data`
+     * (i.e., first successful validate()). Subsequent validate() calls skip
+     * re-reading the config file — the file is treated as immutable for the
+     * lifetime of this ConfigManager.
+     */
+    private dataInitialized;
+    /**
+     * True when at least one service has been registered since the last
+     * successful validate(). Lets `validateServices()` no-op cleanly when
+     * called after everything's already been validated.
+     */
+    private hasNewRegistrations;
+    constructor(configFilePath?: string);
     addCustomProvider(provider: INexxusConfigProvider): void;
     private addJsonSchemaDef;
-    validateServices(svcs: Array<typeof NexxusBaseService>): void;
-    private addCliArgsToSpec;
-    private addEnvVarsToSpec;
+    /**
+     * Register a service's config schema, env-var spec, and CLI-arg spec so
+     * they're included in the next `validateServices()` pass. Idempotent per
+     * class name — repeat calls with the same class are silent no-ops.
+     *
+     * Intended usage: call once per service class ahead of time (in any order),
+     * then call `validateServices()` once to actually run validation. For the
+     * shorthand where you know all services up front, `validateServices([...])`
+     * still accepts an array and registers each entry before validating.
+     */
+    registerService(svc: NexxusServiceClass): void;
+    /**
+     * Runs config validation against every registered service's schema. Safe
+     * to call multiple times — the config file is read only on the first call,
+     * and repeat calls with no new registrations short-circuit as a no-op.
+     *
+     * The optional `svcs` array is a shorthand: each entry is passed through
+     * `registerService()` before validation runs. Existing callers passing all
+     * services up front (`validateServices([A, B, C])`) continue to work.
+     * Later calls can register additional services (e.g. dynamically-resolved
+     * logger/db/mq implementations) and re-validate.
+     */
+    validateServices(svcs?: Array<NexxusServiceClass>): Promise<void>;
     private populateFromCliArgs;
     private populateFromEnvVars;
     private populateFromCustomProviders;

package/dist-types/lib/ConfigProvider.d.ts

@@ -21,7 +21,13 @@ export declare class NexxusEnvVarsConfigProvider extends NexxusConfigProvider {
 export declare class NexxusCliArgConfigProvider extends NexxusConfigProvider {
     private argParser;
     private originalExit;
+    private addedArgs;
     constructor();
+    /**
+     * Idempotent per argument name — safe to call multiple times across repeat
+     * `ConfigManager.validateServices()` invocations. Argparse would otherwise
+     * throw on a second `add_argument` with the same name.
+     */
     addArgument(name: string, type: CliArgType): void;
     getConfig(): NexxusConfig;
 }

package/dist-types/lib/Exceptions.d.ts

@@ -5,13 +5,22 @@ export declare enum NexxusExceptions {
     INVALID_CONFIG = "InvalidConfigException",
     INVALID_JSON_PATCH = "InvalidJsonPatchException",
     INVALID_QUERY_FILTER = "InvalidQueryFilterException",
+    INVALID_SCHEMA_DATA = "InvalidSchemaDataException",
     INVALID_USER_MODEL = "InvalidUserModelException"
 }
 export declare class NexxusException extends Error {
-    constructor(type: string, message: string);
+    readonly subcode?: string;
+    constructor(type: string, message: string, subcode?: string);
+}
+declare enum FatalErrorSubcodes {
+    CONFIG_FILE_NOT_FOUND = "CONFIG_FILE_NOT_FOUND",
+    CONFIG_FILE_INVALID_JSON = "CONFIG_FILE_INVALID_JSON",
+    CONFIG_FILE_INVALID_SCHEMA = "CONFIG_FILE_INVALID_SCHEMA",
+    CONFIG_FILE_UNREADABLE = "CONFIG_FILE_UNREADABLE"
 }
 export declare class FatalErrorException extends NexxusException {
-    constructor(message: string);
+    static SUBCODES: Readonly<typeof FatalErrorSubcodes>;
+    constructor(message: string, subcode?: FatalErrorSubcodes);
 }
 export declare class BadRequestException extends NexxusException {
     constructor(message: string);
@@ -28,6 +37,10 @@ export declare class InvalidJsonPatchException extends NexxusException {
 export declare class InvalidQueryFilterException extends NexxusException {
     constructor(message: string);
 }
+export declare class InvalidSchemaDataException extends NexxusException {
+    constructor(message: string);
+}
 export declare class InvalidUserModelException extends NexxusException {
     constructor(message: string);
 }
+export {};

package/dist-types/lib/Logger.d.ts

@@ -1,7 +1,7 @@
 import { ConfigEnvVars, ConfigCliArgs } from './ConfigManager';
 import { NexxusBaseService, INexxusBaseServices } from './BaseService';
 import { NexxusConfig } from './ConfigProvider';
-type LoggableType = string | object | number | boolean | null | undefined;
+export type LogAttributes = Record<string, unknown>;
 export declare const enum NexxusLoggerLevels {
     EMERGENCY = "emerg",
     ALERT = "alert",
@@ -12,37 +12,107 @@ export declare const enum NexxusLoggerLevels {
     INFO = "info",
     DEBUG = "debug"
 }
+export type StdoutTransportConfig = {
+    type: 'stdout';
+};
+export type FileTransportConfig = {
+    type: 'file';
+    filename: string;
+    maxSize?: number;
+    maxFiles?: number;
+};
+/**
+ * Catch-all for transports loaded dynamically from npm packages. The `type`
+ * field is the package name (e.g. "winston-papertrail"); `export` optionally
+ * names the class export within the package; `options` is the passthrough
+ * config object handed to the transport's constructor.
+ *
+ * The schema's `oneOf` discriminator excludes built-in type strings from this
+ * variant, so the TS-side `type: string` doesn't cause ambiguity at runtime.
+ */
+export type CustomTransportConfig = {
+    type: string;
+    export?: string;
+    options?: Record<string, unknown>;
+};
+export type WinstonNexxusTransportConfig = StdoutTransportConfig | FileTransportConfig | CustomTransportConfig;
 type WinstonNexxusLoggerConfig = {
     level: NexxusLoggerLevels;
     logType: "json" | "text";
     timestamps: boolean;
     colors: boolean;
+    transports?: Array<WinstonNexxusTransportConfig>;
 } & NexxusConfig;
 export interface INexxusLogger {
-    log(level: NexxusLoggerLevels, message: LoggableType, label?: string): void;
+    log(level: NexxusLoggerLevels, message: string, attributes?: LogAttributes, label?: string): void;
 }
-export interface INexxusAsyncLogger extends INexxusLogger {
-    log(level: NexxusLoggerLevels, message: LoggableType, label?: string): Promise<void>;
+export interface INexxusAsyncLogger {
+    log(level: NexxusLoggerLevels, message: string, attributes?: LogAttributes, label?: string): Promise<void>;
 }
 interface NexxusLoggerServices extends Omit<INexxusBaseServices, 'logger'> {
 }
 export declare abstract class NexxusBaseLogger<T extends NexxusConfig> extends NexxusBaseService<T> implements INexxusLogger {
+    protected static configRootKey: string;
     constructor(services: NexxusLoggerServices);
-    abstract log(level: NexxusLoggerLevels, message: LoggableType, label?: string): void;
-    debug(message: LoggableType, label?: string): void;
-    info(message: LoggableType, label?: string): void;
-    warn(message: LoggableType, label?: string): void;
-    error(message: LoggableType, label?: string): void;
-    critical(message: LoggableType, label?: string): void;
-    alert(message: LoggableType, label?: string): void;
-    emerg(message: LoggableType, label?: string): void;
+    abstract log(level: NexxusLoggerLevels, message: string, attributes?: LogAttributes, label?: string): void;
+    protected static serializeError(err: Error): Record<string, unknown>;
+    protected static makeSafeReplacer(): (key: string, value: unknown) => unknown;
+    protected static safeStringify(value: unknown): string;
+    debug(message: string, label?: string): void;
+    debug(message: string, attributes: LogAttributes, label?: string): void;
+    info(message: string, label?: string): void;
+    info(message: string, attributes: LogAttributes, label?: string): void;
+    warn(message: string, label?: string): void;
+    warn(message: string, attributes: LogAttributes, label?: string): void;
+    error(message: string, label?: string): void;
+    error(message: string, attributes: LogAttributes, label?: string): void;
+    critical(message: string, label?: string): void;
+    critical(message: string, attributes: LogAttributes, label?: string): void;
+    alert(message: string, label?: string): void;
+    alert(message: string, attributes: LogAttributes, label?: string): void;
+    emerg(message: string, label?: string): void;
+    emerg(message: string, attributes: LogAttributes, label?: string): void;
+    private dispatch;
 }
 export declare class WinstonNexxusLogger extends NexxusBaseLogger<WinstonNexxusLoggerConfig> {
     private winston;
     protected static schemaPath: string;
     protected static envVars: ConfigEnvVars;
     protected static cliArgs: ConfigCliArgs;
-    constructor(services: NexxusLoggerServices);
-    log(level: NexxusLoggerLevels, message: LoggableType, label?: string): void;
+    /**
+     * Private — use `WinstonNexxusLogger.create(...)` instead. Transport instances
+     * must be resolved (async, since custom ones are dynamically imported) before
+     * the Winston logger can be constructed; the factory owns that step.
+     */
+    private constructor();
+    /**
+     * Async factory. Custom transports are loaded via dynamic `import()` so
+     * initialization is unavoidably async. API/Worker bootstrap code should
+     * `await WinstonNexxusLogger.create(...)` in place of `new WinstonNexxusLogger(...)`.
+     */
+    static create(services: NexxusLoggerServices): Promise<WinstonNexxusLogger>;
+    /**
+     * Maps each transport config entry to a constructed Winston transport.
+     * Built-in types are instantiated synchronously; everything else falls
+     * through to `loadCustomTransport`, which dynamically imports the npm
+     * package named by `type`.
+     *
+     * If the config has no transports (undefined or empty array), defaults to
+     * a single Console transport so the logger is never silent.
+     */
+    private static resolveTransports;
+    /**
+     * Dynamically imports the npm package named by `transport.type` and instantiates
+     * its transport class. The class is resolved in priority order:
+     *   1. `mod[transport.export]` if `transport.export` is set in config
+     *   2. `mod.default` if it's a function/class (ESM default export)
+     *   3. The module itself if it's a function/class (CJS `module.exports = Cls`)
+     *
+     * On any failure (package missing, no resolvable class, constructor throws)
+     * we re-wrap as `InvalidConfigException` so the operator sees an actionable
+     * message rather than a raw module-resolution stack trace.
+     */
+    private static loadCustomTransport;
+    log(level: NexxusLoggerLevels, message: string, attributes?: LogAttributes, label?: string): void;
 }
 export {};

package/dist-types/lib/ServiceResolver.d.ts

@@ -0,0 +1,23 @@
+import { NexxusConstructableServiceClass, NexxusFactoryServiceClass } from './BaseService';
+/**
+ * Resolves a config-declared service to a **constructable** class — one the
+ * bootstrap will instantiate via `new Cls(services)`.
+ *
+ *   1. If `configuredName` is in `builtins`, that class is returned directly
+ *      (fast path — no I/O, no dynamic import). Callers pass their known
+ *      static-imported builtins here.
+ *   2. Otherwise the name is treated as an npm package specifier and loaded
+ *      via dynamic import against the app's install tree.
+ *
+ * Used by `NexxusApi.resolveConstructableService` and
+ * `NexxusBaseWorker.resolveConstructableService` — the host classes provide
+ * their own builtin maps.
+ */
+export declare function resolveConstructableServiceClass(configuredName: string, builtins: Record<string, NexxusConstructableServiceClass>): Promise<NexxusConstructableServiceClass>;
+/**
+ * Same as `resolveConstructableServiceClass` but for services that expose an
+ * async `static create(services)` factory. Runtime-checks the class actually
+ * has `create` before returning, so misconfigurations surface here instead
+ * of blowing up at bootstrap time.
+ */
+export declare function resolveFactoryServiceClass(configuredName: string, builtins: Record<string, NexxusFactoryServiceClass>): Promise<NexxusFactoryServiceClass>;

package/dist-types/models/AppModel.d.ts

@@ -1,9 +1,35 @@
+import { NexxusApplicationSchema } from "./Application";
 import { NexxusBaseModel, INexxusBaseModel } from "./BaseModel";
-export type NexxusAppModelType = INexxusBaseModel & {
+export interface INexxusAppModel extends INexxusBaseModel {
     appId: string;
     userId?: string;
-    [key: string]: any;
-};
-export declare class NexxusAppModel extends NexxusBaseModel<NexxusAppModelType> {
-    constructor(props: NexxusAppModelType);
+    /**
+     * Monotonically-increasing per-document version counter, assigned by the
+     * database adapter on every write. Used for client-side gap detection and
+     * dedup when applying real-time update events. App models flow through the
+     * async Writer → Transport Manager → client pipeline; built-in models
+     * (Application, User) do not and therefore do not carry a version.
+     * Never set by user input — the validator rejects user-supplied values.
+     */
+    version?: number;
+    [key: string]: unknown;
+}
+export declare class NexxusAppModel extends NexxusBaseModel<INexxusAppModel> {
+    /**
+     * Construct an AppModel from user-supplied or pre-validated data.
+     *
+     * Pass the application's schema as the second argument to validate + normalize
+     * the input (e.g. date strings → integer timestamps). Pass `null` to skip
+     * validation — only do that when the data is already trusted (e.g. coming
+     * back from storage). The `fromStorage` static factory below is the preferred
+     * way to express that intent.
+     */
+    constructor(props: INexxusAppModel, appSchema: NexxusApplicationSchema | null);
+    /**
+     * Hydrate an AppModel from already-validated storage. Use when reading back
+     * from the database — the data was validated when it was written, so we don't
+     * re-validate (saves work and avoids false-positives on legacy/edge-case docs
+     * that pre-date a later schema change).
+     */
+    static fromStorage(props: INexxusAppModel): NexxusAppModel;
 }

package/dist-types/models/Application.d.ts

@@ -1,5 +1,8 @@
-import { NexxusBaseModel, INexxusBaseModel } from "./BaseModel";
+import { INexxusBaseModel } from "./BaseModel";
+import { NexxusBuiltinModel } from "./BuiltinModel";
 import { NexxusModelDef } from "../common/ModelTypes";
+import { InferModel } from "../common/InferModel";
+import { NEXXUS_BUILTIN_MODEL_SCHEMAS } from "../common/BuiltinSchemas";
 import { NexxusUserDetailSchema } from "./User";
 export interface NexxusApplicationSchema {
     [modelName: string]: NexxusModelDef;
@@ -7,23 +10,48 @@ export interface NexxusApplicationSchema {
 export interface NexxusUserTypeConfig {
     private?: boolean;
 }
-export type NexxusApplicationModelType = INexxusBaseModel<'application'> & {
-    name: string;
-    description?: string;
+/**
+ * Per-application auth configuration. Lives on the Application document so
+ * that each tenant carries its own JWT secret and per-strategy settings.
+ *
+ * `strategies` is a map keyed by strategy name (must be a subset of the
+ * deployment's `api.auth.availableStrategies`). Each value's shape is
+ * whatever the strategy's own JSON Schema defines — validated by the
+ * corresponding `NexxusAuthStrategy` subclass at instantiation time.
+ */
+export interface NexxusApplicationAuthConfig {
+    jwtSecret: string;
+    jwtExpiresIn?: string;
+    strategies: Record<string, unknown>;
+}
+export type INexxusApplication = INexxusBaseModel<'application'> & InferModel<typeof NEXXUS_BUILTIN_MODEL_SCHEMAS.application> & {
     schema: NexxusApplicationSchema;
-    authEnabled: boolean;
-    allowMultipleLogin: boolean | null;
     userTypes?: {
         [userType: string]: NexxusUserTypeConfig;
     };
     userDetailSchema?: {
         [userType: string]: NexxusUserDetailSchema;
     };
+    auth?: NexxusApplicationAuthConfig;
+    defaultLimit?: number;
+    maxLimit?: number;
 };
-export declare class NexxusApplication extends NexxusBaseModel<NexxusApplicationModelType> {
-    constructor(data: NexxusApplicationModelType);
+export declare class NexxusApplication extends NexxusBuiltinModel<INexxusApplication> {
+    constructor(data: INexxusApplication);
     getSchema(): NexxusApplicationSchema;
     getUserDetailSchema(userType?: string): NexxusUserDetailSchema | null;
+    hasAuthEnabled(): boolean;
+    /**
+     * Runtime field schema for one of the developer-declared models in this
+     * application's `schema` field. Built-in models (user, application) have
+     * their own static `getModelSchema` and are not resolved here.
+     */
+    getAppModelSchema(modelType: string): NexxusModelDef;
+    /**
+     * Runtime field schema for Application records. Static because the schema
+     * is global — not per-app.
+     */
+    static getModelSchema(): NexxusModelDef;
     getAppModelFieldType(modelType: string, fieldPath: string): string | undefined;
     getModelFilterableFields(modelType: string): Set<string>;
 }