zerodrift 1.0.0

package/dist/core/MemoryAdapter.d.ts

@@ -0,0 +1,67 @@
+/**
+ * MemoryAdapter — a fully in-memory StorageAdapter for use in Node.js, agents,
+ * and any environment without IndexedDB.
+ *
+ * Data lives in Maps and arrays for the lifetime of the StoreManager.
+ * Nothing is persisted to disk — the engine always starts with a full
+ * bootstrap and loses pending transactions on restart. For durable off-heap
+ * storage in a server environment, implement StorageAdapter with your own
+ * SQLite / Redis / file-system backend.
+ */
+import { BootstrapType, type DatabaseMeta, type PartialIndexEntry, type StorageAdapter, type SyncActionHeader } from "./Database";
+export declare class MemoryAdapter implements StorageAdapter {
+    private meta;
+    private models;
+    private txLog;
+    /** Persisted SSE sync action headers — keyed by syncId. */
+    private syncActions;
+    private nextKey;
+    private connected;
+    /** modelName → indexKey → value → firstSyncId at the time of fetch. */
+    private partialIndexes;
+    /** Set true when connect() cleared rows for a schemaVersion-bumped model. */
+    migrationClearedModels: boolean;
+    /** Names of models added since the last connect — StoreManager target-fetches
+     * these so adopters don't have to bump schemaVersion by hand. */
+    newlyAddedModels: string[];
+    private loadedTracker;
+    get loadedModels(): ReadonlySet<string>;
+    onLoadedModelsChange(cb: () => void): () => void;
+    markModelLoaded(modelName: string): void;
+    connect(): Promise<void>;
+    get isConnected(): boolean;
+    loadMeta(): Promise<DatabaseMeta | null>;
+    saveMeta(meta: DatabaseMeta): Promise<void>;
+    get currentMeta(): DatabaseMeta | null;
+    determineBootstrapType(): Promise<BootstrapType>;
+    writeModels(modelName: string, records: Record<string, unknown>[]): Promise<void>;
+    writeModelsIfAbsent(modelName: string, records: Record<string, unknown>[]): Promise<void>;
+    readAllModels(modelName: string): Promise<Record<string, unknown>[]>;
+    readModel(modelName: string, id: string): Promise<Record<string, unknown> | null>;
+    readModelsByIndex(modelName: string, indexName: string, value: string): Promise<Record<string, unknown>[]>;
+    deleteModel(modelName: string, id: string): Promise<void>;
+    deleteModels(modelName: string, ids: string[]): Promise<void>;
+    deleteModelsByIndex(modelName: string, indexName: string, value: string): Promise<void>;
+    clearModelStore(modelName: string): Promise<void>;
+    cacheTransaction(data: unknown): Promise<number | null>;
+    getCachedTransactions(): Promise<{
+        idbKey: number;
+        data: unknown;
+    }[]>;
+    deleteCachedTransactions(keys: number[]): Promise<void>;
+    clearCachedTransactions(): Promise<void>;
+    updateCachedTransaction(idbKey: number, data: unknown): Promise<void>;
+    recordSyncActions(actions: SyncActionHeader[]): Promise<void>;
+    hasSyncAction(syncId: number): Promise<boolean>;
+    findSyncActionsForModel(modelName: string, modelId: string): Promise<{
+        syncId: number;
+        action: string;
+    }[]>;
+    pruneSyncActionsBelow(belowSyncId: number): Promise<void>;
+    recordPartialIndex(modelName: string, indexKey: string, value: string, firstSyncId: number): Promise<void>;
+    clearPartialIndex(modelName: string, indexKey: string, value: string): Promise<void>;
+    clearPartialIndexesForModel(modelName: string): Promise<void>;
+    loadPartialIndexes(): Promise<PartialIndexEntry[]>;
+    close(): Promise<void>;
+    destroy(): Promise<void>;
+}

package/dist/core/MemoryAdapter.js

