@twin.org/entity-storage-service 0.0.3-next.21 → 0.0.3-next.22

package/dist/es/entities/schemaVersion.js

@@ -0,0 +1,42 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { entity, property, EntitySchemaPropertyFormat } from "@twin.org/entity";
+/**
+ * Entity that records the currently applied schema version for a managed entity schema.
+ * Persisted through a normal entity-storage connector, giving every backend a schemaVersion
+ * table/collection for free.
+ *
+ * SchemaVersionService processes this schema first before all others so that the version
+ * store is fully migrated before any version records are written for other schemas.
+ */
+let SchemaVersion = class SchemaVersion {
+    /**
+     * The schema type name (matches the key used in EntitySchemaFactory).
+     */
+    schemaName;
+    /**
+     * The version currently applied in storage for 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: EntitySchemaPropertyFormat.DateTime }),
+    __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,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAEhF;;;;;;;GAOG;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,0BAA0B,CAAC,QAAQ,EAAE,CAAC;;gDAChD;AAjBd,aAAa;IADzB,MAAM,EAAE;GACI,aAAa,CAkBzB","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { entity, property, EntitySchemaPropertyFormat } from \"@twin.org/entity\";\n\n/**\n * Entity that records the currently applied schema version for a managed entity schema.\n * Persisted through a normal entity-storage connector, giving every backend a schemaVersion\n * table/collection for free.\n *\n * SchemaVersionService processes this schema first before all others so that the version\n * store is fully migrated before any version records are written for other schemas.\n */\n@entity()\nexport class SchemaVersion {\n\t/**\n\t * The schema type name (matches the key used in EntitySchemaFactory).\n\t */\n\t@property({ type: \"string\", isPrimary: true })\n\tpublic schemaName!: string;\n\n\t/**\n\t * The version currently applied in storage for 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: EntitySchemaPropertyFormat.DateTime })\n\tpublic updatedAt!: string;\n}\n"]}

package/dist/es/index.js

@@ -1,9 +1,13 @@
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
+export * from "./entities/schemaVersion.js";
 export * from "./entityStorageRoutes.js";
 export * from "./entityStorageService.js";
-export * from "./models/IEntityStorageServiceConfig.js";
 export * from "./models/IEntityStorageRoutesExamples.js";
+export * from "./models/IEntityStorageServiceConfig.js";
 export * from "./models/IEntityStorageServiceConstructorOptions.js";
+export * from "./models/ISchemaVersionServiceConstructorOptions.js";
 export * from "./restEntryPoints.js";
+export * from "./schemaVersionService.js";
+export * from "./schema.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,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yCAAyC,CAAC;AACxD,cAAc,0CAA0C,CAAC;AACzD,cAAc,qDAAqD,CAAC;AACpE,cAAc,sBAAsB,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./entityStorageRoutes.js\";\nexport * from \"./entityStorageService.js\";\nexport * from \"./models/IEntityStorageServiceConfig.js\";\nexport * from \"./models/IEntityStorageRoutesExamples.js\";\nexport * from \"./models/IEntityStorageServiceConstructorOptions.js\";\nexport * from \"./restEntryPoints.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0CAA0C,CAAC;AACzD,cAAc,yCAAyC,CAAC;AACxD,cAAc,qDAAqD,CAAC;AACpE,cAAc,qDAAqD,CAAC;AACpE,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,aAAa,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./entities/schemaVersion.js\";\nexport * from \"./entityStorageRoutes.js\";\nexport * from \"./entityStorageService.js\";\nexport * from \"./models/IEntityStorageRoutesExamples.js\";\nexport * from \"./models/IEntityStorageServiceConfig.js\";\nexport * from \"./models/IEntityStorageServiceConstructorOptions.js\";\nexport * from \"./models/ISchemaVersionServiceConstructorOptions.js\";\nexport * from \"./restEntryPoints.js\";\nexport * from \"./schemaVersionService.js\";\nexport * from \"./schema.js\";\n"]}

