@seedprotocol/sdk 0.7.9 → 0.7.10-next.1353.g74aeeed

package/dist/{errors-DLSoqSHG.js → errors-CnT0fSMK.js}

@@ -1,8 +1,8 @@
 import { fromCallback, setup, assign, createActor, waitFor, fromPromise } from 'xstate';
-import { aj as isActorStopped, T as applyContextUpdate, U as isInternalUpdate, ak as differsFromOriginals, X as isEntityTornDown, al as onEntityTeardown, V as evictionLog, Y as sameEntity, Z as DEFAULT_READY_TIMEOUT_MS, _ as waitForEntityReady, $ as createReactiveProxy, a0 as runEntityLoad, a2 as entityStatus, I as Item, a1 as evictEntities, a3 as releaseEntity, a4 as destroyEntity, a7 as modelPropertiesToObject, a5 as EntityCache, a9 as easPropertyNameForPublish, ae as matchMetadataProperty, aQ as getSeedPublisher, af as metadataRowsOfProperty, ag as METADATA_LATEST_FIRST_ORDER_SQL, aR as deleteStagedFile, aS as storageFileName, aT as STORAGE_SUBDIR, aU as resolveNewSeedFields, aV as lookupPropertySchemaUid, aW as stageStorageContent, aX as requireStagedFile, aY as createSeed, aZ as createMetadata, H as compareMetadataRowsLatestFirst, a_ as storageValueRowOf, t as registerOutboxApplier, r as outboxOpValue, a$ as findSetConflict, b0 as recordPropertyEdit, h as OutboxOpDeferredError, u as startOutbox, i as OutboxOpFailedError, y as OwnershipError, B as isItemOwned, R as getLatestVersionRow, S as parseListPropertyValueFromStorage, ar as resolvePublisherFromSeedRow, aB as isLocalUnsealedDraft } from './Item-Bf4kWKpH.js';
+import { ak as isActorStopped, T as applyContextUpdate, U as isInternalUpdate, al as differsFromOriginals, X as isEntityTornDown, am as onEntityTeardown, V as evictionLog, Y as sameEntity, Z as DEFAULT_READY_TIMEOUT_MS, _ as createReactiveProxy, $ as runEntityLoad, a0 as waitForEntityReady, a2 as EntityUnloadedError, a3 as entityStatus, I as Item, a1 as evictEntities, a4 as releaseEntity, a5 as destroyEntity, a8 as modelPropertiesToObject, a6 as EntityCache, aa as easPropertyNameForPublish, af as matchMetadataProperty, aT as getSeedPublisher, ag as metadataRowsOfProperty, ah as METADATA_LATEST_FIRST_ORDER_SQL, aU as deleteStagedFile, aV as storageFileName, aW as STORAGE_SUBDIR, aX as resolveNewSeedFields, aY as lookupPropertySchemaUid, aZ as stageStorageContent, a_ as requireStagedFile, a$ as createSeed, b0 as createMetadata, H as compareMetadataRowsLatestFirst, b1 as storageValueRowOf, t as registerOutboxApplier, r as outboxOpValue, b2 as findSetConflict, b3 as recordPropertyEdit, h as OutboxOpDeferredError, u as startOutbox, i as OutboxOpFailedError, y as OwnershipError, B as isItemOwned, R as getLatestVersionRow, S as parseListPropertyValueFromStorage, au as resolvePublisherFromSeedRow, aE as isLocalUnsealedDraft, b4 as setEntityUnloadGraceMs, b5 as stopOutbox, b6 as evictAllEntities } from './Item-oPnmIehk.js';
 import debug from 'debug';