@@ -0,0 +1,243 @@
+/**
+ * MemoryAdapter — a fully in-memory StorageAdapter for use in Node.js, agents,
+ * and any environment without IndexedDB.
+ *
+ * Data lives in Maps and arrays for the lifetime of the StoreManager.
+ * Nothing is persisted to disk — the engine always starts with a full
+ * bootstrap and loses pending transactions on restart. For durable off-heap
+ * storage in a server environment, implement StorageAdapter with your own
+ * SQLite / Redis / file-system backend.
+ */
+import { BootstrapType, LoadedModelsTracker, diffModelVersions, currentModelVersions, } from "./Database";
+export class MemoryAdapter {
+    constructor() {
+        this.meta = null;
+        this.models = new Map();
+        this.txLog = [];
+        /** Persisted SSE sync action headers — keyed by syncId. */
+        this.syncActions = new Map();
+        this.nextKey = 1;
+        this.connected = false;
+        /** modelName → indexKey → value → firstSyncId at the time of fetch. */
+        this.partialIndexes = new Map();
+        /** Set true when connect() cleared rows for a schemaVersion-bumped model. */
+        this.migrationClearedModels = false;
+        /** Names of models added since the last connect — StoreManager target-fetches
+         * these so adopters don't have to bump schemaVersion by hand. */
+        this.newlyAddedModels = [];
+        this.loadedTracker = new LoadedModelsTracker();
+    }
+    get loadedModels() {
+        return this.loadedTracker.loadedModels;
+    }
+    onLoadedModelsChange(cb) {
+        return this.loadedTracker.onChange(cb);
+    }
+    markModelLoaded(modelName) {
+        this.loadedTracker.markLoaded(modelName);
+    }
+    async connect() {
+        this.connected = true;
+        this.migrationClearedModels = false;
+        this.newlyAddedModels = [];
+        this.loadedTracker.reset();
+        for (const [name, bucket] of this.models) {
+            if (bucket.size > 0) {
+                this.loadedTracker.seed(name);
+            }
+        }
+        if (this.meta != null) {
+            const { cleared, newlyAdded } = await diffModelVersions(this, this.meta.modelSchemaVersions);
+            this.migrationClearedModels = cleared.length > 0;
+            this.newlyAddedModels = newlyAdded;
+            if (cleared.length > 0 || newlyAdded.length > 0) {
+                this.meta.modelSchemaVersions = currentModelVersions();
+            }
+        }
+    }
+    get isConnected() {
+        return this.connected;
+    }
+    async loadMeta() {
+        return this.meta;
+    }
+    async saveMeta(meta) {
+        this.meta = {
+            ...meta,
+            modelSchemaVersions: meta.modelSchemaVersions ?? currentModelVersions(),
+        };
+    }
+    get currentMeta() {
+        return this.meta;
+    }
+    async determineBootstrapType() {
+        if (this.migrationClearedModels) {
+            return BootstrapType.Full;
+        }
+        if (this.meta == null) {
+            return BootstrapType.Full;
+        }
+        if (this.meta.lastSyncId > 0) {
+            return BootstrapType.Partial;
+        }
+        return BootstrapType.Local;
+    }
+    async writeModels(modelName, records) {
+        if (records.length === 0) {
+            return;
+        }
+        let bucket = this.models.get(modelName);
+        if (bucket == null) {
+            bucket = new Map();
+            this.models.set(modelName, bucket);
+        }
+        for (const record of records) {
+            bucket.set(record.id, record);
+        }
+        this.loadedTracker.markLoaded(modelName);
+    }
+    async writeModelsIfAbsent(modelName, records) {
+        if (records.length === 0) {
+            return;
+        }
+        let bucket = this.models.get(modelName);
+        if (bucket == null) {
+            bucket = new Map();
+            this.models.set(modelName, bucket);
+        }
+        let inserted = false;
+        for (const record of records) {
+            const id = record.id;
+            if (!bucket.has(id)) {
+                bucket.set(id, record);
+                inserted = true;
+            }
+        }
+        if (inserted) {
+            this.loadedTracker.markLoaded(modelName);
+        }
+    }
+    async readAllModels(modelName) {
+        return [...(this.models.get(modelName)?.values() ?? [])];
+    }
+    async readModel(modelName, id) {
+        return this.models.get(modelName)?.get(id) ?? null;
+    }
+    async readModelsByIndex(modelName, indexName, value) {
+        return [...(this.models.get(modelName)?.values() ?? [])].filter((r) => r[indexName] === value);
+    }
+    async deleteModel(modelName, id) {
+        this.models.get(modelName)?.delete(id);
+    }
+    async deleteModels(modelName, ids) {
+        const bucket = this.models.get(modelName);
+        if (bucket == null) {
+            return;
+        }
+        for (const id of ids) {
+            bucket.delete(id);
+        }
+    }
+    async deleteModelsByIndex(modelName, indexName, value) {
+        const bucket = this.models.get(modelName);
+        if (bucket == null) {
+            return;
+        }
+        for (const [id, record] of bucket.entries()) {
+            if (record[indexName] === value) {
+                bucket.delete(id);
+            }
+        }
+    }
+    async clearModelStore(modelName) {
+        this.models.get(modelName)?.clear();
+        this.loadedTracker.markUnloaded(modelName);
+    }
+    async cacheTransaction(data) {
+        const key = this.nextKey++;
+        this.txLog.push({ key, data });
+        return key;
+    }
+    async getCachedTransactions() {
+        return this.txLog.map((t) => ({ idbKey: t.key, data: t.data }));
+    }
+    async deleteCachedTransactions(keys) {
+        const keySet = new Set(keys);
+        this.txLog = this.txLog.filter((t) => !keySet.has(t.key));
+    }
+    async clearCachedTransactions() {
+        this.txLog = [];
+    }
+    async updateCachedTransaction(idbKey, data) {
+        const i = this.txLog.findIndex((t) => t.key === idbKey);
+        if (i !== -1) {
+            this.txLog[i] = { key: idbKey, data };
+        }
+    }
+    async recordSyncActions(actions) {
+        for (const a of actions) {
+            this.syncActions.set(a.syncId, a);
+        }
+    }
+    async hasSyncAction(syncId) {
+        return this.syncActions.has(syncId);
+    }
+    async findSyncActionsForModel(modelName, modelId) {
+        const out = [];
+        for (const a of this.syncActions.values()) {
+            if (a.modelName === modelName && a.modelId === modelId) {
+                out.push({ syncId: a.syncId, action: a.action });
+            }
+        }
+        return out;
+    }
+    async pruneSyncActionsBelow(belowSyncId) {
+        for (const id of this.syncActions.keys()) {
+            if (id < belowSyncId) {
+                this.syncActions.delete(id);
+            }
+        }
+    }
+    async recordPartialIndex(modelName, indexKey, value, firstSyncId) {
+        let byModel = this.partialIndexes.get(modelName);
+        if (byModel == null) {
+            byModel = new Map();
+            this.partialIndexes.set(modelName, byModel);
+        }
+        let byKey = byModel.get(indexKey);
+        if (byKey == null) {
+            byKey = new Map();
+            byModel.set(indexKey, byKey);
+        }
+        byKey.set(value, firstSyncId);
+    }
+    async clearPartialIndex(modelName, indexKey, value) {
+        this.partialIndexes.get(modelName)?.get(indexKey)?.delete(value);
+    }
+    async clearPartialIndexesForModel(modelName) {
+        this.partialIndexes.delete(modelName);
+    }
+    async loadPartialIndexes() {
+        const out = [];
+        for (const [modelName, byKey] of this.partialIndexes) {
+            for (const [indexKey, values] of byKey) {
+                for (const [value, firstSyncId] of values) {
+                    out.push({ modelName, indexKey, value, firstSyncId });
+                }
+            }
+        }
+        return out;
+    }
+    async close() {
+        this.connected = false;
+    }
+    async destroy() {
+        this.models.clear();
+        this.txLog = [];
+        this.syncActions.clear();
+        this.meta = null;
+        this.nextKey = 1;
+        this.connected = false;
+        this.partialIndexes.clear();
+    }
+}

