@skillcap/gdh 0.23.0 → 0.25.0

package/node_modules/@gdh/adapters/dist/deferred-actions-advisory.js

@@ -0,0 +1,89 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { readMigrationState, runDeferredActionProbe, } from "@gdh/core";
+import { BACKUP_STAGING_RELATIVE_PATH, readBackupManifest, } from "./durable-backup.js";
+/**
+ * Read `migration.json`, run the probe per deferred action, and decide whether
+ * to emit the backup-cleanup advisory.
+ *
+ * Threat mitigations:
+ * - T-72-05-03 (TOCTOU): re-reads migration.json AND backup state freshly
+ *   inside this function; no cached probe results are consumed across calls.
+ * - T-72-05-04 (malformed migration.json): `readMigrationState` returns null
+ *   on parse/shape failure → `deferredActions` is `[]` and the advisory is
+ *   gated through the standard truth table.
+ * - T-72-05-06 (stale probe → clean): the gate requires `status === "clean"`
+ *   for every probe; `stale` and `pending` both block the advisory.
+ * - T-72-05-07 (interrupted migration): staging-dir check forces the advisory
+ *   to null whenever `.gdh-state/backup.new/` exists.
+ *
+ * Defaults: `adapters.hostHarnessIntrospect = null` and `adapters.processProbe
+ * = null` (every probe degrades to `pending`, so the advisory does not spuriously
+ * fire when a host cannot evaluate the deferred conditions).
+ */
+export async function computeDeferredActionsAdvisory(targetPath, adapters) {
+    const hostHarnessIntrospect = adapters?.hostHarnessIntrospect ?? null;
+    const processProbe = adapters?.processProbe ?? null;
+    const migrationState = await readMigrationState(targetPath);
+    const probedActions = [];
+    for (const action of migrationState?.deferred_actions ?? []) {
+        const result = await runDeferredActionProbe(action, {
+            targetPath,
+            hostHarnessIntrospect,
+            processProbe,
+        });
+        const entry = result.reason !== undefined
+            ? {
+                id: action.id,
+                description: action.description,
+                status: result.status,
+                reason: result.reason,
+            }
+            : {
+                id: action.id,
+                description: action.description,
+                status: result.status,
+            };
+        probedActions.push(entry);
+    }
+    // Phase 73 D-12 — envelope-pending fourth gate. The marker is the in-flight
+    // resume substrate (D-11); clearing the durable backup while a chain is
+    // paused mid-bump destroys the rollback substrate. The two advisories are
+    // mutually exclusive: when the envelope marker is set, the backup advisory
+    // MUST be null, regardless of whether the other backup-cleanup gates pass.
+    const pendingEnvelope = migrationState?.pending_envelope_resume ?? null;
+    const noEnvelopePending = pendingEnvelope === null;
+    // Gate evaluation (advisory truth table):
+    //  (a) every probed action is clean (zero is trivially true)
+    //  (b) `.gdh-state/backup/` is present (manifest readable)
+    //  (c) `.gdh-state/backup.new/` is NOT present (no interrupted migration)
+    //  (d) Phase 73 D-12: no envelope is pending (mutually exclusive with
+    //      envelopeAdvisory)
+    const allClean = probedActions.every((a) => a.status === "clean");
+    const manifest = await readBackupManifest(targetPath);
+    const backupExists = manifest !== null;
+    const stagingPath = path.join(targetPath, BACKUP_STAGING_RELATIVE_PATH);
+    const stagingExists = await fs
+        .stat(stagingPath)
+        .then(() => true)
+        .catch(() => false);
+    const noMigrationInProgress = !stagingExists;
+    const backupAdvisory = allClean && backupExists && noMigrationInProgress && noEnvelopePending
+        ? {
+            command: "gdh migration clear-backups",
+            reason: "all_deferred_actions_clean",
+            from_pin: manifest.from_pin,
+            to_pin: manifest.to_pin,
+        }
+        : null;
+    const envelopeAdvisory = pendingEnvelope !== null
+        ? {
+            envelope_ref: pendingEnvelope.envelope_ref,
+            from_pin: pendingEnvelope.from_pin,
+            to_pin: pendingEnvelope.to_pin,
+            command: `gdh migration record-envelope-result ${pendingEnvelope.envelope_ref} --result-file <path>`,
+        }
+        : null;
+    return { deferredActions: probedActions, backupAdvisory, envelopeAdvisory };
+}
+//# sourceMappingURL=deferred-actions-advisory.js.map