-import { B as BaseDb, l as properties, d as models$1, j as modelSchemas, t as schemas, f as easSyncProcesses, a as appState, w as BaseFileManager, b as modelUids, s as seeds, v as versions, m as metadata$1, p as pendingWrites, h as htmlEmbeddedImageCoPublish, e as arweaveL1FinalizeJobs, r as publishProcesses } from './BaseFileManager-BAlySv8w.js';
-import { aH as writeModelToDb, aI as writePropertyToDb, m as generateId, p as isInternalSchema, A as AmbiguousModelError, aJ as currentNameMatchLevels, aK as renameModelInDb, s as isClientReady, a as TProperty, ay as withDbTabLock, af as MachineIds, ap as isLeaderTab, aL as postTabMessage, aM as onTabMessage, ax as whenLeaderTab, aN as listenForOtherTabsEvents, F as isBrowser, $ as isNode, aO as startTabCoordination, aq as normalizeAddressConfig, aP as isTestOrSeedDev, L as nameMatchLevels, C as loadNameMatchLevels, aD as withSeedDbLock, q as inDefinitionsTransaction, aQ as insertModelStubs, G as emitAcrossTabs, a8 as ADDRESSES_PERSISTED_EVENT, ar as normalizeAddressList, aR as warnOnInvalidNameMatch, u as upsertSchemaRow, aS as refreshCachedProperties, g as normalizePropertyRecordSchema, M as ModelPropertyDataTypes, j as findSeedRow, aT as tryWithTabLock, Y as getItemStorageSubdir, _ as getItemStorageLocalFileName, aU as notifyFileSaved, ad as ImageSize, n as normalizeDataType, ab as ClientManagerState, aV as ClientManagerEvents, at as parseAddressesPersistedPayload, x as normalizePublisher, w as writeInBatches, K as selectInBatches, ae as LOCAL_COPIES_REMOVED_EVENT, aW as getWatchedAddressesFromDb, aX as getOwnedAddressesFromDb, aY as CLIENT_NOT_INITIALIZED, aZ as registerClientActor } from './tabEvents-CaVmngqr.js';
+import { B as BaseDb, l as properties, d as models$1, j as modelSchemas, t as schemas, f as easSyncProcesses, a as appState, w as BaseFileManager, b as modelUids, s as seeds, v as versions, m as metadata$1, p as pendingWrites, h as htmlEmbeddedImageCoPublish, e as arweaveL1FinalizeJobs, r as publishProcesses } from './BaseFileManager-DLou1TZS.js';
+import { aI as writeModelToDb, aJ as writePropertyToDb, m as generateId, p as isInternalSchema, A as AmbiguousModelError, aK as currentNameMatchLevels, aL as renameModelInDb, s as isClientReady, a as TProperty, ay as withDbTabLock, af as MachineIds, ap as isLeaderTab, aM as postTabMessage, aN as onTabMessage, ax as whenLeaderTab, aO as listenForOtherTabsEvents, F as isBrowser, $ as isNode, aP as startTabCoordination, aq as normalizeAddressConfig, aQ as isTestOrSeedDev, L as nameMatchLevels, C as loadNameMatchLevels, aD as withSeedDbLock, q as inDefinitionsTransaction, aR as insertModelStubs, G as emitAcrossTabs, a8 as ADDRESSES_PERSISTED_EVENT, ar as normalizeAddressList, aS as warnOnInvalidNameMatch, u as upsertSchemaRow, aT as refreshCachedProperties, g as normalizePropertyRecordSchema, M as ModelPropertyDataTypes, j as findSeedRow, aU as tryWithTabLock, Y as getItemStorageSubdir, _ as getItemStorageLocalFileName, aV as notifyFileSaved, ad as ImageSize, n as normalizeDataType, ab as ClientManagerState, aW as ClientManagerEvents, at as parseAddressesPersistedPayload, x as normalizePublisher, w as writeInBatches, K as selectInBatches, ae as LOCAL_COPIES_REMOVED_EVENT, aX as getWatchedAddressesFromDb, aY as getOwnedAddressesFromDb, aZ as CLIENT_NOT_INITIALIZED, a_ as stopTabCoordination, a$ as registerClientActor } from './tabEvents-DT5ez6io.js';
 import { seedGatewayConfigFromSeedConfig, setPreferredArweaveReadBaseUrls, resolveSeedGatewayEndpoints, setResolvedSeedGatewayEndpoints, BaseArweaveClient, ensureReadGatewaySelected, DEFAULT_ARWEAVE_HOST } from '@seedprotocol/arweave';
 import 'pluralize';
 import { localNamesInBestMatchTier, configureEasReadChain, matchEasModelSchemas, whenEasReadChainSettled, getEasReadChainId, DEFAULT_EAS_CHAIN_ID, isEasReadChainConfigured, easName, isValidEasAttestationUid } from '@seedprotocol/eas';
