niceeval 0.13.1 → 0.13.2

package/dist/record/host/runtime.cjs

@@ -49,9 +49,11 @@ function readerClosed() {
 function handleInvalid() {
     return new errors_ts_3.RecordHandleInvalid({ code: "record-handle-invalid" });
 }
-function migrationInterrupted() {
+function migrationInterrupted(restoreCommit, restoreSafe) {
     return new errors_ts_3.RecordMigrationInterruptedState({
         code: "record-migration-interrupted",
+        ...(restoreCommit === undefined ? {} : { restoreCommit }),
+        ...(restoreSafe === undefined ? {} : { restoreSafe }),
     });
 }
 function bootstrapInvalid() {
@@ -115,10 +117,12 @@ function sameRoot(left, right) {
         leftPaths.portableRoot === rightPaths.portableRoot;
 }
 function currentFormatInspection(fileSystem, root) {
-    return (0, format_ts_1.readCurrentRecordFormat)(fileSystem, root).pipe(effect_1.Effect.map(() => ({
-        state: "already-current",
+    return (0, format_ts_1.readRecordFormatForMaintenance)(fileSystem, root).pipe(effect_1.Effect.flatMap((format) => effect_1.Effect.map(planAttachmentMigration({ fileSystem, root }), (attachments) => ({
+        state: format.sourceSchemaVersion === identifiers_ts_1.RECORD_SCHEMA_VERSION && attachments.targets.length === 0
+            ? "already-current"
+            : "migration-required",
         format: identifiers_ts_1.RECORD_FORMAT,
-    })), effect_1.Effect.catchAll((error) => error instanceof errors_ts_3.RecordFormatUnsupported
+    }))), effect_1.Effect.catchAll((error) => error instanceof errors_ts_3.RecordFormatUnsupported
         ? effect_1.Effect.succeed({
             state: "unsupported-format",
             format: error.format,
@@ -126,7 +130,7 @@ function currentFormatInspection(fileSystem, root) {
         : effect_1.Effect.fail(error)));
 }
 function isSealedRun(fileSystem, root, runId) {
-    return effect_1.Effect.map(fileSystem.pathKind(runPath(root, runId, "complete")), (kind) => kind === "file");
+    return fileSystem.isCompleteMarker({ root, runId });
 }
 function readRunDocument(fileSystem, root, runId) {
     return effect_1.Effect.map(readJson(fileSystem, runPath(root, runId, "run.json")), (json) => {
@@ -224,6 +228,19 @@ function readRunAttempts(fileSystem, root, runId) {
         return Object.freeze(attempts);
     });
 }
+function maintenanceReaderRuntime(root, record) {
+    return {
+        root,
+        record,
+        lifecycle: { closed: false },
+        runs: new WeakMap(),
+        attempts: new WeakMap(),
+        owners: new WeakMap(),
+        runsById: new Map(),
+        attemptsByKey: new Map(),
+        sealedCoreSnapshot: undefined,
+    };
+}
 /**
  * The reader deliberately reconstructs the complete published aggregate only
  * at the point where it is about to sign a Run/Attempt as available. This is
@@ -439,9 +456,11 @@ function readFixedFamily(input) {
                     runId: owner.runId,
                     descriptor: descriptor,
                     payload: value.value,
-                }).pipe(effect_1.Effect.map((joined) => joined
+                }).pipe(effect_1.Effect.map((join) => join.state === "joined"
                     ? value
-                    : Object.freeze({ state: "invalid", issues: coreInvalid().issues })));
+                    : join.state === "migration-required" || join.state === "unsupported"
+                        ? join
+                        : Object.freeze({ state: "invalid", issues: coreInvalid().issues })));
             }));
         }
         const descriptor = input.descriptor;
@@ -467,9 +486,11 @@ function readFixedFamily(input) {
                 attemptId: owner.ref.attemptId,
                 descriptor: descriptor,
                 payload: value.value,
-            }).pipe(effect_1.Effect.map((joined) => joined
+            }).pipe(effect_1.Effect.map((join) => join.state === "joined"
                 ? value
-                : Object.freeze({ state: "invalid", issues: coreInvalid().issues })));
+                : join.state === "migration-required" || join.state === "unsupported"
+                    ? join
+                    : Object.freeze({ state: "invalid", issues: coreInvalid().issues })));
         }));
     });
 }
@@ -486,11 +507,20 @@ function isSourceNavigationDescriptor(descriptor) {
 function hasSourceFrames(payload) {
     return payload.diagnostics.diagnostics.some((diagnostic) => diagnostic.sourceFrame !== null);
 }
+const joinedCrossFamily = Object.freeze({ state: "joined" });
+const invalidCrossFamily = Object.freeze({ state: "invalid" });
+function dependentFamilyJoin(read) {
+    if (read.state === "available")
+        return joinedCrossFamily;
+    if (read.state === "migration-required" || read.state === "unsupported")
+        return read;
+    return invalidCrossFamily;
+}
 /** Common cross-family closure boundary used by both reader and writer seal. */
 function validateObservabilitySourceFrameJoin(input) {
     return effect_1.Effect.gen(function* () {
         if (!hasSourceFrames(input.payload))
-            return true;
+            return joinedCrossFamily;
         const sources = yield* (0, runtime_ts_1.readFixedRecordAttachment)({
             fileSystem: input.fileSystem,
             root: input.root,
@@ -498,8 +528,8 @@ function validateObservabilitySourceFrameJoin(input) {
             descriptor: catalog_ts_1.NiceEvalRecordFamilyCatalog.sources,
         });
         if (sources.state !== "available")
-            return false;
-        return (0, observability_ts_1.observabilitySourceFrameIntegrityIssues)(input.payload, sources.value).length === 0;
+            return dependentFamilyJoin(sources);
+        return (0, observability_ts_1.observabilitySourceFrameIntegrityIssues)(input.payload, sources.value).length === 0 ? joinedCrossFamily : invalidCrossFamily;
     });
 }
 function hasMappedNavigationRows(payload) {
@@ -522,7 +552,7 @@ function validateFixedCrossFamilyJoin(input) {
     if (isAssertionsDescriptor(input.descriptor)) {
         const payload = input.payload;
         if (payload.sourceSites.length === 0)
-            return effect_1.Effect.succeed(true);
+            return effect_1.Effect.succeed(joinedCrossFamily);
         return effect_1.Effect.gen(function* () {
             const sources = yield* (0, runtime_ts_1.readFixedRecordAttachment)({
                 fileSystem: input.fileSystem,
@@ -530,14 +560,17 @@ function validateFixedCrossFamilyJoin(input) {
                 location: Object.freeze({ owner: "run", runId: input.runId }),
                 descriptor: catalog_ts_1.NiceEvalRecordFamilyCatalog.sources,
             });
-            return sources.state === "available" &&
-                (0, assertions_ts_1.assertionsSourceSiteIntegrityIssues)(payload, sources.value).length === 0;
+            if (sources.state !== "available")
+                return dependentFamilyJoin(sources);
+            return (0, assertions_ts_1.assertionsSourceSiteIntegrityIssues)(payload, sources.value).length === 0
+                ? joinedCrossFamily
+                : invalidCrossFamily;
         });
     }
     if (isSourceNavigationDescriptor(input.descriptor)) {
         const payload = input.payload;
         if (input.attemptId === undefined)
-            return effect_1.Effect.succeed(false);
+            return effect_1.Effect.succeed(invalidCrossFamily);
         return effect_1.Effect.gen(function* () {
             const observability = yield* (0, runtime_ts_1.readFixedRecordAttachment)({
                 fileSystem: input.fileSystem,
@@ -550,7 +583,7 @@ function validateFixedCrossFamilyJoin(input) {
                 descriptor: catalog_ts_1.NiceEvalRecordFamilyCatalog.observability.attempt,
             });
             if (observability.state !== "available")
-                return false;
+                return dependentFamilyJoin(observability);
             const sources = hasMappedNavigationRows(payload)
                 ? yield* (0, runtime_ts_1.readFixedRecordAttachment)({
                     fileSystem: input.fileSystem,
@@ -559,16 +592,18 @@ function validateFixedCrossFamilyJoin(input) {
                     descriptor: catalog_ts_1.NiceEvalRecordFamilyCatalog.sources,
                 })
                 : undefined;
-            if (sources !== undefined && sources.state !== "available")
-                return false;
+            if (sources !== undefined) {
+                if (sources.state !== "available")
+                    return dependentFamilyJoin(sources);
+            }
             return (0, source_navigation_ts_1.sourceNavigationIntegrityIssues)({
                 payload,
                 observability: observability.value,
                 sources: sources?.state === "available" ? sources.value : undefined,
-            }).length === 0;
+            }).length === 0 ? joinedCrossFamily : invalidCrossFamily;
         });
     }
-    return effect_1.Effect.succeed(true);
+    return effect_1.Effect.succeed(joinedCrossFamily);
 }
 function makeReadSession(runtime, fileSystem) {
     const session = Object.freeze({
@@ -768,6 +803,7 @@ function openCurrentRead(input) {
             return yield* effect_1.Effect.fail(migrationInterrupted());
         }
         const current = yield* (0, format_ts_1.readCurrentRecordFormat)(fileSystem, input.root);
+        yield* ensureOrdinaryCurrentAttachments({ fileSystem, root: input.root });
         yield* coordination.verifyRecordIdentity({ root: input.root, recordId: current.document.recordId });
         const lifecycle = { closed: false };
         const runtime = {
@@ -1623,6 +1659,7 @@ function openNewRuntime(request) {
         }
         yield* initializeRecord({ root: request.root, fileSystem, entropy });
         const current = yield* (0, format_ts_1.readCurrentRecordFormat)(fileSystem, request.root);
+        yield* ensureOrdinaryCurrentAttachments({ fileSystem, root: request.root });
         yield* coordination.verifyRecordIdentity({ root: request.root, recordId: current.document.recordId });
         const runId = yield* createFreshRunDirectory(request.root, fileSystem, entropy);
         const mutex = yield* effect_1.Effect.makeSemaphore(1);
@@ -1662,26 +1699,558 @@ function openNewRun(request) {
 function openNewReferenceRun(request) {
     return effect_1.Effect.map(openNewRuntime(request), makeReferenceRunSession);
 }
+function migrationDescriptor(descriptor) {
+    return descriptor;
+}
+const runMigrationDescriptors = Object.freeze([
+    migrationDescriptor(catalog_ts_1.NiceEvalRecordFamilyCatalog.observability.run),
+    migrationDescriptor(catalog_ts_1.NiceEvalRecordFamilyCatalog.sources),
+    migrationDescriptor(catalog_ts_1.NiceEvalRecordFamilyCatalog.artifacts.run),
+]);
+const attemptMigrationDescriptors = Object.freeze([
+    migrationDescriptor(catalog_ts_1.NiceEvalRecordFamilyCatalog.assertions),
+    migrationDescriptor(catalog_ts_1.NiceEvalRecordFamilyCatalog.observability.attempt),
+    migrationDescriptor(catalog_ts_1.NiceEvalRecordFamilyCatalog.fileChanges),
+    migrationDescriptor(catalog_ts_1.NiceEvalRecordFamilyCatalog.sourceNavigation),
+    migrationDescriptor(catalog_ts_1.NiceEvalRecordFamilyCatalog.artifacts.attempt),
+]);
+function validateAttachmentDirectoryInventory(input) {
+    return effect_1.Effect.gen(function* () {
+        const kind = yield* input.fileSystem.pathKind(input.directory);
+        if (kind === "missing")
+            return;
+        if (kind !== "directory") {
+            return yield* effect_1.Effect.fail(new errors_ts_3.RecordFormatUnsupported({
+                code: "record-format-unsupported",
+                format: "attachment-inventory",
+            }));
+        }
+        const entries = yield* input.fileSystem.listDirectory({
+            directory: input.directory,
+            maximumEntries: 256,
+        });
+        const unsupported = entries.find((entry) => entry.kind !== "directory" || !input.allowed.has(entry.name));
+        if (unsupported !== undefined) {
+            return yield* effect_1.Effect.fail(new errors_ts_3.RecordFormatUnsupported({
+                code: "record-format-unsupported",
+                format: `unknown-family:${unsupported.name}`,
+            }));
+        }
+    });
+}
+function validateCurrentFamilyInventory(fileSystem, root) {
+    const runFamilies = new Set(runMigrationDescriptors.map((descriptor) => descriptor.family));
+    const attemptFamilies = new Set(attemptMigrationDescriptors.map((descriptor) => descriptor.family));
+    return effect_1.Effect.gen(function* () {
+        const runs = yield* fileSystem.listDirectory({
+            directory: (0, services_ts_1.recordPortablePath)(root, "runs"),
+            maximumEntries: MAXIMUM_RUN_ENTRIES,
+        });
+        for (const entry of runs) {
+            if (entry.kind !== "directory")
+                continue;
+            const runId = decodeRunId(entry.name);
+            if (runId === undefined || !(yield* isSealedRun(fileSystem, root, runId)))
+                continue;
+            yield* validateAttachmentDirectoryInventory({
+                fileSystem,
+                directory: (0, services_ts_1.recordPortablePath)(root, "runs", runId, "attachments"),
+                allowed: runFamilies,
+            });
+            const attemptsDirectory = (0, services_ts_1.recordPortablePath)(root, "runs", runId, "attempts");
+            if ((yield* fileSystem.pathKind(attemptsDirectory)) !== "directory")
+                continue;
+            const attempts = yield* fileSystem.listDirectory({
+                directory: attemptsDirectory,
+                maximumEntries: MAXIMUM_ATTEMPT_ENTRIES,
+            });
+            for (const attempt of attempts) {
+                if (attempt.kind !== "directory")
+                    continue;
+                const attemptId = decodeAttemptId(attempt.name);
+                if (attemptId === undefined)
+                    continue;
+                yield* validateAttachmentDirectoryInventory({
+                    fileSystem,
+                    directory: (0, services_ts_1.recordPortablePath)(root, "runs", runId, "attempts", attemptId, "attachments"),
+                    allowed: attemptFamilies,
+                });
+            }
+        }
+    });
+}
+function migrationAttachmentDirectory(root, location) {
+    return location.owner === "run"
+        ? (0, services_ts_1.recordPortablePath)(root, "runs", location.runId, "attachments", location.descriptor.family)
+        : (0, services_ts_1.recordPortablePath)(root, "runs", location.runId, "attempts", location.attemptId, "attachments", location.descriptor.family);
+}
+function migrationReaderLocation(location) {
+    return location.owner === "run"
+        ? Object.freeze({ owner: "run", runId: location.runId })
+        : Object.freeze({
+            owner: "attempt",
+            runId: location.runId,
+            attemptId: location.attemptId,
+        });
+}
+/**
+ * This traversal only addresses declared family directories. It deliberately
+ * never enumerates an attachment directory, so unknown families cannot enter
+ * the migration graph or be rewritten as a side effect.
+ */
+function knownMigrationAttachments(fileSystem, root) {
+    return effect_1.Effect.gen(function* () {
+        const locations = [];
+        const runs = yield* fileSystem.listDirectory({
+            directory: (0, services_ts_1.recordPortablePath)(root, "runs"),
+            maximumEntries: MAXIMUM_RUN_ENTRIES,
+        });
+        for (const entry of runs) {
+            if (entry.kind !== "directory")
+                continue;
+            const runId = decodeRunId(entry.name);
+            if (runId === undefined)
+                continue;
+            // Draft directories are not Runs and belong exclusively to `niceeval
+            // clean`; maintenance must preserve every byte beneath them.
+            if (!(yield* isSealedRun(fileSystem, root, runId)))
+                continue;
+            for (const descriptor of runMigrationDescriptors) {
+                const location = Object.freeze({
+                    owner: "run",
+                    runId,
+                    descriptor,
+                });
+                if ((yield* fileSystem.pathKind(migrationAttachmentDirectory(root, location))) !== "missing") {
+                    locations.push(location);
+                }
+            }
+            const attempts = yield* fileSystem.listDirectory({
+                directory: (0, services_ts_1.recordPortablePath)(root, "runs", runId, "attempts"),
+                maximumEntries: MAXIMUM_ATTEMPT_ENTRIES,
+            });
+            for (const attemptEntry of attempts) {
+                if (attemptEntry.kind !== "directory")
+                    continue;
+                const attemptId = decodeAttemptId(attemptEntry.name);
+                if (attemptId === undefined)
+                    continue;
+                for (const descriptor of attemptMigrationDescriptors) {
+                    const location = Object.freeze({
+                        owner: "attempt",
+                        runId,
+                        attemptId,
+                        descriptor,
+                    });
+                    if ((yield* fileSystem.pathKind(migrationAttachmentDirectory(root, location))) !== "missing") {
+                        locations.push(location);
+                    }
+                }
+            }
+        }
+        return Object.freeze(locations);
+    });
+}
+function readKnownMigrationAttachment(fileSystem, root, location) {
+    return (0, runtime_ts_1.readFixedRecordAttachment)({
+        fileSystem,
+        root,
+        location: migrationReaderLocation(location),
+        descriptor: location.descriptor,
+    });
+}
+function migrationInvalid(family) {
+    return new errors_ts_3.RecordMigrationInvalid({ code: "record-migration-invalid", family });
+}
+function migrationPlanStale() {
+    return new errors_ts_3.RecordMigrationPlanStale({ code: "record-migration-plan-stale" });
+}
+function migrationFailureCode(error) {
+    if (typeof error !== "object" || error === null)
+        return "record-command-failed";
+    const code = Reflect.get(error, "code");
+    return typeof code === "string" ? code : "record-command-failed";
+}
+function migrationTarget(location) {
+    return Object.freeze({
+        family: location.descriptor.family,
+        owner: location.owner,
+        runId: location.runId,
+        ...(location.attemptId === undefined ? {} : { attemptId: location.attemptId }),
+        fromSchemaVersion: 1,
+        toSchemaVersion: location.descriptor.schemaVersion,
+    });
+}
+const RECORD_MIGRATION_IMPLEMENTATION_ID = "niceeval.record/root-1-observability-1-to-root-2-observability-2/v1";
+const migrationPlanSources = new WeakMap();
+function bytesEqual(left, right) {
+    return left.byteLength === right.byteLength && left.every((byte, index) => byte === right[index]);
+}
+function migrationEnvelopePath(root, location) {
+    return (0, services_ts_1.recordPortablePath)(root, ...migrationAttachmentDirectory(root, location).segments, "attachment.json");
+}
+function sameMigrationPlan(left, right) {
+    if (left.state !== right.state || left.format !== right.format)
+        return false;
+    if (left.state !== "migration-required" || right.state !== "migration-required")
+        return true;
+    if (JSON.stringify(left.backup) !== JSON.stringify(right.backup))
+        return false;
+    if (JSON.stringify(left.root) !== JSON.stringify(right.root))
+        return false;
+    if (left.attachments.length !== right.attachments.length)
+        return false;
+    return left.attachments.every((target, index) => {
+        const candidate = right.attachments[index];
+        return candidate !== undefined &&
+            target.family === candidate.family &&
+            target.owner === candidate.owner &&
+            target.runId === candidate.runId &&
+            target.attemptId === candidate.attemptId &&
+            target.fromSchemaVersion === candidate.fromSchemaVersion &&
+            target.toSchemaVersion === candidate.toSchemaVersion;
+    });
+}
+function planAttachmentMigration(input) {
+    return effect_1.Effect.gen(function* () {
+        yield* validateCurrentFamilyInventory(input.fileSystem, input.root);
+        const targets = [];
+        const sources = [];
+        for (const location of yield* knownMigrationAttachments(input.fileSystem, input.root)) {
+            const read = yield* readKnownMigrationAttachment(input.fileSystem, input.root, location);
+            if (read.state === "available")
+                continue;
+            if (read.state === "migration-required" &&
+                location.descriptor.family === catalog_ts_1.NiceEvalRecordAttachments.observability.family &&
+                read.fromSchemaVersion === 1 &&
+                read.toSchemaVersion === 2) {
+                const target = migrationTarget(location);
+                const envelopeBytes = yield* input.fileSystem.readFile({
+                    file: migrationEnvelopePath(input.root, location),
+                    maximumBytes: limits_ts_1.RECORD_JSON_MAXIMUM_BYTES,
+                });
+                if (envelopeBytes === undefined) {
+                    return yield* effect_1.Effect.fail(migrationInvalid(location.descriptor.family));
+                }
+                targets.push(target);
+                sources.push(Object.freeze({ target, envelopeBytes }));
+                continue;
+            }
+            if (read.state === "unsupported") {
+                return yield* effect_1.Effect.fail(new errors_ts_3.RecordFormatUnsupported({
+                    code: "record-format-unsupported",
+                    format: `${read.family}@${read.schemaVersion}`,
+                }));
+            }
+            return yield* effect_1.Effect.fail(migrationInvalid(location.descriptor.family));
+        }
+        return Object.freeze({
+            targets: Object.freeze(targets),
+            sources: Object.freeze(sources),
+        });
+    });
+}
+function ensureOrdinaryCurrentAttachments(input) {
+    return planAttachmentMigration(input).pipe(effect_1.Effect.flatMap((plan) => plan.targets.length === 0
+        ? effect_1.Effect.void
+        : effect_1.Effect.fail(new errors_ts_3.RecordMigrationRequired({
+            code: "record-migration-required",
+            source: "niceeval.record attachment predecessor",
+            target: `${identifiers_ts_1.RECORD_FORMAT}@${identifiers_ts_1.RECORD_SCHEMA_VERSION}`,
+            command: "niceeval migrate",
+        }))), effect_1.Effect.mapError((error) => error instanceof errors_ts_3.RecordMigrationInvalid
+        ? bootstrapInvalid()
+        : error));
+}
+function migrationPlan(input) {
+    return effect_1.Effect.gen(function* () {
+        const format = yield* (0, format_ts_1.readRecordFormatForMaintenance)(input.fileSystem, input.root);
+        yield* validateSealedCoreForMigration(input.fileSystem, input.root, format.document);
+        const attachments = yield* planAttachmentMigration(input);
+        const rootMigration = format.sourceSchemaVersion === identifiers_ts_1.RECORD_SCHEMA_VERSION
+            ? null
+            : Object.freeze({
+                fromSchemaVersion: format.sourceSchemaVersion,
+                toSchemaVersion: identifiers_ts_1.RECORD_SCHEMA_VERSION,
+            });
+        if (rootMigration === null && attachments.targets.length === 0) {
+            return Object.freeze({ state: "already-current", format: identifiers_ts_1.RECORD_FORMAT });
+        }
+        const backup = yield* input.git.inspectBackupState(input.root);
+        const plan = Object.freeze({
+            state: "migration-required",
+            format: identifiers_ts_1.RECORD_FORMAT,
+            backup,
+            root: rootMigration,
+            attachments: attachments.targets,
+        });
+        migrationPlanSources.set(plan, Object.freeze({
+            attachments: attachments.sources,
+            rootBytes: rootMigration === null ? null : format.sourceBytes,
+            record: format.document,
+            implementationIdentity: RECORD_MIGRATION_IMPLEMENTATION_ID,
+        }));
+        return plan;
+    });
+}
+function validateSealedCoreForMigration(fileSystem, root, record) {
+    return effect_1.Effect.flatMap(loadSealedCoreSnapshot(maintenanceReaderRuntime(root, record), fileSystem), (snapshot) => snapshot.state === "available"
+        ? effect_1.Effect.void
+        : effect_1.Effect.fail(migrationInvalid("niceeval.core")));
+}
+function loadObservabilityV1Maintenance() {
+    const loader = catalog_ts_1.NiceEvalRecordAttachments.observability.maintenance;
+    if (loader === undefined)
+        return effect_1.Effect.fail(migrationInvalid(catalog_ts_1.NiceEvalRecordAttachments.observability.family));
+    return effect_1.Effect.tryPromise({
+        try: loader,
+        catch: () => migrationInvalid(catalog_ts_1.NiceEvalRecordAttachments.observability.family),
+    });
+}
+function migrateObservabilityAttachment(input) {
+    return effect_1.Effect.gen(function* () {
+        if (input.target.family !== catalog_ts_1.NiceEvalRecordAttachments.observability.family ||
+            input.target.fromSchemaVersion !== 1 ||
+            input.target.toSchemaVersion !== 2) {
+            return yield* effect_1.Effect.fail(migrationInvalid(input.target.family));
+        }
+        const descriptor = input.target.owner === "run"
+            ? migrationDescriptor(catalog_ts_1.NiceEvalRecordFamilyCatalog.observability.run)
+            : migrationDescriptor(catalog_ts_1.NiceEvalRecordFamilyCatalog.observability.attempt);
+        const location = input.target.owner === "run"
+            ? Object.freeze({ owner: "run", runId: input.target.runId, descriptor })
+            : Object.freeze({
+                owner: "attempt",
+                runId: input.target.runId,
+                attemptId: input.target.attemptId,
+                descriptor,
+            });
+        const facet = yield* loadObservabilityV1Maintenance();
+        const historical = facet.historicalCodecs.find((codec) => codec.schemaVersion === 1);
+        const step = facet.adjacentMigrations.find((migration) => migration.fromSchemaVersion === 1 && migration.toSchemaVersion === 2);
+        if (historical === undefined || step === undefined) {
+            return yield* effect_1.Effect.fail(migrationInvalid(input.target.family));
+        }
+        const envelopePath = migrationEnvelopePath(input.root, location);
+        const sourceBeforeValidation = yield* input.fileSystem.readFile({
+            file: envelopePath,
+            maximumBytes: limits_ts_1.RECORD_JSON_MAXIMUM_BYTES,
+        });
+        if (sourceBeforeValidation === undefined || !bytesEqual(sourceBeforeValidation, input.expectedEnvelopeBytes)) {
+            return yield* effect_1.Effect.fail(migrationPlanStale());
+        }
+        const valid = yield* (0, runtime_ts_1.validateFixedRecordAttachmentMigrationSource)({
+            fileSystem: input.fileSystem,
+            root: input.root,
+            location: migrationReaderLocation(location),
+            descriptor,
+            fromSchemaVersion: 1,
+            decodeHistorical: historical.decode,
+            migrate: step.migrate,
+        });
+        if (!valid) {
+            const sourceAfterInvalid = yield* input.fileSystem.readFile({
+                file: envelopePath,
+                maximumBytes: limits_ts_1.RECORD_JSON_MAXIMUM_BYTES,
+            });
+            if (sourceAfterInvalid === undefined || !bytesEqual(sourceAfterInvalid, input.expectedEnvelopeBytes)) {
+                return yield* effect_1.Effect.fail(migrationPlanStale());
+            }
+            return yield* effect_1.Effect.fail(migrationInvalid(input.target.family));
+        }
+        const envelope = (0, catalog_ts_1.encodeFixedRecordAttachmentEnvelope)({
+            family: catalog_ts_1.NiceEvalRecordAttachments.observability.family,
+            schemaVersion: 2,
+        });
+        if (effect_1.Either.isLeft(envelope))
+            return yield* effect_1.Effect.fail(migrationInvalid(input.target.family));
+        const sourceBeforeWrite = yield* input.fileSystem.readFile({
+            file: envelopePath,
+            maximumBytes: limits_ts_1.RECORD_JSON_MAXIMUM_BYTES,
+        });
+        if (sourceBeforeWrite === undefined || !bytesEqual(sourceBeforeWrite, input.expectedEnvelopeBytes)) {
+            return yield* effect_1.Effect.fail(migrationPlanStale());
+        }
+        yield* input.fileSystem.writeFile({
+            file: envelopePath,
+            bytes: jsonBytes(envelope.right),
+            maximumBytes: limits_ts_1.RECORD_JSON_MAXIMUM_BYTES,
+            mode: "replace-no-follow",
+        });
+    });
+}
+function validateCurrentKnownAttachments(input) {
+    return effect_1.Effect.gen(function* () {
+        for (const location of yield* knownMigrationAttachments(input.fileSystem, input.root)) {
+            const read = yield* readKnownMigrationAttachment(input.fileSystem, input.root, location);
+            if (read.state !== "available") {
+                return yield* effect_1.Effect.fail(migrationInvalid(location.descriptor.family));
+            }
+            const joined = yield* validateFixedCrossFamilyJoin({
+                fileSystem: input.fileSystem,
+                root: input.root,
+                runId: location.runId,
+                ...(location.attemptId === undefined ? {} : { attemptId: location.attemptId }),
+                descriptor: location.descriptor,
+                payload: read.value,
+            });
+            if (joined.state !== "joined") {
+                return yield* effect_1.Effect.fail(migrationInvalid(location.descriptor.family));
+            }
+        }
+    });
+}
+function migrationRecoveryIsSafe(input) {
+    return effect_1.Effect.gen(function* () {
+        const encoded = (0, catalog_ts_1.encodeFixedRecordAttachmentEnvelope)({
+            family: catalog_ts_1.NiceEvalRecordAttachments.observability.family,
+            schemaVersion: 2,
+        });
+        if (effect_1.Either.isLeft(encoded))
+            return false;
+        const currentEnvelopeBytes = jsonBytes(encoded.right);
+        const expectedPaths = [(0, services_ts_1.recordPortablePath)(input.root, "migration.in-progress")];
+        const currentRoot = yield* input.fileSystem.readFile({
+            file: (0, services_ts_1.recordPortablePath)(input.root, "record.json"),
+            maximumBytes: format_ts_1.RECORD_FORMAT_DOCUMENT_MAXIMUM_BYTES,
+        });
+        if (currentRoot !== undefined) {
+            const parsed = parseJson(currentRoot);
+            if (typeof parsed === "object" && parsed !== null &&
+                Reflect.get(parsed, "schemaVersion") === identifiers_ts_1.RECORD_SCHEMA_VERSION)
+                expectedPaths.push((0, services_ts_1.recordPortablePath)(input.root, "record.json"));
+        }
+        for (const location of yield* knownMigrationAttachments(input.fileSystem, input.root)) {
+            if (location.descriptor.family !== catalog_ts_1.NiceEvalRecordAttachments.observability.family)
+                continue;
+            const path = migrationEnvelopePath(input.root, location);
+            const bytes = yield* input.fileSystem.readFile({
+                file: path,
+                maximumBytes: limits_ts_1.RECORD_JSON_MAXIMUM_BYTES,
+            });
+            if (bytes !== undefined && bytesEqual(bytes, currentEnvelopeBytes))
+                expectedPaths.push(path);
+        }
+        return yield* input.git.recoveryChangesAreExpected({
+            root: input.root,
+            restoreCommit: input.restoreCommit,
+            expectedPaths,
+        });
+    }).pipe(effect_1.Effect.catchAll(() => effect_1.Effect.succeed(false)));
+}
 function openMaintenance(input) {
     return effect_1.Effect.gen(function* () {
         const coordination = yield* record_leases_ts_1.RecordCoordination;
         const fileSystem = yield* services_ts_1.RecordFileSystem;
+        const git = yield* services_ts_1.RecordGit;
         yield* coordination.enterRecordMaintenance(input.root);
         if (yield* fileSystem.migrationSentinelPresent(input.root)) {
-            return yield* effect_1.Effect.fail(migrationInterrupted());
+            const restoreCommit = yield* fileSystem.readMigrationSentinelRestoreCommit(input.root);
+            const restoreSafe = restoreCommit === undefined
+                ? false
+                : yield* migrationRecoveryIsSafe({ fileSystem, git, root: input.root, restoreCommit });
+            return yield* effect_1.Effect.fail(migrationInterrupted(restoreCommit, restoreSafe));
         }
         const inspect = () => currentFormatInspection(fileSystem, input.root);
+        const planMigrate = () => effect_1.Effect.gen(function* () {
+            const format = yield* (0, format_ts_1.readRecordFormatForMaintenance)(fileSystem, input.root);
+            yield* coordination.verifyRecordIdentity({ root: input.root, recordId: format.document.recordId });
+            return yield* migrationPlan({ fileSystem, root: input.root, git });
+        });
         return Object.freeze({
             inspect,
-            planMigrate: () => effect_1.Effect.map(inspect(), (inspection) => inspection.state === "already-current"
-                ? Object.freeze({ state: "already-current", format: inspection.format })
-                : Object.freeze({ state: "unsupported-format", format: inspection.format })),
-            applyMigrate: (plan) => plan.state === "already-current" && plan.format === identifiers_ts_1.RECORD_FORMAT
-                ? effect_1.Effect.succeed(Object.freeze({ state: "already-current", format: identifiers_ts_1.RECORD_FORMAT }))
-                : effect_1.Effect.fail(new errors_ts_3.RecordFormatUnsupported({
-                    code: "record-format-unsupported",
-                    format: plan.format,
-                })),
+            planMigrate,
+            applyMigrate: (plan) => effect_1.Effect.gen(function* () {
+                const currentPlan = yield* planMigrate();
+                if (!sameMigrationPlan(plan, currentPlan)) {
+                    return yield* effect_1.Effect.fail(migrationPlanStale());
+                }
+                if (currentPlan.state === "already-current") {
+                    return Object.freeze({ state: "already-current", format: identifiers_ts_1.RECORD_FORMAT });
+                }
+                if (currentPlan.state === "unsupported-format") {
+                    return yield* effect_1.Effect.fail(new errors_ts_3.RecordFormatUnsupported({
+                        code: "record-format-unsupported",
+                        format: currentPlan.format,
+                    }));
+                }
+                if (currentPlan.backup.state !== "git-restore-point") {
+                    return yield* effect_1.Effect.fail(new errors_ts_3.RecordMigrationGitRestoreRequired({
+                        code: "record-migration-git-restore-required",
+                    }));
+                }
+                const restoreCommit = currentPlan.backup.commit;
+                const plannedSources = migrationPlanSources.get(currentPlan);
+                if (plannedSources === undefined ||
+                    plannedSources.implementationIdentity !== RECORD_MIGRATION_IMPLEMENTATION_ID ||
+                    plannedSources.attachments.length !== currentPlan.attachments.length ||
+                    (currentPlan.root === null) !== (plannedSources.rootBytes === null)) {
+                    return yield* effect_1.Effect.fail(migrationInvalid(catalog_ts_1.NiceEvalRecordAttachments.observability.family));
+                }
+                let portableTargetWritten = false;
+                // The sentinel is the first portable write. Any later failure or
+                // interruption intentionally leaves it behind for Git recovery.
+                yield* fileSystem.createMigrationSentinel(input.root, restoreCommit);
+                const sentinelOnly = yield* git.recoveryChangesAreExpected({
+                    root: input.root,
+                    restoreCommit,
+                    expectedPaths: [(0, services_ts_1.recordPortablePath)(input.root, "migration.in-progress")],
+                });
+                if (!sentinelOnly) {
+                    yield* fileSystem.removeMigrationSentinel(input.root);
+                    return yield* effect_1.Effect.fail(migrationPlanStale());
+                }
+                yield* effect_1.Effect.gen(function* () {
+                    for (const source of plannedSources.attachments) {
+                        yield* migrateObservabilityAttachment({
+                            fileSystem,
+                            root: input.root,
+                            target: source.target,
+                            expectedEnvelopeBytes: source.envelopeBytes,
+                        });
+                        portableTargetWritten = true;
+                    }
+                    if (plannedSources.rootBytes !== null) {
+                        const rootPath = (0, services_ts_1.recordPortablePath)(input.root, "record.json");
+                        const sourceBeforeRootWrite = yield* fileSystem.readFile({
+                            file: rootPath,
+                            maximumBytes: format_ts_1.RECORD_FORMAT_DOCUMENT_MAXIMUM_BYTES,
+                        });
+                        if (sourceBeforeRootWrite === undefined ||
+                            !bytesEqual(sourceBeforeRootWrite, plannedSources.rootBytes))
+                            return yield* effect_1.Effect.fail(migrationPlanStale());
+                        const encodedRoot = (0, index_ts_1.encodeRecordDocument)(plannedSources.record);
+                        if (effect_1.Either.isLeft(encodedRoot))
+                            return yield* effect_1.Effect.fail(migrationInvalid("niceeval.core"));
+                        yield* fileSystem.writeFile({
+                            file: rootPath,
+                            bytes: jsonBytes(encodedRoot.right),
+                            maximumBytes: format_ts_1.RECORD_FORMAT_DOCUMENT_MAXIMUM_BYTES,
+                            mode: "replace-no-follow",
+                        });
+                        portableTargetWritten = true;
+                    }
+                    const current = yield* (0, format_ts_1.readCurrentRecordFormat)(fileSystem, input.root);
+                    yield* validateSealedCoreForMigration(fileSystem, input.root, current.document);
+                    yield* validateCurrentKnownAttachments({ fileSystem, root: input.root });
+                    yield* fileSystem.removeMigrationSentinel(input.root);
+                }).pipe(effect_1.Effect.catchAll((error) => {
+                    const recoveryRequired = () => effect_1.Effect.flatMap(migrationRecoveryIsSafe({ fileSystem, git, root: input.root, restoreCommit }), (restoreSafe) => effect_1.Effect.fail(new errors_ts_3.RecordMigrationRecoveryRequired({
+                        code: "record-migration-recovery-required",
+                        causeCode: migrationFailureCode(error),
+                        restoreCommit,
+                        restoreSafe,
+                    })));
+                    if (error instanceof errors_ts_3.RecordMigrationPlanStale && !portableTargetWritten) {
+                        return fileSystem.removeMigrationSentinel(input.root).pipe(effect_1.Effect.matchEffect({
+                            onFailure: () => recoveryRequired(),
+                            onSuccess: () => effect_1.Effect.fail(error),
+                        }));
+                    }
+                    return recoveryRequired();
+                }));
+                return Object.freeze({ state: "migrated", format: identifiers_ts_1.RECORD_FORMAT });
+            }),
         });
     });
 }