@twin.org/entity-storage-models 0.0.3-next.23 → 0.0.3-next.24

package/dist/es/entities/schemaVersion.js

@@ -0,0 +1,39 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { entity, property } from "@twin.org/entity";
+/**
+ * Tracks the currently applied schema version for each managed entity schema.
+ * One record per schema name. Written once on first boot, then updated after
+ * each successful migration.
+ */
+let SchemaVersion = class SchemaVersion {
+    /**
+     * The entity schema type name — primary key.
+     */
+    schemaName;
+    /**
+     * The currently deployed version of this schema.
+     */
+    version;
+    /**
+     * ISO 8601 timestamp of the last version write.
+     */
+    updatedAt;
+};
+__decorate([
+    property({ type: "string", isPrimary: true }),
+    __metadata("design:type", String)
+], SchemaVersion.prototype, "schemaName", void 0);
+__decorate([
+    property({ type: "integer" }),
+    __metadata("design:type", Number)
+], SchemaVersion.prototype, "version", void 0);
+__decorate([
+    property({ type: "string", format: "date-time" }),
+    __metadata("design:type", String)
+], SchemaVersion.prototype, "updatedAt", void 0);
+SchemaVersion = __decorate([
+    entity()
+], SchemaVersion);
+export { SchemaVersion };
+//# sourceMappingURL=schemaVersion.js.map

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

@@ -0,0 +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"]}

package/dist/es/factories/schemaMigrationFactory.js

@@ -9,7 +9,7 @@ import { Factory } from "@twin.org/core";
  * SchemaVersionService diffs the two versioned schema classes automatically
  * without needing any factory entry.
  *
- * Keys follow the convention "<BaseSchemaName>_<fromVersion>_<toVersion>",
+ * Keys follow the convention "BaseSchemaName_fromVersion_toVersion",
  * for example "MyEntity_0_1" for the step that migrates MyEntity from version 0 to 1.
  */
 // eslint-disable-next-line @typescript-eslint/naming-convention

package/dist/es/factories/schemaMigrationFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"schemaMigrationFactory.js","sourceRoot":"","sources":["../../../src/factories/schemaMigrationFactory.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAGzC;;;;;;;;;;GAUG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,sBAAsB,GAAG,OAAO,CAAC,aAAa,CAAmB,kBAAkB,CAAC,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Factory } from \"@twin.org/core\";\nimport type { ISchemaMigration } from \"../models/ISchemaMigration.js\";\n\n/**\n * Factory for optional per-step migration overrides.\n *\n * Only register an entry when a version step requires property renames or a custom\n * transform hook. For purely structural changes (add/remove/type-change) the\n * SchemaVersionService diffs the two versioned schema classes automatically\n * without needing any factory entry.\n *\n * Keys follow the convention \"<BaseSchemaName>_<fromVersion>_<toVersion>\",\n * for example \"MyEntity_0_1\" for the step that migrates MyEntity from version 0 to 1.\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const SchemaMigrationFactory = Factory.createFactory<ISchemaMigration>(\"schema-migration\");\n"]}
+{"version":3,"file":"schemaMigrationFactory.js","sourceRoot":"","sources":["../../../src/factories/schemaMigrationFactory.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAGzC;;;;;;;;;;GAUG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,sBAAsB,GAAG,OAAO,CAAC,aAAa,CAAmB,kBAAkB,CAAC,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Factory } from \"@twin.org/core\";\nimport type { ISchemaMigration } from \"../models/ISchemaMigration.js\";\n\n/**\n * Factory for optional per-step migration overrides.\n *\n * Only register an entry when a version step requires property renames or a custom\n * transform hook. For purely structural changes (add/remove/type-change) the\n * SchemaVersionService diffs the two versioned schema classes automatically\n * without needing any factory entry.\n *\n * Keys follow the convention \"BaseSchemaName_fromVersion_toVersion\",\n * for example \"MyEntity_0_1\" for the step that migrates MyEntity from version 0 to 1.\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const SchemaMigrationFactory = Factory.createFactory<ISchemaMigration>(\"schema-migration\");\n"]}

package/dist/es/index.js

@@ -1,5 +1,6 @@
 // Copyright 2026 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
+export * from "./entities/schemaVersion.js";
 export * from "./factories/entityStorageConnectorFactory.js";
 export * from "./factories/schemaMigrationFactory.js";
 export * from "./helpers/entityStorageHelper.js";
@@ -21,4 +22,6 @@ export * from "./models/IEntityStorageMigrationConnector.js";
 export * from "./models/IMigrationOptions.js";
 export * from "./models/IResolvedMigrationStep.js";
 export * from "./models/ISchemaMigration.js";
+export * from "./schema.js";
+export * from "./services/schemaVersionService.js";
 //# sourceMappingURL=index.js.map