package/dist/core/ModelRegistry.d.ts

@@ -0,0 +1,64 @@
+/**
+ * ModelRegistry is a singleton that holds metadata for every model class.
+ *
+ * When decorators like @ClientModel and @Property run at class definition time,
+ * they register information here. The rest of the engine reads from this
+ * registry to know how to serialize, hydrate, observe, and sync each model.
+ *
+ * Also computes a schemaHash — a fingerprint of all models and their properties.
+ * If the hash changes between sessions, the local IndexedDB needs a migration.
+ */
+import { type ModelMeta, type PropertyMeta, type CoveringPath } from "./types";
+declare class ModelRegistryImpl {
+    private models;
+    private cachedHash;
+    /** Register a model class. Returns existing metadata if already registered. */
+    registerModel(name: string, ctor: new (...args: unknown[]) => unknown): ModelMeta;
+    /** Register a property on a model. */
+    registerProperty(modelName: string, prop: PropertyMeta): void;
+    /**
+     * Merge partial metadata into an already-registered property.
+     * Used by @Reference to promote a user-declared @Property to PropertyType.Reference,
+     * adding referenceTo / onDelete / nullable without losing indexed / serializer etc.
+     */
+    updateProperty(modelName: string, propertyName: string, updates: Partial<PropertyMeta>): void;
+    registerAction(modelName: string, name: string): void;
+    registerComputed(modelName: string, name: string): void;
+    /** Look up metadata by model name. */
+    getModelMeta(name: string): ModelMeta | undefined;
+    /** Look up metadata from a model instance (reads the class name). */
+    getMetaForInstance(instance: object): ModelMeta | undefined;
+    /** Get all registered model metadata. */
+    allModels(): ModelMeta[];
+    /** Names of every Eager-load-strategy model. Lazy / Partial /
+     * LocalOnly / Ephemeral models are loaded on demand or
+     * via SSE — never via a full-bootstrap payload. */
+    eagerModelNames(): string[];
+    /** Names of models that pre-subscribe to SSE deltas regardless of whether
+     * any rows have been loaded locally — Eager (always fully loaded) and
+     * Ephemeral (pool-only, fed by SSE). The catchup URL unions this with the
+     * adapter's `loadedModels` so an Eager model the server happens to have
+     * zero rows for in this workspace still receives future inserts. */
+    alwaysSubscribedModelNames(): string[];
+    private coveringPathsCache;
+    /**
+     * Auto-derive covering axes for a `RefCollection<child>` declared on
+     * `parentModel`. Walks `parentModel`'s outgoing FK chain up to `maxDepth`
+     * hops; at each level checks whether the child has the same FK name as an
+     * indexed property (denormalization). Each match becomes a `CoveringPath`
+     * resolved later at hydrate time.
+     *
+     * Cycle-detected (a model in the chain isn't traversed twice). Cached per
+     * `(parent, child, depth)` triple. Result is union'd with the manual
+     * `coveringIndexes` decorator option at the call site.
+     */
+    getDerivedCoveringPaths(parentModelName: string, childModelName: string, maxDepth: number): CoveringPath[];
+    private walkCoveringPaths;
+    /**
+     * A hash of all model names, versions, load strategies, and property metadata.
+     * Used to detect when IndexedDB needs a migration.
+     */
+    get schemaHash(): string;
+}
+export declare const ModelRegistry: ModelRegistryImpl;
+export {};

