grepmax 0.26.63 → 0.26.65

package/dist/lib/store/recovery.js

@@ -0,0 +1,163 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recoverStore = recoverStore;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const resource_budget_1 = require("../utils/resource-budget");
+const lance_cleanup_1 = require("./lance-cleanup");
+const prune_state_1 = require("./prune-state");
+const recovery_admission_1 = require("./recovery-admission");
+const store_lease_1 = require("./store-lease");
+function recoverStore(request) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d;
+        (_a = request.signal) === null || _a === void 0 ? void 0 : _a.throwIfAborted();
+        const input = path.resolve(request.table);
+        const stat = fs.lstatSync(input);
+        if (!stat.isDirectory() || stat.isSymbolicLink() || !input.endsWith(".lance"))
+            throw new Error("Recovery requires an existing local Lance table directory, without a table symlink");
+        const table = fs.realpathSync(input);
+        const store = path.dirname(table);
+        const previous = (0, prune_state_1.readPruneState)(store);
+        if (!request.prune && !request.check)
+            return {
+                outcome: "status",
+                table,
+                state: previous,
+                fullTableRewriting: "disabled",
+            };
+        if (request.prune &&
+            (!Number.isSafeInteger(request.version) ||
+                request.version < 1 ||
+                !request.cutoff ||
+                !Number.isSafeInteger(request.cutoff.getTime()) ||
+                request.cutoff.getTime() > Date.now()))
+            throw new Error("Explicit prune requires a positive --version and a real, nonfuture --cutoff");
+        if (request.prune &&
+            (previous === null || previous === void 0 ? void 0 : previous.outcome) === "uncertain" &&
+            request.acknowledgeUncertain !== previous.attemptId)
+            throw new Error(`Previous prune completion is uncertain; inspect retained state, then use --acknowledge-uncertain ${previous.attemptId} for a verified explicit retry`);
+        const budget = (0, recovery_admission_1.createRecoveryBudget)();
+        (0, recovery_admission_1.assertRecoveryAdmission)(store, budget);
+        if (!request.prune) {
+            const admission = (0, recovery_admission_1.admitPrune)(store, budget);
+            try {
+                return {
+                    outcome: "preflight-passed",
+                    table,
+                    state: previous,
+                    host: admission.snapshot,
+                    helperReserveMb: resource_budget_1.HELPER_RESOURCE_RESERVE_MB,
+                    fullTableRewriting: "disabled",
+                };
+            }
+            finally {
+                admission.close();
+            }
+        }
+        // Setup is admitted and monitored before acquiring store exclusion. No owner
+        // is killed and no marker is created or cleared by recovery itself.
+        const controller = new AbortController();
+        const abort = () => controller.abort();
+        (_b = request.signal) === null || _b === void 0 ? void 0 : _b.addEventListener("abort", abort, { once: true });
+        if ((_c = request.signal) === null || _c === void 0 ? void 0 : _c.aborted)
+            controller.abort();
+        let setup;
+        let monitor;
+        let lease;
+        try {
+            setup = budget.reserve(resource_budget_1.HELPER_RESOURCE_RESERVE_MB, "prune-runtime-setup");
+            monitor = setInterval(() => {
+                try {
+                    (0, recovery_admission_1.assertRecoveryAdmission)(store, budget);
+                }
+                catch (_a) {
+                    controller.abort();
+                }
+            }, 5000);
+            const runtime = yield (0, lance_cleanup_1.prepareCleanupRuntime)(controller.signal);
+            clearInterval(monitor);
+            setup.release();
+            (0, recovery_admission_1.assertRecoveryAdmission)(store, budget);
+            lease = yield store_lease_1.StoreLease.acquireExclusive({
+                storeDir: store,
+                timeoutMs: 1000,
+                signal: controller.signal,
+                role: "explicit-prune-recovery",
+            });
+            // Another completed/interrupted attempt may have happened during setup.
+            const current = (0, prune_state_1.readPruneState)(store);
+            if ((current === null || current === void 0 ? void 0 : current.outcome) === "uncertain" &&
+                request.acknowledgeUncertain !== current.attemptId)
+                throw new Error(`Prune completion is uncertain; inspect and acknowledge attempt ${current.attemptId} before retry`);
+            (0, recovery_admission_1.assertRecoveryAdmission)(store, budget);
+            const result = yield (0, lance_cleanup_1.pruneVersions)(runtime, table, request.version, request.cutoff, {
+                lease,
+                signal: controller.signal,
+                acknowledgeUncertain: request.acknowledgeUncertain,
+            });
+            return {
+                outcome: "verified",
+                table,
+                state: (0, prune_state_1.readPruneState)(store),
+                result,
+                allocatedBytesRecovered: result.allocatedBytesBefore - result.allocatedBytesAfter,
+                filesystemFreeBytesChange: result.freeBytesAfter - result.freeBytesBefore,
+                fullTableRewriting: "disabled",
+            };
+        }
+        catch (error) {
+            if (error instanceof store_lease_1.StoreLeaseTimeoutError)
+                throw new Error(`Recovery refused: store owners are live or unknown (${error.blockers.map((owner) => `${owner.role} pid=${owner.pid}`).join(", ") || "unverified owner"}); close them separately`);
+            throw error;
+        }
+        finally {
+            clearInterval(monitor);
+            (_d = request.signal) === null || _d === void 0 ? void 0 : _d.removeEventListener("abort", abort);
+            setup === null || setup === void 0 ? void 0 : setup.release();
+            yield lease === null || lease === void 0 ? void 0 : lease.release();
+        }
+    });
+}

