@zq-silk/yui 0.11.3 → 0.12.1

package/dist/storage/migration/productionRegistry.js

@@ -79,6 +79,8 @@ const STORED_TASK_JOB_CALLER_KEY_HASHES_FROM_VERSION = 15;
 const STORED_TASK_JOB_CALLER_KEY_HASHES_TO_VERSION = 16;
 const STORED_TASK_WAKES_FROM_VERSION = 16;
 const STORED_TASK_WAKES_TO_VERSION = 17;
+const STORED_TASK_EVENT_NOTICES_FROM_VERSION = 17;
+const STORED_TASK_EVENT_NOTICES_TO_VERSION = 18;
 const TASK_WAKE_FROM_VERSION = 0;
 const TASK_WAKE_TO_VERSION = 1;
 const STORED_TASK_PUBLICATION_REFERENCES_FROM_VERSION = 16;
@@ -97,6 +99,8 @@ const PUBLICATION_REFERENCE_FROM_VERSION = 0;
 const PUBLICATION_REFERENCE_TO_VERSION = 1;
 const CONFIG_FROM_VERSION = 1;
 const CONFIG_TO_VERSION = 2;
+const CONFIG_REVIEW_CONTROLS_FROM_VERSION = 2;
+const CONFIG_REVIEW_CONTROLS_TO_VERSION = 3;
 /**
  * Build the authoritative production graph. Transition intent and executable
  * transforms are registered together here; compatible loading and offline
@@ -146,6 +150,7 @@ export function createProductionStorageRegistry() {
     })
         .registerOfflineMigration(projectOwnershipStep())
         .registerOfflineMigration(configV2Step())
+        .registerOfflineMigration(configReviewControlsRemovalStep())
         .registerCompatible(projectKnowledgeProposalsStep())
         .registerCompatible(projectLifecycleStep())
         .registerOfflineMigration(taskWorkspaceIdentityStep())
@@ -180,6 +185,7 @@ export function createProductionStorageRegistry() {
         .registerCompatible(storedTaskDurableJobsStep())
         .registerCompatible(storedTaskJobCallerKeyHashesStep())
         .registerCompatible(storedTaskWakesAndPublicationReferencesStep())
+        .registerOfflineMigration(storedTaskEventNoticesStep())
         .registerCompatible(taskWakeIntroductionStep())
         .registerCompatible(durableJobIntroductionStep())
         .registerOfflineMigration(capabilityGrantIntroductionStep())
@@ -246,6 +252,61 @@ function migrateConfigV1ToV2(snapshot) {
         }
     };
 }
+/** Removes retired Core controls for the Leader-owned Delta decision. */
+function configReviewControlsRemovalStep() {
+    return {
+        axis: "record",
+        recordKind: "config",
+        fromVersion: CONFIG_REVIEW_CONTROLS_FROM_VERSION,
+        toVersion: CONFIG_REVIEW_CONTROLS_TO_VERSION,
+        preconditions: requireConfigV2,
+        transform: migrateConfigV2ToV3,
+        declaredEffects: []
+    };
+}
+function requireConfigV2(snapshot) {
+    const versions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    if (versions.config !== CONFIG_REVIEW_CONTROLS_FROM_VERSION) {
+        throw new Error(`Record config migration requires manifest version ${CONFIG_REVIEW_CONTROLS_FROM_VERSION}.`);
+    }
+    if (snapshot.state === null)
+        return;
+    const config = asObject(snapshot.state.config, "Yui config");
+    if (config.schemaVersion !== CONFIG_REVIEW_CONTROLS_FROM_VERSION) {
+        throw new Error(`Yui config must use schemaVersion ${CONFIG_REVIEW_CONTROLS_FROM_VERSION} before migration.`);
+    }
+}
+function migrateConfigV2ToV3(snapshot) {
+    requireConfigV2(snapshot);
+    const versions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    const schemaManifest = {
+        ...snapshot.schemaManifest,
+        recordVersions: { ...versions, config: CONFIG_REVIEW_CONTROLS_TO_VERSION }
+    };
+    if (snapshot.state === null)
+        return { schemaManifest, state: null };
+    const config = asObject(snapshot.state.config, "Yui config");
+    const review = config.review === undefined
+        ? undefined
+        : asObject(config.review, "Yui review config");
+    const migratedReview = review === undefined
+        ? undefined
+        : (() => {
+            const { deltaRecheck: _retiredSwitch, deltaRecheckMaxChangedLines: _retiredLineThreshold, deltaRecheckMaxChangedFiles: _retiredFileThreshold, ...retained } = review;
+            return retained;
+        })();
+    return {
+        schemaManifest,
+        state: {
+            ...snapshot.state,
+            config: {
+                ...config,
+                schemaVersion: CONFIG_REVIEW_CONTROLS_TO_VERSION,
+                ...(migratedReview === undefined ? {} : { review: migratedReview })
+            }
+        }
+    };
+}
 function workItemExecutionGroupHistoryStep() {
     return {
         axis: "record",
@@ -1241,6 +1302,324 @@ function normalizeStoredTaskV16ToV17(snapshot) {
         state: { ...snapshot.state, tasks: nextTasks }
     };
 }
+/** StoredTask v18 retires the mutable OperatorNotification projection. */
+function storedTaskEventNoticesStep() {
+    return {
+        axis: "record",
+        recordKind: "storedTask",
+        fromVersion: STORED_TASK_EVENT_NOTICES_FROM_VERSION,
+        toVersion: STORED_TASK_EVENT_NOTICES_TO_VERSION,
+        preconditions: requireStoredTaskV17OperatorNoticeShape,
+        transform: normalizeStoredTaskV17ToV18,
+        declaredEffects: ["operator-mailbox-event-references"]
+    };
+}
+const STORED_TASK_V17_FIELDS = [
+    "schemaVersion",
+    "task",
+    "idHighWaterMarks",
+    "brief",
+    "changeSets",
+    "integrationAttempts",
+    "integrationQueue",
+    "durableJobs",
+    "roles",
+    "managedWorkspaces",
+    "roleSessionSets",
+    "jobCallerKeyHashes",
+    "workItems",
+    "contextSnapshots",
+    "agentRuns",
+    "reviewRounds",
+    "activeRuns",
+    "messages",
+    "inputRequests",
+    "decisions",
+    "milestones",
+    "events",
+    "wakes",
+    "capabilityGrants",
+    "releaseWorkflows",
+    "publicationReferences",
+    "leaderFailure",
+    "operatorNotification"
+];
+function requireStoredTaskV17OperatorNoticeShape(snapshot) {
+    const versions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    if (versions.storedTask !== STORED_TASK_EVENT_NOTICES_FROM_VERSION) {
+        throw new Error(`Record storedTask compatible step requires manifest version ${STORED_TASK_EVENT_NOTICES_FROM_VERSION}.`);
+    }
+    if (snapshot.state === null)
+        return;
+    const tasks = asObject(snapshot.state.tasks, "state tasks");
+    for (const [taskId, rawTask] of Object.entries(tasks)) {
+        const task = asObject(rawTask, `Task aggregate ${taskId}`);
+        if (task.schemaVersion !== STORED_TASK_EVENT_NOTICES_FROM_VERSION) {
+            throw new Error(`Task aggregate ${taskId} must use schemaVersion ${STORED_TASK_EVENT_NOTICES_FROM_VERSION}.`);
+        }
+        const allowed = new Set(STORED_TASK_V17_FIELDS);
+        const unknown = Object.keys(task).find((key) => !allowed.has(key));
+        if (unknown !== undefined) {
+            throw new Error(`Task aggregate ${taskId} has an unknown v17 field: ${unknown}.`);
+        }
+        const missing = STORED_TASK_V17_FIELDS.find((key) => !Object.hasOwn(task, key));
+        if (missing !== undefined) {
+            throw new Error(`Task aggregate ${taskId} is missing v17 field: ${missing}.`);
+        }
+        if (task.operatorNotification !== null) {
+            requireLegacyOperatorNotice(task.operatorNotification, taskId);
+        }
+    }
+}
+function requireLegacyOperatorNotice(value, taskId) {
+    const notice = asObject(value, `Operator notification ${taskId}`);
+    if (notice.schemaVersion !== 1 || notice.taskId !== taskId) {
+        throw new Error(`Operator notification identity is invalid: ${taskId}.`);
+    }
+    if (notice.type === "leader-recovery-failed") {
+        requireLegacyNoticeText(notice.message, `Operator notification message ${taskId}`);
+    }
+    else if (notice.type === "leader-stalled") {
+        requireLegacyNoticeText(notice.message, `Operator notification message ${taskId}`);
+        requireLegacyNoticeText(notice.runId, `Operator notification Run ${taskId}`);
+        requireLegacyNoticeTimestamp(notice.progressAt, `Operator notification progress ${taskId}`);
+        requireLegacyNoticeText(notice.evidenceKey, `Operator notification evidence ${taskId}`);
+        if (notice.classification !== "truly-stalled") {
+            throw new Error(`Operator notification classification is invalid: ${taskId}.`);
+        }
+    }
+    else if (notice.type === "task-terminal") {
+        if (notice.status !== "completed" && notice.status !== "retired") {
+            throw new Error(`Operator notification Task status is invalid: ${taskId}.`);
+        }
+        if (!["user", "operator", "leader"].includes(String(notice.by))) {
+            throw new Error(`Operator notification Task actor is invalid: ${taskId}.`);
+        }
+        requireLegacyNoticeText(notice.summary, `Operator notification summary ${taskId}`);
+    }
+    else {
+        throw new Error(`Operator notification type is invalid: ${taskId}.`);
+    }
+    requireLegacyNoticeTimestamp(notice.createdAt, `Operator notification createdAt ${taskId}`);
+    requireLegacyNoticeTimestamp(notice.updatedAt, `Operator notification updatedAt ${taskId}`);
+}
+function requireLegacyNoticeText(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0 || value.includes("\0")) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return value;
+}
+function requireLegacyNoticeTimestamp(value, label) {
+    const timestamp = requireLegacyNoticeText(value, label);
+    if (!Number.isFinite(Date.parse(timestamp)))
+        throw new Error(`${label} is invalid.`);
+    return timestamp;
+}
+function normalizeStoredTaskV17ToV18(snapshot) {
+    requireStoredTaskV17OperatorNoticeShape(snapshot);
+    const versions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    const schemaManifest = {
+        ...snapshot.schemaManifest,
+        recordVersions: {
+            ...versions,
+            storedTask: STORED_TASK_EVENT_NOTICES_TO_VERSION
+        }
+    };
+    if (snapshot.state === null)
+        return { schemaManifest, state: null };
+    const tasks = asObject(snapshot.state.tasks, "state tasks");
+    const nextTasks = {};
+    const legacyNotices = new Map();
+    for (const [taskId, rawTask] of Object.entries(tasks)) {
+        const task = asObject(rawTask, `Task aggregate ${taskId}`);
+        legacyNotices.set(taskId, task.operatorNotification === null
+            ? null
+            : asObject(task.operatorNotification, `Operator notification ${taskId}`));
+        const nextTask = {
+            ...task,
+            schemaVersion: STORED_TASK_EVENT_NOTICES_TO_VERSION,
+            events: { ...asObject(task.events, `Task events ${taskId}`) },
+            idHighWaterMarks: {
+                ...asObject(task.idHighWaterMarks, `Task id high-water marks ${taskId}`)
+            }
+        };
+        delete nextTask.operatorNotification;
+        nextTasks[taskId] = nextTask;
+    }
+    const eventByTask = new Map();
+    const eventRefForTask = (taskId) => {
+        const existing = eventByTask.get(taskId);
+        if (existing !== undefined)
+            return { type: "event", taskId, id: existing };
+        const task = asObject(nextTasks[taskId], `Task aggregate ${taskId}`);
+        const events = asObject(task.events, `Task events ${taskId}`);
+        const marks = asObject(task.idHighWaterMarks, `Task id high-water marks ${taskId}`);
+        let sequence = Number(marks.event ?? 0) + 1;
+        if (!Number.isSafeInteger(sequence) || sequence < 1) {
+            throw new Error(`Task event high-water mark is invalid: ${taskId}.`);
+        }
+        while (events[`event-${sequence}`] !== undefined)
+            sequence += 1;
+        const eventId = `event-${sequence}`;
+        const notice = legacyNotices.get(taskId) ?? null;
+        const migrated = migratedOperatorNoticeEvent(taskId, eventId, notice, task);
+        events[eventId] = migrated;
+        marks.event = sequence;
+        eventByTask.set(taskId, eventId);
+        return { type: "event", taskId, id: eventId };
+    };
+    const mailboxes = asObject(snapshot.state.mailboxes, "state mailboxes");
+    const nextMailboxes = {};
+    for (const [key, rawMailbox] of Object.entries(mailboxes)) {
+        const mailbox = asObject(rawMailbox, `WorkMailbox ${key}`);
+        const target = asObject(mailbox.target, `WorkMailbox target ${key}`);
+        nextMailboxes[key] = target.kind === "operator"
+            ? rewriteLegacyOperatorMailbox(mailbox, key, eventRefForTask)
+            : { ...mailbox };
+    }
+    for (const [taskId, notice] of legacyNotices) {
+        if (notice !== null)
+            eventRefForTask(taskId);
+    }
+    return {
+        schemaManifest,
+        state: { ...snapshot.state, tasks: nextTasks, mailboxes: nextMailboxes }
+    };
+}
+function migratedOperatorNoticeEvent(taskId, eventId, notice, taskAggregate) {
+    const task = asObject(taskAggregate.task, `Task ${taskId}`);
+    const timestamp = String(notice?.updatedAt ?? task.updatedAt ?? task.createdAt ?? "");
+    if (!Number.isFinite(Date.parse(timestamp))) {
+        throw new Error(`Legacy Operator notice timestamp is invalid: ${taskId}.`);
+    }
+    const type = notice?.type;
+    if (notice !== null && type === "task-terminal") {
+        const status = String(notice.status ?? "");
+        if (status !== "completed" && status !== "retired") {
+            throw new Error(`Legacy terminal Operator notice status is invalid: ${taskId}.`);
+        }
+        return {
+            schemaVersion: 2,
+            id: eventId,
+            taskId,
+            type: `task.${status}`,
+            payload: {
+                status,
+                by: String(notice.by ?? "operator"),
+                summary: String(notice.summary ?? "Task reached a terminal state."),
+                migratedFrom: "operator-notification"
+            },
+            createdAt: timestamp
+        };
+    }
+    if (notice !== null && type === "leader-stalled") {
+        return {
+            schemaVersion: 2,
+            id: eventId,
+            taskId,
+            type: "run.stalled",
+            payload: {
+                runId: String(notice.runId ?? "unknown"),
+                roleName: "leader",
+                progressAt: String(notice.progressAt ?? timestamp),
+                classification: "truly-stalled",
+                evidenceKey: String(notice.evidenceKey ?? "legacy-operator-notification"),
+                migratedFrom: "operator-notification"
+            },
+            createdAt: timestamp
+        };
+    }
+    return {
+        schemaVersion: 2,
+        id: eventId,
+        taskId,
+        type: "leader.attention-required",
+        payload: {
+            reason: type === "leader-recovery-failed"
+                ? "leader-recovery-failed"
+                : "legacy-operator-mailbox",
+            message: String(notice?.message ?? "Inspect the migrated Operator notice."),
+            migratedFrom: notice === null ? "operator-mailbox" : "operator-notification"
+        },
+        createdAt: timestamp
+    };
+}
+function rewriteLegacyOperatorMailbox(mailbox, key, eventRefForTask) {
+    const rewriteRef = (rawRef) => {
+        const ref = asObject(rawRef, `WorkMailbox ${key} entity ref`);
+        if (ref.type === "input" || ref.type === "event")
+            return { ...ref };
+        const taskId = ref.type === "task" ? ref.id : ref.taskId;
+        if (typeof taskId !== "string" || taskId.trim().length === 0) {
+            throw new Error(`Legacy Operator mailbox ref has no Task identity: ${key}.`);
+        }
+        return eventRefForTask(taskId);
+    };
+    const rewriteBatch = (rawBatch, label) => {
+        const batch = asObject(rawBatch, label);
+        if (!Array.isArray(batch.refs))
+            throw new Error(`${label} refs must be an array.`);
+        const sourceRefs = batch.refs.map((rawRef) => asObject(rawRef, `${label} entity ref`));
+        const semanticTaskIds = new Set(sourceRefs.flatMap((ref) => ((ref.type === "input" || ref.type === "event") && typeof ref.taskId === "string"
+            ? [ref.taskId]
+            : [])));
+        const refs = [];
+        const seen = new Set();
+        for (const sourceRef of sourceRefs) {
+            const referencedTaskId = sourceRef.type === "task" ? sourceRef.id : sourceRef.taskId;
+            if (sourceRef.type !== "input"
+                && sourceRef.type !== "event"
+                && typeof referencedTaskId === "string"
+                && semanticTaskIds.has(referencedTaskId)) {
+                continue;
+            }
+            const ref = rewriteRef(sourceRef);
+            const identity = `${String(ref.type)}\0${String(ref.taskId ?? "")}\0${String(ref.id)}`;
+            if (seen.has(identity))
+                continue;
+            seen.add(identity);
+            refs.push(ref);
+        }
+        return { ...batch, refs };
+    };
+    const rewriteProcessing = (raw) => {
+        if (raw === null)
+            return null;
+        const processing = asObject(raw, `WorkMailbox ${key} processing`);
+        return {
+            ...processing,
+            batch: rewriteBatch(processing.batch, `WorkMailbox ${key} processing batch`),
+            ...(processing.executionRef === undefined
+                ? {}
+                : { executionRef: rewriteRef(processing.executionRef) })
+        };
+    };
+    const rewriteDelivery = (raw) => {
+        if (raw === null)
+            return null;
+        const delivery = asObject(raw, `WorkMailbox ${key} input delivery`);
+        return {
+            ...delivery,
+            batch: rewriteBatch(delivery.batch, `WorkMailbox ${key} input delivery batch`),
+            executionRef: rewriteRef(delivery.executionRef)
+        };
+    };
+    const pending = asObject(mailbox.pending, `WorkMailbox ${key} pending lanes`);
+    return {
+        ...mailbox,
+        processing: rewriteProcessing(mailbox.processing),
+        pending: {
+            ...pending,
+            normal: pending.normal === null
+                ? null
+                : rewriteBatch(pending.normal, `WorkMailbox ${key} normal batch`),
+            userCorrection: pending.userCorrection === null
+                ? null
+                : rewriteBatch(pending.userCorrection, `WorkMailbox ${key} correction batch`)
+        },
+        inputDelivery: rewriteDelivery(mailbox.inputDelivery)
+    };
+}
 /**
  * The taskWake record family is introduced alongside StoredTask v17. The
  * compatible step supplies the empty map and high-water mark; this step only

package/dist/storage/sqliteSchema.js

@@ -327,7 +327,8 @@ CREATE TABLE IF NOT EXISTS events (
 );
 CREATE INDEX IF NOT EXISTS idx_events_type_time ON events(task_id, type, occurred_at);
 
--- Per-task scheduler projections (leaderFailure, operatorNotification).
+-- Per-task scheduler projections. operator-notification is a retired legacy
+-- kind retained only so old layout-7 Homes can be read by the upgrade path.
 CREATE TABLE IF NOT EXISTS task_projections (
   task_id    TEXT NOT NULL,
   kind       TEXT NOT NULL CHECK (kind IN ('leader-failure','operator-notification')),
@@ -930,6 +931,12 @@ CREATE TABLE IF NOT EXISTS context_snapshots (
 CREATE UNIQUE INDEX IF NOT EXISTS idx_context_snapshots_scope_sequence
   ON context_snapshots(task_id, scope, COALESCE(scope_ref, ''), sequence);
 `;
+/**
+ * The single forward migration history for current SQLite Homes. New durable
+ * layout, aggregate, and record changes belong here and must be expressible as
+ * one atomic in-place transaction. The separate logical migration registry is
+ * only the bridge from valid pre-SQLite Homes and is allowed to rebuild them.
+ */
 const MIGRATIONS = [
     { version: 1, axis: "layout", sql: MIGRATION_1_SQL },
     { version: 2, axis: "record", recordKind: "durableJob+capability-grant+release-workflow", sql: MIGRATION_2_SQL },
@@ -986,10 +993,13 @@ const SCHEMA_MIGRATIONS_SQL = `
  * layout migrations.  A database with any sqlite_master object is therefore
  * diagnosed as corrupt/partially initialized and left untouched.
  */
-function ensureMigrationLedger(db) {
+function ensureMigrationLedger(db, mode) {
     const objects = db.prepare("SELECT type, name FROM sqlite_master WHERE name IS NOT NULL").all();
     const ledger = objects.find(({ name }) => name === "schema_migrations");
     if (ledger === undefined) {
+        if (mode === "validate") {
+            throw new SqliteSchemaMigrationError("schema_migrations ledger is missing from an existing database");
+        }
         if (objects.length !== 0) {
             throw new SqliteSchemaMigrationError("schema_migrations ledger is missing from a non-empty database");
         }
@@ -1134,34 +1144,67 @@ function validatePendingProjectionBackfillSources(db) {
     }
 }
 /**
- * Apply pending migrations idempotently inside transactions.
- *
- * Each migration runs in its own transaction: the DDL and the
- * `schema_migrations` bookkeeping commit atomically, so a crash mid-migration
- * rolls back and the next open re-applies cleanly. Re-running on a current
- * database performs no work (every version is already recorded).
+ * Inspect a database's checksummed migration prefix without changing it.
+ * Pending versions are a supported upgrade state; malformed, gapped, changed,
+ * or future ledger entries remain explicit integrity failures.
  */
-export function migrateSqliteSchema(db) {
-    const ledgerWasCreated = ensureMigrationLedger(db);
-    // Validate the complete ledger before touching any pending migration.  This
-    // prevents a manually altered or partially recorded ledger from silently
-    // skipping the partial-index/projection migrations added after a valid Home.
+export function inspectSqliteSchemaMigrations(db) {
+    const ledgerWasCreated = ensureMigrationLedger(db, "validate");
     const applied = validateAppliedMigrations(db, ledgerWasCreated);
-    const newlyApplied = [];
-    for (const migration of MIGRATIONS) {
-        if (applied.has(migration.version))
-            continue;
-        const apply = db.transaction(() => {
+    const pendingVersions = MIGRATIONS
+        .filter((migration) => !applied.has(migration.version))
+        .map((migration) => migration.version);
+    if (pendingVersions.length === 0)
+        validateSchemaObjects(db);
+    const current = MIGRATIONS[applied.size - 1];
+    const target = MIGRATIONS.at(-1);
+    if (current === undefined) {
+        throw new SqliteSchemaMigrationError("schema_migrations ledger has no current head");
+    }
+    return {
+        currentVersion: applied.size,
+        currentChecksum: checksum(current.sql),
+        targetVersion: SQLITE_SCHEMA_VERSION,
+        targetChecksum: checksum(target.sql),
+        pendingVersions
+    };
+}
+/**
+ * Apply or validate schema migrations without letting an ordinary open mutate
+ * an existing authoritative database.
+ *
+ * In `apply` mode every pending DDL/data step and every ledger row runs in one
+ * outer transaction. The database therefore advances to the release version
+ * as one commit or remains entirely at its previous version. `validate` mode
+ * rejects a pending version before executing any migration.
+ */
+export function migrateSqliteSchema(db, options) {
+    const migrate = () => {
+        const ledgerWasCreated = ensureMigrationLedger(db, options.mode);
+        // Validate the complete ledger before touching any pending migration. This
+        // prevents a manually altered or partially recorded ledger from silently
+        // skipping a later schema/data step.
+        const applied = validateAppliedMigrations(db, ledgerWasCreated);
+        const pending = MIGRATIONS.filter((migration) => !applied.has(migration.version));
+        if (options.mode === "validate" && pending.length > 0) {
+            throw new SqliteSchemaMigrationError(`pending SQLite schema migration ${pending[0].version}; `
+                + "run the explicit storage upgrade before opening this database", "admission");
+        }
+        const newlyApplied = [];
+        for (const migration of pending) {
             if (migration.version === 13)
                 validatePendingProjectionBackfillSources(db);
             db.exec(migration.sql);
             db.prepare(`INSERT INTO schema_migrations (version, axis, record_kind, applied_at, checksum)
          VALUES (?, ?, ?, ?, ?)`).run(migration.version, migration.axis, migration.recordKind ?? null, new Date().toISOString(), checksum(migration.sql));
-        });
-        apply();
-        newlyApplied.push(migration.version);
-    }
-    validateSchemaObjects(db);
+            newlyApplied.push(migration.version);
+        }
+        validateSchemaObjects(db);
+        return newlyApplied;
+    };
+    const newlyApplied = options.mode === "apply" && !db.inTransaction
+        ? db.transaction(migrate)()
+        : migrate();
     return { applied: newlyApplied, version: SQLITE_SCHEMA_VERSION };
 }
 /** The names of every table the schema creates (for tests/introspection). */

package/dist/storage/sqliteStore.js

@@ -55,7 +55,7 @@ import { assertHomeWritable } from "./upgradeFence.js";
 import { CURRENT_CONFIG_SCHEMA_VERSION, CURRENT_PENDING_WAKEUP_SCHEMA_VERSION, CURRENT_WORK_MAILBOX_SCHEMA_VERSION, executionLaneActiveRunKey, executionLaneActiveRunKeyParts, StorageConflictError, StorageCancelledError, StorageRecordError, FileTaskStore, storedCapabilityGrant, storedPublicationReference, storedReleaseWorkflow, isValidCapabilityGrantTransition, isValidReleaseWorkflowTransition, validateYuiConfig } from "./taskStore.js";
 import { publicationExternalKey } from "../task/publicationReference.js";
 import { gateArtifactKey, validateGateArtifact } from "../verification/gateArtifact.js";
-import { migrateSqliteSchema, SQLITE_AGGREGATE_VERSION, SQLITE_LAYOUT_VERSION, TELEMETRY_KEEP_PER_GENERATION, TELEMETRY_RUN_CAP } from "./sqliteSchema.js";
+import { inspectSqliteSchemaMigrations, migrateSqliteSchema, SqliteSchemaMigrationError, SQLITE_AGGREGATE_VERSION, SQLITE_LAYOUT_VERSION, TELEMETRY_KEEP_PER_GENERATION, TELEMETRY_RUN_CAP } from "./sqliteSchema.js";
 import { inspectStorageSchema } from "./storageSchema.js";
 /** Read the immutable Home identity without opening a writable Store connection. */
 export function readSqliteHomeIdentity(rootDir, databaseFilename = "yui.db") {
@@ -136,6 +136,7 @@ export class SqliteTaskStore {
     #db;
     #rootDir;
     #migration;
+    #openedSchemaHead;
     #inTransaction = false;
     #dirty = false;
     constructor(rootDir, _options = {}) {
@@ -143,16 +144,34 @@ export class SqliteTaskStore {
         this.#migration = _options.migration ?? false;
         mkdirSync(rootDir, { recursive: true, mode: 0o700 });
         const filename = _options.databaseFilename ?? "yui.db";
-        this.#db = new Database(join(rootDir, filename));
-        // §4.1 / §9: WAL, no fsync weakening, FKs on, busy timeout for CLI contention.
-        this.#db.pragma("journal_mode = WAL");
-        this.#db.pragma("synchronous = FULL");
-        this.#db.pragma("foreign_keys = ON");
-        this.#db.pragma("busy_timeout = 5000");
-        this.#db.pragma("wal_autocheckpoint = 1000");
-        migrateSqliteSchema(this.#db);
-        this.#seedHomeMeta();
-        this.#seedConfig();
+        const databasePath = join(rootDir, filename);
+        const databaseExisted = existsSync(databasePath);
+        if (this.#migration && filename === "yui.db") {
+            throw new SqliteSchemaMigrationError("offline migration mode cannot open the authoritative yui.db", "admission");
+        }
+        this.#db = new Database(databasePath);
+        try {
+            // §4.1 / §9: WAL, no fsync weakening, FKs on, busy timeout for CLI contention.
+            this.#db.pragma("journal_mode = WAL");
+            this.#db.pragma("synchronous = FULL");
+            this.#db.pragma("foreign_keys = ON");
+            this.#db.pragma("busy_timeout = 5000");
+            this.#db.pragma("wal_autocheckpoint = 1000");
+            migrateSqliteSchema(this.#db, {
+                mode: this.#migration || !databaseExisted ? "apply" : "validate"
+            });
+            const schema = inspectSqliteSchemaMigrations(this.#db);
+            this.#openedSchemaHead = {
+                version: schema.currentVersion,
+                checksum: schema.currentChecksum
+            };
+            this.#seedHomeMeta();
+            this.#seedConfig();
+        }
+        catch (error) {
+            this.#db.close();
+            throw error;
+        }
     }
     rootDirectory() { return this.#rootDir; }
     /** Close the underlying database connection. */
@@ -202,6 +221,13 @@ export class SqliteTaskStore {
         if (this.#migration)
             return;
         assertHomeWritable(this.#rootDir);
+        const current = this.#db.prepare("SELECT version, checksum FROM schema_migrations ORDER BY version DESC LIMIT 1").get();
+        if (current?.version !== this.#openedSchemaHead.version
+            || current.checksum !== this.#openedSchemaHead.checksum) {
+            throw new SqliteSchemaMigrationError(`open Store schema head ${this.#openedSchemaHead.version}/${this.#openedSchemaHead.checksum} `
+                + `changed to ${String(current?.version)}/${String(current?.checksum)}; `
+                + "reopen the Store with the active Yui version before writing", "admission");
+        }
     }
     #bumpRevision() {
         this.#db.prepare("UPDATE home_meta SET revision = revision + 1, updated_at = ? WHERE id = 1").run(this.#now());
