@twin.org/entity-storage-service 0.9.2-next.1 → 0.9.2-next.10

package/dist/es/entities/schemaVersion.js

@@ -8,7 +8,7 @@ import { entity, property } from "@twin.org/entity";
  */
 let SchemaVersion = class SchemaVersion {
     /**
-     * The entity schema type name — primary key.
+     * The entity schema type name - primary key.
      */
     schemaName;
     /**

package/dist/es/entities/schemaVersion.js.map

@@ -1 +1 @@
-{"version":3,"file":"schemaVersion.js","sourceRoot":"","sources":["../../../src/entities/schemaVersion.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;GAIG;AAEI,IAAM,aAAa,GAAnB,MAAM,aAAa;IACzB;;OAEG;IAEI,UAAU,CAAU;IAE3B;;OAEG;IAEI,OAAO,CAAU;IAExB;;OAEG;IAEI,SAAS,CAAU;CAC1B,CAAA;AAbO;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;;iDACnB;AAMpB;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;;8CACN;AAMjB;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;;gDACxB;AAjBd,aAAa;IADzB,MAAM,EAAE;GACI,aAAa,CAkBzB","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { entity, property } from \"@twin.org/entity\";\n\n/**\n * Tracks the currently applied schema version for each managed entity schema.\n * One record per schema name. Written once on first boot, then updated after\n * each successful migration.\n */\n@entity()\nexport class SchemaVersion {\n\t/**\n\t * The entity schema type name — primary key.\n\t */\n\t@property({ type: \"string\", isPrimary: true })\n\tpublic schemaName!: string;\n\n\t/**\n\t * The currently deployed version of this schema.\n\t */\n\t@property({ type: \"integer\" })\n\tpublic version!: number;\n\n\t/**\n\t * ISO 8601 timestamp of the last version write.\n\t */\n\t@property({ type: \"string\", format: \"date-time\" })\n\tpublic updatedAt!: string;\n}\n"]}
+{"version":3,"file":"schemaVersion.js","sourceRoot":"","sources":["../../../src/entities/schemaVersion.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;GAIG;AAEI,IAAM,aAAa,GAAnB,MAAM,aAAa;IACzB;;OAEG;IAEI,UAAU,CAAU;IAE3B;;OAEG;IAEI,OAAO,CAAU;IAExB;;OAEG;IAEI,SAAS,CAAU;CAC1B,CAAA;AAbO;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;;iDACnB;AAMpB;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;;8CACN;AAMjB;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;;gDACxB;AAjBd,aAAa;IADzB,MAAM,EAAE;GACI,aAAa,CAkBzB","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { entity, property } from \"@twin.org/entity\";\n\n/**\n * Tracks the currently applied schema version for each managed entity schema.\n * One record per schema name. Written once on first boot, then updated after\n * each successful migration.\n */\n@entity()\nexport class SchemaVersion {\n\t/**\n\t * The entity schema type name - primary key.\n\t */\n\t@property({ type: \"string\", isPrimary: true })\n\tpublic schemaName!: string;\n\n\t/**\n\t * The currently deployed version of this schema.\n\t */\n\t@property({ type: \"integer\" })\n\tpublic version!: number;\n\n\t/**\n\t * ISO 8601 timestamp of the last version write.\n\t */\n\t@property({ type: \"string\", format: \"date-time\" })\n\tpublic updatedAt!: string;\n}\n"]}

package/dist/es/models/ISchemaVersionServiceConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"ISchemaVersionServiceConfig.js","sourceRoot":"","sources":["../../../src/models/ISchemaVersionServiceConfig.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Constructor options config for SchemaVersionService.\n */\nexport interface ISchemaVersionServiceConfig {\n\t/**\n\t * The batch size for processing schema versions.\n\t */\n\tbatchSize?: number;\n}\n"]}
+{"version":3,"file":"ISchemaVersionServiceConfig.js","sourceRoot":"","sources":["../../../src/models/ISchemaVersionServiceConfig.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Constructor options config for SchemaVersionService.\n */\nexport interface ISchemaVersionServiceConfig {\n\t/**\n\t * Whether schema migration is enabled. When false the service detects pending migrations\n\t * and logs a warning for each lagging schema but does not apply any changes.\n\t * @default true\n\t */\n\tenabled?: boolean;\n\n\t/**\n\t * The batch size for processing schema versions.\n\t */\n\tbatchSize?: number;\n}\n"]}

package/dist/es/schemaVersionService.js

@@ -1,5 +1,3 @@
-// Copyright 2026 IOTA Stiftung.
-// SPDX-License-Identifier: Apache-2.0.
 import { ComponentFactory, GeneralError, Is } from "@twin.org/core";
 import { EntitySchemaFactory, EntitySchemaHelper } from "@twin.org/entity";
 import { EntityStorageConnectorFactory, MigrationHelper, SchemaMigrationFactory } from "@twin.org/entity-storage-models";
@@ -8,14 +6,14 @@ import { SchemaVersion } from "./entities/schemaVersion.js";
  * Service that checks and applies entity schema migrations at every node start-up.
  *
  * This service must be the first entry in coreTypeInitialisers.json. The engine iterates that
- * array in order to determine start sequence — there is no engine-level priority mechanism, so
+ * array in order to determine start sequence - there is no engine-level priority mechanism, so
  * registration position is the only guarantee that start() runs before any other service.
  * By the time start() is called, all component bootstraps have completed (every table already
  * exists) and EntitySchemaFactory / EntityStorageConnectorFactory are fully populated with every
  * registered schema and connector.
  *
  * Migration mechanics: old schema versions are registered in EntitySchemaFactory by naming
- * convention — current schema = "MyEntity", first history = "MyEntityV0", second = "MyEntityV1".
+ * convention - current schema = "MyEntity", first history = "MyEntityV0", second = "MyEntityV1".
  * The service groups schemas by base name (strips the trailing V number suffix) and resolves the
  * migration chain automatically by diffing consecutive versioned schemas. For steps that require
  * property renames or a custom transform hook, register an optional ISchemaMigration entry in
@@ -38,6 +36,11 @@ export class SchemaVersionService {
      * @internal
      */
     static _VERSION_SUFFIX_RE = /^(.+)V(\d+)$/;
+    /**
+     * Key used for the global connector-version record in the schema-version table.
+     * @internal
+     */
+    static _CONNECTOR_VERSION_KEY = "connectorVersion";
     /**
      * The connector used to read and write SchemaVersion records.
      * Not readonly because finalizeMigration may return a replacement connector object.
@@ -71,11 +74,15 @@ export class SchemaVersionService {
      * SchemaVersion itself is processed first so the version store is migrated before any
      * version records are written for other schemas.
      *
+     * When config.enabled is false the service runs in detect-only mode: it identifies schemas
+     * that need migration and logs a warning for each one, but applies no changes.
+     *
      * Runs after all component bootstraps, so every managed table already exists.
      * @param nodeLoggingComponentType An optional logging component type.
      */
     async start(nodeLoggingComponentType) {
         const logging = ComponentFactory.getIfExists(nodeLoggingComponentType);
+        const enabled = this._config?.enabled !== false;
         const migrationOptions = {
             batchSize: this._config?.batchSize,
             onProgress: async (progressItem, itemTotal, itemIndex) => {
@@ -104,27 +111,73 @@ export class SchemaVersionService {
         }
         // 2. Read ALL stored version records, paging through the full table.
         const storedVersions = new Map();
+        let storedConnectorVersion;
         let cursor;
         do {
             const queryResult = await this._versionConnector.query(undefined, undefined, undefined, cursor);
             for (const record of queryResult.entities ?? []) {
                 if (Is.object(record)) {
-                    storedVersions.set(record.schemaName, record.version);
+                    if (record.schemaName === SchemaVersionService._CONNECTOR_VERSION_KEY) {
+                        storedConnectorVersion = record.version;
+                    }
+                    else {
+                        storedVersions.set(record.schemaName, record.version);
+                    }
                 }
             }
             cursor = queryResult.cursor;
         } while (Is.stringValue(cursor));
+        if (!enabled) {
+            // Detect-only: compare stored vs declared versions and warn about any lagging schemas.
+            // Schemas with no stored version record are skipped — they are either fresh installs
+            // or pre-tracking tables, neither of which can be diagnosed safely here.
+            for (const [schemaName, schema] of currentSchemas) {
+                const storedVersion = storedVersions.get(schemaName);
+                const currentVersion = EntitySchemaHelper.getVersion(schema);
+                if (!Is.undefined(storedVersion) && storedVersion < currentVersion) {
+                    await logging?.log({
+                        source: SchemaVersionService.CLASS_NAME,
+                        level: "warn",
+                        message: "migrationDisabled",
+                        data: {
+                            schemaName,
+                            from: storedVersion,
+                            to: currentVersion
+                        }
+                    });
+                }
+            }
+            return;
+        }
+        const currentConnectorVersion = await this.calculateConnectorVersion();
+        const effectiveStoredConnectorVersion = storedConnectorVersion ?? 0;
+        const forceUpgradeAllSchemas = effectiveStoredConnectorVersion !== currentConnectorVersion;
+        if (forceUpgradeAllSchemas) {
+            await logging?.log({
+                source: SchemaVersionService.CLASS_NAME,
+                level: "info",
+                message: "connectorVersionUpdated",
+                data: {
+                    from: effectiveStoredConnectorVersion,
+                    to: currentConnectorVersion
+                }
+            });
+        }
         // 3. Process SchemaVersion first so the version store itself is fully migrated
         //    before any version records are written for other schemas.
         const schemaVersionName = "SchemaVersion";
         const schemaVersionSchema = currentSchemas.get(schemaVersionName);
         if (schemaVersionSchema) {
             currentSchemas.delete(schemaVersionName);
-            await this.processSchema(schemaVersionName, schemaVersionSchema, storedVersions, historicalByBase.get(schemaVersionName), migrationOptions, nodeLoggingComponentType, logging);
+            await this.processSchema(schemaVersionName, schemaVersionSchema, storedVersions.get(schemaVersionName), historicalByBase.get(schemaVersionName), forceUpgradeAllSchemas, migrationOptions, nodeLoggingComponentType, logging);
         }
         // 4. Process all remaining schemas.
         for (const [schemaName, schema] of currentSchemas) {
-            await this.processSchema(schemaName, schema, storedVersions, historicalByBase.get(schemaName), migrationOptions, nodeLoggingComponentType, logging);
+            await this.processSchema(schemaName, schema, storedVersions.get(schemaName), historicalByBase.get(schemaName), forceUpgradeAllSchemas, migrationOptions, nodeLoggingComponentType, logging);
+        }
+        if (effectiveStoredConnectorVersion !== currentConnectorVersion ||
+            Is.undefined(storedConnectorVersion)) {
+            await this.writeConnectorVersion(currentConnectorVersion);
         }
     }
     /**
@@ -132,14 +185,15 @@ export class SchemaVersionService {
      * Extracted to avoid continue statements in the outer loop.
      * @param schemaName The base schema name.
      * @param schema The current schema definition.
-     * @param storedVersions The full map of stored version records.
+     * @param storedVersion The full map of stored version records.
      * @param history The versioned-schema map for this schema (historicalByBase.get(schemaName)), or undefined if none exist.
+     * @param forceUpgradeAllSchemas True when any connector version changed and all schemas must re-run connector bootstrap.
      * @param migrationOptions The migration options to pass through to MigrationHelper.
      * @param loggingComponentType The optional component type to use for logging the migration progress.
      * @param logging An optional logging component to pass through to MigrationHelper for migration progress logging.
      * @internal
      */
-    async processSchema(schemaName, schema, storedVersions, history, migrationOptions, loggingComponentType, logging) {
+    async processSchema(schemaName, schema, storedVersion, history, forceUpgradeAllSchemas, migrationOptions, loggingComponentType, logging) {
         const currentVersion = EntitySchemaHelper.getVersion(schema);
         // Find the entity-storage connector whose schema type matches this schema name.
         // For SchemaVersion itself, use the injected connector directly rather than re-discovering
@@ -148,39 +202,69 @@ export class SchemaVersionService {
             ? { connector: this._versionConnector, factoryKey: undefined }
             : this.findConnector(schemaName);
         if (!connectorEntry) {
-            // No connector registered for this schema — nothing to migrate.
+            // No connector registered for this schema - nothing to migrate.
             return;
         }
         const { connector, factoryKey } = connectorEntry;
         // Resolve the stored version, applying the backwards-compat baseline when no record exists.
-        const stored = storedVersions.get(schemaName);
         let resolvedStoredVersion;
-        if (stored === undefined) {
-            // No version record: treat as v0 regardless of whether the table has data.
-            // On SQL connectors the table may have a stale column structure even when empty;
-            // running the chain over zero rows still calls finalizeMigration, which reconciles
-            // the table shape via a connector swap.
-            // Deployment precondition: any pre-existing data is genuinely at v0. A deployment
-            // that hand-applied a later schema before this service was introduced would be
-            // incorrectly replayed v0→…→current and should be seeded with an explicit record.
+        // Captured when the fresh-vs-legacy check below already resolved the connector's
+        // partitions, so migrateWithChain can reuse them instead of fetching them again.
+        let partitions;
+        const migrationConnector = connector;
+        const boundGetPartitionContextIds = migrationConnector.getPartitionContextIds?.bind(migrationConnector);
+        if (Is.function(boundGetPartitionContextIds)) {
+            partitions = await boundGetPartitionContextIds();
+        }
+        if (storedVersion === undefined) {
+            // No version record: check whether the table has any data.
+            // Empty table → this is a fresh bootstrap; seed at the current version so the
+            // migration chain never runs over an already-current-shape (or empty) table.
+            // Non-empty table → pre-existing data from before version tracking was introduced;
+            // treat as v0 and run the migration chain. applyEntityTransform preserves existing
+            // property values so current-shape rows are not degraded.
+            let hasExistingData;
+            if (Is.undefined(partitions)) {
+                // Connector does not have partitioning, so we can safely call count.
+                hasExistingData = (await connector.count()) > 0;
+            }
+            else {
+                // Connector has partitioning, if there are partition keys
+                // then it must have data, otherwise the table is empty.
+                hasExistingData = partitions.length > 0;
+            }
+            if (!hasExistingData) {
+                await this.writeVersion(schemaName, currentVersion);
+                return;
+            }
             resolvedStoredVersion = 0;
             await this.writeVersion(schemaName, 0);
         }
         else {
-            resolvedStoredVersion = stored;
+            resolvedStoredVersion = storedVersion;
         }
         // No-op: stored version already matches current.
         if (resolvedStoredVersion === currentVersion) {
+            if (!forceUpgradeAllSchemas) {
+                await logging?.log({
+                    source: SchemaVersionService.CLASS_NAME,
+                    level: "info",
+                    message: "noMigrationRequired",
+                    data: {
+                        schemaName,
+                        version: resolvedStoredVersion
+                    }
+                });
+                return;
+            }
             await logging?.log({
                 source: SchemaVersionService.CLASS_NAME,
                 level: "info",
-                message: "noMigrationRequired",
+                message: "connectorVersionForceUpgrade",
                 data: {
-                    schemaName,
-                    version: resolvedStoredVersion
+                    schemaName
                 }
             });
-            return;
         }
         await logging?.log({
             source: SchemaVersionService.CLASS_NAME,
@@ -192,7 +276,7 @@ export class SchemaVersionService {
                 to: currentVersion
             }
         });
-        // Downgrade — not supported.
+        // Downgrade - not supported.
         if (resolvedStoredVersion > currentVersion) {
             throw new GeneralError(SchemaVersionService.CLASS_NAME, "storedVersionNewer", {
                 schemaName,
@@ -209,8 +293,7 @@ export class SchemaVersionService {
                 current: currentVersion
             });
         }
-        const migrationConnector = connector;
-        // Upgrade — resolve and run the chain.
+        // Upgrade - resolve and run the chain.
         const steps = [];
         for (let v = resolvedStoredVersion; v < currentVersion; v++) {
             const fromSchema = history?.get(v);
@@ -242,7 +325,7 @@ export class SchemaVersionService {
                 transformEntityProperty: override?.transformEntityProperty
             });
         }
-        const { finalConnector } = await MigrationHelper.migrateWithChain(migrationConnector, schemaName, steps, migrationOptions, loggingComponentType);
+        const { finalConnector } = await MigrationHelper.migrateWithChain(migrationConnector, schemaName, partitions, steps, migrationOptions, loggingComponentType);
         // Some connectors (e.g. in-memory) return a brand-new object from finalizeMigration
         // rather than mutating the source in place.  Re-register the factory entry so that any
         // subsequent EntityStorageConnectorFactory.get() call returns the migrated instance.
@@ -273,6 +356,35 @@ export class SchemaVersionService {
             updatedAt: new Date().toISOString()
         });
     }
+    /**
+     * Upserts the global connector-version record.
+     * @param connectorVersion The connector implementation version.
+     * @internal
+     */
+    async writeConnectorVersion(connectorVersion) {
+        await this._versionConnector.set({
+            schemaName: SchemaVersionService._CONNECTOR_VERSION_KEY,
+            version: connectorVersion,
+            updatedAt: new Date().toISOString()
+        });
+    }
+    /**
+     * Get the global connector version from a migration-capable connector.
+     * Missing connectorVersion support is treated as version 0.
+     * @returns The connector version.
+     * @internal
+     */
+    async calculateConnectorVersion() {
+        if (!this._versionConnector || !("connectorVersion" in this._versionConnector)) {
+            return 0;
+        }
+        const connector = this._versionConnector;
+        const boundConnectorVersion = connector.connectorVersion.bind(connector);
+        if (Is.function(boundConnectorVersion)) {
+            return boundConnectorVersion();
+        }
+        return 0;
+    }
     /**
      * Searches EntityStorageConnectorFactory for the connector whose registered schema type
      * matches the given schema name.
@@ -289,7 +401,7 @@ export class SchemaVersionService {
                 }
             }
             catch {
-                // Connector not yet created or registration issue — skip.
+                // Connector not yet created or registration issue - skip.
             }
         }
         return undefined;

package/dist/es/schemaVersionService.js.map

@@ -1 +1 @@
-{"version":3,"file":"schemaVersionService.js","sourceRoot":"","sources":["../../src/schemaVersionService.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { ComponentFactory, GeneralError, Is, type IComponent } from \"@twin.org/core\";\nimport { EntitySchemaFactory, EntitySchemaHelper, type IEntitySchema } from \"@twin.org/entity\";\nimport {\n\tEntityStorageConnectorFactory,\n\ttype IEntityStorageConnector,\n\ttype IEntityStorageMigrationConnector,\n\ttype IMigrationOptions,\n\ttype IResolvedMigrationStep,\n\tMigrationHelper,\n\tSchemaMigrationFactory\n} from \"@twin.org/entity-storage-models\";\nimport type { ILoggingComponent } from \"@twin.org/logging-models\";\nimport { nameof } from \"@twin.org/nameof\";\nimport { SchemaVersion } from \"./entities/schemaVersion.js\";\nimport type { ISchemaVersionServiceConfig } from \"./models/ISchemaVersionServiceConfig.js\";\nimport type { ISchemaVersionServiceConstructorOptions } from \"./models/ISchemaVersionServiceConstructorOptions.js\";\n\n/**\n * Service that checks and applies entity schema migrations at every node start-up.\n *\n * This service must be the first entry in coreTypeInitialisers.json. The engine iterates that\n * array in order to determine start sequence — there is no engine-level priority mechanism, so\n * registration position is the only guarantee that start() runs before any other service.\n * By the time start() is called, all component bootstraps have completed (every table already\n * exists) and EntitySchemaFactory / EntityStorageConnectorFactory are fully populated with every\n * registered schema and connector.\n *\n * Migration mechanics: old schema versions are registered in EntitySchemaFactory by naming\n * convention — current schema = \"MyEntity\", first history = \"MyEntityV0\", second = \"MyEntityV1\".\n * The service groups schemas by base name (strips the trailing V number suffix) and resolves the\n * migration chain automatically by diffing consecutive versioned schemas. For steps that require\n * property renames or a custom transform hook, register an optional ISchemaMigration entry in\n * SchemaMigrationFactory under the key \"Base_from_to\" (e.g. \"MyEntity_0_1\").\n *\n * Crash-window note: finalizeMigration and the subsequent version-record write are two\n * separate operations. If the process dies between them the next boot re-runs the chain\n * over already-migrated data. applyEntityTransform is NOT idempotent for structural changes\n * (newly-added optional fields would be dropped on re-run). A transaction spanning both\n * writes is a precondition for production; track this in the concurrency follow-up.\n */\nexport class SchemaVersionService implements IComponent {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<SchemaVersionService>();\n\n\t/**\n\t * Regex to detect a versioned schema name and extract the base name and version number.\n\t * Matches names like \"MyEntityV0\", \"AuditableItemGraphV2\", etc.\n\t * @internal\n\t */\n\tprivate static readonly _VERSION_SUFFIX_RE = /^(.+)V(\\d+)$/;\n\n\t/**\n\t * The connector used to read and write SchemaVersion records.\n\t * Not readonly because finalizeMigration may return a replacement connector object.\n\t * @internal\n\t */\n\tprivate _versionConnector: IEntityStorageConnector<SchemaVersion>;\n\n\t/**\n\t * Optional config passed through constructor options.\n\t * @internal\n\t */\n\tprivate readonly _config?: ISchemaVersionServiceConfig;\n\n\t/**\n\t * Create a new SchemaVersionService.\n\t * @param options Optional constructor options.\n\t */\n\tconstructor(options?: ISchemaVersionServiceConstructorOptions) {\n\t\tthis._versionConnector = EntityStorageConnectorFactory.get(\n\t\t\toptions?.schemaVersionStorageType ?? \"schema-version\"\n\t\t);\n\t\tthis._config = options?.config;\n\t}\n\n\t/**\n\t * Returns the class name.\n\t * @returns The class name.\n\t */\n\tpublic className(): string {\n\t\treturn SchemaVersionService.CLASS_NAME;\n\t}\n\n\t/**\n\t * Reads all registered entity schemas, groups versioned schemas by base name, reads the\n\t * full schemaVersion table in one pass, then orchestrates chain migrations for any schema\n\t * whose stored version is behind the current version declared in EntitySchemaFactory.\n\t * SchemaVersion itself is processed first so the version store is migrated before any\n\t * version records are written for other schemas.\n\t *\n\t * Runs after all component bootstraps, so every managed table already exists.\n\t * @param nodeLoggingComponentType An optional logging component type.\n\t */\n\tpublic async start(nodeLoggingComponentType?: string): Promise<void> {\n\t\tconst logging = ComponentFactory.getIfExists<ILoggingComponent>(nodeLoggingComponentType);\n\n\t\tconst migrationOptions: IMigrationOptions = {\n\t\t\tbatchSize: this._config?.batchSize,\n\t\t\tonProgress: async (progressItem, itemTotal, itemIndex) => {\n\t\t\t\tawait this.logProgress(logging, progressItem, itemTotal, itemIndex);\n\t\t\t}\n\t\t};\n\n\t\t// 1. Collect all registered schema names and partition into current vs historical.\n\t\tconst allNames = EntitySchemaFactory.names();\n\n\t\tconst historicalByBase = new Map<string, Map<number, IEntitySchema>>();\n\t\tconst currentSchemas = new Map<string, IEntitySchema>();\n\n\t\tfor (const name of allNames) {\n\t\t\tconst match = SchemaVersionService._VERSION_SUFFIX_RE.exec(name);\n\t\t\tif (match) {\n\t\t\t\tconst baseName = match[1];\n\t\t\t\tconst version = Number.parseInt(match[2], 10);\n\t\t\t\tlet versions = historicalByBase.get(baseName);\n\t\t\t\tif (!versions) {\n\t\t\t\t\tversions = new Map();\n\t\t\t\t\thistoricalByBase.set(baseName, versions);\n\t\t\t\t}\n\t\t\t\tversions.set(version, EntitySchemaFactory.get(name));\n\t\t\t} else {\n\t\t\t\tcurrentSchemas.set(name, EntitySchemaFactory.get(name));\n\t\t\t}\n\t\t}\n\n\t\t// 2. Read ALL stored version records, paging through the full table.\n\t\tconst storedVersions = new Map<string, number>();\n\t\tlet cursor: string | undefined;\n\t\tdo {\n\t\t\tconst queryResult = await this._versionConnector.query(\n\t\t\t\tundefined,\n\t\t\t\tundefined,\n\t\t\t\tundefined,\n\t\t\t\tcursor\n\t\t\t);\n\t\t\tfor (const record of queryResult.entities ?? []) {\n\t\t\t\tif (Is.object<SchemaVersion>(record)) {\n\t\t\t\t\tstoredVersions.set(record.schemaName, record.version);\n\t\t\t\t}\n\t\t\t}\n\t\t\tcursor = queryResult.cursor;\n\t\t} while (Is.stringValue(cursor));\n\n\t\t// 3. Process SchemaVersion first so the version store itself is fully migrated\n\t\t//    before any version records are written for other schemas.\n\t\tconst schemaVersionName = nameof(SchemaVersion);\n\t\tconst schemaVersionSchema = currentSchemas.get(schemaVersionName);\n\t\tif (schemaVersionSchema) {\n\t\t\tcurrentSchemas.delete(schemaVersionName);\n\t\t\tawait this.processSchema(\n\t\t\t\tschemaVersionName,\n\t\t\t\tschemaVersionSchema,\n\t\t\t\tstoredVersions,\n\t\t\t\thistoricalByBase.get(schemaVersionName),\n\t\t\t\tmigrationOptions,\n\t\t\t\tnodeLoggingComponentType,\n\t\t\t\tlogging\n\t\t\t);\n\t\t}\n\n\t\t// 4. Process all remaining schemas.\n\t\tfor (const [schemaName, schema] of currentSchemas) {\n\t\t\tawait this.processSchema(\n\t\t\t\tschemaName,\n\t\t\t\tschema,\n\t\t\t\tstoredVersions,\n\t\t\t\thistoricalByBase.get(schemaName),\n\t\t\t\tmigrationOptions,\n\t\t\t\tnodeLoggingComponentType,\n\t\t\t\tlogging\n\t\t\t);\n\t\t}\n\t}\n\n\t/**\n\t * Checks and applies any pending migration for a single entity schema.\n\t * Extracted to avoid continue statements in the outer loop.\n\t * @param schemaName The base schema name.\n\t * @param schema The current schema definition.\n\t * @param storedVersions The full map of stored version records.\n\t * @param history The versioned-schema map for this schema (historicalByBase.get(schemaName)), or undefined if none exist.\n\t * @param migrationOptions The migration options to pass through to MigrationHelper.\n\t * @param loggingComponentType The optional component type to use for logging the migration progress.\n\t * @param logging An optional logging component to pass through to MigrationHelper for migration progress logging.\n\t * @internal\n\t */\n\tprivate async processSchema(\n\t\tschemaName: string,\n\t\tschema: IEntitySchema,\n\t\tstoredVersions: Map<string, number>,\n\t\thistory: Map<number, IEntitySchema> | undefined,\n\t\tmigrationOptions: IMigrationOptions,\n\t\tloggingComponentType: string | undefined,\n\t\tlogging: ILoggingComponent | undefined\n\t): Promise<void> {\n\t\tconst currentVersion = EntitySchemaHelper.getVersion(schema);\n\n\t\t// Find the entity-storage connector whose schema type matches this schema name.\n\t\t// For SchemaVersion itself, use the injected connector directly rather than re-discovering\n\t\t// it through the factory, which could resolve a different instance than _versionConnector.\n\t\tconst connectorEntry =\n\t\t\tschemaName === nameof(SchemaVersion)\n\t\t\t\t? { connector: this._versionConnector as IEntityStorageConnector, factoryKey: undefined }\n\t\t\t\t: this.findConnector(schemaName);\n\t\tif (!connectorEntry) {\n\t\t\t// No connector registered for this schema — nothing to migrate.\n\t\t\treturn;\n\t\t}\n\t\tconst { connector, factoryKey } = connectorEntry;\n\n\t\t// Resolve the stored version, applying the backwards-compat baseline when no record exists.\n\t\tconst stored = storedVersions.get(schemaName);\n\t\tlet resolvedStoredVersion: number;\n\n\t\tif (stored === undefined) {\n\t\t\t// No version record: treat as v0 regardless of whether the table has data.\n\t\t\t// On SQL connectors the table may have a stale column structure even when empty;\n\t\t\t// running the chain over zero rows still calls finalizeMigration, which reconciles\n\t\t\t// the table shape via a connector swap.\n\t\t\t// Deployment precondition: any pre-existing data is genuinely at v0. A deployment\n\t\t\t// that hand-applied a later schema before this service was introduced would be\n\t\t\t// incorrectly replayed v0→…→current and should be seeded with an explicit record.\n\t\t\tresolvedStoredVersion = 0;\n\t\t\tawait this.writeVersion(schemaName, 0);\n\t\t} else {\n\t\t\tresolvedStoredVersion = stored;\n\t\t}\n\n\t\t// No-op: stored version already matches current.\n\t\tif (resolvedStoredVersion === currentVersion) {\n\t\t\tawait logging?.log({\n\t\t\t\tsource: SchemaVersionService.CLASS_NAME,\n\t\t\t\tlevel: \"info\",\n\t\t\t\tmessage: \"noMigrationRequired\",\n\t\t\t\tdata: {\n\t\t\t\t\tschemaName,\n\t\t\t\t\tversion: resolvedStoredVersion\n\t\t\t\t}\n\t\t\t});\n\t\t\treturn;\n\t\t}\n\n\t\tawait logging?.log({\n\t\t\tsource: SchemaVersionService.CLASS_NAME,\n\t\t\tlevel: \"info\",\n\t\t\tmessage: \"migrationRequired\",\n\t\t\tdata: {\n\t\t\t\tschemaName,\n\t\t\t\tfrom: resolvedStoredVersion,\n\t\t\t\tto: currentVersion\n\t\t\t}\n\t\t});\n\n\t\t// Downgrade — not supported.\n\t\tif (resolvedStoredVersion > currentVersion) {\n\t\t\tthrow new GeneralError(SchemaVersionService.CLASS_NAME, \"storedVersionNewer\", {\n\t\t\t\tschemaName,\n\t\t\t\tstored: resolvedStoredVersion,\n\t\t\t\tcurrent: currentVersion\n\t\t\t});\n\t\t}\n\n\t\t// Migration is needed. If the connector does not support it, throw immediately so\n\t\t// the problem surfaces at boot rather than at runtime when writes hit the wrong table shape.\n\t\tif (!(\"createTargetConnector\" in connector)) {\n\t\t\tthrow new GeneralError(SchemaVersionService.CLASS_NAME, \"connectorNotMigrationCapable\", {\n\t\t\t\tschemaName,\n\t\t\t\tstored: resolvedStoredVersion,\n\t\t\t\tcurrent: currentVersion\n\t\t\t});\n\t\t}\n\n\t\tconst migrationConnector = connector as IEntityStorageMigrationConnector;\n\n\t\t// Upgrade — resolve and run the chain.\n\t\tconst steps: IResolvedMigrationStep[] = [];\n\n\t\tfor (let v = resolvedStoredVersion; v < currentVersion; v++) {\n\t\t\tconst fromSchema = history?.get(v);\n\t\t\tif (!fromSchema) {\n\t\t\t\tthrow new GeneralError(SchemaVersionService.CLASS_NAME, \"noMigrationStep\", {\n\t\t\t\t\tschemaName,\n\t\t\t\t\tstored: resolvedStoredVersion,\n\t\t\t\t\tcurrent: currentVersion,\n\t\t\t\t\tmissingFromVersion: v,\n\t\t\t\t\tmissingToVersion: v + 1\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tconst toSchema = v + 1 < currentVersion ? history?.get(v + 1) : schema;\n\t\t\tif (!toSchema) {\n\t\t\t\tthrow new GeneralError(SchemaVersionService.CLASS_NAME, \"noMigrationStepTarget\", {\n\t\t\t\t\tschemaName,\n\t\t\t\t\tstored: resolvedStoredVersion,\n\t\t\t\t\tcurrent: currentVersion,\n\t\t\t\t\tmissingFromVersion: v,\n\t\t\t\t\tmissingToVersion: v + 1\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tconst overrideKey = `${schemaName}_${v}_${v + 1}`;\n\t\t\tconst override = SchemaMigrationFactory.getIfExists(overrideKey);\n\n\t\t\tsteps.push({\n\t\t\t\tfromProperties: fromSchema.properties ?? [],\n\t\t\t\ttoProperties: toSchema.properties ?? [],\n\t\t\t\trenames: override?.renames,\n\t\t\t\ttransformEntityProperty: override?.transformEntityProperty\n\t\t\t});\n\t\t}\n\n\t\tconst { finalConnector } = await MigrationHelper.migrateWithChain(\n\t\t\tmigrationConnector,\n\t\t\tschemaName,\n\t\t\tsteps,\n\t\t\tmigrationOptions,\n\t\t\tloggingComponentType\n\t\t);\n\n\t\t// Some connectors (e.g. in-memory) return a brand-new object from finalizeMigration\n\t\t// rather than mutating the source in place.  Re-register the factory entry so that any\n\t\t// subsequent EntityStorageConnectorFactory.get() call returns the migrated instance.\n\t\tif (finalConnector !== connector) {\n\t\t\tif (factoryKey) {\n\t\t\t\tEntityStorageConnectorFactory.register(factoryKey, () => finalConnector);\n\t\t\t}\n\t\t\t// For SchemaVersion keep _versionConnector in sync so writeVersion below uses\n\t\t\t// the migrated instance.\n\t\t\tif (schemaName === nameof(SchemaVersion)) {\n\t\t\t\tthis._versionConnector = finalConnector as IEntityStorageConnector<SchemaVersion>;\n\t\t\t}\n\t\t}\n\n\t\t// Advance the stored version only after finalizeMigration has succeeded.\n\t\t// See crash-window note in the class comment.\n\t\tawait this.writeVersion(schemaName, currentVersion);\n\t}\n\n\t/**\n\t * Upserts a SchemaVersion record for the given schema name.\n\t * @param schemaName The schema type name.\n\t * @param version The version to record.\n\t * @internal\n\t */\n\tprivate async writeVersion(schemaName: string, version: number): Promise<void> {\n\t\tawait this._versionConnector.set({\n\t\t\tschemaName,\n\t\t\tversion,\n\t\t\tupdatedAt: new Date().toISOString()\n\t\t});\n\t}\n\n\t/**\n\t * Searches EntityStorageConnectorFactory for the connector whose registered schema type\n\t * matches the given schema name.\n\t * @param schemaName The entity type name to look up.\n\t * @returns The matching connector and its factory key, or undefined if none is registered.\n\t * @internal\n\t */\n\tprivate findConnector(\n\t\tschemaName: string\n\t): { connector: IEntityStorageConnector; factoryKey: string } | undefined {\n\t\tfor (const name of EntityStorageConnectorFactory.names()) {\n\t\t\ttry {\n\t\t\t\tconst connector = EntityStorageConnectorFactory.get(name);\n\t\t\t\tif (connector.getSchema?.().type === schemaName) {\n\t\t\t\t\treturn { connector, factoryKey: name };\n\t\t\t\t}\n\t\t\t} catch {\n\t\t\t\t// Connector not yet created or registration issue — skip.\n\t\t\t}\n\t\t}\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Logs migration progress using the provided logging component, if available.\n\t * @param logging The logging component to use for logging progress, if available.\n\t * @param progressItem The progress item being updated.\n\t * @param itemTotal The total number of items to process for this progress item.\n\t * @param itemIndex The index of the current item being processed for this progress item.\n\t * @internal\n\t */\n\tprivate async logProgress(\n\t\tlogging: ILoggingComponent | undefined,\n\t\tprogressItem: string,\n\t\titemTotal: number,\n\t\titemIndex: number\n\t): Promise<void> {\n\t\tif (progressItem === \"partitionStart\") {\n\t\t\tawait logging?.log({\n\t\t\t\tsource: SchemaVersionService.CLASS_NAME,\n\t\t\t\tlevel: \"info\",\n\t\t\t\tmessage: \"partitionStart\",\n\t\t\t\tdata: { progressItem, itemTotal, itemIndex }\n\t\t\t});\n\t\t} else if (progressItem === \"partitionProgress\") {\n\t\t\tawait logging?.log({\n\t\t\t\tsource: SchemaVersionService.CLASS_NAME,\n\t\t\t\tlevel: \"info\",\n\t\t\t\tmessage: \"partitionProgress\",\n\t\t\t\tdata: { progressItem, itemTotal, itemIndex }\n\t\t\t});\n\t\t} else if (progressItem === \"partitionEnd\") {\n\t\t\tawait logging?.log({\n\t\t\t\tsource: SchemaVersionService.CLASS_NAME,\n\t\t\t\tlevel: \"info\",\n\t\t\t\tmessage: \"partitionEnd\",\n\t\t\t\tdata: { progressItem, itemTotal, itemIndex }\n\t\t\t});\n\t\t} else if (progressItem === \"partitionItemsStart\") {\n\t\t\tawait logging?.log({\n\t\t\t\tsource: SchemaVersionService.CLASS_NAME,\n\t\t\t\tlevel: \"info\",\n\t\t\t\tmessage: \"partitionItemsStart\",\n\t\t\t\tdata: { progressItem, itemTotal, itemIndex }\n\t\t\t});\n\t\t} else if (progressItem === \"partitionItemsProgress\") {\n\t\t\tawait logging?.log({\n\t\t\t\tsource: SchemaVersionService.CLASS_NAME,\n\t\t\t\tlevel: \"info\",\n\t\t\t\tmessage: \"partitionItemsProgress\",\n\t\t\t\tdata: { progressItem, itemTotal, itemIndex }\n\t\t\t});\n\t\t} else if (progressItem === \"partitionItemsEnd\") {\n\t\t\tawait logging?.log({\n\t\t\t\tsource: SchemaVersionService.CLASS_NAME,\n\t\t\t\tlevel: \"info\",\n\t\t\t\tmessage: \"partitionItemsEnd\",\n\t\t\t\tdata: { progressItem, itemTotal, itemIndex }\n\t\t\t});\n\t\t}\n\t}\n}\n"]}
+{"version":3,"file":"schemaVersionService.js","sourceRoot":"","sources":["../../src/schemaVersionService.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IContextIds } from \"@twin.org/context\";\nimport { ComponentFactory, GeneralError, Is, type IComponent } from \"@twin.org/core\";\nimport { EntitySchemaFactory, EntitySchemaHelper, type IEntitySchema } from \"@twin.org/entity\";\nimport {\n\tEntityStorageConnectorFactory,\n\ttype IEntityStorageConnector,\n\ttype IEntityStorageMigrationConnector,\n\ttype IMigrationOptions,\n\ttype IResolvedMigrationStep,\n\tMigrationHelper,\n\tSchemaMigrationFactory\n} from \"@twin.org/entity-storage-models\";\nimport type { ILoggingComponent } from \"@twin.org/logging-models\";\nimport { nameof } from \"@twin.org/nameof\";\nimport { SchemaVersion } from \"./entities/schemaVersion.js\";\nimport type { ISchemaVersionServiceConfig } from \"./models/ISchemaVersionServiceConfig.js\";\nimport type { ISchemaVersionServiceConstructorOptions } from \"./models/ISchemaVersionServiceConstructorOptions.js\";\n\n/**\n * Service that checks and applies entity schema migrations at every node start-up.\n *\n * This service must be the first entry in coreTypeInitialisers.json. The engine iterates that\n * array in order to determine start sequence - there is no engine-level priority mechanism, so\n * registration position is the only guarantee that start() runs before any other service.\n * By the time start() is called, all component bootstraps have completed (every table already\n * exists) and EntitySchemaFactory / EntityStorageConnectorFactory are fully populated with every\n * registered schema and connector.\n *\n * Migration mechanics: old schema versions are registered in EntitySchemaFactory by naming\n * convention - current schema = \"MyEntity\", first history = \"MyEntityV0\", second = \"MyEntityV1\".\n * The service groups schemas by base name (strips the trailing V number suffix) and resolves the\n * migration chain automatically by diffing consecutive versioned schemas. For steps that require\n * property renames or a custom transform hook, register an optional ISchemaMigration entry in\n * SchemaMigrationFactory under the key \"Base_from_to\" (e.g. \"MyEntity_0_1\").\n *\n * Crash-window note: finalizeMigration and the subsequent version-record write are two\n * separate operations. If the process dies between them the next boot re-runs the chain\n * over already-migrated data. applyEntityTransform is NOT idempotent for structural changes\n * (newly-added optional fields would be dropped on re-run). A transaction spanning both\n * writes is a precondition for production; track this in the concurrency follow-up.\n */\nexport class SchemaVersionService implements IComponent {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<SchemaVersionService>();\n\n\t/**\n\t * Regex to detect a versioned schema name and extract the base name and version number.\n\t * Matches names like \"MyEntityV0\", \"AuditableItemGraphV2\", etc.\n\t * @internal\n\t */\n\tprivate static readonly _VERSION_SUFFIX_RE = /^(.+)V(\\d+)$/;\n\n\t/**\n\t * Key used for the global connector-version record in the schema-version table.\n\t * @internal\n\t */\n\tprivate static readonly _CONNECTOR_VERSION_KEY = \"connectorVersion\";\n\n\t/**\n\t * The connector used to read and write SchemaVersion records.\n\t * Not readonly because finalizeMigration may return a replacement connector object.\n\t * @internal\n\t */\n\tprivate _versionConnector: IEntityStorageConnector<SchemaVersion>;\n\n\t/**\n\t * Optional config passed through constructor options.\n\t * @internal\n\t */\n\tprivate readonly _config?: ISchemaVersionServiceConfig;\n\n\t/**\n\t * Create a new SchemaVersionService.\n\t * @param options Optional constructor options.\n\t */\n\tconstructor(options?: ISchemaVersionServiceConstructorOptions) {\n\t\tthis._versionConnector = EntityStorageConnectorFactory.get(\n\t\t\toptions?.schemaVersionStorageType ?? \"schema-version\"\n\t\t);\n\t\tthis._config = options?.config;\n\t}\n\n\t/**\n\t * Returns the class name.\n\t * @returns The class name.\n\t */\n\tpublic className(): string {\n\t\treturn SchemaVersionService.CLASS_NAME;\n\t}\n\n\t/**\n\t * Reads all registered entity schemas, groups versioned schemas by base name, reads the\n\t * full schemaVersion table in one pass, then orchestrates chain migrations for any schema\n\t * whose stored version is behind the current version declared in EntitySchemaFactory.\n\t * SchemaVersion itself is processed first so the version store is migrated before any\n\t * version records are written for other schemas.\n\t *\n\t * When config.enabled is false the service runs in detect-only mode: it identifies schemas\n\t * that need migration and logs a warning for each one, but applies no changes.\n\t *\n\t * Runs after all component bootstraps, so every managed table already exists.\n\t * @param nodeLoggingComponentType An optional logging component type.\n\t */\n\tpublic async start(nodeLoggingComponentType?: string): Promise<void> {\n\t\tconst logging = ComponentFactory.getIfExists<ILoggingComponent>(nodeLoggingComponentType);\n\t\tconst enabled = this._config?.enabled !== false;\n\n\t\tconst migrationOptions: IMigrationOptions = {\n\t\t\tbatchSize: this._config?.batchSize,\n\t\t\tonProgress: async (progressItem, itemTotal, itemIndex) => {\n\t\t\t\tawait this.logProgress(logging, progressItem, itemTotal, itemIndex);\n\t\t\t}\n\t\t};\n\n\t\t// 1. Collect all registered schema names and partition into current vs historical.\n\t\tconst allNames = EntitySchemaFactory.names();\n\n\t\tconst historicalByBase = new Map<string, Map<number, IEntitySchema>>();\n\t\tconst currentSchemas = new Map<string, IEntitySchema>();\n\n\t\tfor (const name of allNames) {\n\t\t\tconst match = SchemaVersionService._VERSION_SUFFIX_RE.exec(name);\n\t\t\tif (match) {\n\t\t\t\tconst baseName = match[1];\n\t\t\t\tconst version = Number.parseInt(match[2], 10);\n\t\t\t\tlet versions = historicalByBase.get(baseName);\n\t\t\t\tif (!versions) {\n\t\t\t\t\tversions = new Map();\n\t\t\t\t\thistoricalByBase.set(baseName, versions);\n\t\t\t\t}\n\t\t\t\tversions.set(version, EntitySchemaFactory.get(name));\n\t\t\t} else {\n\t\t\t\tcurrentSchemas.set(name, EntitySchemaFactory.get(name));\n\t\t\t}\n\t\t}\n\n\t\t// 2. Read ALL stored version records, paging through the full table.\n\t\tconst storedVersions = new Map<string, number>();\n\t\tlet storedConnectorVersion: number | undefined;\n\t\tlet cursor: string | undefined;\n\t\tdo {\n\t\t\tconst queryResult = await this._versionConnector.query(\n\t\t\t\tundefined,\n\t\t\t\tundefined,\n\t\t\t\tundefined,\n\t\t\t\tcursor\n\t\t\t);\n\t\t\tfor (const record of queryResult.entities ?? []) {\n\t\t\t\tif (Is.object<SchemaVersion>(record)) {\n\t\t\t\t\tif (record.schemaName === SchemaVersionService._CONNECTOR_VERSION_KEY) {\n\t\t\t\t\t\tstoredConnectorVersion = record.version;\n\t\t\t\t\t} else {\n\t\t\t\t\t\tstoredVersions.set(record.schemaName, record.version);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t\tcursor = queryResult.cursor;\n\t\t} while (Is.stringValue(cursor));\n\n\t\tif (!enabled) {\n\t\t\t// Detect-only: compare stored vs declared versions and warn about any lagging schemas.\n\t\t\t// Schemas with no stored version record are skipped — they are either fresh installs\n\t\t\t// or pre-tracking tables, neither of which can be diagnosed safely here.\n\t\t\tfor (const [schemaName, schema] of currentSchemas) {\n\t\t\t\tconst storedVersion = storedVersions.get(schemaName);\n\t\t\t\tconst currentVersion = EntitySchemaHelper.getVersion(schema);\n\t\t\t\tif (!Is.undefined(storedVersion) && storedVersion < currentVersion) {\n\t\t\t\t\tawait logging?.log({\n\t\t\t\t\t\tsource: SchemaVersionService.CLASS_NAME,\n\t\t\t\t\t\tlevel: \"warn\",\n\t\t\t\t\t\tmessage: \"migrationDisabled\",\n\t\t\t\t\t\tdata: {\n\t\t\t\t\t\t\tschemaName,\n\t\t\t\t\t\t\tfrom: storedVersion,\n\t\t\t\t\t\t\tto: currentVersion\n\t\t\t\t\t\t}\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn;\n\t\t}\n\n\t\tconst currentConnectorVersion = await this.calculateConnectorVersion();\n\t\tconst effectiveStoredConnectorVersion = storedConnectorVersion ?? 0;\n\t\tconst forceUpgradeAllSchemas = effectiveStoredConnectorVersion !== currentConnectorVersion;\n\n\t\tif (forceUpgradeAllSchemas) {\n\t\t\tawait logging?.log({\n\t\t\t\tsource: SchemaVersionService.CLASS_NAME,\n\t\t\t\tlevel: \"info\",\n\t\t\t\tmessage: \"connectorVersionUpdated\",\n\t\t\t\tdata: {\n\t\t\t\t\tfrom: effectiveStoredConnectorVersion,\n\t\t\t\t\tto: currentConnectorVersion\n\t\t\t\t}\n\t\t\t});\n\t\t}\n\n\t\t// 3. Process SchemaVersion first so the version store itself is fully migrated\n\t\t//    before any version records are written for other schemas.\n\t\tconst schemaVersionName = nameof(SchemaVersion);\n\t\tconst schemaVersionSchema = currentSchemas.get(schemaVersionName);\n\t\tif (schemaVersionSchema) {\n\t\t\tcurrentSchemas.delete(schemaVersionName);\n\t\t\tawait this.processSchema(\n\t\t\t\tschemaVersionName,\n\t\t\t\tschemaVersionSchema,\n\t\t\t\tstoredVersions.get(schemaVersionName),\n\t\t\t\thistoricalByBase.get(schemaVersionName),\n\t\t\t\tforceUpgradeAllSchemas,\n\t\t\t\tmigrationOptions,\n\t\t\t\tnodeLoggingComponentType,\n\t\t\t\tlogging\n\t\t\t);\n\t\t}\n\n\t\t// 4. Process all remaining schemas.\n\t\tfor (const [schemaName, schema] of currentSchemas) {\n\t\t\tawait this.processSchema(\n\t\t\t\tschemaName,\n\t\t\t\tschema,\n\t\t\t\tstoredVersions.get(schemaName),\n\t\t\t\thistoricalByBase.get(schemaName),\n\t\t\t\tforceUpgradeAllSchemas,\n\t\t\t\tmigrationOptions,\n\t\t\t\tnodeLoggingComponentType,\n\t\t\t\tlogging\n\t\t\t);\n\t\t}\n\n\t\tif (\n\t\t\teffectiveStoredConnectorVersion !== currentConnectorVersion ||\n\t\t\tIs.undefined(storedConnectorVersion)\n\t\t) {\n\t\t\tawait this.writeConnectorVersion(currentConnectorVersion);\n\t\t}\n\t}\n\n\t/**\n\t * Checks and applies any pending migration for a single entity schema.\n\t * Extracted to avoid continue statements in the outer loop.\n\t * @param schemaName The base schema name.\n\t * @param schema The current schema definition.\n\t * @param storedVersion The full map of stored version records.\n\t * @param history The versioned-schema map for this schema (historicalByBase.get(schemaName)), or undefined if none exist.\n\t * @param forceUpgradeAllSchemas True when any connector version changed and all schemas must re-run connector bootstrap.\n\t * @param migrationOptions The migration options to pass through to MigrationHelper.\n\t * @param loggingComponentType The optional component type to use for logging the migration progress.\n\t * @param logging An optional logging component to pass through to MigrationHelper for migration progress logging.\n\t * @internal\n\t */\n\tprivate async processSchema(\n\t\tschemaName: string,\n\t\tschema: IEntitySchema,\n\t\tstoredVersion: number | undefined,\n\t\thistory: Map<number, IEntitySchema> | undefined,\n\t\tforceUpgradeAllSchemas: boolean,\n\t\tmigrationOptions: IMigrationOptions,\n\t\tloggingComponentType: string | undefined,\n\t\tlogging: ILoggingComponent | undefined\n\t): Promise<void> {\n\t\tconst currentVersion = EntitySchemaHelper.getVersion(schema);\n\n\t\t// Find the entity-storage connector whose schema type matches this schema name.\n\t\t// For SchemaVersion itself, use the injected connector directly rather than re-discovering\n\t\t// it through the factory, which could resolve a different instance than _versionConnector.\n\t\tconst connectorEntry =\n\t\t\tschemaName === nameof(SchemaVersion)\n\t\t\t\t? { connector: this._versionConnector as IEntityStorageConnector, factoryKey: undefined }\n\t\t\t\t: this.findConnector(schemaName);\n\t\tif (!connectorEntry) {\n\t\t\t// No connector registered for this schema - nothing to migrate.\n\t\t\treturn;\n\t\t}\n\t\tconst { connector, factoryKey } = connectorEntry;\n\n\t\t// Resolve the stored version, applying the backwards-compat baseline when no record exists.\n\t\tlet resolvedStoredVersion: number;\n\n\t\t// Captured when the fresh-vs-legacy check below already resolved the connector's\n\t\t// partitions, so migrateWithChain can reuse them instead of fetching them again.\n\t\tlet partitions: IContextIds[] | undefined;\n\n\t\tconst migrationConnector = connector as IEntityStorageMigrationConnector;\n\n\t\tconst boundGetPartitionContextIds =\n\t\t\tmigrationConnector.getPartitionContextIds?.bind(migrationConnector);\n\t\tif (Is.function(boundGetPartitionContextIds)) {\n\t\t\tpartitions = await boundGetPartitionContextIds();\n\t\t}\n\n\t\tif (storedVersion === undefined) {\n\t\t\t// No version record: check whether the table has any data.\n\t\t\t// Empty table → this is a fresh bootstrap; seed at the current version so the\n\t\t\t// migration chain never runs over an already-current-shape (or empty) table.\n\t\t\t// Non-empty table → pre-existing data from before version tracking was introduced;\n\t\t\t// treat as v0 and run the migration chain. applyEntityTransform preserves existing\n\t\t\t// property values so current-shape rows are not degraded.\n\t\t\tlet hasExistingData: boolean;\n\t\t\tif (Is.undefined(partitions)) {\n\t\t\t\t// Connector does not have partitioning, so we can safely call count.\n\t\t\t\thasExistingData = (await connector.count()) > 0;\n\t\t\t} else {\n\t\t\t\t// Connector has partitioning, if there are partition keys\n\t\t\t\t// then it must have data, otherwise the table is empty.\n\t\t\t\thasExistingData = partitions.length > 0;\n\t\t\t}\n\n\t\t\tif (!hasExistingData) {\n\t\t\t\tawait this.writeVersion(schemaName, currentVersion);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tresolvedStoredVersion = 0;\n\t\t\tawait this.writeVersion(schemaName, 0);\n\t\t} else {\n\t\t\tresolvedStoredVersion = storedVersion;\n\t\t}\n\n\t\t// No-op: stored version already matches current.\n\t\tif (resolvedStoredVersion === currentVersion) {\n\t\t\tif (!forceUpgradeAllSchemas) {\n\t\t\t\tawait logging?.log({\n\t\t\t\t\tsource: SchemaVersionService.CLASS_NAME,\n\t\t\t\t\tlevel: \"info\",\n\t\t\t\t\tmessage: \"noMigrationRequired\",\n\t\t\t\t\tdata: {\n\t\t\t\t\t\tschemaName,\n\t\t\t\t\t\tversion: resolvedStoredVersion\n\t\t\t\t\t}\n\t\t\t\t});\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tawait logging?.log({\n\t\t\t\tsource: SchemaVersionService.CLASS_NAME,\n\t\t\t\tlevel: \"info\",\n\t\t\t\tmessage: \"connectorVersionForceUpgrade\",\n\t\t\t\tdata: {\n\t\t\t\t\tschemaName\n\t\t\t\t}\n\t\t\t});\n\t\t}\n\n\t\tawait logging?.log({\n\t\t\tsource: SchemaVersionService.CLASS_NAME,\n\t\t\tlevel: \"info\",\n\t\t\tmessage: \"migrationRequired\",\n\t\t\tdata: {\n\t\t\t\tschemaName,\n\t\t\t\tfrom: resolvedStoredVersion,\n\t\t\t\tto: currentVersion\n\t\t\t}\n\t\t});\n\n\t\t// Downgrade - not supported.\n\t\tif (resolvedStoredVersion > currentVersion) {\n\t\t\tthrow new GeneralError(SchemaVersionService.CLASS_NAME, \"storedVersionNewer\", {\n\t\t\t\tschemaName,\n\t\t\t\tstored: resolvedStoredVersion,\n\t\t\t\tcurrent: currentVersion\n\t\t\t});\n\t\t}\n\n\t\t// Migration is needed. If the connector does not support it, throw immediately so\n\t\t// the problem surfaces at boot rather than at runtime when writes hit the wrong table shape.\n\t\tif (!(\"createTargetConnector\" in connector)) {\n\t\t\tthrow new GeneralError(SchemaVersionService.CLASS_NAME, \"connectorNotMigrationCapable\", {\n\t\t\t\tschemaName,\n\t\t\t\tstored: resolvedStoredVersion,\n\t\t\t\tcurrent: currentVersion\n\t\t\t});\n\t\t}\n\n\t\t// Upgrade - resolve and run the chain.\n\t\tconst steps: IResolvedMigrationStep[] = [];\n\n\t\tfor (let v = resolvedStoredVersion; v < currentVersion; v++) {\n\t\t\tconst fromSchema = history?.get(v);\n\t\t\tif (!fromSchema) {\n\t\t\t\tthrow new GeneralError(SchemaVersionService.CLASS_NAME, \"noMigrationStep\", {\n\t\t\t\t\tschemaName,\n\t\t\t\t\tstored: resolvedStoredVersion,\n\t\t\t\t\tcurrent: currentVersion,\n\t\t\t\t\tmissingFromVersion: v,\n\t\t\t\t\tmissingToVersion: v + 1\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tconst toSchema = v + 1 < currentVersion ? history?.get(v + 1) : schema;\n\t\t\tif (!toSchema) {\n\t\t\t\tthrow new GeneralError(SchemaVersionService.CLASS_NAME, \"noMigrationStepTarget\", {\n\t\t\t\t\tschemaName,\n\t\t\t\t\tstored: resolvedStoredVersion,\n\t\t\t\t\tcurrent: currentVersion,\n\t\t\t\t\tmissingFromVersion: v,\n\t\t\t\t\tmissingToVersion: v + 1\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tconst overrideKey = `${schemaName}_${v}_${v + 1}`;\n\t\t\tconst override = SchemaMigrationFactory.getIfExists(overrideKey);\n\n\t\t\tsteps.push({\n\t\t\t\tfromProperties: fromSchema.properties ?? [],\n\t\t\t\ttoProperties: toSchema.properties ?? [],\n\t\t\t\trenames: override?.renames,\n\t\t\t\ttransformEntityProperty: override?.transformEntityProperty\n\t\t\t});\n\t\t}\n\n\t\tconst { finalConnector } = await MigrationHelper.migrateWithChain(\n\t\t\tmigrationConnector,\n\t\t\tschemaName,\n\t\t\tpartitions,\n\t\t\tsteps,\n\t\t\tmigrationOptions,\n\t\t\tloggingComponentType\n\t\t);\n\n\t\t// Some connectors (e.g. in-memory) return a brand-new object from finalizeMigration\n\t\t// rather than mutating the source in place.  Re-register the factory entry so that any\n\t\t// subsequent EntityStorageConnectorFactory.get() call returns the migrated instance.\n\t\tif (finalConnector !== connector) {\n\t\t\tif (factoryKey) {\n\t\t\t\tEntityStorageConnectorFactory.register(factoryKey, () => finalConnector);\n\t\t\t}\n\t\t\t// For SchemaVersion keep _versionConnector in sync so writeVersion below uses\n\t\t\t// the migrated instance.\n\t\t\tif (schemaName === nameof(SchemaVersion)) {\n\t\t\t\tthis._versionConnector = finalConnector as IEntityStorageConnector<SchemaVersion>;\n\t\t\t}\n\t\t}\n\n\t\t// Advance the stored version only after finalizeMigration has succeeded.\n\t\t// See crash-window note in the class comment.\n\t\tawait this.writeVersion(schemaName, currentVersion);\n\t}\n\n\t/**\n\t * Upserts a SchemaVersion record for the given schema name.\n\t * @param schemaName The schema type name.\n\t * @param version The version to record.\n\t * @internal\n\t */\n\tprivate async writeVersion(schemaName: string, version: number): Promise<void> {\n\t\tawait this._versionConnector.set({\n\t\t\tschemaName,\n\t\t\tversion,\n\t\t\tupdatedAt: new Date().toISOString()\n\t\t});\n\t}\n\n\t/**\n\t * Upserts the global connector-version record.\n\t * @param connectorVersion The connector implementation version.\n\t * @internal\n\t */\n\tprivate async writeConnectorVersion(connectorVersion: number): Promise<void> {\n\t\tawait this._versionConnector.set({\n\t\t\tschemaName: SchemaVersionService._CONNECTOR_VERSION_KEY,\n\t\t\tversion: connectorVersion,\n\t\t\tupdatedAt: new Date().toISOString()\n\t\t});\n\t}\n\n\t/**\n\t * Get the global connector version from a migration-capable connector.\n\t * Missing connectorVersion support is treated as version 0.\n\t * @returns The connector version.\n\t * @internal\n\t */\n\tprivate async calculateConnectorVersion(): Promise<number> {\n\t\tif (!this._versionConnector || !(\"connectorVersion\" in this._versionConnector)) {\n\t\t\treturn 0;\n\t\t}\n\n\t\tconst connector = this._versionConnector as IEntityStorageMigrationConnector;\n\t\tconst boundConnectorVersion = connector.connectorVersion.bind(connector);\n\t\tif (Is.function(boundConnectorVersion)) {\n\t\t\treturn boundConnectorVersion();\n\t\t}\n\n\t\treturn 0;\n\t}\n\n\t/**\n\t * Searches EntityStorageConnectorFactory for the connector whose registered schema type\n\t * matches the given schema name.\n\t * @param schemaName The entity type name to look up.\n\t * @returns The matching connector and its factory key, or undefined if none is registered.\n\t * @internal\n\t */\n\tprivate findConnector(\n\t\tschemaName: string\n\t): { connector: IEntityStorageConnector; factoryKey: string } | undefined {\n\t\tfor (const name of EntityStorageConnectorFactory.names()) {\n\t\t\ttry {\n\t\t\t\tconst connector = EntityStorageConnectorFactory.get(name);\n\t\t\t\tif (connector.getSchema?.().type === schemaName) {\n\t\t\t\t\treturn { connector, factoryKey: name };\n\t\t\t\t}\n\t\t\t} catch {\n\t\t\t\t// Connector not yet created or registration issue - skip.\n\t\t\t}\n\t\t}\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Logs migration progress using the provided logging component, if available.\n\t * @param logging The logging component to use for logging progress, if available.\n\t * @param progressItem The progress item being updated.\n\t * @param itemTotal The total number of items to process for this progress item.\n\t * @param itemIndex The index of the current item being processed for this progress item.\n\t * @internal\n\t */\n\tprivate async logProgress(\n\t\tlogging: ILoggingComponent | undefined,\n\t\tprogressItem: string,\n\t\titemTotal: number,\n\t\titemIndex: number\n\t): Promise<void> {\n\t\tif (progressItem === \"partitionStart\") {\n\t\t\tawait logging?.log({\n\t\t\t\tsource: SchemaVersionService.CLASS_NAME,\n\t\t\t\tlevel: \"info\",\n\t\t\t\tmessage: \"partitionStart\",\n\t\t\t\tdata: { progressItem, itemTotal, itemIndex }\n\t\t\t});\n\t\t} else if (progressItem === \"partitionProgress\") {\n\t\t\tawait logging?.log({\n\t\t\t\tsource: SchemaVersionService.CLASS_NAME,\n\t\t\t\tlevel: \"info\",\n\t\t\t\tmessage: \"partitionProgress\",\n\t\t\t\tdata: { progressItem, itemTotal, itemIndex }\n\t\t\t});\n\t\t} else if (progressItem === \"partitionEnd\") {\n\t\t\tawait logging?.log({\n\t\t\t\tsource: SchemaVersionService.CLASS_NAME,\n\t\t\t\tlevel: \"info\",\n\t\t\t\tmessage: \"partitionEnd\",\n\t\t\t\tdata: { progressItem, itemTotal, itemIndex }\n\t\t\t});\n\t\t} else if (progressItem === \"partitionItemsStart\") {\n\t\t\tawait logging?.log({\n\t\t\t\tsource: SchemaVersionService.CLASS_NAME,\n\t\t\t\tlevel: \"info\",\n\t\t\t\tmessage: \"partitionItemsStart\",\n\t\t\t\tdata: { progressItem, itemTotal, itemIndex }\n\t\t\t});\n\t\t} else if (progressItem === \"partitionItemsProgress\") {\n\t\t\tawait logging?.log({\n\t\t\t\tsource: SchemaVersionService.CLASS_NAME,\n\t\t\t\tlevel: \"info\",\n\t\t\t\tmessage: \"partitionItemsProgress\",\n\t\t\t\tdata: { progressItem, itemTotal, itemIndex }\n\t\t\t});\n\t\t} else if (progressItem === \"partitionItemsEnd\") {\n\t\t\tawait logging?.log({\n\t\t\t\tsource: SchemaVersionService.CLASS_NAME,\n\t\t\t\tlevel: \"info\",\n\t\t\t\tmessage: \"partitionItemsEnd\",\n\t\t\t\tdata: { progressItem, itemTotal, itemIndex }\n\t\t\t});\n\t\t}\n\t}\n}\n"]}

package/dist/types/entities/schemaVersion.d.ts

@@ -5,7 +5,7 @@
  */
 export declare class SchemaVersion {
     /**
-     * The entity schema type name — primary key.
+     * The entity schema type name - primary key.
      */
     schemaName: string;
     /**

package/dist/types/models/ISchemaVersionServiceConfig.d.ts

@@ -2,6 +2,12 @@
  * Constructor options config for SchemaVersionService.
  */
 export interface ISchemaVersionServiceConfig {
+    /**
+     * Whether schema migration is enabled. When false the service detects pending migrations
+     * and logs a warning for each lagging schema but does not apply any changes.
+     * @default true
+     */
+    enabled?: boolean;
     /**
      * The batch size for processing schema versions.
      */

package/dist/types/schemaVersionService.d.ts

@@ -4,14 +4,14 @@ import type { ISchemaVersionServiceConstructorOptions } from "./models/ISchemaVe
  * Service that checks and applies entity schema migrations at every node start-up.
  *
  * This service must be the first entry in coreTypeInitialisers.json. The engine iterates that
- * array in order to determine start sequence — there is no engine-level priority mechanism, so
+ * array in order to determine start sequence - there is no engine-level priority mechanism, so
  * registration position is the only guarantee that start() runs before any other service.
  * By the time start() is called, all component bootstraps have completed (every table already
  * exists) and EntitySchemaFactory / EntityStorageConnectorFactory are fully populated with every
  * registered schema and connector.
  *
  * Migration mechanics: old schema versions are registered in EntitySchemaFactory by naming
- * convention — current schema = "MyEntity", first history = "MyEntityV0", second = "MyEntityV1".
+ * convention - current schema = "MyEntity", first history = "MyEntityV0", second = "MyEntityV1".
  * The service groups schemas by base name (strips the trailing V number suffix) and resolves the
  * migration chain automatically by diffing consecutive versioned schemas. For steps that require
  * property renames or a custom transform hook, register an optional ISchemaMigration entry in
@@ -45,6 +45,9 @@ export declare class SchemaVersionService implements IComponent {
      * SchemaVersion itself is processed first so the version store is migrated before any
      * version records are written for other schemas.
      *
+     * When config.enabled is false the service runs in detect-only mode: it identifies schemas
+     * that need migration and logs a warning for each one, but applies no changes.
+     *
      * Runs after all component bootstraps, so every managed table already exists.
      * @param nodeLoggingComponentType An optional logging component type.
      */

package/docs/changelog.md

@@ -1,5 +1,149 @@
 # Changelog
 
+## [0.9.2-next.10](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-service-v0.9.2-next.9...entity-storage-service-v0.9.2-next.10) (2026-08-14)
+
+
+### Features
+
+* schema service warning ([#215](https://github.com/iotaledger/twin-entity-storage/issues/215)) ([a69c9ae](https://github.com/iotaledger/twin-entity-storage/commit/a69c9ae54506a1f5dafd0e073678a105cd9ec9b9))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/entity-storage-models bumped from 0.9.2-next.9 to 0.9.2-next.10
+  * devDependencies
+    * @twin.org/entity-storage-connector-memory bumped from 0.9.2-next.9 to 0.9.2-next.10
+
+## [0.9.2-next.9](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-service-v0.9.2-next.8...entity-storage-service-v0.9.2-next.9) (2026-08-12)
+
+
+### Miscellaneous Chores
+
+* **entity-storage-service:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/entity-storage-models bumped from 0.9.2-next.8 to 0.9.2-next.9
+  * devDependencies
+    * @twin.org/entity-storage-connector-memory bumped from 0.9.2-next.8 to 0.9.2-next.9
+
+## [0.9.2-next.8](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-service-v0.9.2-next.7...entity-storage-service-v0.9.2-next.8) (2026-08-12)
+
+
+### Features
+
+* indexing ([#207](https://github.com/iotaledger/twin-entity-storage/issues/207)) ([2fd1f0d](https://github.com/iotaledger/twin-entity-storage/commit/2fd1f0d992344905c9dd1a44addfc4f9d5b5c168))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/entity-storage-models bumped from 0.9.2-next.7 to 0.9.2-next.8
+  * devDependencies
+    * @twin.org/entity-storage-connector-memory bumped from 0.9.2-next.7 to 0.9.2-next.8
+
+## [0.9.2-next.7](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-service-v0.9.2-next.6...entity-storage-service-v0.9.2-next.7) (2026-08-11)
+
+
+### Miscellaneous Chores
+
+* **entity-storage-service:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/entity-storage-models bumped from 0.9.2-next.6 to 0.9.2-next.7
+  * devDependencies
+    * @twin.org/entity-storage-connector-memory bumped from 0.9.2-next.6 to 0.9.2-next.7
+
+## [0.9.2-next.6](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-service-v0.9.2-next.5...entity-storage-service-v0.9.2-next.6) (2026-08-07)
+
+
+### Miscellaneous Chores
+
+* **entity-storage-service:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/entity-storage-models bumped from 0.9.2-next.5 to 0.9.2-next.6
+  * devDependencies
+    * @twin.org/entity-storage-connector-memory bumped from 0.9.2-next.5 to 0.9.2-next.6
+
+## [0.9.2-next.5](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-service-v0.9.2-next.4...entity-storage-service-v0.9.2-next.5) (2026-08-07)
+
+
+### Features
+
+* linting and dependency update ([c307b60](https://github.com/iotaledger/twin-entity-storage/commit/c307b606d03ea436b7c43d4e1764b5c08f415555))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/entity-storage-models bumped from 0.9.2-next.4 to 0.9.2-next.5
+  * devDependencies
+    * @twin.org/entity-storage-connector-memory bumped from 0.9.2-next.4 to 0.9.2-next.5
+
+## [0.9.2-next.4](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-service-v0.9.2-next.3...entity-storage-service-v0.9.2-next.4) (2026-08-04)
+
+
+### Bug Fixes
+
+* schema version check crashes in multi-tenant mode ([#192](https://github.com/iotaledger/twin-entity-storage/issues/192)) ([a816341](https://github.com/iotaledger/twin-entity-storage/commit/a8163415ce116582f3c3c23294f7f4062099d8f3))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/entity-storage-models bumped from 0.9.2-next.3 to 0.9.2-next.4
+  * devDependencies
+    * @twin.org/entity-storage-connector-memory bumped from 0.9.2-next.3 to 0.9.2-next.4
+
+## [0.9.2-next.3](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-service-v0.9.2-next.2...entity-storage-service-v0.9.2-next.3) (2026-08-03)
+
+
+### Miscellaneous Chores
+
+* **entity-storage-service:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/entity-storage-models bumped from 0.9.2-next.2 to 0.9.2-next.3
+  * devDependencies
+    * @twin.org/entity-storage-connector-memory bumped from 0.9.2-next.2 to 0.9.2-next.3
+
+## [0.9.2-next.2](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-service-v0.9.2-next.1...entity-storage-service-v0.9.2-next.2) (2026-07-29)
+
+
+### Bug Fixes
+
+* use existing data during migration ([#186](https://github.com/iotaledger/twin-entity-storage/issues/186)) ([c6e91f5](https://github.com/iotaledger/twin-entity-storage/commit/c6e91f54198d4ab1cc242d0825f63082980d4f9c))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/entity-storage-models bumped from 0.9.2-next.1 to 0.9.2-next.2
+  * devDependencies
+    * @twin.org/entity-storage-connector-memory bumped from 0.9.2-next.1 to 0.9.2-next.2
+
 ## [0.9.2-next.1](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-service-v0.9.2-next.0...entity-storage-service-v0.9.2-next.1) (2026-07-29)
 
 

package/docs/reference/classes/SchemaVersion.md

@@ -20,7 +20,7 @@ each successful migration.
 
 > **schemaName**: `string`
 
-The entity schema type name — primary key.
+The entity schema type name - primary key.
 
 ***
 

package/docs/reference/classes/SchemaVersionService.md

@@ -3,14 +3,14 @@
 Service that checks and applies entity schema migrations at every node start-up.
 
 This service must be the first entry in coreTypeInitialisers.json. The engine iterates that
-array in order to determine start sequence — there is no engine-level priority mechanism, so
+array in order to determine start sequence - there is no engine-level priority mechanism, so
 registration position is the only guarantee that start() runs before any other service.
 By the time start() is called, all component bootstraps have completed (every table already
 exists) and EntitySchemaFactory / EntityStorageConnectorFactory are fully populated with every
 registered schema and connector.
 
 Migration mechanics: old schema versions are registered in EntitySchemaFactory by naming
-convention — current schema = "MyEntity", first history = "MyEntityV0", second = "MyEntityV1".
+convention - current schema = "MyEntity", first history = "MyEntityV0", second = "MyEntityV1".
 The service groups schemas by base name (strips the trailing V number suffix) and resolves the
 migration chain automatically by diffing consecutive versioned schemas. For steps that require
 property renames or a custom transform hook, register an optional ISchemaMigration entry in
@@ -84,6 +84,9 @@ whose stored version is behind the current version declared in EntitySchemaFacto
 SchemaVersion itself is processed first so the version store is migrated before any
 version records are written for other schemas.
 
+When config.enabled is false the service runs in detect-only mode: it identifies schemas
+that need migration and logs a warning for each one, but applies no changes.
+
 Runs after all component bootstraps, so every managed table already exists.
 
 #### Parameters

package/docs/reference/interfaces/ISchemaVersionServiceConfig.md

@@ -4,6 +4,21 @@ Constructor options config for SchemaVersionService.
 
 ## Properties
 
+### enabled? {#enabled}
+
+> `optional` **enabled?**: `boolean`
+
+Whether schema migration is enabled. When false the service detects pending migrations
+and logs a warning for each lagging schema but does not apply any changes.
+
+#### Default
+
+```ts
+true
+```
+
+***
+
 ### batchSize? {#batchsize}
 
 > `optional` **batchSize?**: `number`

package/locales/en.json

@@ -7,10 +7,17 @@
 			"connectorNotMigrationCapable": "Schema \"{schemaName}\" needs migration from version {stored} to {current} but its connector does not support automatic migration. Please migrate the schema manually before starting the node."
 		}
 	},
+	"warn": {
+		"schemaVersionService": {
+			"migrationDisabled": "Schema migration is disabled. Schema \"{schemaName}\" requires migration from version {from} to {to}. Continuing without migration may cause errors."
+		}
+	},
 	"info": {
 		"schemaVersionService": {
 			"noMigrationRequired": "No migration required for schema \"{schemaName}\", version {version}.",
 			"migrationRequired": "Migration required for schema \"{schemaName}\" from version {from} to {to}.",
+			"connectorVersionUpdated": "Connector version changed from {from} to {to}; forcing schema migrations.",
+			"connectorVersionForceUpgrade": "Forcing migration for schema \"{schemaName}\" because connector version changed.",
 			"partitionStart": "Starting migration of {itemTotal} partitions.",
 			"partitionProgress": "Migrating partition {itemIndex} of {itemTotal}.",
 			"partitionEnd": "Completed migration of {itemTotal} partitions.",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/entity-storage-service",
-	"version": "0.9.2-next.1",
+	"version": "0.9.2-next.10",
 	"description": "Service layer exposing storage contracts and REST endpoint definitions.",
 	"repository": {
 		"type": "git",
@@ -15,9 +15,10 @@
 	},
 	"dependencies": {
 		"@twin.org/api-models": "next",
+		"@twin.org/context": "next",
 		"@twin.org/core": "next",
 		"@twin.org/entity": "next",
-		"@twin.org/entity-storage-models": "0.9.2-next.1",
+		"@twin.org/entity-storage-models": "0.9.2-next.10",
 		"@twin.org/logging-models": "next",
 		"@twin.org/nameof": "next",
 		"@twin.org/web": "next"