package/dist/es/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,8CAA8C,CAAC;AAC7D,cAAc,uCAAuC,CAAC;AACtD,cAAc,kCAAkC,CAAC;AACjD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4CAA4C,CAAC;AAC3D,cAAc,6CAA6C,CAAC;AAC5D,cAAc,4CAA4C,CAAC;AAC3D,cAAc,0CAA0C,CAAC;AACzD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,2CAA2C,CAAC;AAC1D,cAAc,4CAA4C,CAAC;AAC3D,cAAc,kDAAkD,CAAC;AACjE,cAAc,6CAA6C,CAAC;AAC5D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,0CAA0C,CAAC;AACzD,cAAc,qCAAqC,CAAC;AACpD,cAAc,qCAAqC,CAAC;AACpD,cAAc,8CAA8C,CAAC;AAC7D,cAAc,+BAA+B,CAAC;AAC9C,cAAc,oCAAoC,CAAC;AACnD,cAAc,8BAA8B,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./factories/entityStorageConnectorFactory.js\";\nexport * from \"./factories/schemaMigrationFactory.js\";\nexport * from \"./helpers/entityStorageHelper.js\";\nexport * from \"./helpers/migrationHelper.js\";\nexport * from \"./models/api/IEntityStorageCountRequest.js\";\nexport * from \"./models/api/IEntityStorageCountResponse.js\";\nexport * from \"./models/api/IEntityStorageEmptyRequest.js\";\nexport * from \"./models/api/IEntityStorageGetRequest.js\";\nexport * from \"./models/api/IEntityStorageGetResponse.js\";\nexport * from \"./models/api/IEntityStorageListRequest.js\";\nexport * from \"./models/api/IEntityStorageListResponse.js\";\nexport * from \"./models/api/IEntityStorageRemoveBatchRequest.js\";\nexport * from \"./models/api/IEntityStorageRemoveRequest.js\";\nexport * from \"./models/api/IEntityStorageSetBatchRequest.js\";\nexport * from \"./models/api/IEntityStorageSetRequest.js\";\nexport * from \"./models/IEntityStorageComponent.js\";\nexport * from \"./models/IEntityStorageConnector.js\";\nexport * from \"./models/IEntityStorageMigrationConnector.js\";\nexport * from \"./models/IMigrationOptions.js\";\nexport * from \"./models/IResolvedMigrationStep.js\";\nexport * from \"./models/ISchemaMigration.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8CAA8C,CAAC;AAC7D,cAAc,uCAAuC,CAAC;AACtD,cAAc,kCAAkC,CAAC;AACjD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4CAA4C,CAAC;AAC3D,cAAc,6CAA6C,CAAC;AAC5D,cAAc,4CAA4C,CAAC;AAC3D,cAAc,0CAA0C,CAAC;AACzD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,2CAA2C,CAAC;AAC1D,cAAc,4CAA4C,CAAC;AAC3D,cAAc,kDAAkD,CAAC;AACjE,cAAc,6CAA6C,CAAC;AAC5D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,0CAA0C,CAAC;AACzD,cAAc,qCAAqC,CAAC;AACpD,cAAc,qCAAqC,CAAC;AACpD,cAAc,8CAA8C,CAAC;AAC7D,cAAc,+BAA+B,CAAC;AAC9C,cAAc,oCAAoC,CAAC;AACnD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,aAAa,CAAC;AAC5B,cAAc,oCAAoC,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./entities/schemaVersion.js\";\nexport * from \"./factories/entityStorageConnectorFactory.js\";\nexport * from \"./factories/schemaMigrationFactory.js\";\nexport * from \"./helpers/entityStorageHelper.js\";\nexport * from \"./helpers/migrationHelper.js\";\nexport * from \"./models/api/IEntityStorageCountRequest.js\";\nexport * from \"./models/api/IEntityStorageCountResponse.js\";\nexport * from \"./models/api/IEntityStorageEmptyRequest.js\";\nexport * from \"./models/api/IEntityStorageGetRequest.js\";\nexport * from \"./models/api/IEntityStorageGetResponse.js\";\nexport * from \"./models/api/IEntityStorageListRequest.js\";\nexport * from \"./models/api/IEntityStorageListResponse.js\";\nexport * from \"./models/api/IEntityStorageRemoveBatchRequest.js\";\nexport * from \"./models/api/IEntityStorageRemoveRequest.js\";\nexport * from \"./models/api/IEntityStorageSetBatchRequest.js\";\nexport * from \"./models/api/IEntityStorageSetRequest.js\";\nexport * from \"./models/IEntityStorageComponent.js\";\nexport * from \"./models/IEntityStorageConnector.js\";\nexport * from \"./models/IEntityStorageMigrationConnector.js\";\nexport * from \"./models/IMigrationOptions.js\";\nexport * from \"./models/IResolvedMigrationStep.js\";\nexport * from \"./models/ISchemaMigration.js\";\nexport * from \"./schema.js\";\nexport * from \"./services/schemaVersionService.js\";\n"]}

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