package/dist/es/models/ISchemaVersionServiceConstructorOptions.js

@@ -0,0 +1,4 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+export {};
+//# sourceMappingURL=ISchemaVersionServiceConstructorOptions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ISchemaVersionServiceConstructorOptions.js","sourceRoot":"","sources":["../../../src/models/ISchemaVersionServiceConstructorOptions.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Constructor options for SchemaVersionService.\n */\nexport interface ISchemaVersionServiceConstructorOptions {\n\t/**\n\t * The version storage type.\n\t * @default schema-version\n\t */\n\tschemaVersionStorageType?: string;\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.
+ */
+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.\n */\nexport function initSchema(): void {\n\tEntitySchemaFactory.register(nameof<SchemaVersion>(), () =>\n\t\tEntitySchemaHelper.getSchema(SchemaVersion)\n\t);\n}\n"]}

package/dist/es/schemaVersionService.js

@@ -0,0 +1,239 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { GeneralError, Is } from "@twin.org/core";
+import { EntitySchemaFactory, EntitySchemaHelper } from "@twin.org/entity";
+import { EntityStorageConnectorFactory, MigrationHelper, SchemaMigrationFactory } from "@twin.org/entity-storage-models";
+import { SchemaVersion } from "./entities/schemaVersion.js";
+/**
+ * Service that checks and applies entity schema migrations at every node start-up.
+ *
+ * This service should be registered as the first component so that its 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
+     */
+    _schemaVersionConnector;
+    /**
+     * Create a new SchemaVersionService.
+     * @param options The constructor options.
+     */
+    constructor(options) {
+        this._schemaVersionConnector = EntityStorageConnectorFactory.get(options.schemaVersionStorageType ?? "schema-version");
+    }
+    /**
+     * Returns the class name.
+     * @returns The class name.
+     */
+    className() {
+        return SchemaVersionService.CLASS_NAME;
+    }
+    /**
+     * 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 in one query.
+        const queryResult = await this._schemaVersionConnector.query();
+        const storedVersions = new Map();
+        for (const record of queryResult.entities ?? []) {
+            if (Is.object(record)) {
+                storedVersions.set(record.schemaName, record.version);
+            }
+        }
+        // 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.
+        const connector = this.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._schemaVersionConnector.set({
+            schemaName,
+            version,
+            updatedAt: new Date().toISOString()
+        });
+    }
+    /**
+     * 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
+     */
+    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;
+    }
+}
+//# sourceMappingURL=schemaVersionService.js.map

package/dist/es/schemaVersionService.js.map

@@ -0,0 +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 { GeneralError, Is, type IComponent } from \"@twin.org/core\";\nimport { EntitySchemaFactory, EntitySchemaHelper, type IEntitySchema } from \"@twin.org/entity\";\nimport {\n\tEntityStorageConnectorFactory,\n\tMigrationHelper,\n\tSchemaMigrationFactory,\n\ttype IEntityStorageConnector,\n\ttype IEntityStorageMigrationConnector,\n\ttype IResolvedMigrationStep\n} from \"@twin.org/entity-storage-models\";\nimport { nameof } from \"@twin.org/nameof\";\nimport { SchemaVersion } from \"./entities/schemaVersion.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 should be registered as the first component so that its start() runs before\n * any other service. By the time start() is called, all component bootstraps have completed\n * (every table already exists) and EntitySchemaFactory / EntityStorageConnectorFactory are\n * fully populated with every 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 _schemaVersionConnector: IEntityStorageConnector<SchemaVersion>;\n\n\t/**\n\t * Create a new SchemaVersionService.\n\t * @param options The constructor options.\n\t */\n\tconstructor(options: ISchemaVersionServiceConstructorOptions) {\n\t\tthis._schemaVersionConnector = EntityStorageConnectorFactory.get(\n\t\t\toptions.schemaVersionStorageType ?? \"schema-version\"\n\t\t);\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\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 in one query.\n\t\tconst queryResult = await this._schemaVersionConnector.query();\n\t\tconst storedVersions = new Map<string, number>();\n\t\tfor (const record of queryResult.entities ?? []) {\n\t\t\tif (Is.object<SchemaVersion>(record)) {\n\t\t\t\tstoredVersions.set(record.schemaName, record.version);\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,\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\tconst connector = this.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._schemaVersionConnector.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, or undefined if none is registered.\n\t * @internal\n\t */\n\tprivate 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"]}

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