package/dist/core/ModelRegistry.js

@@ -0,0 +1,217 @@
+/**
+ * ModelRegistry is a singleton that holds metadata for every model class.
+ *
+ * When decorators like @ClientModel and @Property run at class definition time,
+ * they register information here. The rest of the engine reads from this
+ * registry to know how to serialize, hydrate, observe, and sync each model.
+ *
+ * Also computes a schemaHash — a fingerprint of all models and their properties.
+ * If the hash changes between sessions, the local IndexedDB needs a migration.
+ */
+import { hashString } from "./hash";
+import { LoadStrategy, PropertyType, } from "./types";
+class ModelRegistryImpl {
+    constructor() {
+        this.models = new Map();
+        this.cachedHash = null;
+        this.coveringPathsCache = new Map();
+    }
+    /** Register a model class. Returns existing metadata if already registered. */
+    registerModel(name, ctor) {
+        if (!this.models.has(name)) {
+            this.models.set(name, {
+                name,
+                loadStrategy: LoadStrategy.Eager,
+                usedForPartialIndexes: false,
+                properties: new Map(),
+                actions: new Set(),
+                computedProps: new Set(),
+                ctor: ctor,
+                schemaVersion: 1,
+            });
+        }
+        // Any registry change invalidates downstream caches.
+        this.cachedHash = null;
+        this.coveringPathsCache.clear();
+        return this.models.get(name);
+    }
+    /** Register a property on a model. */
+    registerProperty(modelName, prop) {
+        const meta = this.models.get(modelName);
+        if (meta == null) {
+            throw new Error(`Model "${modelName}" not registered`);
+        }
+        meta.properties.set(prop.name, prop);
+        this.cachedHash = null;
+        this.coveringPathsCache.clear();
+    }
+    /**
+     * Merge partial metadata into an already-registered property.
+     * Used by @Reference to promote a user-declared @Property to PropertyType.Reference,
+     * adding referenceTo / onDelete / nullable without losing indexed / serializer etc.
+     */
+    updateProperty(modelName, propertyName, updates) {
+        const meta = this.models.get(modelName);
+        if (meta == null) {
+            throw new Error(`Model "${modelName}" not registered`);
+        }
+        const existing = meta.properties.get(propertyName);
+        if (existing == null) {
+            throw new Error(`Property "${propertyName}" not found on model "${modelName}". ` +
+                `Declare it with @Property() before applying @Reference.`);
+        }
+        meta.properties.set(propertyName, { ...existing, ...updates });
+        this.cachedHash = null;
+        this.coveringPathsCache.clear();
+    }
+    registerAction(modelName, name) {
+        this.models.get(modelName)?.actions.add(name);
+    }
+    registerComputed(modelName, name) {
+        this.models.get(modelName)?.computedProps.add(name);
+    }
+    /** Look up metadata by model name. */
+    getModelMeta(name) {
+        return this.models.get(name);
+    }
+    /** Look up metadata from a model instance (reads the class name). */
+    getMetaForInstance(instance) {
+        const name = instance.constructor._modelName;
+        return name != null ? this.models.get(name) : undefined;
+    }
+    /** Get all registered model metadata. */
+    allModels() {
+        return [...this.models.values()];
+    }
+    /** Names of every Eager-load-strategy model. Lazy / Partial /
+     * LocalOnly / Ephemeral models are loaded on demand or
+     * via SSE — never via a full-bootstrap payload. */
+    eagerModelNames() {
+        const out = [];
+        for (const meta of this.models.values()) {
+            if (meta.loadStrategy === LoadStrategy.Eager) {
+                out.push(meta.name);
+            }
+        }
+        return out;
+    }
+    /** Names of models that pre-subscribe to SSE deltas regardless of whether
+     * any rows have been loaded locally — Eager (always fully loaded) and
+     * Ephemeral (pool-only, fed by SSE). The catchup URL unions this with the
+     * adapter's `loadedModels` so an Eager model the server happens to have
+     * zero rows for in this workspace still receives future inserts. */
+    alwaysSubscribedModelNames() {
+        const out = [];
+        for (const meta of this.models.values()) {
+            if (meta.loadStrategy === LoadStrategy.Eager ||
+                meta.loadStrategy === LoadStrategy.Ephemeral) {
+                out.push(meta.name);
+            }
+        }
+        return out;
+    }
+    /**
+     * Auto-derive covering axes for a `RefCollection<child>` declared on
+     * `parentModel`. Walks `parentModel`'s outgoing FK chain up to `maxDepth`
+     * hops; at each level checks whether the child has the same FK name as an
+     * indexed property (denormalization). Each match becomes a `CoveringPath`
+     * resolved later at hydrate time.
+     *
+     * Cycle-detected (a model in the chain isn't traversed twice). Cached per
+     * `(parent, child, depth)` triple. Result is union'd with the manual
+     * `coveringIndexes` decorator option at the call site.
+     */
+    getDerivedCoveringPaths(parentModelName, childModelName, maxDepth) {
+        if (maxDepth < 1) {
+            return [];
+        }
+        const key = `${parentModelName}|${childModelName}|${maxDepth}`;
+        const cached = this.coveringPathsCache.get(key);
+        if (cached != null) {
+            return cached;
+        }
+        const childMeta = this.models.get(childModelName);
+        if (childMeta == null) {
+            this.coveringPathsCache.set(key, []);
+            return [];
+        }
+        const childIndexed = new Set();
+        for (const prop of childMeta.properties.values()) {
+            if (prop.indexed === true) {
+                childIndexed.add(prop.name);
+            }
+        }
+        if (childIndexed.size === 0) {
+            this.coveringPathsCache.set(key, []);
+            return [];
+        }
+        const out = [];
+        this.walkCoveringPaths(parentModelName, childIndexed, maxDepth, [], new Set([parentModelName]), out);
+        this.coveringPathsCache.set(key, out);
+        return out;
+    }
+    walkCoveringPaths(currentModel, childIndexed, remainingDepth, soFar, visited, out) {
+        if (remainingDepth <= 0) {
+            return;
+        }
+        const meta = this.models.get(currentModel);
+        if (meta == null) {
+            return;
+        }
+        for (const prop of meta.properties.values()) {
+            if (prop.type !== PropertyType.Reference || prop.referenceTo == null) {
+                continue;
+            }
+            const hop = { fk: prop.name, throughModel: prop.referenceTo };
+            const nextHops = [...soFar, hop];
+            if (childIndexed.has(prop.name)) {
+                out.push({ axis: prop.name, hops: nextHops });
+            }
+            if (remainingDepth > 1 && !visited.has(prop.referenceTo)) {
+                visited.add(prop.referenceTo);
+                this.walkCoveringPaths(prop.referenceTo, childIndexed, remainingDepth - 1, nextHops, visited, out);
+                visited.delete(prop.referenceTo);
+            }
+        }
+    }
+    /**
+     * A hash of all model names, versions, load strategies, and property metadata.
+     * Used to detect when IndexedDB needs a migration.
+     */
+    get schemaHash() {
+        if (this.cachedHash != null) {
+            return this.cachedHash;
+        }
+        const sorted = [...this.models.entries()].sort(([a], [b]) => a.localeCompare(b));
+        const parts = sorted.map(([name, meta]) => {
+            const props = [...meta.properties.values()]
+                .sort((a, b) => a.name.localeCompare(b.name))
+                .map((prop) => [
+                prop.name,
+                prop.type,
+                `lazy=${prop.lazy === true}`,
+                `nullable=${prop.nullable === true}`,
+                `indexed=${prop.indexed === true}`,
+                `serializer=${prop.serializer != null}`,
+                `deserializer=${prop.deserializer != null}`,
+                `referenceTo=${prop.referenceTo ?? ""}`,
+                `inverseOf=${prop.inverseOf ?? ""}`,
+                `idField=${prop.idField ?? ""}`,
+                `idsField=${prop.idsField ?? ""}`,
+                `onDelete=${prop.onDelete ?? ""}`,
+                `coveringIndexes=${(prop.coveringIndexes ?? []).join("|")}`,
+            ].join(";"))
+                .join(",");
+            return [
+                name,
+                `version=${meta.schemaVersion}`,
+                `loadStrategy=${meta.loadStrategy}`,
+                `usedForPartialIndexes=${meta.usedForPartialIndexes}`,
+                `props=[${props}]`,
+            ].join(":");
+        });
+        this.cachedHash = hashString(parts.join("|")).toString(36);
+        return this.cachedHash;
+    }
+}
+export const ModelRegistry = new ModelRegistryImpl();