@@ -1 +1 @@
-{"version":3,"file":"ISchemaMigration.js","sourceRoot":"","sources":["../../../src/models/ISchemaMigration.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IMigrationOptions } from \"./IMigrationOptions.js\";\n\n/**\n * Optional per-step override for a single version-to-version migration.\n * Only register an entry in SchemaMigrationFactory when a step requires property\n * renames or a custom object/array transform. For purely structural changes\n * (add/remove/type-change fields) no entry is needed — the runner diffs the two\n * versioned schema classes (e.g. MyEntityV0 vs MyEntityV1) from EntitySchemaFactory\n * automatically.\n *\n * Register under the key \"<BaseSchemaName>_<fromVersion>_<toVersion>\"\n * e.g. \"MyEntity_0_1\" for the step that migrates from version 0 to version 1.\n * The key itself encodes the version pair; no version field is needed on the object.\n */\nexport interface ISchemaMigration<T = unknown, U = unknown> {\n\t/**\n\t * Optional property renames to apply during this step.\n\t */\n\trenames?: { from: string; to: string }[];\n\n\t/**\n\t * Optional per-property transformer for object/array properties that cannot be\n\t * automatically coerced. T is the source entity type, U is the target entity type.\n\t */\n\ttransformEntityProperty?: IMigrationOptions<T, U>[\"transformEntityProperty\"];\n}\n"]}
+{"version":3,"file":"ISchemaMigration.js","sourceRoot":"","sources":["../../../src/models/ISchemaMigration.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IMigrationOptions } from \"./IMigrationOptions.js\";\n\n/**\n * Optional per-step override for a single version-to-version migration.\n * Only register an entry in SchemaMigrationFactory when a step requires property\n * renames or a custom object/array transform. For purely structural changes\n * (add/remove/type-change fields) no entry is needed — the runner diffs the two\n * versioned schema classes (e.g. MyEntityV0 vs MyEntityV1) from EntitySchemaFactory\n * automatically.\n *\n * Register under the key \"BaseSchemaName_fromVersion_toVersion\"\n * e.g. \"MyEntity_0_1\" for the step that migrates from version 0 to version 1.\n * The key itself encodes the version pair; no version field is needed on the object.\n */\nexport interface ISchemaMigration<T = unknown, U = unknown> {\n\t/**\n\t * Optional property renames to apply during this step.\n\t */\n\trenames?: { from: string; to: string }[];\n\n\t/**\n\t * Optional per-property transformer for object/array properties that cannot be\n\t * automatically coerced. T is the source entity type, U is the target entity type.\n\t */\n\ttransformEntityProperty?: IMigrationOptions<T, U>[\"transformEntityProperty\"];\n}\n"]}

package/dist/es/schema.js

@@ -0,0 +1,11 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { EntitySchemaFactory, EntitySchemaHelper } from "@twin.org/entity";
+import { SchemaVersion } from "./entities/schemaVersion.js";
+/**
+ * Initialize the schema for the entity storage models.
+ */
+export function initSchema() {
+    EntitySchemaFactory.register("SchemaVersion", () => EntitySchemaHelper.getSchema(SchemaVersion));
+}
+//# sourceMappingURL=schema.js.map

package/dist/es/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/schema.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3E,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAE5D;;GAEG;AACH,MAAM,UAAU,UAAU;IACzB,mBAAmB,CAAC,QAAQ,kBAA0B,GAAG,EAAE,CAC1D,kBAAkB,CAAC,SAAS,CAAC,aAAa,CAAC,CAC3C,CAAC;AACH,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { EntitySchemaFactory, EntitySchemaHelper } from \"@twin.org/entity\";\nimport { nameof } from \"@twin.org/nameof\";\nimport { SchemaVersion } from \"./entities/schemaVersion.js\";\n\n/**\n * Initialize the schema for the entity storage models.\n */\nexport function initSchema(): void {\n\tEntitySchemaFactory.register(nameof<SchemaVersion>(), () =>\n\t\tEntitySchemaHelper.getSchema(SchemaVersion)\n\t);\n}\n"]}

package/dist/es/services/schemaVersionService.js