@@ -0,0 +1,22 @@
+/**
+ * Entity that records the currently applied schema version for a managed entity schema.
+ * Persisted through a normal entity-storage connector, giving every backend a schemaVersion
+ * table/collection for free.
+ *
+ * SchemaVersionService processes this schema first before all others so that the version
+ * store is fully migrated before any version records are written for other schemas.
+ */
+export declare class SchemaVersion {
+    /**
+     * The schema type name (matches the key used in EntitySchemaFactory).
+     */
+    schemaName: string;
+    /**
+     * The version currently applied in storage for this schema.
+     */
+    version: number;
+    /**
+     * ISO 8601 timestamp of the last version write.
+     */
+    updatedAt: string;
+}

package/dist/types/index.d.ts

@@ -1,6 +1,10 @@
+export * from "./entities/schemaVersion.js";
 export * from "./entityStorageRoutes.js";
 export * from "./entityStorageService.js";
-export * from "./models/IEntityStorageServiceConfig.js";
 export * from "./models/IEntityStorageRoutesExamples.js";
+export * from "./models/IEntityStorageServiceConfig.js";
 export * from "./models/IEntityStorageServiceConstructorOptions.js";
+export * from "./models/ISchemaVersionServiceConstructorOptions.js";
 export * from "./restEntryPoints.js";
+export * from "./schemaVersionService.js";
+export * from "./schema.js";

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

@@ -0,0 +1,10 @@
+/**
+ * Constructor options for SchemaVersionService.
+ */
+export interface ISchemaVersionServiceConstructorOptions {
+    /**
+     * The version storage type.
+     * @default schema-version
+     */
+    schemaVersionStorageType?: string;
+}

package/dist/types/schema.d.ts

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

package/dist/types/schemaVersionService.d.ts

