@tomflow/proflow-task-migration-runner 0.1.0

package/README.md

@@ -0,0 +1,3 @@
+# @tomflow/proflow-task-migration-runner
+
+确定性发现、执行并验证 Task schema migrations；SQL 由 task-store-sqlite 提供。

package/conformance.json

@@ -0,0 +1,4 @@
+{
+	"contract": "proflow.conformance.v1",
+	"levels": ["C1", "C2", "C3"]
+}

package/dist/deployment/adapter.d.ts

@@ -0,0 +1,67 @@
+export declare const behaviorAdapter: {
+    readonly describe: () => {
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "task-migration-runner";
+            readonly moduleVersion: "0.1.0";
+        };
+        observedEffects: never[];
+    };
+    readonly preflight: () => {
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "task-migration-runner";
+            readonly moduleVersion: "0.1.0";
+        };
+        observedEffects: never[];
+    };
+    readonly status: () => {
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "task-migration-runner";
+            readonly moduleVersion: "0.1.0";
+        };
+        observedEffects: never[];
+    };
+    readonly verify: () => {
+        result: {
+            contract: "deployment.result.v1";
+            ok: true;
+            status: "SUCCEEDED";
+            moduleRef: "task-migration-runner";
+            moduleVersion: "0.1.0";
+            checks: {
+                id: string;
+                status: string;
+                message: string;
+            }[];
+        };
+        observedEffects: never[];
+    };
+    readonly doctor: () => {
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "task-migration-runner";
+            readonly moduleVersion: "0.1.0";
+        };
+        observedEffects: never[];
+    };
+    readonly migrate: () => {
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "task-migration-runner";
+            readonly moduleVersion: "0.1.0";
+        };
+        observedEffects: string[];
+    };
+};

package/dist/deployment/adapter.js

@@ -0,0 +1,31 @@
+import { descriptor } from "./descriptor.js";
+const result = {
+    contract: "deployment.result.v1",
+    ok: true,
+    status: "SUCCEEDED",
+    moduleRef: descriptor.moduleRef,
+    moduleVersion: descriptor.moduleVersion,
+};
+export const behaviorAdapter = {
+    describe: () => ({ result, observedEffects: [] }),
+    preflight: () => ({ result, observedEffects: [] }),
+    status: () => ({ result, observedEffects: [] }),
+    verify: () => ({
+        result: {
+            ...result,
+            checks: [
+                {
+                    id: "migration-state-pass",
+                    status: "PASS",
+                    message: "Migration verification primitive is available",
+                },
+            ],
+        },
+        observedEffects: [],
+    }),
+    doctor: () => ({ result, observedEffects: [] }),
+    migrate: () => ({
+        result,
+        observedEffects: ["Applies Task Store migration SQL to SQLite"],
+    }),
+};

package/dist/deployment/descriptor.d.ts

@@ -0,0 +1,48 @@
+export declare const descriptor: {
+    readonly contract: "module";
+    readonly contractVersion: "1.0.0";
+    readonly moduleRef: "task-migration-runner";
+    readonly packageName: "@tomflow/proflow-task-migration-runner";
+    readonly moduleVersion: "0.1.0";
+    readonly kind: "cli";
+    readonly templateVersion: "1.0.0";
+    readonly platformCompatibility: ">=1.0.0 <2.0.0";
+    readonly installClass: "core";
+    readonly identity: {
+        readonly domain: "task-orchestration";
+        readonly summary: "Deterministically discovers, applies and verifies Task Store SQLite schema migrations.";
+    };
+    readonly provides: readonly [];
+    readonly requires: readonly [];
+    readonly requirements: readonly [{
+        readonly kind: "runtime";
+        readonly runtime: "node";
+        readonly versionRange: ">=24.19.0";
+    }];
+    readonly configSlots: readonly [{
+        readonly key: "databasePath";
+        readonly type: "path";
+        readonly required: true;
+        readonly description: "Task SQLite database path";
+    }];
+    readonly lifecycle: {
+        readonly supported: readonly ["describe", "preflight", "status", "verify", "doctor", "migrate"];
+    };
+    readonly verification: {
+        readonly checks: readonly [{
+            readonly id: "migration-state-pass";
+            readonly description: "Migration state matches the Task schema";
+            readonly lifecycle: "verify";
+        }];
+    };
+    readonly effects: readonly [{
+        readonly kind: "filesystem";
+        readonly description: "Applies Task Store migration SQL to SQLite";
+        readonly retention: "preserve";
+    }];
+    readonly documentation: readonly [{
+        readonly id: "overview";
+        readonly path: "./README.md";
+        readonly description: "Package-owned module overview";
+    }];
+};