@@ -0,0 +1,265 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { GeneralError, Guards, Is } from "@twin.org/core";
+import { EntitySchemaFactory, EntitySchemaHelper } from "@twin.org/entity";
+import { SchemaVersion } from "../entities/schemaVersion.js";
+import { EntityStorageConnectorFactory } from "../factories/entityStorageConnectorFactory.js";
+import { SchemaMigrationFactory } from "../factories/schemaMigrationFactory.js";
+import { MigrationHelper } from "../helpers/migrationHelper.js";
+/**
+ * IComponent 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
+ * 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".
+ * 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
+ * SchemaMigrationFactory under the key "Base_from_to" (e.g. "MyEntity_0_1").
+ *
+ * Crash-window note: finalizeMigration and the subsequent version-record write are two
+ * separate operations. If the process dies between them the next boot re-runs the chain
+ * over already-migrated data. applyEntityTransform is NOT idempotent for structural changes
+ * (newly-added optional fields would be dropped on re-run). A transaction spanning both
+ * writes is a precondition for production; track this in the concurrency follow-up.
+ */
+export class SchemaVersionService {
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "SchemaVersionService";
+    /**
+     * Regex to detect a versioned schema name and extract the base name and version number.
+     * Matches names like "MyEntityV0", "AuditableItemGraphV2", etc.
+     * @internal
+     */
+    static _VERSION_SUFFIX_RE = /^(.+)V(\d+)$/;
+    /**
+     * The connector used to read and write SchemaVersion records.
+     * @internal
+     */
+    _versionConnector;
+    /**
+     * Create a new SchemaVersionService.
+     * @param versionConnector Entity-storage connector backed by the schemaVersion table.
+     */
+    constructor(versionConnector) {
+        Guards.object(SchemaVersionService.CLASS_NAME, "versionConnector", versionConnector);
+        this._versionConnector = versionConnector;
+    }
+    /**
+     * Searches EntityStorageConnectorFactory for the connector whose registered schema type
+     * matches the given schema name.
+     * @param schemaName The entity type name to look up.
+     * @returns The matching connector, or undefined if none is registered.
+     * @internal
+     */
+    static findConnector(schemaName) {
+        for (const name of EntityStorageConnectorFactory.names()) {
+            try {
+                const connector = EntityStorageConnectorFactory.get(name);
+                if (connector.getSchema?.().type === schemaName) {
+                    return connector;
+                }
+            }
+            catch {
+                // Connector not yet created or registration issue — skip.
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Returns the class name.
+     * @returns The class name.
+     */
+    className() {
+        return SchemaVersionService.CLASS_NAME;
+    }
+    /**
+     * Bootstraps the version-store connector so the schemaVersion table exists
+     * before start() attempts to read or write version records.
+     * @param nodeLoggingComponentType An optional logging component type.
+     * @returns True on success.
+     */
+    async bootstrap(nodeLoggingComponentType) {
+        const bootstrapFn = this._versionConnector.bootstrap?.bind(this._versionConnector);
+        if (Is.function(bootstrapFn)) {
+            return bootstrapFn(nodeLoggingComponentType);
+        }
+        return true;
+    }
+    /**
+     * Reads all registered entity schemas, groups versioned schemas by base name, reads the
+     * full schemaVersion table in one pass, then orchestrates chain migrations for any schema
+     * whose stored version is behind the current version declared in EntitySchemaFactory.
+     * SchemaVersion itself is processed first so the version store is migrated before any
+     * version records are written for other schemas.
+     *
+     * Runs after all component bootstraps, so every managed table already exists.
+     * @param nodeLoggingComponentType An optional logging component type.
+     */
+    async start(nodeLoggingComponentType) {
+        // 1. Collect all registered schema names and partition into current vs historical.
+        const allNames = EntitySchemaFactory.names();
+        const historicalByBase = new Map();
+        const currentSchemas = new Map();
+        for (const name of allNames) {
+            const match = SchemaVersionService._VERSION_SUFFIX_RE.exec(name);
+            if (match) {
+                const baseName = match[1];
+                const version = Number.parseInt(match[2], 10);
+                let versions = historicalByBase.get(baseName);
+                if (!versions) {
+                    versions = new Map();
+                    historicalByBase.set(baseName, versions);
+                }
+                versions.set(version, EntitySchemaFactory.get(name));
+            }
+            else {
+                currentSchemas.set(name, EntitySchemaFactory.get(name));
+            }
+        }
+        // 2. Read ALL stored version records, paging through the full table.
+        const storedVersions = new Map();
+        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);
+                }
+            }
+            cursor = queryResult.cursor;
+        } while (Is.stringValue(cursor));
+        // 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), nodeLoggingComponentType);
+        }
+        // 4. Process all remaining schemas.
+        for (const [schemaName, schema] of currentSchemas) {
+            await this.processSchema(schemaName, schema, storedVersions, historicalByBase.get(schemaName), nodeLoggingComponentType);
+        }
+    }
+    /**
+     * Checks and applies any pending migration for a single entity schema.
+     * 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 history The versioned-schema map for this schema (historicalByBase.get(schemaName)), or undefined if none exist.
+     * @param nodeLoggingComponentType An optional logging component type.
+     * @internal
+     */
+    async processSchema(schemaName, schema, storedVersions, history, nodeLoggingComponentType) {
+        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
+        // it through the factory, which could resolve a different instance than _versionConnector.
+        const connector = schemaName === "SchemaVersion"
+            ? this._versionConnector
+            : SchemaVersionService.findConnector(schemaName);
+        if (!connector) {
+            // No connector registered for this schema — nothing to migrate.
+            return;
+        }
+        // Resolve the stored version, applying the backwards-compat baseline when no record exists.
+        const stored = storedVersions.get(schemaName);
+        let resolvedStored;
+        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.
+            resolvedStored = 0;
+            await this.writeVersion(schemaName, 0);
+        }
+        else {
+            resolvedStored = stored;
+        }
+        // No-op: stored version already matches current.
+        if (resolvedStored === currentVersion) {
+            return;
+        }
+        // Downgrade — not supported.
+        if (resolvedStored > currentVersion) {
+            throw new GeneralError(SchemaVersionService.CLASS_NAME, "storedVersionNewer", {
+                schemaName,
+                stored: resolvedStored,
+                current: currentVersion
+            });
+        }
+        // Migration is needed. If the connector does not support it, throw immediately so
+        // the problem surfaces at boot rather than at runtime when writes hit the wrong table shape.
+        if (!("createTargetConnector" in connector)) {
+            throw new GeneralError(SchemaVersionService.CLASS_NAME, "connectorNotMigrationCapable", {
+                schemaName,
+                stored: resolvedStored,
+                current: currentVersion
+            });
+        }
+        const migrationConnector = connector;
+        // Upgrade — resolve and run the chain.
+        const steps = [];
+        for (let v = resolvedStored; v < currentVersion; v++) {
+            const fromSchema = history?.get(v);
+            if (!fromSchema) {
+                throw new GeneralError(SchemaVersionService.CLASS_NAME, "noMigrationStep", {
+                    schemaName,
+                    stored: resolvedStored,
+                    current: currentVersion,
+                    missingFromVersion: v,
+                    missingToVersion: v + 1
+                });
+            }
+            const toSchema = v + 1 < currentVersion ? history?.get(v + 1) : schema;
+            if (!toSchema) {
+                throw new GeneralError(SchemaVersionService.CLASS_NAME, "noMigrationStepTarget", {
+                    schemaName,
+                    stored: resolvedStored,
+                    current: currentVersion,
+                    missingFromVersion: v,
+                    missingToVersion: v + 1
+                });
+            }
+            const overrideKey = `${schemaName}_${v}_${v + 1}`;
+            const override = SchemaMigrationFactory.getIfExists(overrideKey);
+            steps.push({
+                fromProperties: fromSchema.properties ?? [],
+                toProperties: toSchema.properties ?? [],
+                renames: override?.renames,
+                transformEntityProperty: override?.transformEntityProperty
+            });
+        }
+        await MigrationHelper.migrateWithChain(migrationConnector, schemaName, steps, nodeLoggingComponentType);
+        // Advance the stored version only after finalizeMigration has succeeded.
+        // See crash-window note in the class comment.
+        await this.writeVersion(schemaName, currentVersion);
+    }
+    /**
+     * Upserts a SchemaVersion record for the given schema name.
+     * @param schemaName The schema type name.
+     * @param version The version to record.
+     * @internal
+     */
+    async writeVersion(schemaName, version) {
+        await this._versionConnector.set({
+            schemaName,
+            version,
+            updatedAt: new Date().toISOString()
+        });
+    }
+}
+//# sourceMappingURL=schemaVersionService.js.map