@@ -0,0 +1,50 @@
+import { type IComponent } from "@twin.org/core";
+import type { ISchemaVersionServiceConstructorOptions } from "./models/ISchemaVersionServiceConstructorOptions.js";
+/**
+ * Service that checks and applies entity schema migrations at every node start-up.
+ *
+ * This service should be registered as the first component so that its 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 options The constructor options.
+     */
+    constructor(options: ISchemaVersionServiceConstructorOptions);
+    /**
+     * Returns the class name.
+     * @returns The class name.
+     */
+    className(): string;
+    /**
+     * 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,21 @@
 # Changelog
 
+## [0.0.3-next.22](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-service-v0.0.3-next.21...entity-storage-service-v0.0.3-next.22) (2026-06-08)
+
+
+### Features
+
+* add ISchemaMigration chain, SchemaVersionMigrator runner and version store ([#110](https://github.com/iotaledger/twin-entity-storage/issues/110)) ([2dac924](https://github.com/iotaledger/twin-entity-storage/commit/2dac9244a752cb58304d1649ff03c3a2469783dd))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/entity-storage-models bumped from 0.0.3-next.21 to 0.0.3-next.22
+  * devDependencies
+    * @twin.org/entity-storage-connector-memory bumped from 0.0.3-next.21 to 0.0.3-next.22
+
 ## [0.0.3-next.21](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-service-v0.0.3-next.20...entity-storage-service-v0.0.3-next.21) (2026-06-01)
 
 

package/docs/reference/classes/SchemaVersion.md

@@ -0,0 +1,42 @@
+# Class: SchemaVersion
+
+Entity that records the currently applied schema version for a managed entity schema.
+Persisted through a normal entity-storage connector, giving every backend a schemaVersion
+table/collection for free.
+
+SchemaVersionService processes this schema first before all others so that the version
+store is fully migrated before any version records are written for other schemas.
+
+## Constructors
+
+### Constructor
+
+> **new SchemaVersion**(): `SchemaVersion`
+
+#### Returns
+
+`SchemaVersion`
+
+## Properties
+
+### schemaName {#schemaname}
+
+> **schemaName**: `string`
+
+The schema type name (matches the key used in EntitySchemaFactory).
+
+***
+
+### version {#version}
+
+> **version**: `number`
+
+The version currently applied in storage for this schema.
+
+***
+
+### updatedAt {#updatedat}
+
+> **updatedAt**: `string`
+
+ISO 8601 timestamp of the last version write.

package/docs/reference/classes/SchemaVersionService.md

@@ -0,0 +1,101 @@
+# Class: SchemaVersionService
+
+Service that checks and applies entity schema migrations at every node start-up.
+
+This service should be registered as the first component so that its 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**(`options`): `SchemaVersionService`
+
+Create a new SchemaVersionService.
+
+#### Parameters
+
+##### options
+
+[`ISchemaVersionServiceConstructorOptions`](../interfaces/ISchemaVersionServiceConstructorOptions.md)
+
+The constructor options.
+
+#### 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`
+
+***
+
+### 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.
+
+## Returns
+
+`void`

package/docs/reference/index.md

@@ -2,13 +2,16 @@
 
 ## Classes
 
+- [SchemaVersion](classes/SchemaVersion.md)
 - [EntityStorageService](classes/EntityStorageService.md)
+- [SchemaVersionService](classes/SchemaVersionService.md)
 
 ## Interfaces
 
 - [IEntityStorageRoutesExamples](interfaces/IEntityStorageRoutesExamples.md)
 - [IEntityStorageServiceConfig](interfaces/IEntityStorageServiceConfig.md)
 - [IEntityStorageServiceConstructorOptions](interfaces/IEntityStorageServiceConstructorOptions.md)
+- [ISchemaVersionServiceConstructorOptions](interfaces/ISchemaVersionServiceConstructorOptions.md)
 
 ## Variables
 
@@ -26,3 +29,4 @@
 - [entityStorageList](functions/entityStorageList.md)
 - [entityStorageCount](functions/entityStorageCount.md)
 - [entityStorageRemoveBatch](functions/entityStorageRemoveBatch.md)
+- [initSchema](functions/initSchema.md)

package/docs/reference/interfaces/ISchemaVersionServiceConstructorOptions.md

@@ -0,0 +1,17 @@
+# Interface: ISchemaVersionServiceConstructorOptions
+
+Constructor options for SchemaVersionService.
+
+## Properties
+
+### schemaVersionStorageType? {#schemaversionstoragetype}
+
+> `optional` **schemaVersionStorageType?**: `string`
+
+The version storage type.
+
+#### Default
+
+```ts
+schema-version
+```

package/locales/en.json

@@ -1 +1,10 @@
-{}
+{
+	"error": {
+		"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-service",
-	"version": "0.0.3-next.21",
+	"version": "0.0.3-next.22",
 	"description": "Service layer exposing storage contracts and REST endpoint definitions.",
 	"repository": {
 		"type": "git",
@@ -17,7 +17,7 @@
 		"@twin.org/api-models": "next",
 		"@twin.org/core": "next",
 		"@twin.org/entity": "next",
-		"@twin.org/entity-storage-models": "0.0.3-next.21",
+		"@twin.org/entity-storage-models": "0.0.3-next.22",
 		"@twin.org/nameof": "next",
 		"@twin.org/web": "next"
 	},