@@ -36,10 +36,10 @@ const validateModel = fromCallback(({ sendBack, input: { context }, self }) => {
     const _validateModel = async () => {
         try {
             // Use dynamic imports to break circular dependencies
-            const validationServiceMod = await import('./SchemaValidationService-CnmKyzR-.js');
+            const validationServiceMod = await import('./SchemaValidationService-CieGrj5c.js');
             const { SchemaValidationService } = validationServiceMod;
             const validationService = new SchemaValidationService();
-            const _mod_0 = await import('./Schema-J_1f6p0c.js');
+            const _mod_0 = await import('./Schema-BMXRF4j9.js');
             const _ns_0 = _mod_0.a;
             const schemaMod = _ns_0;
             const { Schema } = schemaMod;
@@ -61,7 +61,7 @@ const validateModel = fromCallback(({ sendBack, input: { context }, self }) => {
                 return;
             if (context.schemaName) {
                 try {
-                    const schema = await Schema.find({ schemaName: context.schemaName, waitForReady: false, hold: false });
+                    const schema = await Schema.find({ schemaName: context.schemaName, waitForReady: false });
                     if (!schema)
                         throw new Error(`No schema named "${context.schemaName}"`);
                     const schemaSnapshot = schema.getService().getSnapshot();
@@ -320,7 +320,7 @@ async function createModelProperties(model, propertyDefinitions) {
         throw new Error('Model ID, file ID, and name are required to create properties');
     }
     logger$f(`Creating ${Object.keys(propertyDefinitions).length} properties for model "${modelName}" (id: ${_dbId})`);
-    const { ModelProperty } = await import('./ModelProperty-BlaEgb_U.js');
+    const { ModelProperty } = await import('./ModelProperty-D2vJozmW.js');
     const { and, eq } = await import('drizzle-orm');
     const db = BaseDb.getAppDb();
     for (const [propName, propData] of Object.entries(propertyDefinitions)) {
@@ -338,8 +338,8 @@ async function createModelProperties(model, propertyDefinitions) {
             : undefined;
         // Otherwise use provided ID or generate a random one
         // IDs should be generated in the import process before creating properties
-        const _mod_1 = await import('./tabEvents-CaVmngqr.js');
-        const _ns_1 = _mod_1.bi;
+        const _mod_1 = await import('./tabEvents-DT5ez6io.js');
+        const _ns_1 = _mod_1.bl;
         const { generateId } = _ns_1;
         const propertyFileId = propData.id || propertyRecord?.schemaFileId || generateId();
         logger$f(`Creating property "${propName}" with fileId "${propertyFileId}"`);
@@ -356,8 +356,8 @@ async function createModelProperties(model, propertyDefinitions) {
                 }
                 else if (refModelName) {
                     // Fallback: resolve the ref by name within this model's schema
-                    const _mod_2 = await import('./tabEvents-CaVmngqr.js');
-                    const _ns_2 = _mod_2.be;
+                    const _mod_2 = await import('./tabEvents-DT5ez6io.js');
+                    const _ns_2 = _mod_2.bh;
                     const { resolveModelRecord } = _ns_2;
                     const refModelRecord = await resolveModelRecord(refModelName, { schemaName }, db);
                     if (refModelRecord?.id) {
@@ -405,8 +405,8 @@ async function createModelProperties(model, propertyDefinitions) {
             _dbId: propertyRecord?.schemaFileId === propertyFileId
                 ? propertyRecord.id
                 : undefined, // Already persisted: skip the write
-        }, { schemaName, hold: false }); // Use 'as any' because _propertyFileId is not in TProperty type
-        // The model keeps its properties; an app's unload of the same instance doesn't stop them.
+        }, { schemaName }); // Use 'as any' because _propertyFileId is not in TProperty type
+        // The model holds its properties (a child hold), released when the model is destroyed or evicted
         ModelProperty.holdForModel(property, model);
     }
     logger$f(`Created all properties for model "${modelName}"`);
@@ -452,7 +452,7 @@ const write = async (input) => {
         });
     }
     // Imported here: the validation service imports the Schema barrel, which imports this module's callers
-    const { SchemaValidationService } = await import('./SchemaValidationService-CnmKyzR-.js');
+    const { SchemaValidationService } = await import('./SchemaValidationService-CieGrj5c.js');
     const data = input.data();
     const { errors } = new SchemaValidationService().validatePropertyStructure(data);
     if (errors.length > 0) {
@@ -613,7 +613,7 @@ const createPropertyInstances = async (propertyFileIds, since) => {
         return;
     }
     try {
-        const mod = await import('./ModelProperty-BlaEgb_U.js');
+        const mod = await import('./ModelProperty-D2vJozmW.js');
         const ModelProperty = mod?.ModelProperty ?? mod?.default;
         if (!ModelProperty) {
             logger$d('createPropertyInstances: ModelProperty not available from dynamic import');
@@ -684,10 +684,10 @@ async function loadModel(context, isStopped) {
             if (!modelRecord) {
                 // Model names are only unique per schema: prefer this schema's row, and otherwise only
                 // consider same-name rows that no schema claims yet (never another schema's model).
-                const _mod_3 = await import('./BaseFileManager-BAlySv8w.js');
+                const _mod_3 = await import('./BaseFileManager-DLou1TZS.js');
                 const _ns_3 = _mod_3.M;
                 const { modelSchemas } = _ns_3;
-                const _mod_4 = await import('./BaseFileManager-BAlySv8w.js');
+                const _mod_4 = await import('./BaseFileManager-DLou1TZS.js');
                 const _ns_4 = _mod_4.z;
                 const { schemas: schemasTable } = _ns_4;
                 let dbModels = await db
@@ -827,13 +827,13 @@ async function loadModel(context, isStopped) {
     // Step 2: Fallback to Schema context (only if database doesn't have the model)
     // This handles the case where model exists in schema file but not yet in database
     try {
-        const _mod_5 = await import('./Schema-J_1f6p0c.js');
+        const _mod_5 = await import('./Schema-BMXRF4j9.js');
         const _ns_5 = _mod_5.a;
         const { Schema } = _ns_5;
         // Stopped meanwhile (unloaded, or evicted with its schema): don't load the schema again
         if (isStopped())
             throw new Error('the model was unloaded while it loaded');
-        const schema = Schema.create(schemaName, { waitForReady: false, hold: false });
+        const schema = Schema.create(schemaName, { waitForReady: false });
         // A schema still loading: its models are known once it has loaded
         await schema.waitForReady();
         const schemaContext = schema.getService().getSnapshot().context;
@@ -912,11 +912,11 @@ async function loadModel(context, isStopped) {
                 }
                 // Also check database for models (in case they're persisted but not in Schema context)
                 if (db) {
-                    const _mod_6 = await import('./BaseFileManager-BAlySv8w.js');
+                    const _mod_6 = await import('./BaseFileManager-DLou1TZS.js');
                     const _ns_6 = _mod_6.M;
                     const modelSchemaSchemaMod = _ns_6;
                     const { modelSchemas } = modelSchemaSchemaMod;
-                    const _mod_7 = await import('./BaseFileManager-BAlySv8w.js');
+                    const _mod_7 = await import('./BaseFileManager-DLou1TZS.js');
                     const _ns_7 = _mod_7.z;
                     const schemaSchemaMod = _ns_7;
                     const { schemas: schemasTable } = schemaSchemaMod;
@@ -995,11 +995,11 @@ async function loadModel(context, isStopped) {
     }
     // Mark schema as draft when a new model is created so saveNewVersion() can persist it
     try {
-        const _mod_8 = await import('./Schema-J_1f6p0c.js');
+        const _mod_8 = await import('./Schema-BMXRF4j9.js');
         const _ns_8 = _mod_8.a;
         const { Schema } = _ns_8;
         if (!isStopped()) {
-            const schema = Schema.create(schemaName, { waitForReady: false, hold: false });
+            const schema = Schema.create(schemaName, { waitForReady: false });
             schema.getService().send({ type: 'markAsDraft', propertyKey: 'schema:models' });
         }
     }
@@ -1089,7 +1089,7 @@ const saveDraftLogger = debug('seedSdk:model:saveDraftToDb');
 // Lazy import cache for ModelProperty to avoid circular dependency
 // Eagerly start loading to minimize delay on first access
 let ModelPropertyClass = null;
-const modelPropertyImportPromise = import('./ModelProperty-BlaEgb_U.js')
+const modelPropertyImportPromise = import('./ModelProperty-D2vJozmW.js')
     .then(module => {
     ModelPropertyClass = module.ModelProperty;
     return ModelPropertyClass;
@@ -1319,7 +1319,7 @@ class Model {
         }
         const waitForReady = options?.waitForReady !== false;
         const readyTimeout = options?.readyTimeout ?? DEFAULT_READY_TIMEOUT_MS;
-        const holds = options?.hold === false ? 0 : 1;
+        const holds = options?.hold === true;
         // Extract schema name and instance
         let schemaName;
         let schemaInstance; // Using any to avoid circular dependency with Schema
@@ -1344,7 +1344,7 @@ class Model {
             logger$c(`Model.create: Found instance in ID cache for "${modelName}" (ID: ${id})`);
             if (!waitForReady)
                 return cachedById;
-            return waitForEntityReady(cachedById, { timeout: readyTimeout }).then(() => cachedById);
+            return Model.readyOrRelease(cachedById, readyTimeout, holds);
         }
         // A runtime create (no id) gets a new model, numbered when the name is taken ("My Model 1");
         // a schema model (with id) keeps its name.
@@ -1364,6 +1364,7 @@ class Model {
         }
         // Wrap instance in Proxy for reactive property access. `name` is an alias for `modelName`.
         const sendUpdate = (target, prop, value) => {
+            target._assertLoaded(`set ${prop} on`);
             if (prop === 'modelName') {
                 // Model name change - need to update Schema and database
                 const context = target._getSnapshotContext();
@@ -1427,7 +1428,7 @@ class Model {
         });
         // A runtime create gets its name key once its load settles the name (it may be numbered)
         this.cache.add(proxiedInstance, [resolvedId, id ? modelKey(schemaName, uniqueModelName) : undefined], {
-            hold: holds === 1,
+            hold: holds,
         });
         logger$c(`Model.create: Created new instance for "${uniqueModelName}" (ID: ${id})`);
         // Step 11: Register with schema if requested, OR trigger write if properties are provided
@@ -1465,36 +1466,54 @@ class Model {
         });
         if (!waitForReady)
             return proxiedInstance;
-        return waitForEntityReady(proxiedInstance, { timeout: readyTimeout }).then(() => proxiedInstance);
+        return Model.readyOrRelease(proxiedInstance, readyTimeout, holds);
     }
-    /**
-     * Get Model instance by modelFileId (O(1) lookup). Takes a hold on the instance; release it with
-     * `unload()`.
-     */
-    static getById(modelFileId) {
-        return this.cache.hold(modelFileId);
+    /** The model once ready; a call that took a hold gives it back when the model isn't ready in time. */
+    static async readyOrRelease(model, timeout, held) {
+        try {
+            await waitForEntityReady(model, { timeout });
+        }
+        catch (error) {
+            if (held)
+                model.unload();
+            throw error;
+        }
+        return model;
+    }
+    /** The cached Model with this modelFileId. Takes no hold unless `hold: true`. */
+    static getById(modelFileId, options) {
+        return options?.hold ? this.cache.hold(modelFileId) : this.cache.peek(modelFileId);
     }
     /**
-     * The cached Model with this modelFileId, without taking a hold. For SDK code that reads the
-     * model and doesn't hand it to a caller; callers that keep it use `getById`, `find` or `create`.
+     * The cached Model with this modelFileId, without taking a hold.
      */
     static peek(modelFileId) {
         return this.cache.peek(modelFileId);
     }
     /**
-     * Get Model instance by name (O(1) lookup via name→ID mapping). Takes a hold on the instance;
-     * release it with `unload()`.
+     * Takes one more hold on a cached, running instance, released with `unload()`. False (and no
+     * hold) when the instance isn't cached or was stopped.
+     */
+    static retain(instance) {
+        return instance.getService().getSnapshot().status === 'active' && this.cache.holdInstance(instance);
+    }
+    /**
+     * Get Model instance by name (O(1) lookup via name→ID mapping). Takes no hold unless `hold: true`.
      *
      * @param modelName - The name of the model
      * @param schemaName - The schema name (optional, will query DB if not provided)
      * @returns The Model instance if found, undefined otherwise
      */
-    static getByName(modelName, schemaName) {
+    static getByName(modelName, schemaName, options) {
         const model = this.peekByName(modelName, schemaName);
-        return model && this.cache.holdInstance(model) ? model : undefined;
+        if (!model)
+            return undefined;
+        if (options?.hold)
+            this.cache.holdInstance(model);
+        return model;
     }
     /**
-     * `getByName` without taking a hold. Without `schemaName` it searches every cached schema and
+     * The cached Model by name, without taking a hold. Without `schemaName` it searches every cached schema and
      * throws AmbiguousModelError when models from several schemas share the name; callers that know
      * the schema or model id should use Model.resolve() instead.
      */
@@ -1579,8 +1598,8 @@ class Model {
             if (db) {
                 const since = evictionLog.now();
                 try {
-                    const _mod_9 = await import('./tabEvents-CaVmngqr.js');
-                    const _ns_9 = _mod_9.be;
+                    const _mod_9 = await import('./tabEvents-DT5ez6io.js');
+                    const _ns_9 = _mod_9.bh;
                     const { resolveModelRecord, getModelSchemaName } = _ns_9;
                     const resolved = scope.modelFileId
                         ? await resolveModelRecord(undefined, { modelFileId: scope.modelFileId }, db)
@@ -1594,7 +1613,7 @@ class Model {
                         // Its schema was evicted, or it was destroyed, while we read the row: don't bring it back.
                         if (evictionLog.evictedSince([`schema:${record.schemaName}`, `model:${record.modelFileId}`], since))
                             return undefined;
-                        return this.create(record.modelName, record.schemaName, { id: record.modelFileId, hold: false });
+                        return this.create(record.modelName, record.schemaName, { id: record.modelFileId });
                     }
                 }
                 catch (error) {
@@ -1602,7 +1621,7 @@ class Model {
                 }
             }
         }
-        return modelName ? this.getByNameAsync(modelName, undefined, { hold: false }) : undefined;
+        return modelName ? this.getByNameAsync(modelName) : undefined;
     }
     /**
      * Get Model instance by name, querying database if not in cache
@@ -1610,11 +1629,11 @@ class Model {
      *
      * @param modelName - The name of the model
      * @param schemaName - Optional schema name (will query DB if not provided)
-     * @returns The Model instance if found, undefined otherwise. Takes a hold unless `hold: false`.
+     * @returns The Model instance if found, undefined otherwise. Takes no hold unless `hold: true`.
      */
     static async getByNameAsync(modelName, schemaName, options) {
         // First try cache
-        const cached = options?.hold === false ? this.peekByName(modelName, schemaName) : this.getByName(modelName, schemaName);
+        const cached = this.getByName(modelName, schemaName, options);
         if (cached) {
             return cached;
         }
@@ -1626,8 +1645,8 @@ class Model {
         }
         const since = options?.since ?? evictionLog.now();
         try {
-            const _mod_10 = await import('./tabEvents-CaVmngqr.js');
-            const _ns_10 = _mod_10.be;
+            const _mod_10 = await import('./tabEvents-DT5ez6io.js');
+            const _ns_10 = _mod_10.bh;
             const { resolveModelRecord, getModelSchemaName } = _ns_10;
             const resolved = await resolveModelRecord(modelName, schemaName ? { schemaName, strict: true } : {}, db);
             if (!resolved?.schemaFileId) {
@@ -1644,7 +1663,7 @@ class Model {
             // Create model instance (will be cached)
             return this.create(resolved.name, recordSchemaName, {
                 id: resolved.schemaFileId, // id is now the schemaFileId (string)
-                ...(options?.hold === false && { hold: false }),
+                hold: options?.hold,
             });
         }
         catch (error) {
@@ -1659,14 +1678,14 @@ class Model {
      * Checks cache first, then database if not found
      *
      * @param modelFileId - The model file ID to look up
-     * @returns The Model instance if found, undefined otherwise
+     * @returns The Model instance if found, undefined otherwise. Takes no hold unless `hold: true`.
      */
     static async createById(modelFileId, options) {
         if (!modelFileId) {
             return undefined;
         }
         // Step 1: Check cache first (fast path)
-        const cached = options?.hold === false ? this.peek(modelFileId) : this.getById(modelFileId);
+        const cached = this.getById(modelFileId, options);
         if (cached) {
             logger$c(`Model.createById: Found instance in cache for ID "${modelFileId}"`);
             return cached;
@@ -1711,7 +1730,7 @@ class Model {
             logger$c(`Model.createById: Creating model "${modelName}" in schema "${schemaName}" from ID "${modelFileId}"`);
             return this.create(modelName, schemaName, {
                 id: modelFileId, // id is now the schemaFileId (string)
-                ...(options?.hold === false && { hold: false }),
+                hold: options?.hold,
             });
         }
         catch (error) {
@@ -1721,18 +1740,27 @@ class Model {
     }
     /**
      * Find Model instance by modelFileId, modelName/schemaName, or both
-     * Waits for the model to be fully loaded (idle state) by default
+     * Waits for the model to be fully loaded (idle state) by default. Takes no hold unless
+     * `hold: true`; a call that throws (the model isn't ready in `readyTimeout`) keeps none.
      * @param options - Find options including lookup parameters and wait configuration
      * @returns Model instance if found, undefined otherwise
      */
-    static async find({ modelFileId, modelName, schemaName, waitForReady = true, readyTimeout = DEFAULT_READY_TIMEOUT_MS, }) {
+    static async find({ modelFileId, modelName, schemaName, waitForReady = true, readyTimeout = DEFAULT_READY_TIMEOUT_MS, hold = false, }) {
         const model = modelFileId
-            ? (Model.getById(modelFileId) ?? (await Model.createById(modelFileId)))
+            ? await Model.createById(modelFileId, { hold })
             : modelName
-                ? (Model.getByName(modelName, schemaName) ?? (await Model.getByNameAsync(modelName, schemaName)))
+                ? await Model.getByNameAsync(modelName, schemaName, { hold })
                 : undefined;
-        if (model && waitForReady)
-            await waitForEntityReady(model, { timeout: readyTimeout });
+        if (model && waitForReady) {
+            try {
+                await waitForEntityReady(model, { timeout: readyTimeout });
+            }
+            catch (error) {
+                if (hold)
+                    model.unload();
+                throw error;
+            }
+        }
         return model;
     }
     /**
@@ -1740,9 +1768,9 @@ class Model {
      * Queries database for all models with the given schemaId/schemaName and returns Model instances
      *
      * @param schemaIdentifier - The schema file ID or schema name to get models for
-     * @returns Array of Model instances for the schema
+     * @returns Array of Model instances for the schema. Takes no holds unless `hold: true`.
      */
-    static async createBySchemaId(schemaIdentifier) {
+    static async createBySchemaId(schemaIdentifier, options) {
         if (!schemaIdentifier) {
             return [];
         }
@@ -1779,7 +1807,7 @@ class Model {
                     continue;
                 }
                 // Check cache first
-                const cached = this.getById(record.modelFileId);
+                const cached = this.getById(record.modelFileId, options);
                 if (cached) {
                     modelInstances.push(cached);
                 }
@@ -1788,6 +1816,7 @@ class Model {
                     const model = this.create(record.modelName, record.schemaName, {
                         id: record.modelFileId, // id is now the schemaFileId (string)
                         waitForReady: false,
+                        hold: options?.hold,
                     });
                     modelInstances.push(model);
                 }
@@ -1804,22 +1833,27 @@ class Model {
      * Get all Model instances, optionally filtered by schema.
      * When DB is available, loads from DB via getModelsData; otherwise returns from cache.
      * With waitForReady, waits for each model to be ready (idle, with any properties from Model.create
-     * created) and leaves out models that error or time out. Takes no holds: a caller that keeps a
-     * model uses `Model.find` or `Model.create`.
+     * created) and leaves out models that error or time out. Takes no holds unless `hold: true`.
      */
     static async all(schemaName, options) {
-        const { waitForReady = false, readyTimeout = DEFAULT_READY_TIMEOUT_MS } = options ?? {};
+        const { waitForReady = false, readyTimeout = DEFAULT_READY_TIMEOUT_MS, hold = false } = options ?? {};
+        const held = (models) => {
+            if (hold)
+                for (const model of models)
+                    this.cache.holdInstance(model);
+            return models;
+        };
         const appDb = BaseDb.getAppDb();
         const inSchema = (model) => !schemaName || model._getSnapshotContext().schemaName === schemaName;
         if (!appDb)
-            return this.cache.instances(inSchema);
+            return held(this.cache.instances(inSchema));
         const rows = await getModelsData(schemaName);
         const instances = [];
         const seen = new Set();
         for (const row of rows) {
             // A model can appear more than once (e.g. duplicate model_schemas links); return it once.
             if (row.schemaFileId && !seen.has(row.schemaFileId)) {
-                const instance = await this.createById(row.schemaFileId, { hold: false });
+                const instance = await this.createById(row.schemaFileId);
                 if (instance && !seen.has(instance.id ?? row.schemaFileId)) {
                     instances.push(instance);
                     seen.add(instance.id ?? row.schemaFileId);
@@ -1843,9 +1877,17 @@ class Model {
                 logger$c(`Model.all: leaving out a model that isn't ready: ${error instanceof Error ? error.message : String(error)}`);
                 return false;
             })));
-            return instances.filter((_, i) => ready[i]);
+            return held(instances.filter((_, i) => ready[i]));
         }
-        return instances;
+        return held(instances);
+    }
+    /** Throws EntityUnloadedError, naming the model, when this instance was destroyed or evicted. */
+    _assertLoaded(action) {
+        if (!isEntityTornDown(this))
+            return;
+        const { modelName, schemaName, id } = this._getSnapshotContext();
+        throw new EntityUnloadedError(`Cannot ${action} model ${schemaName ?? '?'}.${modelName ?? '?'} (${id ?? 'no id'}): this Model instance was ` +
+            'destroyed or evicted. Look the model up again (Model.find).');
     }
     getService() {
         return this._service;
@@ -2033,6 +2075,7 @@ class Model {
      * @returns The created item instance
      */
     async create(values) {
+        this._assertLoaded('create an item of');
         if (!this.modelName) {
             throw new Error('Cannot create item: model name is not set on this Model instance');
         }
@@ -2049,6 +2092,7 @@ class Model {
      * This refreshes the actor context with the latest data from the database
      */
     async reload() {
+        this._assertLoaded('reload');
         logger$c(`Reloading model ${this.modelName} from database`);
         await runEntityLoad(this, () => Model.load(this));
         if (this.status === 'error')
@@ -2072,7 +2116,10 @@ class Model {
         }
         return evictedNames;
     }
-    /** Release this caller's hold. The model is stopped and leaves the cache with its last hold. */
+    /**
+     * Release this caller's hold, if it took one. The model stays cached (see `Model.cache`); only
+     * `destroy`, eviction or client stop stop it.
+     */
     unload() {
         releaseEntity(this, Model.cache);
     }
@@ -2099,9 +2146,9 @@ class Model {
                         .limit(1);
                     if (modelRecord) {
                         const modelId = modelRecord.id;
-                        const { detachModelRows } = await import('./detachRowsBeforeDelete-sEaUwlOU.js');
-                        const _mod_11 = await import('./tabEvents-CaVmngqr.js');
-                        const _ns_11 = _mod_11.bg;
+                        const { detachModelRows } = await import('./detachRowsBeforeDelete-BZr_0iZU.js');
+                        const _mod_11 = await import('./tabEvents-DT5ez6io.js');
+                        const _ns_11 = _mod_11.bj;
                         const { inDefinitionsTransaction } = _ns_11;
                         // The model's rows go together or not at all
                         await inDefinitionsTransaction(async (tx) => {
@@ -2117,10 +2164,10 @@ class Model {
                 getModelProperty()?.evictForModel({ modelName, schemaName, modelId: dbId });
                 if (schemaName && modelName) {
                     // Imported here, not at module load: Model and Schema import each other.
-                    const _mod_12 = await import('./Schema-J_1f6p0c.js');
+                    const _mod_12 = await import('./Schema-BMXRF4j9.js');
                     const _ns_12 = _mod_12.a;
                     const { Schema } = _ns_12;
-                    const schema = await Schema.find({ schemaName, waitForReady: false, hold: false });
+                    const schema = await Schema.find({ schemaName, waitForReady: false });
                     const schemaContext = schema?.getService().getSnapshot().context;
                     if (schema && schemaContext?.models?.[modelName]) {
                         const updatedModels = { ...schemaContext.models };
@@ -2156,8 +2203,8 @@ class Model {
                             return undefined;
                         }
                         // Model names are only unique per schema: find this model's row by its id (schemaFileId).
-                        const _mod_13 = await import('./tabEvents-CaVmngqr.js');
-                        const _ns_13 = _mod_13.be;
+                        const _mod_13 = await import('./tabEvents-DT5ez6io.js');
+                        const _ns_13 = _mod_13.bh;
                         const { resolveModelRecord } = _ns_13;
                         const modelRecord = await resolveModelRecord(modelName, { modelFileId: context.id, schemaName: context.schemaName }, db);
                         if (!modelRecord?.id) {
@@ -2322,8 +2369,12 @@ class Model {
         }
     }
 }
-/** Cached under its id and `schemaName:modelName` (ADR 0014). */
-Model.cache = new EntityCache();
+/**
+ * Cached under its id and `schemaName:modelName` (ADR 0014). Stays cached with no holds until it
+ * is destroyed or evicted (`unloadUnheld: false`): Model.resolve, findByModelType and sync read
+ * the cache synchronously.
+ */
+Model.cache = new EntityCache({ unloadUnheld: false });
 
 var Model$1 = /*#__PURE__*/Object.freeze({
     __proto__: null,
@@ -2534,7 +2585,7 @@ function toRunSyncArg(options) {
     return undefined;
 }
 const runEasSync = fromPromise(async ({ input, }) => {
-    const { runSyncFromEas } = await import('./syncDbWithEas-CA7PvBgu.js');
+    const { runSyncFromEas } = await import('./syncDbWithEas-FuyqoEKk.js');
     // Sync checks for rows and then inserts the rest (no unique index on uids), so syncs in
     // different tabs take turns. A sync can run for minutes, so wait without a timeout.
     await withDbTabLock('eas-sync', async () => {
@@ -2867,7 +2918,7 @@ async function platformClassesInit({ event }) {
     if (!config) {
         throw new Error('client.init requires a config');
     }
-    const { configurePlatform } = await import('./configurePlatform-CiOJ1R3q.js');
+    const { configurePlatform } = await import('./configurePlatform-WkmvqeTO.js');
     if (isBrowser()) {
         const { createPlatformServices } = await import('./platform.browser.js');
         configurePlatform(createPlatformServices());
@@ -3154,7 +3205,7 @@ async function addModelsToDb(context) {
                     timeout = setTimeout(() => reject(new Error('EAS query timeout after 10 seconds')), 10000);
                 });
                 // The lookup and the model_uids rule sync uses too (each name at its nameMatch level).
-                const { getModelSchemasFromEas } = await import('./eas-wB_fQ8Tc.js');
+                const { getModelSchemasFromEas } = await import('./eas-FZPPqxqe.js');
                 const lookups = await localModelSchemaLookups([...modelNamesWithRows]);
                 // Cleared, so a finished lookup doesn't keep a Node process alive for 10 s.
                 const schemas = await Promise.race([getModelSchemasFromEas(lookups), timeoutPromise]).finally(() => clearTimeout(timeout));
@@ -3737,7 +3788,7 @@ function schemaFilePropertyDefinition(modelName, propName, prop) {
         dataType: def.dataType,
         ref: hasRef ? def.ref : undefined,
         refModelName: hasRef ? def.refModelName : undefined,
-        refValueType: isList ? def.refValueType : undefined,
+        refValueType: hasRef ? def.refValueType : undefined,
         storageType: def.storageType,
         localStorageDir: def.localStorageDir,
         filenameSuffix: def.filenameSuffix,
@@ -3771,14 +3822,12 @@ async function createModelsForSchemaFile(file) {
     const result = {};
     for (const [modelName, model] of Object.entries(file.models)) {
         const modelFileId = model.id;
-        // No hold: a loaded Schema holds its models (loadOrCreateSchema)
         result[modelName] = Model.create(modelName, file.metadata.name, {
             modelFileId,
             id: modelFileId,
             properties: definitions.get(modelName) ?? {},
             waitForReady: false,
             persistedBy: Promise.resolve(),
-            hold: false,
         });
     }
     return result;
@@ -3871,8 +3920,8 @@ async function applySchemaFile(source, options = {}) {
     if (!schemaRecord) {
         warnOnEasNameCollisions(file);
         warnOnInvalidNameMatch(file);
-        const _mod_14 = await import('./tabEvents-CaVmngqr.js');
-        const _ns_14 = _mod_14.bh;
+        const _mod_14 = await import('./tabEvents-DT5ez6io.js');
+        const _ns_14 = _mod_14.bk;
         const { addModelsToDb, broadcastSchemasInvalidate } = _ns_14;
         const modelFileIds = new Map(Object.entries(file.models).map(([name, model]) => [name, model.id]));
         const propertyDefinitions = schemaFilePropertyDefinitions(file);
@@ -4023,8 +4072,8 @@ async function resolveSchemaRow(row, db = BaseDb.getAppDb()) {
         metadata: { ...schema.metadata, name: row.name },
     };
     if (row.id && db) {
-        const _mod_15 = await import('./tabEvents-CaVmngqr.js');
-        const _ns_15 = _mod_15.bh;
+        const _mod_15 = await import('./tabEvents-DT5ez6io.js');
+        const _ns_15 = _mod_15.bk;
         const { loadModelsFromDbForSchema, mergeDbModelsIntoSchemaModels } = _ns_15;
         const dbModels = await loadModelsFromDbForSchema(row.id, db);
         if (Object.keys(dbModels).length > 0) {
@@ -4603,6 +4652,10 @@ function startCanonicalizeModelTypes() {
         void runInBackground();
     });
 }
+/** Resolves when a background run has finished (at once if none is running). */
+function whenCanonicalizeModelTypesSettled() {
+    return running ?? Promise.resolve();
+}
 
 const getVersionData = async ({ localId, seedLocalId, uid, }, db = BaseDb.getAppDb()) => {
     const appDb = db;
@@ -4955,8 +5008,8 @@ async function applyStorageValue(seedLocalId, propertyName, value, db, prepared)
     const row = prepared
         ? { ...stored, refResolvedValue: prepared.fileName, schemaUid: prepared.schemaUid, refModelUid: prepared.refModelUid }
         : stored;
-    const _mod_16 = await import('./Item-Bf4kWKpH.js');
-    const _ns_16 = _mod_16.b1;
+    const _mod_16 = await import('./Item-oPnmIehk.js');
+    const _ns_16 = _mod_16.b7;
     const { currentPropertyRow } = _ns_16;
     const existing = await currentPropertyRow({ seedLocalId }, {
         propertyName,
@@ -5269,8 +5322,8 @@ function startItemOutbox() {
                     return {};
                 // Cached, shared with item creation, so a save doesn't wait on the EAS indexer each time.
                 // Not required for the row; publish resolves the schema again.
-                const _mod_17 = await import('./Item-Bf4kWKpH.js');
-                const _ns_17 = _mod_17.b4;
+                const _mod_17 = await import('./Item-oPnmIehk.js');
+                const _ns_17 = _mod_17.ba;
                 const { lookupPropertySchemaUid } = _ns_17;
                 return {
                     schemaUid: await lookupPropertySchemaUid(op.propertyName, value.propertyRecordSchema),
@@ -6251,23 +6304,52 @@ const ensureInitialized = () => {
 };
 const CLIENT_ALREADY_STOPPED_WARNING = 'client.stop() or client.unload() was called after the client had already stopped; this call does nothing. ' +
     'Remove the extra call, or call client.init() before stopping again.';
-/** Shared by stop() and unload(). A repeat call after a stop warns and does nothing. */
-const stopClient = ({ unsubscribe }) => {
+/** Set while a stop releases the client's resources; init waits for it. */
+let stopping;
+/**
+ * Shared by stop() and unload(). Stops the client in any state, including after a failed or
+ * unfinished init, then releases what it holds: the outbox drain, cached entities, this tab's
+ * leadership and the database (closed, so its file is released). A repeat call after a stop warns
+ * and does nothing.
+ */
+const stopClient = async ({ unsubscribe }) => {
     if (clientManager.getSnapshot().status === 'stopped') {
         console.warn(CLIENT_ALREADY_STOPPED_WARNING);
         return;
     }
-    ensureInitialized();
     activeInitConfig = undefined;
     cancelAllRetriesWhenOnline();
     unregisterSeedQueryLocalSource();
     resetAddressesPersistedAnnouncement();
+    // The next init sets its own period. Instances waiting out this one are evicted with the rest
+    // (releaseClientResources), which cancels their timers.
+    setEntityUnloadGraceMs(undefined);
     clientManager.stop();
     if (unsubscribe)
         subscription.unsubscribe();
     notifyServiceListeners();
+    const releasing = releaseClientResources();
+    stopping = releasing;
+    try {
+        await releasing;
+    }
+    finally {
+        if (stopping === releasing)
+            stopping = undefined;
+    }
+};
+const releaseClientResources = async () => {
+    await stopOutbox();
+    await whenCanonicalizeModelTypesSettled();
+    // Before the database closes, so their live queries end first.
+    evictAllEntities();
+    stopTabCoordination();
+    await BaseDb.close();
 };
 const coalescedInit = createCoalescedAsync(async (options) => {
+    // A stop still closing the database: open it again only once that's done.
+    if (stopping)
+        await stopping;
     // If the actor is stopped (e.g., from a previous failed test), restart it
     const snapshot = clientManager.getSnapshot();
     const currentState = snapshot.value;
@@ -6302,6 +6384,7 @@ const coalescedInit = createCoalescedAsync(async (options) => {
             }
         });
     }
+    setEntityUnloadGraceMs(options?.config?.entityCache?.unloadGraceMs);
     // The root-level init handler moves to PLATFORM_CLASSES_INIT (stopping any running step) as
     // send() returns; the platformClassesInit step fills the context from options.
     clientManager.send({ type: 'init', options });
@@ -6487,7 +6570,12 @@ const clientInstance = {
         });
         return () => subscription.unsubscribe();
     },
+    /**
+     * Stops the client, from any state (a failed init too), and closes the database. Resolves once
+     * everything is released; `init` may be called right away and waits for that.
+     */
     stop: () => stopClient({ unsubscribe: false }),
+    /** As `stop`, and also ends the client's internal state subscription. */
     unload: () => stopClient({ unsubscribe: true }),
 };
 // Export the singleton instance
@@ -6547,4 +6635,4 @@ var errors = /*#__PURE__*/Object.freeze({
 });
 
 export { sendEasSyncClientRequest as $, waitForEasReadChain as A, assertLocalDbChain as B, ConflictError as C, writeModelUids as D, getContentHash as E, saveDefinition as F, EAS_CHAIN_ID_APP_STATE_KEY as G, INIT_CONFIG_CONFLICT_MESSAGE as H, ItemCreateValidationError as I, ItemCreateError as J, claimUnpublishedDrafts as K, createLocalQueryDataSource as L, Model as M, easSyncActor as N, getClient as O, getPublishedSeedRecord as P, getSchemaNameFromId as Q, RelationTargetError as R, SCHEMA_FILE_FORMAT as S, TModelSchema as T, UnknownModelError as U, isSeedQueryLocalSourceRegistered as V, listCompleteSchemaFiles as W, mergeEasSyncRequestIntents as X, registerSeedQueryLocalSource as Y, requestEasSyncFromAddressChange as Z, requestEasSyncFromModelsInit as _, applyCreateItem as a, setRetriesWhenOnlineEnabled as a0, startEasSyncActor as a1, unregisterSeedQueryLocalSource as a2, saveDefinition$1 as a3, Model$1 as a4, schema as a5, SEEDPROTOCOL_Seed_Protocol_v1 as a6, itemAppliers as a7, errors as a8, applyDelete as b, applyItemStorageValue as c, deleteFiles as d, applyStorageValue as e, TModelValues as f, ClientManager as g, syncSchemaFromSource as h, importJsonSchema as i, transformImportToSchemaFile as j, localModelSchemaLookups as k, loadSchemaFromFile as l, listLatestSchemaFiles as m, readSchemaFile as n, applySchemaFile as o, resolveSchemaRow as p, loadAllSchemasFromDb as q, readJsonImportFile as r, startItemOutbox as s, throwItemWriteError as t, getDraftSaveError as u, queueDraftSave as v, writeNextSchemaVersion as w, setupEntityLiveQuery as x, mergeSchemaFiles as y, trackDraftSave as z };
-//# sourceMappingURL=errors-DLSoqSHG.js.map
+//# sourceMappingURL=errors-CnT0fSMK.js.map