package/dist/es/services/schemaVersionService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemaVersionService.js","sourceRoot":"","sources":["../../../src/services/schemaVersionService.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { GeneralError, Guards, Is, type IComponent } from \"@twin.org/core\";\nimport { EntitySchemaFactory, EntitySchemaHelper, type IEntitySchema } from \"@twin.org/entity\";\nimport { nameof } from \"@twin.org/nameof\";\nimport { SchemaVersion } from \"../entities/schemaVersion.js\";\nimport { EntityStorageConnectorFactory } from \"../factories/entityStorageConnectorFactory.js\";\nimport { SchemaMigrationFactory } from \"../factories/schemaMigrationFactory.js\";\nimport { MigrationHelper } from \"../helpers/migrationHelper.js\";\nimport type { IEntityStorageConnector } from \"../models/IEntityStorageConnector.js\";\nimport type { IEntityStorageMigrationConnector } from \"../models/IEntityStorageMigrationConnector.js\";\nimport type { IResolvedMigrationStep } from \"../models/IResolvedMigrationStep.js\";\n\n/**\n * IComponent 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 * @internal\n\t */\n\tprivate readonly _versionConnector: IEntityStorageConnector<SchemaVersion>;\n\n\t/**\n\t * Create a new SchemaVersionService.\n\t * @param versionConnector Entity-storage connector backed by the schemaVersion table.\n\t */\n\tconstructor(versionConnector: IEntityStorageConnector<SchemaVersion>) {\n\t\tGuards.object<IEntityStorageConnector<SchemaVersion>>(\n\t\t\tSchemaVersionService.CLASS_NAME,\n\t\t\tnameof(versionConnector),\n\t\t\tversionConnector\n\t\t);\n\t\tthis._versionConnector = versionConnector;\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, or undefined if none is registered.\n\t * @internal\n\t */\n\tprivate static findConnector(schemaName: string): IEntityStorageConnector | 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;\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 * 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 * Bootstraps the version-store connector so the schemaVersion table exists\n\t * before start() attempts to read or write version records.\n\t * @param nodeLoggingComponentType An optional logging component type.\n\t * @returns True on success.\n\t */\n\tpublic async bootstrap(nodeLoggingComponentType?: string): Promise<boolean> {\n\t\tconst bootstrapFn = this._versionConnector.bootstrap?.bind(this._versionConnector);\n\t\tif (Is.function(bootstrapFn)) {\n\t\t\treturn bootstrapFn(nodeLoggingComponentType);\n\t\t}\n\t\treturn true;\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\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\tnodeLoggingComponentType\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\tnodeLoggingComponentType\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 nodeLoggingComponentType An optional logging component type.\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\tnodeLoggingComponentType: string | 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 connector =\n\t\t\tschemaName === nameof(SchemaVersion)\n\t\t\t\t? this._versionConnector\n\t\t\t\t: SchemaVersionService.findConnector(schemaName);\n\t\tif (!connector) {\n\t\t\t// No connector registered for this schema — nothing to migrate.\n\t\t\treturn;\n\t\t}\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 resolvedStored: 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\tresolvedStored = 0;\n\t\t\tawait this.writeVersion(schemaName, 0);\n\t\t} else {\n\t\t\tresolvedStored = stored;\n\t\t}\n\n\t\t// No-op: stored version already matches current.\n\t\tif (resolvedStored === currentVersion) {\n\t\t\treturn;\n\t\t}\n\n\t\t// Downgrade — not supported.\n\t\tif (resolvedStored > currentVersion) {\n\t\t\tthrow new GeneralError(SchemaVersionService.CLASS_NAME, \"storedVersionNewer\", {\n\t\t\t\tschemaName,\n\t\t\t\tstored: resolvedStored,\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: resolvedStored,\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 = resolvedStored; 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: resolvedStored,\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: resolvedStored,\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\tawait MigrationHelper.migrateWithChain(\n\t\t\tmigrationConnector,\n\t\t\tschemaName,\n\t\t\tsteps,\n\t\t\tnodeLoggingComponentType\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"]}

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