package/node_modules/@gdh/adapters/dist/deferred-actions-advisory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferred-actions-advisory.js","sourceRoot":"","sources":["../src/deferred-actions-advisory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EACL,kBAAkB,EAClB,sBAAsB,GAKvB,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,4BAA4B,EAC5B,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAuD7B;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,8BAA8B,CAClD,UAAkB,EAClB,QAAiC;IAEjC,MAAM,qBAAqB,GACzB,QAAQ,EAAE,qBAAqB,IAAI,IAAI,CAAC;IAC1C,MAAM,YAAY,GAA2B,QAAQ,EAAE,YAAY,IAAI,IAAI,CAAC;IAE5E,MAAM,cAAc,GAAG,MAAM,kBAAkB,CAAC,UAAU,CAAC,CAAC;IAE5D,MAAM,aAAa,GAAmC,EAAE,CAAC;IACzD,KAAK,MAAM,MAAM,IAAI,cAAc,EAAE,gBAAgB,IAAI,EAAE,EAAE,CAAC;QAC5D,MAAM,MAAM,GAAG,MAAM,sBAAsB,CAAC,MAAM,EAAE;YAClD,UAAU;YACV,qBAAqB;YACrB,YAAY;SACb,CAAC,CAAC;QACH,MAAM,KAAK,GAAiC,MAAM,CAAC,MAAM,KAAK,SAAS;YACrE,CAAC,CAAC;gBACE,EAAE,EAAE,MAAM,CAAC,EAAE;gBACb,WAAW,EAAE,MAAM,CAAC,WAAW;gBAC/B,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,MAAM,EAAE,MAAM,CAAC,MAAM;aACtB;YACH,CAAC,CAAC;gBACE,EAAE,EAAE,MAAM,CAAC,EAAE;gBACb,WAAW,EAAE,MAAM,CAAC,WAAW;gBAC/B,MAAM,EAAE,MAAM,CAAC,MAAM;aACtB,CAAC;QACN,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IAED,4EAA4E;IAC5E,wEAAwE;IACxE,0EAA0E;IAC1E,2EAA2E;IAC3E,2EAA2E;IAC3E,MAAM,eAAe,GAAG,cAAc,EAAE,uBAAuB,IAAI,IAAI,CAAC;IACxE,MAAM,iBAAiB,GAAG,eAAe,KAAK,IAAI,CAAC;IAEnD,0CAA0C;IAC1C,6DAA6D;IAC7D,2DAA2D;IAC3D,0EAA0E;IAC1E,sEAAsE;IACtE,yBAAyB;IACzB,MAAM,QAAQ,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,OAAO,CAAC,CAAC;IAClE,MAAM,QAAQ,GAAG,MAAM,kBAAkB,CAAC,UAAU,CAAC,CAAC;IACtD,MAAM,YAAY,GAAG,QAAQ,KAAK,IAAI,CAAC;IACvC,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,4BAA4B,CAAC,CAAC;IACxE,MAAM,aAAa,GAAG,MAAM,EAAE;SAC3B,IAAI,CAAC,WAAW,CAAC;SACjB,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC;SAChB,KAAK,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;IACtB,MAAM,qBAAqB,GAAG,CAAC,aAAa,CAAC;IAE7C,MAAM,cAAc,GAClB,QAAQ,IAAI,YAAY,IAAI,qBAAqB,IAAI,iBAAiB;QACpE,CAAC,CAAC;YACE,OAAO,EAAE,6BAA6B;YACtC,MAAM,EAAE,4BAA4B;YACpC,QAAQ,EAAE,QAAQ,CAAC,QAAQ;YAC3B,MAAM,EAAE,QAAQ,CAAC,MAAM;SACxB;QACH,CAAC,CAAC,IAAI,CAAC;IAEX,MAAM,gBAAgB,GACpB,eAAe,KAAK,IAAI;QACtB,CAAC,CAAC;YACE,YAAY,EAAE,eAAe,CAAC,YAAY;YAC1C,QAAQ,EAAE,eAAe,CAAC,QAAQ;YAClC,MAAM,EAAE,eAAe,CAAC,MAAM;YAC9B,OAAO,EAAE,wCAAwC,eAAe,CAAC,YAAY,uBAAuB;SACrG;QACH,CAAC,CAAC,IAAI,CAAC;IAEX,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAC;AAC9E,CAAC"}

