@khorsheed/dsh-ankh-guard 0.1.1 → 0.3.0

package/lib/types/transition.d.ts

@@ -0,0 +1,118 @@
+/** One reversible filesystem operation approved before a cutover. */
+export interface TransitionOperation {
+    kind: 'quarantine';
+    /** Path relative to the shared previous/target dsh home. */
+    path: string;
+    /** State that both isolated preflight and live apply must observe. */
+    expect: 'present' | 'absent';
+}
+/** Caller-authored transition plan. Unknown operation kinds fail closed. */
+export interface TransitionPlan {
+    schemaVersion: 1;
+    /** Canonical dsh home containing every operation path. */
+    home: string;
+    operations: TransitionOperation[];
+}
+/** Immutable reference carried by the durable launch state and receipt. */
+export interface TransitionReference {
+    version: 1;
+    planPath: string;
+    planSha256: string;
+    operationCount: number;
+}
+type ApplyState = 'pending' | 'moving' | 'absent' | 'quarantined';
+type RollbackState = 'pending' | 'moving-target' | 'target-retained' | 'target-absent' | 'restoring' | 'restored';
+export type TransitionPhase = 'prepared' | 'applying' | 'applied' | 'rolling-back' | 'rolled-back' | 'failed';
+interface TransitionEntryState {
+    path: string;
+    original: 'present' | 'absent';
+    apply: ApplyState;
+    rollback: RollbackState;
+}
+/** Crash-recovery journal for one transition. */
+export interface TransitionRecord {
+    version: 1;
+    cutoverId: string;
+    planSha256: string;
+    phase: TransitionPhase;
+    entries: TransitionEntryState[];
+    updatedAt: number;
+    failure?: {
+        operation: 'apply' | 'rollback';
+        detail: string;
+    };
+}
+/** Result returned after an idempotent transition operation. */
+export interface TransitionResult {
+    phase: 'applied' | 'rolled-back';
+    changed: string[];
+    unchanged: string[];
+}
+/**
+ * Validate and normalize an untrusted transition plan.
+ * @param raw - Parsed JSON plan.
+ * @param expectedHome - Home shared by the previous and target launch specs.
+ * @param stateDir - Guard state directory, which no operation may move.
+ * @returns A canonical plan safe for durable preparation.
+ */
+export declare function validateTransitionPlan(raw: unknown, expectedHome: string, stateDir?: string): TransitionPlan;
+/**
+ * Persist the immutable plan and an empty crash-recovery journal before the previous host stops.
+ * @param raw - Validated or untrusted plan JSON.
+ * @param expectedHome - Shared launch home.
+ * @param stateDir - Guard state directory.
+ * @param cutoverId - Unique launch cutover identifier.
+ * @returns Reference stored in the launch state and redacted receipt.
+ */
+export declare function prepareTransition(raw: unknown, expectedHome: string, stateDir: string, cutoverId: string): TransitionReference;
+/**
+ * Apply a prepared transition after the previous host has stopped.
+ * @param reference - Immutable reference from the launch state.
+ * @param expectedHome - Shared launch home.
+ * @param stateDir - Guard state directory.
+ * @param cutoverId - Active cutover identifier.
+ * @returns Idempotent apply result.
+ */
+export declare function applyTransition(reference: TransitionReference, expectedHome: string, stateDir: string, cutoverId: string): TransitionResult;
+/**
+ * Roll back an applied or partially applied transition before previous starts.
+ * Target-created replacements are retained for diagnosis rather than deleted.
+ * @param reference - Immutable reference from the launch state.
+ * @param expectedHome - Shared launch home.
+ * @param stateDir - Guard state directory.
+ * @param cutoverId - Active cutover identifier.
+ * @returns Idempotent rollback result.
+ */
+export declare function rollbackTransition(reference: TransitionReference, expectedHome: string, stateDir: string, cutoverId: string): TransitionResult;
+/**
+ * Read and verify a transition record through its immutable reference.
+ * @param reference - Reference stored in launch state.
+ * @param expectedHome - Shared launch home.
+ * @param stateDir - Guard state directory.
+ * @param cutoverId - Cutover identifier.
+ * @returns Verified crash-recovery journal.
+ */
+export declare function readTransitionRecord(reference: TransitionReference, expectedHome: string, stateDir: string, cutoverId: string): TransitionRecord;
+/**
+ * Clone a live home while retaining a contained package-link graph. Internal
+ * links are rebuilt against copied nodes; external targets are deduplicated in
+ * a snapshot-owned materialization area. No retained link resolves outside the
+ * snapshot root, so writes through pnpm/Cordis links cannot reach live bytes.
+ * Runtime entries without copyable content (sockets, FIFOs — and links to
+ * them) are skipped and counted, never copied; the top-level scratch/ tree is
+ * excluded for size. Device nodes still fail closed.
+ * @param sourceHome - Live dsh home to read.
+ * @returns Isolated home, an idempotent cleanup callback, and the count of skipped runtime entries.
+ */
+export declare function createPreflightSnapshot(sourceHome: string): {
+    home: string;
+    root: string;
+    skippedRuntimeEntries: number;
+    cleanup(): void;
+};
+export declare function createTransitionPreflightSnapshot(plan: TransitionPlan): {
+    home: string;
+    cleanup(): void;
+};
+export {};
+//# sourceMappingURL=transition.d.ts.map