@@ -0,0 +1,19 @@
+/**
+ * Tracks the currently applied schema version for each managed entity schema.
+ * One record per schema name. Written once on first boot, then updated after
+ * each successful migration.
+ */
+export declare class SchemaVersion {
+    /**
+     * The entity schema type name — primary key.
+     */
+    schemaName: string;
+    /**
+     * The currently deployed version of this schema.
+     */
+    version: number;
+    /**
+     * ISO 8601 timestamp of the last version write.
+     */
+    updatedAt: string;
+}

package/dist/types/factories/schemaMigrationFactory.d.ts

@@ -8,7 +8,7 @@ import type { ISchemaMigration } from "../models/ISchemaMigration.js";
  * SchemaVersionService diffs the two versioned schema classes automatically
  * without needing any factory entry.
  *
- * Keys follow the convention "<BaseSchemaName>_<fromVersion>_<toVersion>",
+ * Keys follow the convention "BaseSchemaName_fromVersion_toVersion",
  * for example "MyEntity_0_1" for the step that migrates MyEntity from version 0 to 1.
  */
 export declare const SchemaMigrationFactory: Factory<ISchemaMigration<unknown, unknown>>;

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./entities/schemaVersion.js";
 export * from "./factories/entityStorageConnectorFactory.js";
 export * from "./factories/schemaMigrationFactory.js";
 export * from "./helpers/entityStorageHelper.js";
@@ -19,3 +20,5 @@ export * from "./models/IEntityStorageMigrationConnector.js";
 export * from "./models/IMigrationOptions.js";
 export * from "./models/IResolvedMigrationStep.js";
 export * from "./models/ISchemaMigration.js";
+export * from "./schema.js";
+export * from "./services/schemaVersionService.js";

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

@@ -7,7 +7,7 @@ import type { IMigrationOptions } from "./IMigrationOptions.js";
  * versioned schema classes (e.g. MyEntityV0 vs MyEntityV1) from EntitySchemaFactory
  * automatically.
  *
- * Register under the key "<BaseSchemaName>_<fromVersion>_<toVersion>"
+ * Register under the key "BaseSchemaName_fromVersion_toVersion"
  * e.g. "MyEntity_0_1" for the step that migrates from version 0 to version 1.
  * The key itself encodes the version pair; no version field is needed on the object.
  */

package/dist/types/schema.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Initialize the schema for the entity storage models.
+ */
+export declare function initSchema(): void;