package/node_modules/@gdh/adapters/dist/durable-backup.d.ts

@@ -0,0 +1,209 @@
+import { type GdhMigrationVersionPair } from "@gdh/core";
+/**
+ * Workspace-relative directory for the durable update backup.
+ *
+ * Single durable backup per STA-01 / D-14: this directory is overwritten
+ * (rm -rf semantics) on every successful backup write. Multi-backup retention
+ * is explicitly deferred (see 72-CONTEXT.md "Deferred Ideas").
+ */
+export declare const BACKUP_RELATIVE_PATH = ".gdh-state/backup";
+/**
+ * Workspace-relative staging directory used to make the backup write atomic
+ * at the directory level (Pitfall 6 / T-72-04-03). The staged tree is built
+ * here, then renamed onto BACKUP_RELATIVE_PATH so the prior backup is never
+ * absent from disk between rm-rf and write.
+ */
+export declare const BACKUP_STAGING_RELATIVE_PATH = ".gdh-state/backup.new";
+/** Workspace-relative path to the per-backup manifest. */
+export declare const BACKUP_MANIFEST_RELATIVE_PATH = ".gdh-state/backup/manifest.json";
+export type GdhBackupPreservationReason = "class_1_backup_then_overwrite";
+export type GdhBackupMarkerState = "absent" | "present" | "not_applicable";
+/**
+ * WFL-02 / D-24 preservation note attached to the backup manifest. Emitted
+ * when a class-1 file's GDH ownership marker is absent (user-edited drift)
+ * and the file is captured into the backup BEFORE re-rendering.
+ */
+export interface GdhBackupPreservationNote {
+    readonly path: string;
+    readonly reason: GdhBackupPreservationReason;
+    readonly marker_state: GdhBackupMarkerState;
+}
+/**
+ * Per-path capture entry recorded in the backup manifest. `existed: false`
+ * matches the legacy in-memory rollbackOriginals null-content semantics: the
+ * file did not exist pre-update, so restore must `rm` the original path.
+ */
+export interface GdhBackupCapturedPath {
+    readonly path: string;
+    readonly existed: boolean;
+}
+/**
+ * Backup manifest schema (D-13). Version-locked at 1; readers reject any
+ * other backup_version with `null` (degraded fallback) so a future schema
+ * bump does not silently corrupt restore.
+ */
+export interface GdhBackupManifest {
+    readonly backup_version: 1;
+    readonly applied_at: string;
+    readonly from_pair: GdhMigrationVersionPair;
+    readonly to_pair: GdhMigrationVersionPair;
+    readonly from_pin: string;
+    readonly to_pin: string;
+    readonly captured_paths: readonly GdhBackupCapturedPath[];
+    readonly preservation_notes: readonly GdhBackupPreservationNote[];
+}
+export interface GdhWriteDurableBackupInput {
+    readonly targetPath: string;
+    readonly fromPair: GdhMigrationVersionPair;
+    readonly toPair: GdhMigrationVersionPair;
+    readonly fromPin: string;
+    readonly toPin: string;
+    /** Workspace-relative POSIX paths to capture (planned action paths + .gdh/project.yaml). */
+    readonly plannedPaths: readonly string[];
+    /** WFL-02 preservation notes attached to the manifest. */
+    readonly preservationNotes?: readonly GdhBackupPreservationNote[];
+    /** Optional clock for tests; defaults to () => new Date().toISOString(). */
+    readonly nowIso?: () => string;
+}
+export interface GdhWriteDurableBackupSkipped {
+    readonly path: string;
+    readonly reason: "path_traversal_blocked";
+}
+export type GdhWriteDurableBackupResult = {
+    readonly state: "written";
+    readonly backupPath: string;
+    readonly manifest: GdhBackupManifest;
+    readonly skipped: readonly GdhWriteDurableBackupSkipped[];
+} | {
+    readonly state: "skipped_no_planned_paths";
+};
+/**
+ * Write a single durable backup at .gdh-state/backup/ (STA-01 / D-13 / D-14).
+ *
+ * Staged-write strategy (T-72-04-03 mitigation, Pitfall 6):
+ *   1. Pre-clean .gdh-state/backup.new/ from any prior interrupted run.
+ *   2. Capture every plannedPaths entry into .gdh-state/backup.new/, mirroring
+ *      the workspace-relative directory structure. Missing files are recorded
+ *      in the manifest with existed: false but no file is written.
+ *   3. Write manifest.json into the staging directory via writeFileAtomic.
+ *   4. Remove the prior .gdh-state/backup/ (if any) and rename the staging
+ *      directory onto it.
+ *
+ * If interrupted between steps 2 and 4, the prior .gdh-state/backup/ is
+ * unchanged and the next call's pre-clean (step 1) removes the partial
+ * staging tree before it can corrupt anything.
+ *
+ * Path-traversal candidates (failing isWorkspaceRelativePath) are recorded
+ * in `skipped` with `path_traversal_blocked` and never written or captured.
+ */
+export declare function writeDurableBackup(input: GdhWriteDurableBackupInput): Promise<GdhWriteDurableBackupResult>;
+/**
+ * Read the backup manifest from .gdh-state/backup/manifest.json.
+ *
+ * Returns null on any failure (missing file, JSON parse error, schema
+ * mismatch). Never throws — degraded fallback so callers can branch on
+ * "no backup present" without try/catch ceremony, and so a corrupted
+ * manifest cannot trigger a partial restore (T-72-04-06).
+ */
+export declare function readBackupManifest(targetPath: string): Promise<GdhBackupManifest | null>;
+export type GdhRestoreFromDurableBackupResult = {
+    readonly state: "restored";
+    readonly restored: readonly string[];
+    readonly removed: readonly string[];
+    readonly skipped: readonly {
+        readonly path: string;
+        readonly reason: string;
+    }[];
+    /**
+     * WR-06: Count of captured_paths entries that failed to restore (i.e.,
+     * the length of `skipped`). Surfaced as a top-level field so callers
+     * can branch on actual restoration success without re-scanning the
+     * `skipped` array. When `restored.length === 0 && removed.length === 0
+     * && failedCount > 0`, the rollback is effectively a NO-RESTORE: every
+     * captured path failed (e.g., disk full, EROFS, EACCES) and the
+     * caller should NOT report this as a clean rollback. Pre-existing
+     * "best-effort" semantics are preserved (the function still returns
+     * \`state: "restored"\` to keep the discriminated-union contract
+     * stable for existing callers); the new field is additive.
+     */
+    readonly failedCount: number;
+} | {
+    readonly state: "no_backup_present";
+};
+/**
+ * Restore byte-equal content for every captured_paths entry in the backup
+ * manifest. Mirrors the legacy in-memory rollbackOriginals semantics:
+ *
+ *   - existed: true  → atomic-write the backup content over the original path
+ *   - existed: false → fs.rm the original path (file did not exist pre-update)
+ *
+ * The backup directory itself is read-only during restore (T-72-04 contract):
+ * each restore is a fresh copy from .gdh-state/backup/, so running restore
+ * twice produces the same final state.
+ *
+ * Path-traversal candidates in captured_paths are skipped with a structured
+ * warning (T-72-04-01); the rest of the restore still completes. If the
+ * backup content for an existed:true entry is missing on disk, that entry
+ * is skipped with reason "backup_content_missing" rather than aborting.
+ */
+export declare function restoreFromDurableBackup(input: {
+    readonly targetPath: string;
+}): Promise<GdhRestoreFromDurableBackupResult>;
+export interface GdhClass1MarkerDriftInput {
+    readonly targetPath: string;
+    /**
+     * Workspace-relative POSIX paths of class-1 (deterministic) managed files
+     * that the planned action set will re-render.
+     */
+    readonly plannedClass1Paths: readonly string[];
+    /**
+     * Optional per-path expected markers. Overrides KNOWN_GDH_MARKERS for
+     * files whose format ships its own marker convention. Use for class-1
+     * file types not covered by the default list (rare).
+     */
+    readonly expectedMarkersByPath?: ReadonlyMap<string, readonly string[]>;
+}
+export interface GdhClass1MarkerDriftEntry {
+    readonly path: string;
+    readonly markerState: GdhBackupMarkerState;
+}
+export interface GdhClass1MarkerDriftResult {
+    readonly driftedPaths: readonly GdhClass1MarkerDriftEntry[];
+    readonly absentPaths: readonly string[];
+    readonly skipped: readonly {
+        readonly path: string;
+        readonly reason: string;
+    }[];
+}
+/**
+ * Detect WFL-02 / D-24 class-1 marker drift.
+ *
+ * For each `plannedClass1Paths` entry that exists on disk, check whether the
+ * file contains any of its expected GDH ownership markers:
+ *   - Marker present → file is GDH-rendered; no drift; not flagged.
+ *   - Marker absent (but file exists) → user-edited drift; flagged with
+ *     marker_state: "absent".
+ *   - Per-path override supplied but no marker matches → conservative
+ *     marker_state: "not_applicable" + flagged as drifted (T-72-04-07: err on
+ *     the side of preservation when the marker convention is uncertain).
+ *   - File does not exist on disk → no drift; reported in absentPaths so
+ *     the caller knows the file will be rendered fresh (no preservation).
+ *
+ * Path-traversal candidates (failing isWorkspaceRelativePath) are skipped
+ * with structured warnings (T-72-04-01); never read.
+ *
+ * Pair the result with `driftResultToPreservationNotes` to produce the
+ * preservation-notes payload for `writeDurableBackup`.
+ */
+export declare function detectClass1MarkerDrift(input: GdhClass1MarkerDriftInput): Promise<GdhClass1MarkerDriftResult>;
+/**
+ * Convert a drift-detection result into preservation notes ready to attach
+ * to a `writeDurableBackup` call.
+ *
+ * Per D-24, every drifted path is preserved with reason
+ * `class_1_backup_then_overwrite`; the marker_state propagates from the
+ * drift entry so the manifest carries an audit trail of the detection
+ * outcome (absent vs not_applicable).
+ */
+export declare function driftResultToPreservationNotes(drift: GdhClass1MarkerDriftResult): readonly GdhBackupPreservationNote[];
+//# sourceMappingURL=durable-backup.d.ts.map