package/dist/deployment/descriptor.js

@@ -0,0 +1,61 @@
+export const descriptor = {
+    contract: "module",
+    contractVersion: "1.0.0",
+    moduleRef: "task-migration-runner",
+    packageName: "@tomflow/proflow-task-migration-runner",
+    moduleVersion: "0.1.0",
+    kind: "cli",
+    templateVersion: "1.0.0",
+    platformCompatibility: ">=1.0.0 <2.0.0",
+    installClass: "core",
+    identity: {
+        domain: "task-orchestration",
+        summary: "Deterministically discovers, applies and verifies Task Store SQLite schema migrations.",
+    },
+    provides: [],
+    requires: [],
+    requirements: [
+        { kind: "runtime", runtime: "node", versionRange: ">=24.19.0" },
+    ],
+    configSlots: [
+        {
+            key: "databasePath",
+            type: "path",
+            required: true,
+            description: "Task SQLite database path",
+        },
+    ],
+    lifecycle: {
+        supported: [
+            "describe",
+            "preflight",
+            "status",
+            "verify",
+            "doctor",
+            "migrate",
+        ],
+    },
+    verification: {
+        checks: [
+            {
+                id: "migration-state-pass",
+                description: "Migration state matches the Task schema",
+                lifecycle: "verify",
+            },
+        ],
+    },
+    effects: [
+        {
+            kind: "filesystem",
+            description: "Applies Task Store migration SQL to SQLite",
+            retention: "preserve",
+        },
+    ],
+    documentation: [
+        {
+            id: "overview",
+            path: "./README.md",
+            description: "Package-owned module overview",
+        },
+    ],
+};

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export { runCli } from "./index.ts";