package/dist/types/services/schemaVersionService.d.ts

@@ -0,0 +1,60 @@
+import { type IComponent } from "@twin.org/core";
+import { SchemaVersion } from "../entities/schemaVersion.js";
+import type { IEntityStorageConnector } from "../models/IEntityStorageConnector.js";
+/**
+ * IComponent 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
+ * 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".
+ * 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
+ * SchemaMigrationFactory under the key "Base_from_to" (e.g. "MyEntity_0_1").
+ *
+ * Crash-window note: finalizeMigration and the subsequent version-record write are two
+ * separate operations. If the process dies between them the next boot re-runs the chain
+ * over already-migrated data. applyEntityTransform is NOT idempotent for structural changes
+ * (newly-added optional fields would be dropped on re-run). A transaction spanning both
+ * writes is a precondition for production; track this in the concurrency follow-up.
+ */
+export declare class SchemaVersionService implements IComponent {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Create a new SchemaVersionService.
+     * @param versionConnector Entity-storage connector backed by the schemaVersion table.
+     */
+    constructor(versionConnector: IEntityStorageConnector<SchemaVersion>);
+    /**
+     * Returns the class name.
+     * @returns The class name.
+     */
+    className(): string;
+    /**
+     * Bootstraps the version-store connector so the schemaVersion table exists
+     * before start() attempts to read or write version records.
+     * @param nodeLoggingComponentType An optional logging component type.
+     * @returns True on success.
+     */
+    bootstrap(nodeLoggingComponentType?: string): Promise<boolean>;
+    /**
+     * Reads all registered entity schemas, groups versioned schemas by base name, reads the
+     * full schemaVersion table in one pass, then orchestrates chain migrations for any schema
+     * whose stored version is behind the current version declared in EntitySchemaFactory.
+     * SchemaVersion itself is processed first so the version store is migrated before any
+     * version records are written for other schemas.
+     *
+     * Runs after all component bootstraps, so every managed table already exists.
+     * @param nodeLoggingComponentType An optional logging component type.
+     */
+    start(nodeLoggingComponentType?: string): Promise<void>;
+}