package/node_modules/@gdh/adapters/dist/durable-backup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-backup.d.ts","sourceRoot":"","sources":["../src/durable-backup.ts"],"names":[],"mappings":"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"}

package/node_modules/@gdh/adapters/dist/durable-backup.js

@@ -0,0 +1,346 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { isWorkspaceRelativePath, writeFileAtomic, } from "@gdh/core";
+/**
+ * Workspace-relative directory for the durable update backup.
+ *
+ * Single durable backup per STA-01 / D-14: this directory is overwritten
+ * (rm -rf semantics) on every successful backup write. Multi-backup retention
+ * is explicitly deferred (see 72-CONTEXT.md "Deferred Ideas").
+ */
+export const BACKUP_RELATIVE_PATH = ".gdh-state/backup";
+/**
+ * Workspace-relative staging directory used to make the backup write atomic
+ * at the directory level (Pitfall 6 / T-72-04-03). The staged tree is built
+ * here, then renamed onto BACKUP_RELATIVE_PATH so the prior backup is never
+ * absent from disk between rm-rf and write.
+ */
+export const BACKUP_STAGING_RELATIVE_PATH = ".gdh-state/backup.new";
+/** Workspace-relative path to the per-backup manifest. */
+export const BACKUP_MANIFEST_RELATIVE_PATH = ".gdh-state/backup/manifest.json";
+/**
+ * Write a single durable backup at .gdh-state/backup/ (STA-01 / D-13 / D-14).
+ *
+ * Staged-write strategy (T-72-04-03 mitigation, Pitfall 6):
+ *   1. Pre-clean .gdh-state/backup.new/ from any prior interrupted run.
+ *   2. Capture every plannedPaths entry into .gdh-state/backup.new/, mirroring
+ *      the workspace-relative directory structure. Missing files are recorded
+ *      in the manifest with existed: false but no file is written.
+ *   3. Write manifest.json into the staging directory via writeFileAtomic.
+ *   4. Remove the prior .gdh-state/backup/ (if any) and rename the staging
+ *      directory onto it.
+ *
+ * If interrupted between steps 2 and 4, the prior .gdh-state/backup/ is
+ * unchanged and the next call's pre-clean (step 1) removes the partial
+ * staging tree before it can corrupt anything.
+ *
+ * Path-traversal candidates (failing isWorkspaceRelativePath) are recorded
+ * in `skipped` with `path_traversal_blocked` and never written or captured.
+ */
+export async function writeDurableBackup(input) {
+    if (input.plannedPaths.length === 0) {
+        return { state: "skipped_no_planned_paths" };
+    }
+    const stagingPath = path.join(input.targetPath, BACKUP_STAGING_RELATIVE_PATH);
+    const finalPath = path.join(input.targetPath, BACKUP_RELATIVE_PATH);
+    // Step 1: pre-clean staging from any prior interrupted run, then re-create it
+    await fs.rm(stagingPath, { recursive: true, force: true });
+    await fs.mkdir(stagingPath, { recursive: true });
+    // Step 2: capture each planned-path file into the staging tree
+    const capturedPaths = [];
+    const skipped = [];
+    // Deduplicate planned paths and sort for deterministic manifest ordering
+    const uniquePaths = [...new Set(input.plannedPaths)].sort();
+    for (const relPath of uniquePaths) {
+        if (!isWorkspaceRelativePath(relPath)) {
+            skipped.push({ path: relPath, reason: "path_traversal_blocked" });
+            continue;
+        }
+        const sourceAbs = path.join(input.targetPath, relPath);
+        const destAbs = path.join(stagingPath, relPath);
+        let content;
+        try {
+            content = await fs.readFile(sourceAbs, "utf8");
+        }
+        catch {
+            content = null;
+        }
+        if (content !== null) {
+            await fs.mkdir(path.dirname(destAbs), { recursive: true });
+            await fs.writeFile(destAbs, content);
+            capturedPaths.push({ path: relPath, existed: true });
+        }
+        else {
+            capturedPaths.push({ path: relPath, existed: false });
+        }
+    }
+    // Step 3: write manifest into the staging directory
+    const nowIso = input.nowIso ?? (() => new Date().toISOString());
+    const manifest = {
+        backup_version: 1,
+        applied_at: nowIso(),
+        from_pair: input.fromPair,
+        to_pair: input.toPair,
+        from_pin: input.fromPin,
+        to_pin: input.toPin,
+        captured_paths: capturedPaths,
+        preservation_notes: input.preservationNotes ?? [],
+    };
+    await writeFileAtomic(path.join(stagingPath, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+    // Step 4: remove the old backup, then rename staging into place. The rename
+    // is atomic on POSIX filesystems for directories on the same device, and
+    // .gdh-state/ is always on the same device as itself by construction.
+    await fs.rm(finalPath, { recursive: true, force: true });
+    await fs.rename(stagingPath, finalPath);
+    return {
+        state: "written",
+        backupPath: finalPath,
+        manifest,
+        skipped,
+    };
+}
+// ---------------------------------------------------------------------------
+// Manifest read + restore (T-72-04-06 schema guard; D-10 step rollback)
+// ---------------------------------------------------------------------------
+function isBackupCapturedPath(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return typeof v["path"] === "string" && typeof v["existed"] === "boolean";
+}
+function isBackupPreservationNote(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    if (typeof v["path"] !== "string")
+        return false;
+    if (v["reason"] !== "class_1_backup_then_overwrite")
+        return false;
+    const ms = v["marker_state"];
+    return ms === "absent" || ms === "present" || ms === "not_applicable";
+}
+function isMigrationVersionPair(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v["schema"] === "number" && typeof v["agentContract"] === "number");
+}
+function isBackupManifest(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    if (v["backup_version"] !== 1)
+        return false;
+    if (typeof v["applied_at"] !== "string")
+        return false;
+    if (typeof v["from_pin"] !== "string")
+        return false;
+    if (typeof v["to_pin"] !== "string")
+        return false;
+    if (!isMigrationVersionPair(v["from_pair"]))
+        return false;
+    if (!isMigrationVersionPair(v["to_pair"]))
+        return false;
+    const captured = v["captured_paths"];
+    if (!Array.isArray(captured) || !captured.every(isBackupCapturedPath)) {
+        return false;
+    }
+    const notes = v["preservation_notes"];
+    if (!Array.isArray(notes) || !notes.every(isBackupPreservationNote)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Read the backup manifest from .gdh-state/backup/manifest.json.
+ *
+ * Returns null on any failure (missing file, JSON parse error, schema
+ * mismatch). Never throws — degraded fallback so callers can branch on
+ * "no backup present" without try/catch ceremony, and so a corrupted
+ * manifest cannot trigger a partial restore (T-72-04-06).
+ */
+export async function readBackupManifest(targetPath) {
+    const manifestPath = path.join(targetPath, BACKUP_MANIFEST_RELATIVE_PATH);
+    const raw = await fs.readFile(manifestPath, "utf8").catch(() => null);
+    if (raw === null)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    return isBackupManifest(parsed) ? parsed : null;
+}
+/**
+ * Restore byte-equal content for every captured_paths entry in the backup
+ * manifest. Mirrors the legacy in-memory rollbackOriginals semantics:
+ *
+ *   - existed: true  → atomic-write the backup content over the original path
+ *   - existed: false → fs.rm the original path (file did not exist pre-update)
+ *
+ * The backup directory itself is read-only during restore (T-72-04 contract):
+ * each restore is a fresh copy from .gdh-state/backup/, so running restore
+ * twice produces the same final state.
+ *
+ * Path-traversal candidates in captured_paths are skipped with a structured
+ * warning (T-72-04-01); the rest of the restore still completes. If the
+ * backup content for an existed:true entry is missing on disk, that entry
+ * is skipped with reason "backup_content_missing" rather than aborting.
+ */
+export async function restoreFromDurableBackup(input) {
+    const manifest = await readBackupManifest(input.targetPath);
+    if (manifest === null) {
+        return { state: "no_backup_present" };
+    }
+    const backupRoot = path.join(input.targetPath, BACKUP_RELATIVE_PATH);
+    const restored = [];
+    const removed = [];
+    const skipped = [];
+    for (const entry of manifest.captured_paths) {
+        if (!isWorkspaceRelativePath(entry.path)) {
+            skipped.push({ path: entry.path, reason: "path_traversal_blocked" });
+            continue;
+        }
+        const originalAbs = path.join(input.targetPath, entry.path);
+        if (entry.existed) {
+            const backupAbs = path.join(backupRoot, entry.path);
+            const content = await fs.readFile(backupAbs, "utf8").catch(() => null);
+            if (content === null) {
+                skipped.push({ path: entry.path, reason: "backup_content_missing" });
+                continue;
+            }
+            try {
+                await writeFileAtomic(originalAbs, content);
+                restored.push(entry.path);
+            }
+            catch (error) {
+                // Best-effort restore: a destination-collision (e.g. directory at the
+                // expected file path, EACCES, EROFS) becomes a skipped entry rather
+                // than aborting the rest of the restore. Mirrors legacy
+                // rollbackOriginals semantics — partial recovery is preferable to
+                // halting mid-rollback. T-72-04-04 (single-backup contract) is
+                // unchanged; this only widens which failure modes degrade gracefully.
+                skipped.push({
+                    path: entry.path,
+                    reason: `restore_failed:${error instanceof Error ? error.message : String(error)}`,
+                });
+            }
+        }
+        else {
+            try {
+                await fs.rm(originalAbs, { force: true });
+                removed.push(entry.path);
+            }
+            catch (error) {
+                // Same best-effort posture: fs.rm without recursive on a directory
+                // throws EISDIR; recursive removal of an unexpected directory at a
+                // file path is destructive (could surprise an operator who created
+                // the directory deliberately). Skip with a structured reason.
+                skipped.push({
+                    path: entry.path,
+                    reason: `remove_failed:${error instanceof Error ? error.message : String(error)}`,
+                });
+            }
+        }
+    }
+    return {
+        state: "restored",
+        restored,
+        removed,
+        skipped,
+        // WR-06: surface aggregate restore failure as a typed scalar so callers
+        // can branch on actual restoration success without re-scanning `skipped`.
+        failedCount: skipped.length,
+    };
+}
+// ---------------------------------------------------------------------------
+// WFL-02 / D-24 — class-1 marker-drift detection
+// ---------------------------------------------------------------------------
+/**
+ * Known GDH ownership markers (per 72-RESEARCH.md "Established Patterns").
+ *
+ * Each class-1 file format ships at least one of these markers in its
+ * GDH-rendered output. The first match in a file proves "GDH-rendered,
+ * untouched" — no preservation needed. Absence of every marker (when the
+ * file otherwise exists at a class-1 path) proves user-edited drift and
+ * triggers WFL-02 backup-then-overwrite.
+ *
+ * Adding a new marker convention requires updating both this list AND the
+ * renderer that ships it; tests in `detectClass1MarkerDrift` cover each
+ * marker variant explicitly.
+ */
+const KNOWN_GDH_MARKERS = [
+    "<codex_skill_adapter>",
+    "<!-- gdh managed -->",
+    "# gdh:managed-hook",
+    "<!-- GDH-MANAGED -->",
+];
+/**
+ * Detect WFL-02 / D-24 class-1 marker drift.
+ *
+ * For each `plannedClass1Paths` entry that exists on disk, check whether the
+ * file contains any of its expected GDH ownership markers:
+ *   - Marker present → file is GDH-rendered; no drift; not flagged.
+ *   - Marker absent (but file exists) → user-edited drift; flagged with
+ *     marker_state: "absent".
+ *   - Per-path override supplied but no marker matches → conservative
+ *     marker_state: "not_applicable" + flagged as drifted (T-72-04-07: err on
+ *     the side of preservation when the marker convention is uncertain).
+ *   - File does not exist on disk → no drift; reported in absentPaths so
+ *     the caller knows the file will be rendered fresh (no preservation).
+ *
+ * Path-traversal candidates (failing isWorkspaceRelativePath) are skipped
+ * with structured warnings (T-72-04-01); never read.
+ *
+ * Pair the result with `driftResultToPreservationNotes` to produce the
+ * preservation-notes payload for `writeDurableBackup`.
+ */
+export async function detectClass1MarkerDrift(input) {
+    const drifted = [];
+    const absent = [];
+    const skipped = [];
+    for (const relPath of input.plannedClass1Paths) {
+        if (!isWorkspaceRelativePath(relPath)) {
+            skipped.push({ path: relPath, reason: "path_traversal_blocked" });
+            continue;
+        }
+        const absolute = path.join(input.targetPath, relPath);
+        const content = await fs.readFile(absolute, "utf8").catch(() => null);
+        if (content === null) {
+            absent.push(relPath);
+            continue;
+        }
+        const customMarkers = input.expectedMarkersByPath?.get(relPath);
+        const markersToCheck = customMarkers ?? KNOWN_GDH_MARKERS;
+        const hasMarker = markersToCheck.some((marker) => content.includes(marker));
+        if (hasMarker) {
+            // file is GDH-rendered, no drift
+            continue;
+        }
+        // marker absent — flag as drifted. When a custom marker list was supplied
+        // but none matched, the marker convention is uncertain → use the
+        // conservative "not_applicable" state per T-72-04-07.
+        const markerState = customMarkers !== undefined ? "not_applicable" : "absent";
+        drifted.push({ path: relPath, markerState });
+    }
+    return { driftedPaths: drifted, absentPaths: absent, skipped };
+}
+/**
+ * Convert a drift-detection result into preservation notes ready to attach
+ * to a `writeDurableBackup` call.
+ *
+ * Per D-24, every drifted path is preserved with reason
+ * `class_1_backup_then_overwrite`; the marker_state propagates from the
+ * drift entry so the manifest carries an audit trail of the detection
+ * outcome (absent vs not_applicable).
+ */
+export function driftResultToPreservationNotes(drift) {
+    return drift.driftedPaths.map((entry) => ({
+        path: entry.path,
+        reason: "class_1_backup_then_overwrite",
+        marker_state: entry.markerState,
+    }));
+}
+//# sourceMappingURL=durable-backup.js.map