niceeval 0.13.1 → 0.13.2

package/dist/record/platform/services.d.cts

@@ -25,7 +25,7 @@ export interface RecordReadFileInput {
 export interface RecordReadFileStreamInput extends RecordReadFileInput {
     readonly chunkBytes?: number;
 }
-export type RecordFileWriteMode = "exclusive" | "replace";
+export type RecordFileWriteMode = "exclusive" | "replace" | "replace-no-follow";
 export interface RecordWriteFileInput {
     readonly file: RecordPortablePath;
     readonly bytes: Uint8Array;
@@ -69,8 +69,15 @@ export interface RecordFileSystemService {
         readonly root: RecordRoot;
         readonly runId: string;
     }) => Effect.Effect<void, RecordFileSystemError>;
+    /** True only for the zero-byte regular file created by `createCompleteMarker`. */
+    readonly isCompleteMarker: (input: {
+        readonly root: RecordRoot;
+        readonly runId: string;
+    }) => Effect.Effect<boolean, RecordFileSystemError>;
     readonly migrationSentinelPresent: (root: RecordRoot) => Effect.Effect<boolean, RecordFileSystemError>;
-    readonly createMigrationSentinel: (root: RecordRoot) => Effect.Effect<void, RecordFileSystemError>;
+    readonly createMigrationSentinel: (root: RecordRoot, restoreCommit: string) => Effect.Effect<void, RecordFileSystemError>;
+    /** Returns the bounded restore commit recorded by a current migration sentinel. */
+    readonly readMigrationSentinelRestoreCommit: (root: RecordRoot) => Effect.Effect<string | undefined, RecordFileSystemError>;
     readonly removeMigrationSentinel: (root: RecordRoot) => Effect.Effect<void, RecordFileSystemError>;
     /** The caller already owns the exclusive maintenance lease before deletion. */
     readonly deleteIncompleteRun: (input: {
@@ -105,6 +112,12 @@ export type RecordBackupState = {
 };
 export interface RecordGitService {
     readonly inspectBackupState: (root: RecordRoot) => Effect.Effect<RecordBackupState, RecordGitError>;
+    /** Proves HEAD is unchanged and every dirty path is an expected migration write. */
+    readonly recoveryChangesAreExpected: (input: {
+        readonly root: RecordRoot;
+        readonly restoreCommit: string;
+        readonly expectedPaths: readonly RecordPortablePath[];
+    }) => Effect.Effect<boolean, RecordGitError | RecordFileSystemError>;
 }
 declare const RecordGit_base: Context.TagClass<RecordGit, "@niceeval/record/RecordGit", RecordGitService>;
 export declare class RecordGit extends RecordGit_base {

package/dist/record/platform/services.d.mts

@@ -25,7 +25,7 @@ export interface RecordReadFileInput {
 export interface RecordReadFileStreamInput extends RecordReadFileInput {
     readonly chunkBytes?: number;
 }
-export type RecordFileWriteMode = "exclusive" | "replace";
+export type RecordFileWriteMode = "exclusive" | "replace" | "replace-no-follow";
 export interface RecordWriteFileInput {
     readonly file: RecordPortablePath;
     readonly bytes: Uint8Array;
@@ -69,8 +69,15 @@ export interface RecordFileSystemService {
         readonly root: RecordRoot;
         readonly runId: string;
     }) => Effect.Effect<void, RecordFileSystemError>;
+    /** True only for the zero-byte regular file created by `createCompleteMarker`. */
+    readonly isCompleteMarker: (input: {
+        readonly root: RecordRoot;
+        readonly runId: string;
+    }) => Effect.Effect<boolean, RecordFileSystemError>;
     readonly migrationSentinelPresent: (root: RecordRoot) => Effect.Effect<boolean, RecordFileSystemError>;
-    readonly createMigrationSentinel: (root: RecordRoot) => Effect.Effect<void, RecordFileSystemError>;
+    readonly createMigrationSentinel: (root: RecordRoot, restoreCommit: string) => Effect.Effect<void, RecordFileSystemError>;
+    /** Returns the bounded restore commit recorded by a current migration sentinel. */
+    readonly readMigrationSentinelRestoreCommit: (root: RecordRoot) => Effect.Effect<string | undefined, RecordFileSystemError>;
     readonly removeMigrationSentinel: (root: RecordRoot) => Effect.Effect<void, RecordFileSystemError>;
     /** The caller already owns the exclusive maintenance lease before deletion. */
     readonly deleteIncompleteRun: (input: {
@@ -105,6 +112,12 @@ export type RecordBackupState = {
 };
 export interface RecordGitService {
     readonly inspectBackupState: (root: RecordRoot) => Effect.Effect<RecordBackupState, RecordGitError>;
+    /** Proves HEAD is unchanged and every dirty path is an expected migration write. */
+    readonly recoveryChangesAreExpected: (input: {
+        readonly root: RecordRoot;
+        readonly restoreCommit: string;
+        readonly expectedPaths: readonly RecordPortablePath[];
+    }) => Effect.Effect<boolean, RecordGitError | RecordFileSystemError>;
 }
 declare const RecordGit_base: Context.TagClass<RecordGit, "@niceeval/record/RecordGit", RecordGitService>;
 export declare class RecordGit extends RecordGit_base {

package/dist/record/platform/services.d.ts

@@ -25,7 +25,7 @@ export interface RecordReadFileInput {
 export interface RecordReadFileStreamInput extends RecordReadFileInput {
     readonly chunkBytes?: number;
 }
-export type RecordFileWriteMode = "exclusive" | "replace";
+export type RecordFileWriteMode = "exclusive" | "replace" | "replace-no-follow";
 export interface RecordWriteFileInput {
     readonly file: RecordPortablePath;
     readonly bytes: Uint8Array;
@@ -69,8 +69,15 @@ export interface RecordFileSystemService {
         readonly root: RecordRoot;
         readonly runId: string;
     }) => Effect.Effect<void, RecordFileSystemError>;
+    /** True only for the zero-byte regular file created by `createCompleteMarker`. */
+    readonly isCompleteMarker: (input: {
+        readonly root: RecordRoot;
+        readonly runId: string;
+    }) => Effect.Effect<boolean, RecordFileSystemError>;
     readonly migrationSentinelPresent: (root: RecordRoot) => Effect.Effect<boolean, RecordFileSystemError>;
-    readonly createMigrationSentinel: (root: RecordRoot) => Effect.Effect<void, RecordFileSystemError>;
+    readonly createMigrationSentinel: (root: RecordRoot, restoreCommit: string) => Effect.Effect<void, RecordFileSystemError>;
+    /** Returns the bounded restore commit recorded by a current migration sentinel. */
+    readonly readMigrationSentinelRestoreCommit: (root: RecordRoot) => Effect.Effect<string | undefined, RecordFileSystemError>;
     readonly removeMigrationSentinel: (root: RecordRoot) => Effect.Effect<void, RecordFileSystemError>;
     /** The caller already owns the exclusive maintenance lease before deletion. */
     readonly deleteIncompleteRun: (input: {
@@ -105,6 +112,12 @@ export type RecordBackupState = {
 };
 export interface RecordGitService {
     readonly inspectBackupState: (root: RecordRoot) => Effect.Effect<RecordBackupState, RecordGitError>;
+    /** Proves HEAD is unchanged and every dirty path is an expected migration write. */
+    readonly recoveryChangesAreExpected: (input: {
+        readonly root: RecordRoot;
+        readonly restoreCommit: string;
+        readonly expectedPaths: readonly RecordPortablePath[];
+    }) => Effect.Effect<boolean, RecordGitError | RecordFileSystemError>;
 }
 declare const RecordGit_base: Context.TagClass<RecordGit, "@niceeval/record/RecordGit", RecordGitService>;
 export declare class RecordGit extends RecordGit_base {

package/dist/record/reader/errors.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RecordHandleInvalid = exports.RecordReaderClosed = exports.RecordMigrationInterruptedState = exports.RecordFormatUnsupported = exports.RecordMigrationRequired = exports.RecordBootstrapInvalid = void 0;
+exports.RecordHandleInvalid = exports.RecordReaderClosed = exports.RecordMigrationRecoveryRequired = exports.RecordMigrationInvalid = exports.RecordAutoMigrationGitSaveRequired = exports.RecordMigrationGitRestoreRequired = exports.RecordMigrationPlanStale = exports.RecordMigrationInterruptedState = exports.RecordFormatUnsupported = exports.RecordMigrationRequired = exports.RecordBootstrapInvalid = void 0;
 const effect_1 = require("effect");
 /** `record.json` could not be safely recognized as a usable Record root. */
 class RecordBootstrapInvalid extends effect_1.Schema.TaggedError("@niceeval/record/RecordBootstrapInvalid")("RecordBootstrapInvalid", {
@@ -28,9 +28,45 @@ exports.RecordFormatUnsupported = RecordFormatUnsupported;
 /** An existing sentinel means a migration was interrupted or cannot be proven complete. */
 class RecordMigrationInterruptedState extends effect_1.Schema.TaggedError("@niceeval/record/RecordMigrationInterruptedState")("RecordMigrationInterruptedState", {
     code: effect_1.Schema.Literal("record-migration-interrupted"),
+    restoreCommit: effect_1.Schema.optional(effect_1.Schema.String),
+    restoreSafe: effect_1.Schema.optional(effect_1.Schema.Boolean),
 }) {
 }
 exports.RecordMigrationInterruptedState = RecordMigrationInterruptedState;
+/** A previously shown migration plan no longer matches the leased Record. */
+class RecordMigrationPlanStale extends effect_1.Schema.TaggedError("@niceeval/record/RecordMigrationPlanStale")("RecordMigrationPlanStale", {
+    code: effect_1.Schema.Literal("record-migration-plan-stale"),
+}) {
+}
+exports.RecordMigrationPlanStale = RecordMigrationPlanStale;
+/** In-place migration is permitted only with a clean Git restore point. */
+class RecordMigrationGitRestoreRequired extends effect_1.Schema.TaggedError("@niceeval/record/RecordMigrationGitRestoreRequired")("RecordMigrationGitRestoreRequired", {
+    code: effect_1.Schema.Literal("record-migration-git-restore-required"),
+}) {
+}
+exports.RecordMigrationGitRestoreRequired = RecordMigrationGitRestoreRequired;
+/** Automatic migration requires every portable byte to be saved at clean HEAD. */
+class RecordAutoMigrationGitSaveRequired extends effect_1.Schema.TaggedError("@niceeval/record/RecordAutoMigrationGitSaveRequired")("RecordAutoMigrationGitSaveRequired", {
+    code: effect_1.Schema.Literal("record-auto-migration-git-save-required"),
+}) {
+}
+exports.RecordAutoMigrationGitSaveRequired = RecordAutoMigrationGitSaveRequired;
+/** A known historical attachment cannot be proven safe to advance in place. */
+class RecordMigrationInvalid extends effect_1.Schema.TaggedError("@niceeval/record/RecordMigrationInvalid")("RecordMigrationInvalid", {
+    code: effect_1.Schema.Literal("record-migration-invalid"),
+    family: effect_1.Schema.String,
+}) {
+}
+exports.RecordMigrationInvalid = RecordMigrationInvalid;
+/** The migration sentinel exists, so the Record must be restored before reuse. */
+class RecordMigrationRecoveryRequired extends effect_1.Schema.TaggedError("@niceeval/record/RecordMigrationRecoveryRequired")("RecordMigrationRecoveryRequired", {
+    code: effect_1.Schema.Literal("record-migration-recovery-required"),
+    causeCode: effect_1.Schema.String,
+    restoreCommit: effect_1.Schema.String,
+    restoreSafe: effect_1.Schema.Boolean,
+}) {
+}
+exports.RecordMigrationRecoveryRequired = RecordMigrationRecoveryRequired;
 /** A live frozen capability escaped its Effect Scope. */
 class RecordReaderClosed extends effect_1.Schema.TaggedError("@niceeval/record/RecordReaderClosed")("RecordReaderClosed", {
     code: effect_1.Schema.Literal("record-reader-closed"),

package/dist/record/reader/errors.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["errors.ts"],"names":[],"mappings":";;;AAAA,mCAAgC;AAGhC,4EAA4E;AAC5E,MAAa,sBAAuB,SAAQ,eAAM,CAAC,WAAW,CAAyB,yCAAyC,CAAC,CAAC,wBAAwB,EAAE;IACxJ,IAAI,EAAE,eAAM,CAAC,OAAO,CAAC,0BAA0B,CAAC;IAChD,MAAM,EAAE,eAAM,CAAC,OAAO,CAAC,yBAAyB,EAAE,uCAAuC,CAAC;CAC7F,CAAC;CACD;AAJD,wDAIC;AACD,2EAA2E;AAC3E,MAAa,uBAAwB,SAAQ,eAAM,CAAC,WAAW,CAA0B,0CAA0C,CAAC,CAAC,yBAAyB,EAAE;IAC5J,IAAI,EAAE,eAAM,CAAC,OAAO,CAAC,2BAA2B,CAAC;IACjD,MAAM,EAAE,eAAM,CAAC,MAAM;IACrB,MAAM,EAAE,eAAM,CAAC,MAAM;IACrB,OAAO,EAAE,eAAM,CAAC,OAAO,CAAC,kBAAkB,CAAC;CAC9C,CAAC;CACD;AAND,0DAMC;AACD,gFAAgF;AAChF,MAAa,uBAAwB,SAAQ,eAAM,CAAC,WAAW,CAA0B,0CAA0C,CAAC,CAAC,yBAAyB,EAAE;IAC5J,IAAI,EAAE,eAAM,CAAC,OAAO,CAAC,2BAA2B,CAAC;IACjD,MAAM,EAAE,eAAM,CAAC,MAAM;CACxB,CAAC;CACD;AAJD,0DAIC;AACD,2FAA2F;AAC3F,MAAa,+BAAgC,SAAQ,eAAM,CAAC,WAAW,CAAkC,kDAAkD,CAAC,CAAC,iCAAiC,EAAE;IAC5L,IAAI,EAAE,eAAM,CAAC,OAAO,CAAC,8BAA8B,CAAC;CACvD,CAAC;CACD;AAHD,0EAGC;AACD,yDAAyD;AACzD,MAAa,kBAAmB,SAAQ,eAAM,CAAC,WAAW,CAAqB,qCAAqC,CAAC,CAAC,oBAAoB,EAAE;IACxI,IAAI,EAAE,eAAM,CAAC,OAAO,CAAC,sBAAsB,CAAC;CAC/C,CAAC;CACD;AAHD,gDAGC;AACD,sFAAsF;AACtF,MAAa,mBAAoB,SAAQ,eAAM,CAAC,WAAW,CAAsB,sCAAsC,CAAC,CAAC,qBAAqB,EAAE;IAC5I,IAAI,EAAE,eAAM,CAAC,OAAO,CAAC,uBAAuB,CAAC;CAChD,CAAC;CACD;AAHD,kDAGC","sourcesContent":["import { Schema } from \"effect\";\nimport type { RecordCoordinationError } from \"../../coordination/record-leases.ts\";\nimport type { RecordFileSystemError, } from \"../platform/errors.ts\";\n/** `record.json` could not be safely recognized as a usable Record root. */\nexport class RecordBootstrapInvalid extends Schema.TaggedError<RecordBootstrapInvalid>(\"@niceeval/record/RecordBootstrapInvalid\")(\"RecordBootstrapInvalid\", {\n    code: Schema.Literal(\"record-bootstrap-invalid\"),\n    reason: Schema.Literal(\"record-document-invalid\", \"record-format-document-limit-exceeded\"),\n}) {\n}\n/** A known, older major is never opened through a compatibility reader. */\nexport class RecordMigrationRequired extends Schema.TaggedError<RecordMigrationRequired>(\"@niceeval/record/RecordMigrationRequired\")(\"RecordMigrationRequired\", {\n    code: Schema.Literal(\"record-migration-required\"),\n    source: Schema.String,\n    target: Schema.String,\n    command: Schema.Literal(\"niceeval migrate\"),\n}) {\n}\n/** Future, foreign, or malformed format identities are not migration inputs. */\nexport class RecordFormatUnsupported extends Schema.TaggedError<RecordFormatUnsupported>(\"@niceeval/record/RecordFormatUnsupported\")(\"RecordFormatUnsupported\", {\n    code: Schema.Literal(\"record-format-unsupported\"),\n    format: Schema.String,\n}) {\n}\n/** An existing sentinel means a migration was interrupted or cannot be proven complete. */\nexport class RecordMigrationInterruptedState extends Schema.TaggedError<RecordMigrationInterruptedState>(\"@niceeval/record/RecordMigrationInterruptedState\")(\"RecordMigrationInterruptedState\", {\n    code: Schema.Literal(\"record-migration-interrupted\"),\n}) {\n}\n/** A live frozen capability escaped its Effect Scope. */\nexport class RecordReaderClosed extends Schema.TaggedError<RecordReaderClosed>(\"@niceeval/record/RecordReaderClosed\")(\"RecordReaderClosed\", {\n    code: Schema.Literal(\"record-reader-closed\"),\n}) {\n}\n/** A forged, copied, cross-snapshot, or wrong-kind frozen capability was supplied. */\nexport class RecordHandleInvalid extends Schema.TaggedError<RecordHandleInvalid>(\"@niceeval/record/RecordHandleInvalid\")(\"RecordHandleInvalid\", {\n    code: Schema.Literal(\"record-handle-invalid\"),\n}) {\n}\nexport type RecordReaderOpenError = RecordCoordinationError | RecordBootstrapInvalid | RecordMigrationRequired | RecordFormatUnsupported | RecordMigrationInterruptedState;\nexport type RecordReaderReadError = RecordFileSystemError | RecordReaderClosed | RecordHandleInvalid;\n"]}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["errors.ts"],"names":[],"mappings":"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","sourcesContent":["import { Schema } from \"effect\";\nimport type { RecordCoordinationError } from \"../../coordination/record-leases.ts\";\nimport type { RecordFileSystemError, RecordGitError, } from \"../platform/errors.ts\";\n/** `record.json` could not be safely recognized as a usable Record root. */\nexport class RecordBootstrapInvalid extends Schema.TaggedError<RecordBootstrapInvalid>(\"@niceeval/record/RecordBootstrapInvalid\")(\"RecordBootstrapInvalid\", {\n    code: Schema.Literal(\"record-bootstrap-invalid\"),\n    reason: Schema.Literal(\"record-document-invalid\", \"record-format-document-limit-exceeded\"),\n}) {\n}\n/** A known, older major is never opened through a compatibility reader. */\nexport class RecordMigrationRequired extends Schema.TaggedError<RecordMigrationRequired>(\"@niceeval/record/RecordMigrationRequired\")(\"RecordMigrationRequired\", {\n    code: Schema.Literal(\"record-migration-required\"),\n    source: Schema.String,\n    target: Schema.String,\n    command: Schema.Literal(\"niceeval migrate\"),\n}) {\n}\n/** Future, foreign, or malformed format identities are not migration inputs. */\nexport class RecordFormatUnsupported extends Schema.TaggedError<RecordFormatUnsupported>(\"@niceeval/record/RecordFormatUnsupported\")(\"RecordFormatUnsupported\", {\n    code: Schema.Literal(\"record-format-unsupported\"),\n    format: Schema.String,\n}) {\n}\n/** An existing sentinel means a migration was interrupted or cannot be proven complete. */\nexport class RecordMigrationInterruptedState extends Schema.TaggedError<RecordMigrationInterruptedState>(\"@niceeval/record/RecordMigrationInterruptedState\")(\"RecordMigrationInterruptedState\", {\n    code: Schema.Literal(\"record-migration-interrupted\"),\n    restoreCommit: Schema.optional(Schema.String),\n    restoreSafe: Schema.optional(Schema.Boolean),\n}) {\n}\n/** A previously shown migration plan no longer matches the leased Record. */\nexport class RecordMigrationPlanStale extends Schema.TaggedError<RecordMigrationPlanStale>(\"@niceeval/record/RecordMigrationPlanStale\")(\"RecordMigrationPlanStale\", {\n    code: Schema.Literal(\"record-migration-plan-stale\"),\n}) {\n}\n/** In-place migration is permitted only with a clean Git restore point. */\nexport class RecordMigrationGitRestoreRequired extends Schema.TaggedError<RecordMigrationGitRestoreRequired>(\"@niceeval/record/RecordMigrationGitRestoreRequired\")(\"RecordMigrationGitRestoreRequired\", {\n    code: Schema.Literal(\"record-migration-git-restore-required\"),\n}) {\n}\n/** Automatic migration requires every portable byte to be saved at clean HEAD. */\nexport class RecordAutoMigrationGitSaveRequired extends Schema.TaggedError<RecordAutoMigrationGitSaveRequired>(\"@niceeval/record/RecordAutoMigrationGitSaveRequired\")(\"RecordAutoMigrationGitSaveRequired\", {\n    code: Schema.Literal(\"record-auto-migration-git-save-required\"),\n}) {\n}\n/** A known historical attachment cannot be proven safe to advance in place. */\nexport class RecordMigrationInvalid extends Schema.TaggedError<RecordMigrationInvalid>(\"@niceeval/record/RecordMigrationInvalid\")(\"RecordMigrationInvalid\", {\n    code: Schema.Literal(\"record-migration-invalid\"),\n    family: Schema.String,\n}) {\n}\n/** The migration sentinel exists, so the Record must be restored before reuse. */\nexport class RecordMigrationRecoveryRequired extends Schema.TaggedError<RecordMigrationRecoveryRequired>(\"@niceeval/record/RecordMigrationRecoveryRequired\")(\"RecordMigrationRecoveryRequired\", {\n    code: Schema.Literal(\"record-migration-recovery-required\"),\n    causeCode: Schema.String,\n    restoreCommit: Schema.String,\n    restoreSafe: Schema.Boolean,\n}) {\n}\n/** A live frozen capability escaped its Effect Scope. */\nexport class RecordReaderClosed extends Schema.TaggedError<RecordReaderClosed>(\"@niceeval/record/RecordReaderClosed\")(\"RecordReaderClosed\", {\n    code: Schema.Literal(\"record-reader-closed\"),\n}) {\n}\n/** A forged, copied, cross-snapshot, or wrong-kind frozen capability was supplied. */\nexport class RecordHandleInvalid extends Schema.TaggedError<RecordHandleInvalid>(\"@niceeval/record/RecordHandleInvalid\")(\"RecordHandleInvalid\", {\n    code: Schema.Literal(\"record-handle-invalid\"),\n}) {\n}\nexport type RecordReaderOpenError = RecordCoordinationError | RecordBootstrapInvalid | RecordMigrationRequired | RecordFormatUnsupported | RecordMigrationInterruptedState;\nexport type RecordMaintenanceOpenError = RecordReaderOpenError;\nexport type RecordMaintenanceError = RecordMaintenanceOpenError | RecordMigrationPlanStale | RecordMigrationGitRestoreRequired | RecordMigrationInvalid | RecordMigrationRecoveryRequired | RecordGitError;\nexport type RecordReaderReadError = RecordFileSystemError | RecordReaderClosed | RecordHandleInvalid;\n"]}

package/dist/record/reader/errors.d.cts

@@ -1,6 +1,6 @@
 import { Schema } from "effect";
 import type { RecordCoordinationError } from "../../coordination/record-leases.cjs";
-import type { RecordFileSystemError } from "../platform/errors.cjs";
+import type { RecordFileSystemError, RecordGitError } from "../platform/errors.cjs";
 declare const RecordBootstrapInvalid_base: Schema.TaggedErrorClass<RecordBootstrapInvalid, "RecordBootstrapInvalid", {
     readonly _tag: Schema.tag<"RecordBootstrapInvalid">;
 } & {
@@ -34,10 +34,56 @@ declare const RecordMigrationInterruptedState_base: Schema.TaggedErrorClass<Reco
     readonly _tag: Schema.tag<"RecordMigrationInterruptedState">;
 } & {
     code: Schema.Literal<["record-migration-interrupted"]>;
+    restoreCommit: Schema.optional<typeof Schema.String>;
+    restoreSafe: Schema.optional<typeof Schema.Boolean>;
 }>;
 /** An existing sentinel means a migration was interrupted or cannot be proven complete. */
 export declare class RecordMigrationInterruptedState extends RecordMigrationInterruptedState_base {
 }
+declare const RecordMigrationPlanStale_base: Schema.TaggedErrorClass<RecordMigrationPlanStale, "RecordMigrationPlanStale", {
+    readonly _tag: Schema.tag<"RecordMigrationPlanStale">;
+} & {
+    code: Schema.Literal<["record-migration-plan-stale"]>;
+}>;
+/** A previously shown migration plan no longer matches the leased Record. */
+export declare class RecordMigrationPlanStale extends RecordMigrationPlanStale_base {
+}
+declare const RecordMigrationGitRestoreRequired_base: Schema.TaggedErrorClass<RecordMigrationGitRestoreRequired, "RecordMigrationGitRestoreRequired", {
+    readonly _tag: Schema.tag<"RecordMigrationGitRestoreRequired">;
+} & {
+    code: Schema.Literal<["record-migration-git-restore-required"]>;
+}>;
+/** In-place migration is permitted only with a clean Git restore point. */
+export declare class RecordMigrationGitRestoreRequired extends RecordMigrationGitRestoreRequired_base {
+}
+declare const RecordAutoMigrationGitSaveRequired_base: Schema.TaggedErrorClass<RecordAutoMigrationGitSaveRequired, "RecordAutoMigrationGitSaveRequired", {
+    readonly _tag: Schema.tag<"RecordAutoMigrationGitSaveRequired">;
+} & {
+    code: Schema.Literal<["record-auto-migration-git-save-required"]>;
+}>;
+/** Automatic migration requires every portable byte to be saved at clean HEAD. */
+export declare class RecordAutoMigrationGitSaveRequired extends RecordAutoMigrationGitSaveRequired_base {
+}
+declare const RecordMigrationInvalid_base: Schema.TaggedErrorClass<RecordMigrationInvalid, "RecordMigrationInvalid", {
+    readonly _tag: Schema.tag<"RecordMigrationInvalid">;
+} & {
+    code: Schema.Literal<["record-migration-invalid"]>;
+    family: typeof Schema.String;
+}>;
+/** A known historical attachment cannot be proven safe to advance in place. */
+export declare class RecordMigrationInvalid extends RecordMigrationInvalid_base {
+}
+declare const RecordMigrationRecoveryRequired_base: Schema.TaggedErrorClass<RecordMigrationRecoveryRequired, "RecordMigrationRecoveryRequired", {
+    readonly _tag: Schema.tag<"RecordMigrationRecoveryRequired">;
+} & {
+    code: Schema.Literal<["record-migration-recovery-required"]>;
+    causeCode: typeof Schema.String;
+    restoreCommit: typeof Schema.String;
+    restoreSafe: typeof Schema.Boolean;
+}>;
+/** The migration sentinel exists, so the Record must be restored before reuse. */
+export declare class RecordMigrationRecoveryRequired extends RecordMigrationRecoveryRequired_base {
+}
 declare const RecordReaderClosed_base: Schema.TaggedErrorClass<RecordReaderClosed, "RecordReaderClosed", {
     readonly _tag: Schema.tag<"RecordReaderClosed">;
 } & {
@@ -55,5 +101,7 @@ declare const RecordHandleInvalid_base: Schema.TaggedErrorClass<RecordHandleInva
 export declare class RecordHandleInvalid extends RecordHandleInvalid_base {
 }
 export type RecordReaderOpenError = RecordCoordinationError | RecordBootstrapInvalid | RecordMigrationRequired | RecordFormatUnsupported | RecordMigrationInterruptedState;
+export type RecordMaintenanceOpenError = RecordReaderOpenError;
+export type RecordMaintenanceError = RecordMaintenanceOpenError | RecordMigrationPlanStale | RecordMigrationGitRestoreRequired | RecordMigrationInvalid | RecordMigrationRecoveryRequired | RecordGitError;
 export type RecordReaderReadError = RecordFileSystemError | RecordReaderClosed | RecordHandleInvalid;
 export {};

package/dist/record/reader/errors.d.mts

@@ -1,6 +1,6 @@
 import { Schema } from "effect";
 import type { RecordCoordinationError } from "../../coordination/record-leases.mjs";
-import type { RecordFileSystemError } from "../platform/errors.mjs";
+import type { RecordFileSystemError, RecordGitError } from "../platform/errors.mjs";
 declare const RecordBootstrapInvalid_base: Schema.TaggedErrorClass<RecordBootstrapInvalid, "RecordBootstrapInvalid", {
     readonly _tag: Schema.tag<"RecordBootstrapInvalid">;
 } & {
@@ -34,10 +34,56 @@ declare const RecordMigrationInterruptedState_base: Schema.TaggedErrorClass<Reco
     readonly _tag: Schema.tag<"RecordMigrationInterruptedState">;
 } & {
     code: Schema.Literal<["record-migration-interrupted"]>;
+    restoreCommit: Schema.optional<typeof Schema.String>;
+    restoreSafe: Schema.optional<typeof Schema.Boolean>;
 }>;
 /** An existing sentinel means a migration was interrupted or cannot be proven complete. */
 export declare class RecordMigrationInterruptedState extends RecordMigrationInterruptedState_base {
 }
+declare const RecordMigrationPlanStale_base: Schema.TaggedErrorClass<RecordMigrationPlanStale, "RecordMigrationPlanStale", {
+    readonly _tag: Schema.tag<"RecordMigrationPlanStale">;
+} & {
+    code: Schema.Literal<["record-migration-plan-stale"]>;
+}>;
+/** A previously shown migration plan no longer matches the leased Record. */
+export declare class RecordMigrationPlanStale extends RecordMigrationPlanStale_base {
+}
+declare const RecordMigrationGitRestoreRequired_base: Schema.TaggedErrorClass<RecordMigrationGitRestoreRequired, "RecordMigrationGitRestoreRequired", {
+    readonly _tag: Schema.tag<"RecordMigrationGitRestoreRequired">;
+} & {
+    code: Schema.Literal<["record-migration-git-restore-required"]>;
+}>;
+/** In-place migration is permitted only with a clean Git restore point. */
+export declare class RecordMigrationGitRestoreRequired extends RecordMigrationGitRestoreRequired_base {
+}
+declare const RecordAutoMigrationGitSaveRequired_base: Schema.TaggedErrorClass<RecordAutoMigrationGitSaveRequired, "RecordAutoMigrationGitSaveRequired", {
+    readonly _tag: Schema.tag<"RecordAutoMigrationGitSaveRequired">;
+} & {
+    code: Schema.Literal<["record-auto-migration-git-save-required"]>;
+}>;
+/** Automatic migration requires every portable byte to be saved at clean HEAD. */
+export declare class RecordAutoMigrationGitSaveRequired extends RecordAutoMigrationGitSaveRequired_base {
+}
+declare const RecordMigrationInvalid_base: Schema.TaggedErrorClass<RecordMigrationInvalid, "RecordMigrationInvalid", {
+    readonly _tag: Schema.tag<"RecordMigrationInvalid">;
+} & {
+    code: Schema.Literal<["record-migration-invalid"]>;
+    family: typeof Schema.String;
+}>;
+/** A known historical attachment cannot be proven safe to advance in place. */
+export declare class RecordMigrationInvalid extends RecordMigrationInvalid_base {
+}
+declare const RecordMigrationRecoveryRequired_base: Schema.TaggedErrorClass<RecordMigrationRecoveryRequired, "RecordMigrationRecoveryRequired", {
+    readonly _tag: Schema.tag<"RecordMigrationRecoveryRequired">;
+} & {
+    code: Schema.Literal<["record-migration-recovery-required"]>;
+    causeCode: typeof Schema.String;
+    restoreCommit: typeof Schema.String;
+    restoreSafe: typeof Schema.Boolean;
+}>;
+/** The migration sentinel exists, so the Record must be restored before reuse. */
+export declare class RecordMigrationRecoveryRequired extends RecordMigrationRecoveryRequired_base {
+}
 declare const RecordReaderClosed_base: Schema.TaggedErrorClass<RecordReaderClosed, "RecordReaderClosed", {
     readonly _tag: Schema.tag<"RecordReaderClosed">;
 } & {
@@ -55,5 +101,7 @@ declare const RecordHandleInvalid_base: Schema.TaggedErrorClass<RecordHandleInva
 export declare class RecordHandleInvalid extends RecordHandleInvalid_base {
 }
 export type RecordReaderOpenError = RecordCoordinationError | RecordBootstrapInvalid | RecordMigrationRequired | RecordFormatUnsupported | RecordMigrationInterruptedState;
+export type RecordMaintenanceOpenError = RecordReaderOpenError;
+export type RecordMaintenanceError = RecordMaintenanceOpenError | RecordMigrationPlanStale | RecordMigrationGitRestoreRequired | RecordMigrationInvalid | RecordMigrationRecoveryRequired | RecordGitError;
 export type RecordReaderReadError = RecordFileSystemError | RecordReaderClosed | RecordHandleInvalid;
 export {};

package/dist/record/reader/errors.d.ts

@@ -1,6 +1,6 @@
 import { Schema } from "effect";
 import type { RecordCoordinationError } from "../../coordination/record-leases.js";
-import type { RecordFileSystemError } from "../platform/errors.js";
+import type { RecordFileSystemError, RecordGitError } from "../platform/errors.js";
 declare const RecordBootstrapInvalid_base: Schema.TaggedErrorClass<RecordBootstrapInvalid, "RecordBootstrapInvalid", {
     readonly _tag: Schema.tag<"RecordBootstrapInvalid">;
 } & {
@@ -34,10 +34,56 @@ declare const RecordMigrationInterruptedState_base: Schema.TaggedErrorClass<Reco
     readonly _tag: Schema.tag<"RecordMigrationInterruptedState">;
 } & {
     code: Schema.Literal<["record-migration-interrupted"]>;
+    restoreCommit: Schema.optional<typeof Schema.String>;
+    restoreSafe: Schema.optional<typeof Schema.Boolean>;
 }>;
 /** An existing sentinel means a migration was interrupted or cannot be proven complete. */
 export declare class RecordMigrationInterruptedState extends RecordMigrationInterruptedState_base {
 }
+declare const RecordMigrationPlanStale_base: Schema.TaggedErrorClass<RecordMigrationPlanStale, "RecordMigrationPlanStale", {
+    readonly _tag: Schema.tag<"RecordMigrationPlanStale">;
+} & {
+    code: Schema.Literal<["record-migration-plan-stale"]>;
+}>;
+/** A previously shown migration plan no longer matches the leased Record. */
+export declare class RecordMigrationPlanStale extends RecordMigrationPlanStale_base {
+}
+declare const RecordMigrationGitRestoreRequired_base: Schema.TaggedErrorClass<RecordMigrationGitRestoreRequired, "RecordMigrationGitRestoreRequired", {
+    readonly _tag: Schema.tag<"RecordMigrationGitRestoreRequired">;
+} & {
+    code: Schema.Literal<["record-migration-git-restore-required"]>;
+}>;
+/** In-place migration is permitted only with a clean Git restore point. */
+export declare class RecordMigrationGitRestoreRequired extends RecordMigrationGitRestoreRequired_base {
+}
+declare const RecordAutoMigrationGitSaveRequired_base: Schema.TaggedErrorClass<RecordAutoMigrationGitSaveRequired, "RecordAutoMigrationGitSaveRequired", {
+    readonly _tag: Schema.tag<"RecordAutoMigrationGitSaveRequired">;
+} & {
+    code: Schema.Literal<["record-auto-migration-git-save-required"]>;
+}>;
+/** Automatic migration requires every portable byte to be saved at clean HEAD. */
+export declare class RecordAutoMigrationGitSaveRequired extends RecordAutoMigrationGitSaveRequired_base {
+}
+declare const RecordMigrationInvalid_base: Schema.TaggedErrorClass<RecordMigrationInvalid, "RecordMigrationInvalid", {
+    readonly _tag: Schema.tag<"RecordMigrationInvalid">;
+} & {
+    code: Schema.Literal<["record-migration-invalid"]>;
+    family: typeof Schema.String;
+}>;
+/** A known historical attachment cannot be proven safe to advance in place. */
+export declare class RecordMigrationInvalid extends RecordMigrationInvalid_base {
+}
+declare const RecordMigrationRecoveryRequired_base: Schema.TaggedErrorClass<RecordMigrationRecoveryRequired, "RecordMigrationRecoveryRequired", {
+    readonly _tag: Schema.tag<"RecordMigrationRecoveryRequired">;
+} & {
+    code: Schema.Literal<["record-migration-recovery-required"]>;
+    causeCode: typeof Schema.String;
+    restoreCommit: typeof Schema.String;
+    restoreSafe: typeof Schema.Boolean;
+}>;
+/** The migration sentinel exists, so the Record must be restored before reuse. */
+export declare class RecordMigrationRecoveryRequired extends RecordMigrationRecoveryRequired_base {
+}
 declare const RecordReaderClosed_base: Schema.TaggedErrorClass<RecordReaderClosed, "RecordReaderClosed", {
     readonly _tag: Schema.tag<"RecordReaderClosed">;
 } & {
@@ -55,5 +101,7 @@ declare const RecordHandleInvalid_base: Schema.TaggedErrorClass<RecordHandleInva
 export declare class RecordHandleInvalid extends RecordHandleInvalid_base {
 }
 export type RecordReaderOpenError = RecordCoordinationError | RecordBootstrapInvalid | RecordMigrationRequired | RecordFormatUnsupported | RecordMigrationInterruptedState;
+export type RecordMaintenanceOpenError = RecordReaderOpenError;
+export type RecordMaintenanceError = RecordMaintenanceOpenError | RecordMigrationPlanStale | RecordMigrationGitRestoreRequired | RecordMigrationInvalid | RecordMigrationRecoveryRequired | RecordGitError;
 export type RecordReaderReadError = RecordFileSystemError | RecordReaderClosed | RecordHandleInvalid;
 export {};

package/dist/record/reader/errors.js

@@ -1,16 +1,26 @@
 import { createRequire as __niceevalCreateRequire } from "node:module";
 const __niceevalRequire = __niceevalCreateRequire(import.meta.url);
 const __niceevalCanonical = __niceevalRequire("./errors.cjs");
-const __niceevalExport0 = __niceevalCanonical["RecordBootstrapInvalid"];
-export { __niceevalExport0 as RecordBootstrapInvalid };
-const __niceevalExport1 = __niceevalCanonical["RecordFormatUnsupported"];
-export { __niceevalExport1 as RecordFormatUnsupported };
-const __niceevalExport2 = __niceevalCanonical["RecordHandleInvalid"];
-export { __niceevalExport2 as RecordHandleInvalid };
-const __niceevalExport3 = __niceevalCanonical["RecordMigrationInterruptedState"];
-export { __niceevalExport3 as RecordMigrationInterruptedState };
-const __niceevalExport4 = __niceevalCanonical["RecordMigrationRequired"];
-export { __niceevalExport4 as RecordMigrationRequired };
-const __niceevalExport5 = __niceevalCanonical["RecordReaderClosed"];
-export { __niceevalExport5 as RecordReaderClosed };
+const __niceevalExport0 = __niceevalCanonical["RecordAutoMigrationGitSaveRequired"];
+export { __niceevalExport0 as RecordAutoMigrationGitSaveRequired };
+const __niceevalExport1 = __niceevalCanonical["RecordBootstrapInvalid"];
+export { __niceevalExport1 as RecordBootstrapInvalid };
+const __niceevalExport2 = __niceevalCanonical["RecordFormatUnsupported"];
+export { __niceevalExport2 as RecordFormatUnsupported };
+const __niceevalExport3 = __niceevalCanonical["RecordHandleInvalid"];
+export { __niceevalExport3 as RecordHandleInvalid };
+const __niceevalExport4 = __niceevalCanonical["RecordMigrationGitRestoreRequired"];
+export { __niceevalExport4 as RecordMigrationGitRestoreRequired };
+const __niceevalExport5 = __niceevalCanonical["RecordMigrationInterruptedState"];
+export { __niceevalExport5 as RecordMigrationInterruptedState };
+const __niceevalExport6 = __niceevalCanonical["RecordMigrationInvalid"];
+export { __niceevalExport6 as RecordMigrationInvalid };
+const __niceevalExport7 = __niceevalCanonical["RecordMigrationPlanStale"];
+export { __niceevalExport7 as RecordMigrationPlanStale };
+const __niceevalExport8 = __niceevalCanonical["RecordMigrationRecoveryRequired"];
+export { __niceevalExport8 as RecordMigrationRecoveryRequired };
+const __niceevalExport9 = __niceevalCanonical["RecordMigrationRequired"];
+export { __niceevalExport9 as RecordMigrationRequired };
+const __niceevalExport10 = __niceevalCanonical["RecordReaderClosed"];
+export { __niceevalExport10 as RecordReaderClosed };
 //# sourceMappingURL=errors.js.map

package/dist/record/reader/format.cjs

@@ -2,9 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RECORD_FORMAT_DOCUMENT_MAXIMUM_BYTES = void 0;
 exports.readCurrentRecordFormat = readCurrentRecordFormat;
+exports.readRecordFormatForMaintenance = readRecordFormatForMaintenance;
 const effect_1 = require("effect");
 const core_ts_1 = require("../codec/core.cjs");
-const identifiers_ts_1 = require("../model/identifiers.cjs");
+const identifiers_ts_1 = require("../codec/identifiers.cjs");
+const identifiers_ts_2 = require("../model/identifiers.cjs");
 const services_ts_1 = require("../platform/services.cjs");
 const errors_ts_1 = require("./errors.cjs");
 /** `record.json` contains only root identity, so its read has a hard small cap. */
@@ -43,15 +45,19 @@ function classifyRecordDocument(value) {
     const format = formatOf(value);
     if (format === undefined)
         return effect_1.Either.left(bootstrapInvalid("record-document-invalid"));
-    if (format !== identifiers_ts_1.RECORD_FORMAT) {
+    if (format !== identifiers_ts_2.RECORD_FORMAT) {
         return effect_1.Either.left(new errors_ts_1.RecordFormatUnsupported({ code: "record-format-unsupported", format }));
     }
-    // A same-format numeric header is not automatically a reverse migration.
-    // This package currently declares no adjacent root chain, so both a future
-    // root and a hypothetical older root are unsupported rather than a fake
-    // `N -> current` migration-required result.
     const schemaVersion = schemaVersionOf(value);
-    if (schemaVersion !== undefined && schemaVersion !== identifiers_ts_1.RECORD_SCHEMA_VERSION) {
+    if (schemaVersion === 1) {
+        return effect_1.Either.left(new errors_ts_1.RecordMigrationRequired({
+            code: "record-migration-required",
+            source: `${identifiers_ts_2.RECORD_FORMAT}@1`,
+            target: `${identifiers_ts_2.RECORD_FORMAT}@${identifiers_ts_2.RECORD_SCHEMA_VERSION}`,
+            command: "niceeval migrate",
+        }));
+    }
+    if (schemaVersion !== identifiers_ts_2.RECORD_SCHEMA_VERSION) {
         return effect_1.Either.left(new errors_ts_1.RecordFormatUnsupported({ code: "record-format-unsupported", format }));
     }
     const decoded = (0, core_ts_1.decodeRecordDocument)(value);
@@ -59,23 +65,76 @@ function classifyRecordDocument(value) {
         ? effect_1.Either.left(bootstrapInvalid("record-document-invalid"))
         : effect_1.Either.right(Object.freeze({ document: decoded.right }));
 }
-/**
- * Reads only the bounded current root header. Migration-required is emitted
- * only by an actually declared adjacent chain; this current root has none.
- */
-function readCurrentRecordFormat(fileSystem, root) {
-    const readDocument = fileSystem.readFile({
+function legacyRecordDocument(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const record = value;
+    if (Object.keys(record).length !== 3 ||
+        record.format !== identifiers_ts_2.RECORD_FORMAT ||
+        record.schemaVersion !== 1)
+        return undefined;
+    const recordId = effect_1.Schema.decodeUnknownEither(identifiers_ts_1.RecordIdSchema, core_ts_1.RecordExactParseOptions)(record.recordId);
+    return effect_1.Either.isLeft(recordId) ? undefined : Object.freeze({
+        format: identifiers_ts_2.RECORD_FORMAT,
+        schemaVersion: identifiers_ts_2.RECORD_SCHEMA_VERSION,
+        recordId: recordId.right,
+    });
+}
+function readFormatBytes(fileSystem, root) {
+    return fileSystem.readFile({
         file: (0, services_ts_1.recordPortablePath)(root, "record.json"),
         maximumBytes: exports.RECORD_FORMAT_DOCUMENT_MAXIMUM_BYTES,
     }).pipe(effect_1.Effect.catchTag("RecordResourceLimitExceeded", () => effect_1.Effect.fail(bootstrapInvalid("record-format-document-limit-exceeded"))));
-    return effect_1.Effect.flatMap(readDocument, (bytes) => {
+}
+/**
+ * Reads only the bounded exact-current root header. The one published
+ * predecessor is reported as migration-required but is never decoded as current.
+ */
+function readCurrentRecordFormat(fileSystem, root) {
+    return effect_1.Effect.gen(function* () {
+        const bytes = yield* readFormatBytes(fileSystem, root);
         if (bytes === undefined)
-            return effect_1.Effect.fail(bootstrapInvalid("record-document-invalid"));
+            return yield* effect_1.Effect.fail(bootstrapInvalid("record-document-invalid"));
         const parsed = parseRecordJson(bytes);
         if (effect_1.Either.isLeft(parsed))
-            return effect_1.Effect.fail(parsed.left);
+            return yield* effect_1.Effect.fail(parsed.left);
         const classified = classifyRecordDocument(parsed.right);
-        return effect_1.Either.isLeft(classified) ? effect_1.Effect.fail(classified.left) : effect_1.Effect.succeed(classified.right);
+        if (effect_1.Either.isLeft(classified))
+            return yield* effect_1.Effect.fail(classified.left);
+        return classified.right;
+    });
+}
+/** Maintenance-only exact recognition of the one published root predecessor. */
+function readRecordFormatForMaintenance(fileSystem, root) {
+    return effect_1.Effect.gen(function* () {
+        const bytes = yield* readFormatBytes(fileSystem, root);
+        if (bytes === undefined)
+            return yield* effect_1.Effect.fail(bootstrapInvalid("record-document-invalid"));
+        const parsed = parseRecordJson(bytes);
+        if (effect_1.Either.isLeft(parsed))
+            return yield* effect_1.Effect.fail(parsed.left);
+        const version = schemaVersionOf(parsed.right);
+        if (version === identifiers_ts_2.RECORD_SCHEMA_VERSION) {
+            const decoded = (0, core_ts_1.decodeRecordDocument)(parsed.right);
+            if (effect_1.Either.isLeft(decoded))
+                return yield* effect_1.Effect.fail(bootstrapInvalid("record-document-invalid"));
+            return Object.freeze({
+                document: decoded.right,
+                sourceSchemaVersion: identifiers_ts_2.RECORD_SCHEMA_VERSION,
+                sourceBytes: bytes,
+            });
+        }
+        if (version === 1) {
+            const document = legacyRecordDocument(parsed.right);
+            if (document === undefined)
+                return yield* effect_1.Effect.fail(bootstrapInvalid("record-document-invalid"));
+            return Object.freeze({ document, sourceSchemaVersion: 1, sourceBytes: bytes });
+        }
+        const format = formatOf(parsed.right);
+        return yield* effect_1.Effect.fail(new errors_ts_1.RecordFormatUnsupported({
+            code: "record-format-unsupported",
+            format: format ?? "unknown",
+        }));
     });
 }
 //# sourceMappingURL=format.cjs.map