package/docs/changelog.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.0.3-next.24](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-models-v0.0.3-next.23...entity-storage-models-v0.0.3-next.24) (2026-06-08)
+
+
+### Features
+
+* add SchemaVersionService for automatic schema migrations ([#118](https://github.com/iotaledger/twin-entity-storage/issues/118)) ([b2ad843](https://github.com/iotaledger/twin-entity-storage/commit/b2ad8435185c53304aca99eb4d98582009b3902d))
+
+
+### Bug Fixes
+
+* docs ([1a30170](https://github.com/iotaledger/twin-entity-storage/commit/1a301707ee0cb48314223347a6e9f3b3a3a7362d))
+
 ## [0.0.3-next.23](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-models-v0.0.3-next.22...entity-storage-models-v0.0.3-next.23) (2026-06-08)
 
 

package/docs/reference/classes/SchemaVersion.md

@@ -0,0 +1,39 @@
+# Class: SchemaVersion
+
+Tracks the currently applied schema version for each managed entity schema.
+One record per schema name. Written once on first boot, then updated after
+each successful migration.
+
+## Constructors
+
+### Constructor
+
+> **new SchemaVersion**(): `SchemaVersion`
+
+#### Returns
+
+`SchemaVersion`
+
+## Properties
+
+### schemaName {#schemaname}
+
+> **schemaName**: `string`
+
+The entity schema type name — primary key.
+
+***
+
+### version {#version}
+
+> **version**: `number`
+
+The currently deployed version of this schema.
+
+***
+
+### updatedAt {#updatedat}
+
+> **updatedAt**: `string`
+
+ISO 8601 timestamp of the last version write.

package/docs/reference/classes/SchemaVersionService.md

@@ -0,0 +1,130 @@
+# Class: SchemaVersionService
+
+IComponent 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
+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".
+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
+SchemaMigrationFactory under the key "Base_from_to" (e.g. "MyEntity_0_1").
+
+Crash-window note: finalizeMigration and the subsequent version-record write are two
+separate operations. If the process dies between them the next boot re-runs the chain
+over already-migrated data. applyEntityTransform is NOT idempotent for structural changes
+(newly-added optional fields would be dropped on re-run). A transaction spanning both
+writes is a precondition for production; track this in the concurrency follow-up.
+
+## Implements
+
+- `IComponent`
+
+## Constructors
+
+### Constructor
+
+> **new SchemaVersionService**(`versionConnector`): `SchemaVersionService`
+
+Create a new SchemaVersionService.
+
+#### Parameters
+
+##### versionConnector
+
+[`IEntityStorageConnector`](../interfaces/IEntityStorageConnector.md)\<[`SchemaVersion`](SchemaVersion.md)\>
+
+Entity-storage connector backed by the schemaVersion table.
+
+#### Returns
+
+`SchemaVersionService`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+## Methods
+
+### className() {#classname}
+
+> **className**(): `string`
+
+Returns the class name.
+
+#### Returns
+
+`string`
+
+The class name.
+
+#### Implementation of
+
+`IComponent.className`
+
+***
+
+### bootstrap() {#bootstrap}
+
+> **bootstrap**(`nodeLoggingComponentType?`): `Promise`\<`boolean`\>
+
+Bootstraps the version-store connector so the schemaVersion table exists
+before start() attempts to read or write version records.
+
+#### Parameters
+
+##### nodeLoggingComponentType?
+
+`string`
+
+An optional logging component type.
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+True on success.
+
+#### Implementation of
+
+`IComponent.bootstrap`
+
+***
+
+### start() {#start}
+
+> **start**(`nodeLoggingComponentType?`): `Promise`\<`void`\>
+
+Reads all registered entity schemas, groups versioned schemas by base name, reads the
+full schemaVersion table in one pass, then orchestrates chain migrations for any schema
+whose stored version is behind the current version declared in EntitySchemaFactory.
+SchemaVersion itself is processed first so the version store is migrated before any
+version records are written for other schemas.
+
+Runs after all component bootstraps, so every managed table already exists.
+
+#### Parameters
+
+##### nodeLoggingComponentType?
+
+`string`
+
+An optional logging component type.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+#### Implementation of
+
+`IComponent.start`

package/docs/reference/functions/initSchema.md

@@ -0,0 +1,9 @@
+# Function: initSchema()
+
+> **initSchema**(): `void`
+
+Initialize the schema for the entity storage models.
+
+## Returns
+
+`void`

package/docs/reference/index.md

@@ -2,8 +2,10 @@
 
 ## Classes
 
+- [SchemaVersion](classes/SchemaVersion.md)
 - [EntityStorageHelper](classes/EntityStorageHelper.md)
 - [MigrationHelper](classes/MigrationHelper.md)
+- [SchemaVersionService](classes/SchemaVersionService.md)
 
 ## Interfaces
 
@@ -29,3 +31,7 @@
 
 - [EntityStorageConnectorFactory](variables/EntityStorageConnectorFactory.md)
 - [SchemaMigrationFactory](variables/SchemaMigrationFactory.md)
+
+## Functions
+
+- [initSchema](functions/initSchema.md)

package/docs/reference/interfaces/ISchemaMigration.md

@@ -7,7 +7,7 @@ renames or a custom object/array transform. For purely structural changes
 versioned schema classes (e.g. MyEntityV0 vs MyEntityV1) from EntitySchemaFactory
 automatically.
 
-Register under the key "<BaseSchemaName>_<fromVersion>_<toVersion>"
+Register under the key "BaseSchemaName_fromVersion_toVersion"
 e.g. "MyEntity_0_1" for the step that migrates from version 0 to version 1.
 The key itself encodes the version pair; no version field is needed on the object.
 

package/docs/reference/variables/SchemaMigrationFactory.md

@@ -9,5 +9,5 @@ transform hook. For purely structural changes (add/remove/type-change) the
 SchemaVersionService diffs the two versioned schema classes automatically
 without needing any factory entry.
 
-Keys follow the convention "<BaseSchemaName>_<fromVersion>_<toVersion>",
+Keys follow the convention "BaseSchemaName_fromVersion_toVersion",
 for example "MyEntity_0_1" for the step that migrates MyEntity from version 0 to 1.

package/locales/en.json

@@ -8,6 +8,12 @@
 			"migrationFailed": "Migration failed.",
 			"transformRequiredForProperty": "A transformation function is required to migrate property \"{from}\" to \"{to}\" of type \"{type}\"",
 			"coercionProducedUndefined": "Coercion of property \"{property}\" to type \"{type}\" produced undefined but the property is not optional"
+		},
+		"schemaVersionService": {
+			"storedVersionNewer": "Stored schema version ({stored}) for \"{schemaName}\" is newer than the current version ({current}). Downgrade is not supported.",
+			"noMigrationStep": "No migration step from version {missingFromVersion} to {missingToVersion} found for \"{schemaName}\". Cannot complete migration from {stored} to {current}. Register the versioned schema class \"{schemaName}V{missingFromVersion}\" in EntitySchemaFactory.",
+			"noMigrationStepTarget": "No target schema for migration step {missingFromVersion} to {missingToVersion} found for \"{schemaName}\". Cannot complete migration from {stored} to {current}. Register the versioned schema class \"{schemaName}V{missingToVersion}\" in EntitySchemaFactory.",
+			"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."
 		}
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/entity-storage-models",
-	"version": "0.0.3-next.23",
+	"version": "0.0.3-next.24",
 	"description": "Shared models for storage contracts, requests, responses and connector capabilities.",
 	"repository": {
 		"type": "git",