package/dist/core/ModelStream.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Lightweight SSE connection for secondary services (e.g. a calculation engine).
+ * Writes to IDB and upserts into the ObjectPool — no sync state management.
+ * Ephemeral models skip IDB and are only held in the pool.
+ */
+import type { StorageAdapter } from "./Database";
+import { ObjectPool } from "./ObjectPool";
+import { BaseSSEConnection, type SSEClientFactory, type SSEErrorReporter } from "./BaseSSEConnection";
+export interface ModelUpdate {
+    modelName: string;
+    modelId: string;
+    data: Record<string, unknown>;
+}
+/**
+ * Return null to drop the message. When not provided, raw payloads are
+ * assumed to already match `ModelUpdate`.
+ */
+export type ModelStreamMessageTransform = (raw: unknown) => ModelUpdate | ModelUpdate[] | null | undefined;
+export declare class ModelStream extends BaseSSEConnection {
+    private database;
+    private pool;
+    private onStatusChange?;
+    private transform?;
+    private updateQueue;
+    private processing;
+    constructor(url: string, database: StorageAdapter, pool: ObjectPool, onStatusChange?: ((connected: boolean) => void) | undefined, sseClientFactory?: SSEClientFactory, transform?: ModelStreamMessageTransform | undefined, reportError?: SSEErrorReporter);
+    disconnect(): void;
+    protected onOpen(): void;
+    protected onClose(): void;
+    protected onMessage(data: string): void;
+    private enqueue;
+    private applyUpdate;
+}