package/dist/lib/store/store-lease.js

@@ -108,6 +108,14 @@ const defaultProbeDeps = {
     }).trim(),
 };
 function defaultProbeOwner(owner, deps = defaultProbeDeps) {
+    const parent = probeProcessOwner(owner, deps);
+    if ((parent === "dead" || parent === "reused") && owner.activeHelper) {
+        const child = probeProcessOwner(Object.assign(Object.assign({}, owner), { pid: owner.activeHelper.pid, processStart: owner.activeHelper.processStart }), deps);
+        return child === "same" || child === "unknown" ? child : parent;
+    }
+    return parent;
+}
+function probeProcessOwner(owner, deps) {
     try {
         deps.signal(owner.pid);
     }
@@ -124,6 +132,8 @@ function defaultProbeOwner(owner, deps = defaultProbeDeps) {
         if (code !== "EPERM")
             return "unknown";
     }
+    if (owner.processStart === "unverified")
+        return "unknown";
     if (owner.processStart.startsWith(`pid:${owner.pid}:started:`))
         return "same";
     try {
@@ -138,6 +148,7 @@ function defaultProbeOwner(owner, deps = defaultProbeDeps) {
     }
 }
 function readOwner(filePath) {
+    var _a;
     try {
         const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
         if (!parsed || typeof parsed !== "object")
@@ -147,18 +158,40 @@ function readOwner(filePath) {
             typeof owner.processStart === "string" &&
             typeof owner.nonce === "string" &&
             typeof owner.role === "string" &&
-            typeof owner.acquiredAt === "number"
+            typeof owner.acquiredAt === "number" &&
+            (owner.activeHelper === undefined ||
+                (Number.isSafeInteger((_a = owner.activeHelper) === null || _a === void 0 ? void 0 : _a.pid) &&
+                    owner.activeHelper.pid > 0 &&
+                    typeof owner.activeHelper.processStart === "string" &&
+                    !!owner.activeHelper.processStart))
             ? owner
             : null;
     }
-    catch (_a) {
+    catch (_b) {
         return null;
     }
 }
-function writeOwnerAtomic(filePath, owner) {
+function writeOwnerAtomic(filePath, owner, durable = false) {
     const temp = `${filePath}.${owner.nonce}.tmp`;
-    fs.writeFileSync(temp, `${JSON.stringify(owner)}\n`, { flag: "wx" });
+    const fd = fs.openSync(temp, "wx", 0o600);
+    try {
+        fs.writeFileSync(fd, `${JSON.stringify(owner)}\n`);
+        if (durable)
+            fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
     fs.renameSync(temp, filePath);
+    if (durable) {
+        const dir = fs.openSync(path.dirname(filePath), "r");
+        try {
+            fs.fsyncSync(dir);
+        }
+        finally {
+            fs.closeSync(dir);
+        }
+    }
 }
 function delay(ms, signal) {
     return __awaiter(this, void 0, void 0, function* () {
@@ -189,6 +222,7 @@ class StoreLease {
         this.storeDir = storeDir;
         this.released = false;
         this.claimedBy = null;
+        this.exclusiveUseRunning = false;
     }
     static acquireShared(options) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -269,6 +303,9 @@ class StoreLease {
     }
     release() {
         return __awaiter(this, arguments, void 0, function* (options = {}) {
+            if (this.exclusiveUseRunning) {
+                throw new Error("Exclusive store operation must finish before releasing its lease");
+            }
             if (this.released)
                 return;
             if (this.mode === "shared") {
@@ -306,7 +343,82 @@ class StoreLease {
         if (this.claimedBy === holder)
             this.claimedBy = null;
     }
+    /** Hold verified cross-process exclusion through a destructive helper and its
+     * verification. A local write gate is not a substitute for this ownership. */
+    withExclusiveUse(storeDir, operation) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.exclusiveUseRunning) {
+                throw new Error("An exclusive store operation is already running");
+            }
+            const verify = () => {
+                if (this.mode !== "exclusive" || this.released) {
+                    throw new Error("Pruning requires an unreleased exclusive store lease");
+                }
+                if (fs.realpathSync(storeDir) !== fs.realpathSync(this.storeDir)) {
+                    throw new Error("Exclusive store lease belongs to a different store");
+                }
+                const ownerStat = fs.lstatSync(this.paths.intentOwnerFile);
+                if (!ownerStat.isFile() || ownerStat.size > 16 * 1024) {
+                    throw new Error("Exclusive store lease owner is unverified or oversized");
+                }
+                const current = readOwner(this.paths.intentOwnerFile);
+                if ((current === null || current === void 0 ? void 0 : current.nonce) !== this.owner.nonce ||
+                    current.pid !== this.owner.pid ||
+                    current.processStart !== this.owner.processStart) {
+                    throw new Error("Exclusive store lease ownership could not be verified");
+                }
+                // acquireExclusive has already removed verified stale readers. Refuse any
+                // remaining marker rather than assuming ignored/unknown readers are safe.
+                if (fs
+                    .readdirSync(this.paths.readersDir)
+                    .some((name) => name.endsWith(".json"))) {
+                    throw new Error("Pruning requires all shared store owners to close");
+                }
+            };
+            verify();
+            this.exclusiveUseRunning = true;
+            try {
+                const result = yield operation();
+                verify();
+                return result;
+            }
+            finally {
+                this.exclusiveUseRunning = false;
+            }
+        });
+    }
     /** Atomically replace this shared lease with an exclusive lease. */
+    pinExclusiveHelper(pid) {
+        if (!this.exclusiveUseRunning ||
+            this.owner.activeHelper ||
+            !Number.isSafeInteger(pid) ||
+            pid < 1)
+            throw new Error("Helper requires an active exclusive store operation");
+        const current = readOwner(this.paths.intentOwnerFile);
+        if ((current === null || current === void 0 ? void 0 : current.nonce) !== this.owner.nonce || current.activeHelper)
+            throw new Error("Exclusive store ownership changed before helper launch");
+        // Publish uncertainty first. A failed identity probe must retain exclusion
+        // until this child is confirmed dead, even if the parent is killed.
+        this.owner.activeHelper = { pid, processStart: "unverified" };
+        // The helper is the primary on-disk owner, so older readers also retain
+        // exclusion after parent death. It is blocked on stdin until this identity
+        // is durably verified; uncertainty here cannot admit native deletion.
+        writeOwnerAtomic(this.paths.intentOwnerFile, Object.assign(Object.assign({}, this.owner), { pid, processStart: "unverified" }), true);
+        const start = defaultProbeDeps.processStartOf(pid);
+        if (!start)
+            throw new Error("Prune helper identity unavailable");
+        this.owner.activeHelper.processStart = start;
+        writeOwnerAtomic(this.paths.intentOwnerFile, Object.assign(Object.assign({}, this.owner), { pid, processStart: start }), true);
+        return () => {
+            var _a;
+            const latest = readOwner(this.paths.intentOwnerFile);
+            if ((latest === null || latest === void 0 ? void 0 : latest.nonce) !== this.owner.nonce ||
+                ((_a = latest.activeHelper) === null || _a === void 0 ? void 0 : _a.pid) !== pid)
+                throw new Error("Exclusive store ownership changed during helper close");
+            delete this.owner.activeHelper;
+            writeOwnerAtomic(this.paths.intentOwnerFile, this.owner, true);
+        };
+    }
     upgrade() {
         return __awaiter(this, arguments, void 0, function* (options = {}) {
             if (this.mode !== "shared") {
@@ -328,6 +440,9 @@ class StoreLease {
     /** Replace this exclusive lease with a shared lease without an ownership gap. */
     downgrade() {
         return __awaiter(this, arguments, void 0, function* (options = {}) {
+            if (this.exclusiveUseRunning) {
+                throw new Error("Exclusive store operation must finish before downgrading its lease");
+            }
             if (this.mode !== "exclusive") {
                 throw new Error("Only an exclusive store lease can be downgraded");
             }

package/dist/lib/utils/host-resource.js

@@ -132,7 +132,7 @@ function parseBatchFootprints(output) {
 function sampleHostResources(extraPids = [], overrides = {}, extraGroups = []) {
     var _a;
     var _b, _c;
-    const deps = Object.assign({ platform: process.platform, pid: process.pid, uid: (_b = (_a = process.getuid) === null || _a === void 0 ? void 0 : _a.call(process)) !== null && _b !== void 0 ? _b : -1, now: Date.now, monotonic: () => performance.now(), freeBytes: os.freemem, run: (command, args, timeoutMs) => (0, node_child_process_1.execFileSync)(command, args, {
+    const deps = Object.assign({ platform: process.platform, pid: process.pid, uid: (_b = (_a = process.getuid) === null || _a === void 0 ? void 0 : _a.call(process)) !== null && _b !== void 0 ? _b : -1, now: Date.now, monotonic: () => performance.now(), freeBytes: os.freemem, sampleTimeoutMs: exports.HOST_SAMPLE_TIMEOUT_MS, kernelProbeTimeoutMs: 500, run: (command, args, timeoutMs) => (0, node_child_process_1.execFileSync)(command, args, {
             encoding: "utf8",
             timeout: timeoutMs,
             maxBuffer: 512 * 1024,
@@ -153,7 +153,7 @@ function sampleHostResources(extraPids = [], overrides = {}, extraGroups = []) {
     };
     if (deps.platform !== "darwin")
         return snapshot;
-    const deadline = deps.monotonic() + exports.HOST_SAMPLE_TIMEOUT_MS;
+    const deadline = deps.monotonic() + deps.sampleTimeoutMs;
     const run = (command, args, maximumMs = 500) => {
         const remaining = Math.floor(deadline - deps.monotonic());
         if (remaining <= 0)
@@ -167,7 +167,7 @@ function sampleHostResources(extraPids = [], overrides = {}, extraGroups = []) {
     }
     catch (_d) { }
     try {
-        const zone = (0, kernel_zone_1.parseZprintOutput)(run("zprint", ["-L", "data.kalloc.1024"]));
+        const zone = (0, kernel_zone_1.parseZprintOutput)(run("zprint", ["-L", "data.kalloc.1024"], deps.kernelProbeTimeoutMs));
         if (zone) {
             const bytes = zone.elements * zone.elementSize;
             if (Number.isSafeInteger(bytes)) {

package/dist/lib/utils/resource-budget.js

@@ -75,7 +75,7 @@ function resolveResourceBudgetMb(raw = process.env.GMAX_RESOURCE_BUDGET_MB) {
         throw new ResourceAdmissionError("resource budget must be 256..6144 MiB");
     return n;
 }
-function assertResourceSnapshot(snapshot, chargedMb, budgetMb, now = Date.now()) {
+function assertResourceSnapshot(snapshot, chargedMb, budgetMb, now = Date.now(), sampleMaxAgeMs = 5000) {
     if (snapshot.memoryPressure === "critical" ||
         snapshot.kernelPressure === "critical")
         throw new ResourceAdmissionError("critical host pressure; heavy work refused", true);
@@ -84,7 +84,7 @@ function assertResourceSnapshot(snapshot, chargedMb, budgetMb, now = Date.now())
     if (snapshot.platform !== "darwin")
         return;
     if (now < snapshot.at ||
-        now - snapshot.at > 5000 ||
+        now - snapshot.at > sampleMaxAgeMs ||
         snapshot.completedAt < snapshot.at ||
         snapshot.completedAt > now)
         throw new ResourceAdmissionError("resource sample stale or clock changed; heavy work paused");
@@ -107,8 +107,8 @@ class ResourceBudget {
     constructor(overrides = {}) {
         this.deps = Object.assign({ root: path.join(config_1.PATHS.sharedRoot, "resource-budget"), platform: process.platform, pid: process.pid, now: Date.now, sample: (extraPids = []) => {
                 const records = this.readRecords();
-                return (0, host_resource_1.sampleHostResources)([...records.map((r) => r.pid), ...extraPids], {}, records.flatMap((r) => (r.groupPid ? [r.groupPid] : [])));
-            }, signal: (pid) => process.kill(pid, 0), policy: host_guard_policy_1.hostGuardPolicy, criticalSample: host_guard_policy_1.sampleCriticalPressure, quarantine: autostart_1.daemonStartDeniedReason, latch: safety_latch_1.latchSafetyStop, processStart: () => (0, node_child_process_1.execFileSync)("ps", ["-p", String(process.pid), "-o", "lstart="], {
+                return (0, host_resource_1.sampleHostResources)([...records.map((r) => r.pid), ...extraPids], this.deps.samplerOverrides, records.flatMap((r) => (r.groupPid ? [r.groupPid] : [])));
+            }, signal: (pid) => process.kill(pid, 0), policy: host_guard_policy_1.hostGuardPolicy, requireClientRegistration: true, samplerOverrides: {}, sampleMaxAgeMs: 5000, criticalSample: host_guard_policy_1.sampleCriticalPressure, quarantine: autostart_1.daemonStartDeniedReason, latch: safety_latch_1.latchSafetyStop, processStart: () => (0, node_child_process_1.execFileSync)("ps", ["-p", String(process.pid), "-o", "lstart="], {
                 encoding: "utf8",
                 timeout: 500,
                 maxBuffer: 1024,
@@ -250,10 +250,10 @@ class ResourceBudget {
     }
     checked(snapshot, records) {
         try {
-            assertResourceSnapshot(snapshot, this.charge(snapshot, records), resolveResourceBudgetMb(), this.deps.now());
+            assertResourceSnapshot(snapshot, this.charge(snapshot, records), resolveResourceBudgetMb(), this.deps.now(), this.deps.sampleMaxAgeMs);
             const legacy = snapshot.processes.filter((p) => p.role === "mcp" &&
                 !records.some((r) => r.pid === p.pid && r.kind === "client"));
-            if (legacy.length)
+            if (legacy.length && this.deps.requireClientRegistration)
                 throw new ResourceAdmissionError(`${legacy.length} MCP client(s) need to reconnect after upgrading; heavy work paused`);
         }
         catch (error) {

package/lance-maintenance/prune.py

@@ -0,0 +1,200 @@
+"""Explicit, exclusively leased Lance 12 prune-only recovery candidate.
+
+Never compacts, writes rows, builds indexes or starts a server. This helper is
+not an automatic maintenance path. Native production resource validation is
+required before enabling it on a pressured host.
+"""
+
+import argparse
+import importlib.metadata
+import hashlib
+import json
+import os
+from pathlib import Path
+import sys
+import time
+
+MAX_FILES = 100_000
+MAX_VERSIONS = 100_000
+MAX_PROTECTED_VERSIONS = 256
+CACHE_BYTES = 8 * 1024 * 1024
+
+
+def apply_resource_limits():
+    # Must run before importing native libraries. Cache limits are not total
+    # memory limits. RLIMIT_RSS is not enforceable on macOS; do not claim it is.
+    for name in ("RAYON_NUM_THREADS", "TOKIO_WORKER_THREADS", "OMP_NUM_THREADS",
+                 "OPENBLAS_NUM_THREADS", "MKL_NUM_THREADS", "NUMEXPR_NUM_THREADS"):
+        os.environ[name] = "1"
+    import resource
+    resource.setrlimit(resource.RLIMIT_CPU, (90, 91))
+    resource.setrlimit(resource.RLIMIT_NOFILE, (256, 256))
+    if sys.platform.startswith("linux"):
+        resource.setrlimit(resource.RLIMIT_AS, (2 * 1024**3, 2 * 1024**3))
+
+
+def verify_lease(root, owner_file, nonce):
+    expected = Path(str(root.parent) + ".lease") / "exclusive-intent" / "owner.json"
+    if Path(owner_file).resolve(strict=True) != expected.resolve(strict=True):
+        raise ValueError("Exclusive lease belongs to a different store")
+    if expected.is_symlink() or expected.stat().st_size > 16 * 1024:
+        raise ValueError("Exclusive lease owner is unverified or oversized")
+    owner = json.loads(expected.read_text())
+    helper = owner.get("activeHelper")
+    expected_pid = os.getpid() if helper and helper.get("pid") == os.getpid() else os.getppid()
+    if not nonce or owner.get("nonce") != nonce or owner.get("pid") != expected_pid:
+        raise ValueError("Exclusive lease ownership could not be verified")
+    readers = expected.parent.parent / "readers"
+    if not readers.is_dir() or any(readers.glob("*.json")):
+        raise ValueError("All shared store owners must close before pruning")
+    return owner
+
+
+def measure(root):
+    total = allocated = count = 0
+    pending = [root]
+    while pending:
+        directory = pending.pop()
+        with os.scandir(directory) as entries:
+            for entry in entries:
+                count += 1
+                if count > MAX_FILES:
+                    raise ValueError("Recovery metadata scan exceeded bounded file count")
+                if entry.is_symlink():
+                    raise ValueError("Recovery refuses symlinks inside the table")
+                if entry.is_dir(follow_symlinks=False):
+                    pending.append(Path(entry.path))
+                elif entry.is_file(follow_symlinks=False):
+                    stat = entry.stat(follow_symlinks=False)
+                    total += stat.st_size
+                    allocated += stat.st_blocks * 512
+                else:
+                    raise ValueError("Recovery refuses nonregular table entries")
+    space = os.statvfs(root)
+    return total, allocated, space.f_bavail * space.f_frsize
+
+
+def tag_versions(dataset):
+    return {name: dataset.tags.get_version(name) for name in dataset.tags.list()}
+
+
+def open_dataset(lance, root):
+    return lance.dataset(
+        str(root), index_cache_size_bytes=CACHE_BYTES,
+        metadata_cache_size_bytes=CACHE_BYTES,
+        read_params={"cache_repetition_index": False},
+    )
+
+
+def snapshot(dataset):
+    return (
+        [fragment.metadata.to_json() for fragment in dataset.get_fragments()],
+        dataset.list_indices(),
+        dataset.schema.serialize().to_pybytes(),
+        tag_versions(dataset),
+    )
+
+
+def protected_digest(dataset):
+    fragments, indices, schema, tags = snapshot(dataset)
+    value = [fragments, indices, schema.hex(), tags]
+    encoded = json.dumps(value, sort_keys=True, default=lambda item: sorted(item) if isinstance(item, set) else str(item))
+    return hashlib.sha256(encoded.encode()).hexdigest()
+
+
+def open_version(lance, root, version):
+    return lance.dataset(str(root), version=version, index_cache_size_bytes=CACHE_BYTES,
+                         metadata_cache_size_bytes=CACHE_BYTES)
+
+
+def prune(store, expected_version, cutoff_ms, owner_file, nonce, admission=None):
+    root = Path(store).resolve(strict=True)
+    if not root.is_dir() or root.suffix != ".lance":
+        raise ValueError("Cleanup requires a local Lance table directory")
+    owner = verify_lease(root, owner_file, nonce)
+    if not isinstance(expected_version, int) or expected_version < 1:
+        raise ValueError("Cleanup requires a positive current version")
+    if cutoff_ms > time.time_ns() // 1_000_000:
+        raise ValueError("Cleanup cutoff must not be in the future")
+    if importlib.metadata.version("pylance") != "12.0.0":
+        raise ValueError("Cleanup requires pylance 12.0.0")
+    before_bytes, before_allocated, before_free = measure(root)
+    import lance
+    dataset = open_dataset(lance, root)
+    if dataset.version != expected_version or dataset.latest_version != expected_version:
+        raise ValueError("Table changed before cleanup")
+    current = snapshot(dataset)
+    all_versions = dataset.versions()
+    if len(all_versions) > MAX_VERSIONS:
+        raise ValueError("Recovery exceeded bounded version count")
+    protected = {expected_version, *current[3].values()}
+    versions = []
+    for version in all_versions:
+        if version["timestamp"].timestamp() * 1000 >= cutoff_ms:
+            protected.add(version["version"])
+        if version["version"] not in protected and version["timestamp"].timestamp() * 1000 < cutoff_ms:
+            versions.append(version["version"])
+    if dataset.latest_version != expected_version or verify_lease(root, owner_file, nonce) != owner:
+        raise ValueError("Table or exclusive ownership changed during cleanup admission")
+    if len(protected) > MAX_PROTECTED_VERSIONS:
+        raise ValueError("Protected metadata exceeds bounded recovery version count")
+    protected_state = {version: protected_digest(open_version(lance, root, version)) for version in protected}
+    if admission is not None:
+        admission()
+    if dataset.latest_version != expected_version or verify_lease(root, owner_file, nonce) != owner:
+        raise ValueError("Table or exclusive ownership changed at deletion boundary")
+    # Explicit versions preserve current/tagged/post-cutoff commits. Unverified
+    # files stay protected. The native operation cannot rewrite data/index files.
+    stats = dataset.cleanup_old_versions(
+        versions=versions, delete_unverified=False,
+        error_if_tagged_old_versions=True, delete_rate_limit=32,
+    ) if versions else None
+    fresh = open_dataset(lance, root)
+    remaining = {version["version"] for version in fresh.versions()}
+    if (fresh.version != expected_version or fresh.latest_version != expected_version
+            or snapshot(fresh) != current or not protected.issubset(remaining)
+            or set(versions).intersection(remaining)
+            or verify_lease(root, owner_file, nonce) != owner):
+        raise ValueError("Current/protected state or exclusive ownership changed; no retry")
+    if any(protected_digest(open_version(lance, root, version)) != digest
+           for version, digest in protected_state.items()):
+        raise ValueError("Protected state changed; no retry")
+    after_bytes, after_allocated, after_free = measure(root)
+    return {
+        "engine": "12.0.0", "version": expected_version,
+        "fragments": len(current[0]),
+        "bytesRemoved": stats.bytes_removed if stats else 0,
+        "versionsRemoved": stats.old_versions if stats else 0,
+        "rewritten": False,
+        "fileBytesBefore": before_bytes, "fileBytesAfter": after_bytes,
+        "allocatedBytesBefore": before_allocated, "allocatedBytesAfter": after_allocated,
+        "freeBytesBefore": before_free, "freeBytesAfter": after_free,
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--store", required=True)
+    parser.add_argument("--version", required=True, type=int)
+    parser.add_argument("--cutoff-ms", required=True, type=int)
+    parser.add_argument("--lease-owner", required=True)
+    parser.add_argument("--lease-nonce", required=True)
+    parser.add_argument("--require-admission", action="store_true")
+    args = parser.parse_args()
+    if not args.require_admission:
+        parser.error("Prune helper requires guarded gmax recovery admission")
+    apply_resource_limits()
+    if args.require_admission:
+        print(json.dumps({"admission": "launch"}), flush=True)
+        if sys.stdin.readline(256).strip() != args.lease_nonce:
+            raise ValueError("Launch admission unavailable; no cleanup")
+    def admission():
+        print(json.dumps({"admission": "ready"}), flush=True)
+        if sys.stdin.readline(256).strip() != args.lease_nonce:
+            raise ValueError("Deletion admission unavailable; no cleanup")
+    print(json.dumps(prune(args.store, args.version, args.cutoff_ms, args.lease_owner,
+                          args.lease_nonce, admission if args.require_admission else None)))
+
+
+if __name__ == "__main__":
+    main()

package/lance-maintenance/pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "gmax-lance-maintenance"
+version = "0.1.0"
+description = "Prune-only maintenance for grepmax's pinned Lance 12 store"
+requires-python = ">=3.10"
+dependencies = ["pylance==12.0.0"]
+
+[tool.uv]
+package = false