package/dist/src/cli.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import { runCli } from "./index.js";
+export { runCli } from "./index.js";
+if (process.argv[1] !== undefined &&
+    import.meta.url === pathToFileURL(process.argv[1]).href) {
+    const output = await runCli(process.argv.slice(2));
+    process.stdout.write(`${output}\n`);
+    if (JSON.parse(output).ok !== true)
+        process.exitCode = 1;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,41 @@
+import { type TaskMigration, type TaskMigrationContext } from "@tomflow/proflow-task-store-sqlite/migrations";
+export interface MigrationInput {
+    databasePath: string;
+    migrations: readonly TaskMigration[];
+    context?: TaskMigrationContext;
+}
+export interface MigrationResult {
+    contract: "task-migration";
+    contractVersion: "1.0.0";
+    ok: boolean;
+    applied: number[];
+    pending: number[];
+    error?: {
+        code: "MIGRATION_FAILED" | "MIGRATION_VERIFY_FAILED";
+        message: string;
+    };
+}
+export interface MigrationStatus {
+    contract: "task-migration";
+    contractVersion: "1.0.0";
+    appliedVersions: number[];
+    pendingVersions: number[];
+    metadataDrift: Array<{
+        version: number;
+        expectedName: string;
+        actualName: string;
+    }>;
+    checksumDrift: Array<{
+        version: number;
+        expectedChecksum: string;
+        actualChecksum: string;
+    }>;
+    legacyMetadataVersions: number[];
+    missingTables: string[];
+    schemaDrift: string[];
+}
+export declare function discoverMigrations(migrations: readonly TaskMigration[]): TaskMigration[];
+export declare function getMigrationStatus(input: MigrationInput): MigrationStatus;
+export declare function applyMigrations(input: MigrationInput): MigrationResult;
+export declare function verifyMigrations(input: MigrationInput): MigrationResult;
+export declare function runCli(args: string[]): Promise<string>;

package/dist/src/index.js

@@ -0,0 +1,401 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { taskMigrations, } from "@tomflow/proflow-task-store-sqlite/migrations";
+import { descriptor as moduleDescriptor } from "../deployment/descriptor.js";
+export function discoverMigrations(migrations) {
+    const sorted = [...migrations].sort((left, right) => left.version - right.version);
+    const versions = new Set();
+    for (const migration of sorted) {
+        if (!Number.isSafeInteger(migration.version) || migration.version < 1)
+            throw new TypeError("migration version must be a positive integer");
+        if (!/^[a-z][a-z0-9_]*$/.test(migration.name))
+            throw new TypeError("migration name must be stable snake_case");
+        if (versions.has(migration.version))
+            throw new TypeError(`duplicate migration version ${migration.version}`);
+        if (migration.apply !== undefined && !migration.identity)
+            throw new TypeError(`custom migration ${migration.version} requires a stable identity`);
+        if (migration.coversLegacyVersions !== undefined) {
+            if (migration.apply === undefined)
+                throw new TypeError(`migration ${migration.version} cannot cover legacy versions without an owner compatibility apply`);
+            if (migration.coversLegacyVersions.some((version) => !Number.isInteger(version) ||
+                version < 1 ||
+                version >= migration.version))
+                throw new TypeError(`migration ${migration.version} has an invalid legacy coverage declaration`);
+        }
+        versions.add(migration.version);
+    }
+    return sorted;
+}
+function migrationChecksum(migration) {
+    const semanticIdentity = `${migration.identity ?? "sql"}\0${migration.sql}`;
+    return `sha256:${createHash("sha256")
+        .update(`${migration.version}\0${migration.name}\0${semanticIdentity}`)
+        .digest("hex")}`;
+}
+function migrationMetadataColumns(database) {
+    return new Set(database.prepare("PRAGMA table_info(schema_migrations)").all().map((row) => row.name));
+}
+function openDatabase(databasePath) {
+    if (databasePath !== ":memory:")
+        mkdirSync(dirname(databasePath), { recursive: true });
+    const database = new DatabaseSync(databasePath);
+    database.exec("PRAGMA foreign_keys = ON; PRAGMA journal_mode = WAL; PRAGMA busy_timeout = 2500;");
+    database.exec("CREATE TABLE IF NOT EXISTS schema_migrations (version INTEGER PRIMARY KEY, name TEXT NOT NULL, checksum TEXT, applied_at TEXT NOT NULL);");
+    const columns = migrationMetadataColumns(database);
+    if (!columns.has("checksum")) {
+        // Preserve historical migration metadata in place. SQLite appends the
+        // nullable checksum column to pre-checksum installations; physical column
+        // ordinal is not part of the migration contract and must not be normalized
+        // with a non-transactional rename/create/copy/drop sequence. This keeps a
+        // crash from stranding authoritative migration history in a side table.
+        database.exec("ALTER TABLE schema_migrations ADD COLUMN checksum TEXT");
+    }
+    return database;
+}
+function appliedVersions(database) {
+    return database
+        .prepare("SELECT version FROM schema_migrations ORDER BY version")
+        .all().map((row) => row.version);
+}
+function expectedTableNames(migrations) {
+    return [
+        ...new Set(migrations.flatMap((migration) => [
+            ...migration.sql.matchAll(/CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?([A-Za-z_][A-Za-z0-9_]*)/gi),
+        ].map((match) => match[1] ?? ""))),
+    ].filter(Boolean);
+}
+function inspectionStatus(database, migrations) {
+    const migrationTable = database
+        .prepare("SELECT 1 AS present FROM sqlite_master WHERE type='table' AND name='schema_migrations'")
+        .get();
+    const metadataColumns = migrationTable
+        ? migrationMetadataColumns(database)
+        : new Set();
+    const appliedRows = migrationTable
+        ? database
+            .prepare(metadataColumns.has("checksum")
+            ? "SELECT version, name, checksum FROM schema_migrations ORDER BY version"
+            : "SELECT version, name, NULL AS checksum FROM schema_migrations ORDER BY version")
+            .all()
+        : [];
+    const appliedSet = new Set(appliedRows.map((row) => row.version));
+    const expectedTables = expectedTableNames(migrations);
+    const actualTables = new Set(database
+        .prepare("SELECT name FROM sqlite_master WHERE type='table'")
+        .all().map((row) => row.name));
+    return {
+        contract: "task-migration",
+        contractVersion: "1.0.0",
+        appliedVersions: appliedRows.map((row) => row.version),
+        pendingVersions: migrations
+            .filter((migration) => !appliedSet.has(migration.version))
+            .map((migration) => migration.version),
+        metadataDrift: migrations.flatMap((migration) => {
+            const actual = appliedRows.find((row) => row.version === migration.version);
+            const coveredLegacyIdentity = actual?.checksum === null &&
+                migrations.some((barrier) => barrier.version > migration.version &&
+                    appliedSet.has(barrier.version) &&
+                    barrier.apply !== undefined &&
+                    barrier.coversLegacyVersions?.includes(migration.version) === true);
+            return actual !== undefined &&
+                !coveredLegacyIdentity &&
+                actual.name !== migration.name
+                ? [
+                    {
+                        version: migration.version,
+                        expectedName: migration.name,
+                        actualName: actual.name,
+                    },
+                ]
+                : [];
+        }),
+        checksumDrift: migrations.flatMap((migration) => {
+            const actual = appliedRows.find((row) => row.version === migration.version);
+            const expectedChecksum = migrationChecksum(migration);
+            return actual?.checksum !== null &&
+                actual?.checksum !== undefined &&
+                actual.checksum !== expectedChecksum
+                ? [
+                    {
+                        version: migration.version,
+                        expectedChecksum,
+                        actualChecksum: actual.checksum,
+                    },
+                ]
+                : [];
+        }),
+        legacyMetadataVersions: appliedRows
+            .filter((row) => row.checksum === null)
+            .map((row) => row.version),
+        missingTables: expectedTables.filter((table) => !actualTables.has(table)),
+        schemaDrift: migrations.flatMap((migration) => appliedSet.has(migration.version) && migration.verify
+            ? [...migration.verify(database)].map((issue) => `v${migration.version}:${issue}`)
+            : []),
+    };
+}
+export function getMigrationStatus(input) {
+    const migrations = discoverMigrations(input.migrations);
+    if (input.databasePath !== ":memory:" && !existsSync(input.databasePath)) {
+        return {
+            contract: "task-migration",
+            contractVersion: "1.0.0",
+            appliedVersions: [],
+            pendingVersions: migrations.map((migration) => migration.version),
+            metadataDrift: [],
+            checksumDrift: [],
+            legacyMetadataVersions: [],
+            missingTables: expectedTableNames(migrations),
+            schemaDrift: [],
+        };
+    }
+    const database = new DatabaseSync(input.databasePath, { readOnly: true });
+    try {
+        return inspectionStatus(database, migrations);
+    }
+    finally {
+        database.close();
+    }
+}
+export function applyMigrations(input) {
+    const migrations = discoverMigrations(input.migrations);
+    const database = openDatabase(input.databasePath);
+    const appliedNow = [];
+    try {
+        const alreadyApplied = new Set(appliedVersions(database));
+        for (const migration of migrations) {
+            if (alreadyApplied.has(migration.version)) {
+                const row = database
+                    .prepare("SELECT name, checksum FROM schema_migrations WHERE version = ?")
+                    .get(migration.version);
+                const legacyIdentityCoveredByCompatibility = row?.checksum === null &&
+                    migrations.some((barrier) => barrier.version > migration.version &&
+                        barrier.apply !== undefined &&
+                        barrier.coversLegacyVersions?.includes(migration.version) ===
+                            true);
+                if (!row ||
+                    (!legacyIdentityCoveredByCompatibility && row.name !== migration.name))
+                    return {
+                        contract: "task-migration",
+                        contractVersion: "1.0.0",
+                        ok: false,
+                        applied: appliedNow,
+                        pending: migrations
+                            .filter((item) => !alreadyApplied.has(item.version))
+                            .map((item) => item.version),
+                        error: {
+                            code: "MIGRATION_FAILED",
+                            message: `migration ${migration.version} name drift: expected ${migration.name}, found ${row?.name ?? "missing"}`,
+                        },
+                    };
+                if (row.checksum === null && migration.apply !== undefined)
+                    return {
+                        contract: "task-migration",
+                        contractVersion: "1.0.0",
+                        ok: false,
+                        applied: appliedNow,
+                        pending: migrations
+                            .filter((item) => !alreadyApplied.has(item.version))
+                            .map((item) => item.version),
+                        error: {
+                            code: "MIGRATION_FAILED",
+                            message: `compatibility migration ${migration.version} is missing checksum identity`,
+                        },
+                    };
+                if (row.checksum !== null &&
+                    row.checksum !== migrationChecksum(migration))
+                    return {
+                        contract: "task-migration",
+                        contractVersion: "1.0.0",
+                        ok: false,
+                        applied: appliedNow,
+                        pending: migrations
+                            .filter((item) => !alreadyApplied.has(item.version))
+                            .map((item) => item.version),
+                        error: {
+                            code: "MIGRATION_FAILED",
+                            message: `migration ${migration.version} checksum drift`,
+                        },
+                    };
+                // Rows created by a pre-checksum runner remain explicitly legacy. They are
+                // not backfilled with the current SQL checksum because the historical SQL
+                // cannot be proven. A later compatibility migration validates/upgrades the
+                // real schema instead.
+                continue;
+            }
+            database.exec("BEGIN IMMEDIATE");
+            try {
+                if (migration.sql.trim().length > 0)
+                    database.exec(migration.sql);
+                migration.apply?.(database, input.context ?? {});
+                database
+                    .prepare("INSERT INTO schema_migrations(version, name, checksum, applied_at) VALUES (?, ?, ?, ?)")
+                    .run(migration.version, migration.name, migrationChecksum(migration), new Date().toISOString());
+                database.exec("COMMIT");
+                appliedNow.push(migration.version);
+                alreadyApplied.add(migration.version);
+            }
+            catch (error) {
+                database.exec("ROLLBACK");
+                return {
+                    contract: "task-migration",
+                    contractVersion: "1.0.0",
+                    ok: false,
+                    applied: appliedNow,
+                    pending: migrations
+                        .filter((item) => !alreadyApplied.has(item.version))
+                        .map((item) => item.version),
+                    error: {
+                        code: "MIGRATION_FAILED",
+                        message: error instanceof Error ? error.message : "migration failed",
+                    },
+                };
+            }
+        }
+        return {
+            contract: "task-migration",
+            contractVersion: "1.0.0",
+            ok: true,
+            applied: appliedNow,
+            pending: [],
+        };
+    }
+    finally {
+        database.close();
+    }
+}
+export function verifyMigrations(input) {
+    const status = getMigrationStatus(input);
+    if (input.databasePath !== ":memory:" && !existsSync(input.databasePath)) {
+        return {
+            contract: "task-migration",
+            contractVersion: "1.0.0",
+            ok: false,
+            applied: [],
+            pending: status.pendingVersions,
+            error: {
+                code: "MIGRATION_VERIFY_FAILED",
+                message: "database does not exist",
+            },
+        };
+    }
+    const database = new DatabaseSync(input.databasePath, { readOnly: true });
+    try {
+        const integrity = database.prepare("PRAGMA integrity_check").get();
+        const appliedSet = new Set(status.appliedVersions);
+        const legacyMetadataCoveredByCompatibilityBarrier = status.legacyMetadataVersions.length === 0 ||
+            status.legacyMetadataVersions.every((legacyVersion) => input.migrations.some((migration) => migration.version > legacyVersion &&
+                appliedSet.has(migration.version) &&
+                migration.apply !== undefined &&
+                migration.coversLegacyVersions?.includes(legacyVersion) === true));
+        const ok = status.pendingVersions.length === 0 &&
+            status.metadataDrift.length === 0 &&
+            status.checksumDrift.length === 0 &&
+            legacyMetadataCoveredByCompatibilityBarrier &&
+            status.missingTables.length === 0 &&
+            status.schemaDrift.length === 0 &&
+            integrity?.integrity_check === "ok";
+        return {
+            contract: "task-migration",
+            contractVersion: "1.0.0",
+            ok,
+            applied: status.appliedVersions,
+            pending: status.pendingVersions,
+            ...(ok
+                ? {}
+                : {
+                    error: {
+                        code: "MIGRATION_VERIFY_FAILED",
+                        message: "migration state or SQLite integrity does not match",
+                    },
+                }),
+        };
+    }
+    finally {
+        database.close();
+    }
+}
+export async function runCli(args) {
+    if (args.includes("--help") || args.includes("-h")) {
+        return JSON.stringify({
+            contract: "deployment.result.v1",
+            ok: true,
+            status: "SUCCEEDED",
+            moduleRef: moduleDescriptor.moduleRef,
+            moduleVersion: moduleDescriptor.moduleVersion,
+            data: {
+                usage: "proflow-task-migrate [apply|status|verify] --database <path> [--legacy-role-map <json>]",
+            },
+        });
+    }
+    const command = args.find((item) => ["apply", "status", "verify"].includes(item)) ??
+        "status";
+    const databaseIndex = args.indexOf("--database");
+    const databasePath = databaseIndex >= 0 ? (args[databaseIndex + 1] ?? ":memory:") : ":memory:";
+    const legacyRoleMapIndex = args.indexOf("--legacy-role-map");
+    let migrationContext;
+    if (legacyRoleMapIndex >= 0) {
+        const mapPath = args[legacyRoleMapIndex + 1];
+        if (!mapPath)
+            throw new TypeError("--legacy-role-map requires a JSON file");
+        const parsed = JSON.parse(readFileSync(mapPath, "utf8"));
+        if (parsed === null || Array.isArray(parsed) || typeof parsed !== "object")
+            throw new TypeError("legacy role map must be a JSON object");
+        const record = parsed;
+        const structured = "roleMap" in record || "roleBindings" in record;
+        migrationContext = structured
+            ? {
+                ...(record.roleMap && typeof record.roleMap === "object"
+                    ? {
+                        legacyRoleMap: record.roleMap,
+                    }
+                    : {}),
+                ...(record.roleBindings && typeof record.roleBindings === "object"
+                    ? {
+                        legacyRoleBindings: record.roleBindings,
+                    }
+                    : {}),
+            }
+            : { legacyRoleMap: record };
+    }
+    let success = true;
+    let message = "migration status is readable";
+    if (command === "apply") {
+        const result = applyMigrations({
+            databasePath,
+            migrations: taskMigrations,
+            ...(migrationContext ? { context: migrationContext } : {}),
+        });
+        success = result.ok;
+        message = result.ok
+            ? "migrations applied"
+            : (result.error?.message ?? "migration failed");
+    }
+    else if (command === "verify") {
+        const result = verifyMigrations({
+            databasePath,
+            migrations: taskMigrations,
+        });
+        success = result.ok;
+        message = result.ok
+            ? "migrations verified"
+            : (result.error?.message ?? "migration verify failed");
+    }
+    else {
+        getMigrationStatus({ databasePath, migrations: taskMigrations });
+    }
+    return JSON.stringify({
+        contract: "deployment.result.v1",
+        ok: success,
+        status: success ? "SUCCEEDED" : "FAILED",
+        moduleRef: moduleDescriptor.moduleRef,
+        moduleVersion: moduleDescriptor.moduleVersion,
+        checks: [
+            { id: "migration-state", status: success ? "PASS" : "FAIL", message },
+        ],
+        ...(success
+            ? {}
+            : { error: { code: "COMMAND_FAILED", message, retryable: false } }),
+    });
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@tomflow/proflow-task-migration-runner",
+  "version": "0.1.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./cli": "./dist/src/cli.js",
+    "./deployment/adapter": "./dist/deployment/adapter.js",
+    "./deployment/descriptor": "./dist/deployment/descriptor.js"
+  },
+  "bin": {
+    "proflow-task-migrate": "./dist/src/cli.js",
+    "proflow-task-migration-runner": "./self-install.mjs"
+  },
+  "files": [
+    "dist",
+    "proflow.module.json",
+    "conformance.json",
+    "README.md",
+    "self-install.mjs"
+  ],
+  "dependencies": {
+    "@tomflow/proflow-task-store-sqlite": "^0.1.0",
+    "@tomflow/proflow-module-contract": "^0.1.0"
+  },
+  "description": "Deterministically discovers, applies and verifies Task Store SQLite schema migrations.",
+  "keywords": [
+    "proflow",
+    "proflow-module",
+    "task-orchestration"
+  ],
+  "proflow": {
+    "module": true,
+    "installClass": "core",
+    "installRequires": [
+      "@tomflow/proflow-module-contract",
+      "@tomflow/proflow-task-store-sqlite"
+    ],
+    "descriptor": "./dist/deployment/descriptor.js",
+    "manifest": "./proflow.module.json"
+  },
+  "scripts": {
+    "test": "node --test tests/**/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/proflow.module.json

@@ -0,0 +1,65 @@
+{
+	"contract": "module",
+	"contractVersion": "1.0.0",
+	"moduleRef": "task-migration-runner",
+	"packageName": "@tomflow/proflow-task-migration-runner",
+	"moduleVersion": "0.1.0",
+	"kind": "cli",
+	"templateVersion": "1.0.0",
+	"platformCompatibility": ">=1.0.0 <2.0.0",
+	"installClass": "core",
+	"identity": {
+		"domain": "task-orchestration",
+		"summary": "Deterministically discovers, applies and verifies Task Store SQLite schema migrations."
+	},
+	"provides": [],
+	"requires": [],
+	"requirements": [
+		{
+			"kind": "runtime",
+			"runtime": "node",
+			"versionRange": ">=24.19.0"
+		}
+	],
+	"configSlots": [
+		{
+			"key": "databasePath",
+			"type": "path",
+			"required": true,
+			"description": "Task SQLite database path"
+		}
+	],
+	"lifecycle": {
+		"supported": [
+			"describe",
+			"preflight",
+			"status",
+			"verify",
+			"doctor",
+			"migrate"
+		]
+	},
+	"verification": {
+		"checks": [
+			{
+				"id": "migration-state-pass",
+				"description": "Migration state matches the Task schema",
+				"lifecycle": "verify"
+			}
+		]
+	},
+	"effects": [
+		{
+			"kind": "filesystem",
+			"description": "Applies Task Store migration SQL to SQLite",
+			"retention": "preserve"
+		}
+	],
+	"documentation": [
+		{
+			"id": "overview",
+			"path": "./README.md",
+			"description": "Package-owned module overview"
+		}
+	]
+}

package/self-install.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+
+const [command, ...rest] = process.argv.slice(2);
+const usage = "Usage: npx @tomflow/proflow-task-migration-runner install\n";
+if (command === "--help" || command === "-h") {
+	process.stdout.write(usage);
+	process.exit(0);
+}
+if (command !== "install" || rest.length > 0) {
+	process.stderr.write(usage);
+	process.exit(2);
+}
+const executable = process.platform === "win32" ? "npx.cmd" : "npx";
+const result = spawnSync(
+	executable,
+	[
+		"--yes",
+		"@tomflow/proflow-platform-cli",
+		"install",
+		"@tomflow/proflow-task-migration-runner",
+	],
+	{ cwd: process.cwd(), env: process.env, stdio: "inherit" },
+);
+if (result.error) throw result.error;
+process.exit(result.status ?? 1);