package/dist/core/ModelStream.js

@@ -0,0 +1,68 @@
+/**
+ * Lightweight SSE connection for secondary services (e.g. a calculation engine).
+ * Writes to IDB and upserts into the ObjectPool — no sync state management.
+ * Ephemeral models skip IDB and are only held in the pool.
+ */
+import { ModelRegistry } from "./ModelRegistry";
+import { BaseSSEConnection, } from "./BaseSSEConnection";
+import { LoadStrategy } from "./types";
+export class ModelStream extends BaseSSEConnection {
+    constructor(url, database, pool, onStatusChange, sseClientFactory, transform, reportError) {
+        super(url, sseClientFactory, reportError);
+        this.database = database;
+        this.pool = pool;
+        this.onStatusChange = onStatusChange;
+        this.transform = transform;
+        this.updateQueue = [];
+        this.processing = false;
+    }
+    disconnect() {
+        super.disconnect();
+        this.updateQueue = [];
+        this.processing = false;
+    }
+    onOpen() {
+        this.onStatusChange?.(true);
+    }
+    onClose() {
+        this.onStatusChange?.(false);
+    }
+    onMessage(data) {
+        const raw = JSON.parse(data);
+        const transformed = this.transform != null ? this.transform(raw) : raw;
+        if (transformed == null) {
+            return;
+        }
+        this.enqueue(Array.isArray(transformed) ? transformed : [transformed]);
+    }
+    async enqueue(updates) {
+        this.updateQueue.push(...updates);
+        if (this.processing) {
+            return;
+        }
+        this.processing = true;
+        while (this.updateQueue.length > 0) {
+            await this.applyUpdate(this.updateQueue.shift());
+        }
+        this.processing = false;
+    }
+    async applyUpdate(update) {
+        const { modelName, modelId, data } = update;
+        if (data == null) {
+            return;
+        }
+        const modelMeta = ModelRegistry.getModelMeta(modelName);
+        if (modelMeta == null) {
+            return;
+        }
+        const record = { id: modelId, ...data };
+        if (modelMeta.loadStrategy !== LoadStrategy.Ephemeral) {
+            await this.database.writeModels(modelName, [record]);
+        }
+        const existing = this.pool.getById(modelName, modelId);
+        if (existing != null) {
+            existing.hydrate(data);
+            this.pool.put(modelName, existing);
+        }
+    }
+}