@@ -217,9 +243,12 @@ export class SqliteTaskStore {
             this.#dirty = true;
             return result;
         }
-        this.#prepareWrite();
         this.#begin();
         try {
+            // Acquire SQLite's write reservation before checking the upgrade fence.
+            // A writer that started first commits before the upgrader's final
+            // transactional inventory; a writer that starts later sees the fence.
+            this.#prepareWrite();
             const result = fn();
             if (!this.#migration) {
                 this.#bumpRevision();
@@ -238,9 +267,12 @@ export class SqliteTaskStore {
             return run(this);
         this.#begin();
         try {
+            // Pin the Store's validated schema generation before user code runs.
+            // This prevents a long-lived pre-upgrade Store from executing old SQL
+            // after an in-place migration has committed.
+            this.#prepareWrite();
             const result = run(this);
             if (this.#dirty) {
-                this.#prepareWrite();
                 if (options?.requestId !== undefined) {
                     this.#insertOutbox(options.requestId, options.outboxCommand ?? null);
                 }
@@ -265,9 +297,9 @@ export class SqliteTaskStore {
     async transactionAsync(execute) {
         if (this.#inTransaction)
             return execute(this);
-        this.#prepareWrite();
         this.#begin();
         try {
+            this.#prepareWrite();
             const result = await execute(this);
             if (this.#dirty)
                 this.#bumpRevision();
@@ -2048,15 +2080,6 @@ export class SqliteTaskStore {
     clearLeaderFailure(taskId) {
         this.#clearProjection(taskId, "leader-failure");
     }
-    getOperatorNotification(taskId) {
-        return this.#getProjection(taskId, "operator-notification");
-    }
-    saveOperatorNotification(notification) {
-        this.#saveProjection(notification.taskId, "operator-notification", notification);
-    }
-    clearOperatorNotification(taskId) {
-        this.#clearProjection(taskId, "operator-notification");
-    }
     // -- pending wakeups (leader-role work-mailbox projection, mirrors taskStore.ts) --
     getPendingWakeup(taskId) {
         return pendingWakeupProjection(this.getWorkMailbox({ kind: "role", taskId, roleName: "leader" }));