akm-cli 0.9.17-alpha.2 → 0.9.17-alpha.4

package/dist/core/fs-txn.js

@@ -1,405 +0,0 @@
-// This Source Code Form is subject to the terms of the Mozilla Public
-// License, v. 2.0. If a copy of the MPL was not distributed with this
-// file, You can obtain one at https://mozilla.org/MPL/2.0/.
-/**
- * The ONE durable filesystem-transaction engine (plan §2.2 / §4.5, Chunk 6
- * WI-6.3). Replaces the three (+1) per-domain journal engines — proposal
- * accept/revert, proposal reject, mv, consolidate — with a single journal
- * home, journal format, fsync discipline, phase runner, and recovery scanner.
- *
- * ## Journal home
- *
- * `getDataDir()/txn/<rootNs24>/<transactionId>/journal.json`, namespaced by
- * the sha256 of the resolved root the transaction mutates. Every legacy home
- * (`proposal-transactions/`, `proposal-rejections/`, in-stash
- * `.akm/mv-transactions/`, in-stash `consolidate-journal.json`) collapses
- * onto this one.
- *
- * ## Phase model
- *
- * Each transaction KIND declares its ordered phase vocabulary and a commit
- * point. A journal found at a phase strictly BEFORE the commit point rolls
- * BACK (the batch never happened); at or after it rolls FORWARD (the kind's
- * `finalize` resumes idempotently from the recorded phase). Phase writes are
- * durable: tmp + fsync + rename + parent-dir fsync — the exact discipline
- * every legacy engine used, now in one place.
- *
- * ## Kind handlers
- *
- * Domain logic (what the files are, how to roll back, which DB/index/event
- * steps finalize) stays with the domain: each kind registers a
- * {@link TxnKindHandler}. The engine owns discovery, safety fencing, journal
- * I/O, ordering, and cleanup. Recovery entry points call
- * {@link recoverTxnsForRoot} (after importing the domain registrar so the
- * kinds are registered).
- *
- * ## Crash-window test seam
- *
- * `_setTxnMutationHookForTests` replaces the per-engine hooks; domain code
- * fires named points through {@link txnMutationHook} exactly where the legacy
- * engines fired theirs, so the subprocess crash runners re-key mechanically.
- */
-import { createHash, randomUUID } from "node:crypto";
-import fs from "node:fs";
-import path from "node:path";
-import { getDataDir } from "./paths.js";
-import { warn } from "./warn.js";
-// ── Registry ─────────────────────────────────────────────────────────────────
-const kinds = new Map();
-/**
- * Register (or replace) the handler for a transaction kind. Handlers are
- * stored payload-erased; beginTxn/recovery re-associate `P` via the kind tag.
- */
-export function registerTxnKind(kind, handler) {
-    kinds.set(kind, handler);
-}
-function requireKind(kind) {
-    const handler = kinds.get(kind);
-    if (!handler)
-        throw new Error(`No transaction handler registered for kind "${kind}".`);
-    return handler;
-}
-/** True when `kind` has a registered handler (see {@link recoverTxnsForRoot}). */
-function hasKind(kind) {
-    return kinds.has(kind);
-}
-// ── Test seam ────────────────────────────────────────────────────────────────
-let mutationHookForTests;
-/** TEST-ONLY crash-window hook used by subprocess recovery tests. */
-export function _setTxnMutationHookForTests(hook) {
-    mutationHookForTests = hook;
-}
-/** Fire a named crash-window point (no-op outside tests). */
-export function txnMutationHook(point) {
-    mutationHookForTests?.(point);
-}
-// ── Durable file I/O primitives (shared fsync discipline) ────────────────────
-export function txnHash(content) {
-    return createHash("sha256").update(content).digest("hex");
-}
-export function txnFileHash(filePath) {
-    return txnHash(fs.readFileSync(filePath));
-}
-export function fsyncTxnFile(filePath) {
-    // Open for WRITE. Windows implements fsync as FlushFileBuffers, which
-    // requires write access on the handle — a read-only descriptor fails with
-    // EACCES/EPERM, so every proposal accept and reject failed on that platform.
-    // POSIX accepts "r+" here just as readily as "r".
-    const fd = fs.openSync(filePath, "r+");
-    try {
-        fs.fsyncSync(fd);
-    }
-    finally {
-        fs.closeSync(fd);
-    }
-}
-export function fsyncTxnDir(dirPath) {
-    try {
-        // Read-only, unlike {@link fsyncTxnFile}: a directory cannot be opened for
-        // write on POSIX (EISDIR), and on Windows this whole operation is
-        // unsupported anyway and falls into the catch.
-        const fd = fs.openSync(dirPath, "r");
-        try {
-            fs.fsyncSync(fd);
-        }
-        finally {
-            fs.closeSync(fd);
-        }
-    }
-    catch {
-        // Directory fsync is unavailable on some platforms.
-    }
-}
-/** Durably write `content` to `filePath` (tmp + fsync + rename + dir fsync). */
-export function writeTxnFileDurably(filePath, content, mode = 0o600) {
-    const tempPath = `${filePath}.tmp`;
-    fs.writeFileSync(tempPath, content, { mode });
-    fsyncTxnFile(tempPath);
-    fs.renameSync(tempPath, filePath);
-    fsyncTxnDir(path.dirname(filePath));
-}
-// ── Journal home / discovery ─────────────────────────────────────────────────
-/**
- * Canonical spelling of a transaction root: realpath when the root exists
- * (so symlinked spellings — e.g. a stash reached through macOS /tmp — hash
- * to the SAME namespace and bind-compare equal), resolved otherwise.
- */
-export function canonicalTxnRoot(root) {
-    try {
-        return fs.realpathSync(path.resolve(root));
-    }
-    catch {
-        return path.resolve(root);
-    }
-}
-/** Namespace directory for all transactions mutating `root`. */
-export function txnNamespaceDir(root) {
-    const ns = txnHash(canonicalTxnRoot(root)).slice(0, 24);
-    return path.join(getDataDir(), "txn", ns);
-}
-/** Mint a transaction id ahead of {@link beginTxn} (see its `transactionId`). */
-export function mintTxnId() {
-    return randomUUID();
-}
-/** The directory a transaction with `transactionId` on `root` will own. */
-export function txnDirFor(root, transactionId) {
-    return path.join(txnNamespaceDir(root), transactionId);
-}
-function writeJournal(txn) {
-    writeTxnFileDurably(txn.journalPath, `${JSON.stringify(txn.journal, null, 2)}\n`);
-}
-/** Durably record `phase` on the journal, then mirror it in memory. */
-export function advanceTxn(txn, phase) {
-    const handler = requireKind(txn.journal.kind);
-    if (!handler.phases.includes(phase)) {
-        throw new Error(`Unknown phase "${phase}" for transaction kind "${txn.journal.kind}".`);
-    }
-    const next = { ...txn.journal, phase };
-    writeTxnFileDurably(txn.journalPath, `${JSON.stringify(next, null, 2)}\n`);
-    txn.journal.phase = phase;
-}
-/**
- * Open a new transaction: mint the id, create its directory, and durably
- * write the journal at the kind's initial phase. The caller stages sidecar
- * files under `txn.dir` and then applies/finalizes through the kind handler.
- */
-export function beginTxn(args) {
-    const handler = requireKind(args.kind);
-    const transactionId = args.transactionId ?? randomUUID();
-    if (!/^[A-Za-z0-9._-]+$/.test(transactionId) || transactionId === "." || transactionId === "..") {
-        throw new Error(`Invalid transaction id "${transactionId}" — must be a plain path segment.`);
-    }
-    const dir = path.join(txnNamespaceDir(args.root), transactionId);
-    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-    const journal = {
-        version: 1,
-        kind: args.kind,
-        phase: handler.phases[0],
-        transactionId,
-        root: canonicalTxnRoot(args.root),
-        changes: args.changes,
-        decidedAt: args.decidedAt ?? new Date().toISOString(),
-        payload: args.payload,
-    };
-    const txn = { journal, journalPath: path.join(dir, "journal.json"), dir };
-    writeJournal(txn);
-    return txn;
-}
-/** Remove a transaction directory (and its namespace dir when empty). */
-export function cleanupTxn(dir) {
-    try {
-        fs.rmSync(dir, { recursive: true, force: true });
-        try {
-            fs.rmdirSync(path.dirname(dir));
-        }
-        catch {
-            // Other transactions may still exist in the namespace.
-        }
-        return null;
-    }
-    catch (error) {
-        const message = `transaction committed but cleanup failed at ${dir}: ${error instanceof Error ? error.message : String(error)}`;
-        warn(`[txn] ${message}`);
-        return message;
-    }
-}
-/**
- * Grace period (ms) before a transaction directory/journal with no other
- * evidence of activity is treated as stale rather than possibly belonging to
- * a still-running operation. Shared by {@link sweepJournallessTxnDir} (racing
- * a sibling's mkdir→journal window, and the unknown-kind sweep in
- * {@link recoverTxnsForRoot}) and by read-only reporting such as `akm
- * health`'s stale-journal advisory (see {@link listTxnJournalsTolerant}).
- */
-export const TXN_SWEEP_GRACE_MS = 300_000;
-/**
- * Sweep a transaction directory that cannot be recovered — it has NO journal,
- * or (from {@link recoverTxnsForRoot}) a journal whose kind has no registered
- * handler — but only when it is demonstrably stale. All kinds share one
- * namespace per root, so a scanner may encounter a SIBLING transaction inside
- * `beginTxn`'s mkdir→journal window, or one whose registrar this process
- * simply has not imported yet; a grace period keeps the sweep from racing
- * either. Returns true when the directory was removed.
- */
-export function sweepJournallessTxnDir(dir, graceMs = TXN_SWEEP_GRACE_MS) {
-    try {
-        const age = Date.now() - fs.statSync(dir).mtimeMs;
-        if (age < graceMs)
-            return false;
-        fs.rmSync(dir, { recursive: true, force: true });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/** True when `candidate` is inside `root` (both resolved). */
-export function isWithinTxnRoot(candidate, root) {
-    const rel = path.relative(path.resolve(root), path.resolve(candidate));
-    return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
-}
-function readJournal(journalPath) {
-    let journal;
-    try {
-        journal = JSON.parse(fs.readFileSync(journalPath, "utf8"));
-    }
-    catch (error) {
-        throw new Error(`Cannot read transaction journal at ${journalPath}: ${error instanceof Error ? error.message : String(error)}`);
-    }
-    if (journal.version !== 1 || typeof journal.kind !== "string" || typeof journal.phase !== "string") {
-        throw new Error(`Refusing unsafe transaction journal at ${journalPath}.`);
-    }
-    return journal;
-}
-/** Engine-level safety fences shared by every kind. */
-function fenceJournal(journal, txnDir, root, journalPath) {
-    if (canonicalTxnRoot(journal.root) !== canonicalTxnRoot(root)) {
-        throw new Error(`Refusing transaction journal bound to a different root at ${journalPath}.`);
-    }
-    const handler = requireKind(journal.kind);
-    if (!handler.phases.includes(journal.phase)) {
-        throw new Error(`Refusing transaction journal with unknown phase "${journal.phase}" at ${journalPath}.`);
-    }
-    for (const change of journal.changes) {
-        if (typeof change.path !== "string" || !isWithinTxnRoot(change.path, root)) {
-            throw new Error(`Refusing transaction journal touching paths outside its root at ${journalPath}.`);
-        }
-    }
-    handler.validate?.(journal, txnDir, root);
-}
-/** True when `journal.phase` is at or after the kind's commit point. */
-export function isCommittedPhase(journal) {
-    const handler = requireKind(journal.kind);
-    return handler.phases.indexOf(journal.phase) >= handler.phases.indexOf(handler.commitPhase);
-}
-/**
- * Recover every interrupted transaction under `root`'s namespace: journals
- * before their kind's commit point roll BACK; the rest roll FORWARD through
- * the kind's `finalize`. Fully-finalized directories are swept. The domain
- * registrar (which registers the kinds) must be imported by the caller.
- *
- * A journal whose `kind` has NO registered handler is SWEPT (same stale-dir
- * grace period as {@link sweepJournallessTxnDir}) rather than thrown on. A
- * kind can disappear for good — 0.9.0 deleted `akm mv` and with it the
- * `kind:"mv"` handler — and an unrecoverable leftover journal must never
- * brick every later recovery scan (index refresh, proposal accept/reject) run
- * against the same root. Kinds that ARE registered keep failing LOUDLY on any
- * fence violation: those journals may fence an interrupted, irreversible
- * mutation. The grace period also covers the transient case where the caller
- * has not imported a live kind's registrar yet.
- *
- * `filter` optionally narrows recovery (e.g. one kind, one proposal id). The
- * unknown-kind sweep runs BEFORE the filter: such a journal is garbage no
- * matter what the caller asked to recover, and leaving it behind is what
- * bricks the next scan.
- */
-export async function recoverTxnsForRoot(root, filter) {
-    const nsDir = txnNamespaceDir(root);
-    const recovered = [];
-    if (!fs.existsSync(nsDir))
-        return recovered;
-    for (const entry of fs.readdirSync(nsDir, { withFileTypes: true })) {
-        if (!entry.isDirectory())
-            continue;
-        const dir = path.join(nsDir, entry.name);
-        const journalPath = path.join(dir, "journal.json");
-        if (!fs.existsSync(journalPath)) {
-            sweepJournallessTxnDir(dir);
-            continue;
-        }
-        const journal = readJournal(journalPath);
-        if (!hasKind(journal.kind)) {
-            if (sweepJournallessTxnDir(dir)) {
-                warn(`[txn] swept unrecoverable journal of unregistered kind "${journal.kind}" at ${journalPath}.`);
-            }
-            continue;
-        }
-        if (filter && !filter(journal))
-            continue;
-        fenceJournal(journal, dir, root, journalPath);
-        const handler = requireKind(journal.kind);
-        const txn = { journal, journalPath, dir };
-        const terminal = handler.phases[handler.phases.length - 1];
-        if (!isCommittedPhase(journal)) {
-            await handler.rollback(txn);
-        }
-        else if (journal.phase !== terminal) {
-            await handler.finalize(txn);
-        }
-        recovered.push(journal);
-        cleanupTxn(dir);
-    }
-    return recovered;
-}
-/**
- * Enumerate (without recovering) every journal across ALL namespaces that
- * matches `predicate`. Used by stash-scoped recovery entry points that don't
- * know which roots their interrupted transactions were bound to.
- */
-export function listTxnJournals(predicate) {
-    const home = path.join(getDataDir(), "txn");
-    const matches = [];
-    if (!fs.existsSync(home))
-        return matches;
-    for (const ns of fs.readdirSync(home, { withFileTypes: true })) {
-        if (!ns.isDirectory())
-            continue;
-        const nsDir = path.join(home, ns.name);
-        for (const entry of fs.readdirSync(nsDir, { withFileTypes: true })) {
-            if (!entry.isDirectory())
-                continue;
-            const journalPath = path.join(nsDir, entry.name, "journal.json");
-            if (!fs.existsSync(journalPath))
-                continue;
-            // Unreadable/invalid journals fail LOUDLY: a caller deciding what to
-            // recover must never silently overlook a damaged journal (it may fence
-            // an interrupted, irreversible mutation).
-            const journal = readJournal(journalPath);
-            if (predicate(journal))
-                matches.push(journal);
-        }
-    }
-    return matches;
-}
-/**
- * Read-only, best-effort sibling of {@link listTxnJournals} for reporting
- * (e.g. `akm health`'s stale-journal advisory): a corrupt `journal.json` is
- * counted rather than thrown, so one damaged journal doesn't abort the whole
- * scan. Recovery call sites (which must decide how to roll a journal forward
- * or back) keep using {@link listTxnJournals} — it fails loudly on purpose,
- * since silently skipping a damaged journal there could leave an interrupted,
- * irreversible mutation unrecovered.
- */
-export function listTxnJournalsTolerant(predicate) {
-    const home = path.join(getDataDir(), "txn");
-    const matches = [];
-    const unreadableMtimes = [];
-    if (!fs.existsSync(home))
-        return { matches, unreadableMtimes };
-    for (const ns of fs.readdirSync(home, { withFileTypes: true })) {
-        if (!ns.isDirectory())
-            continue;
-        const nsDir = path.join(home, ns.name);
-        for (const entry of fs.readdirSync(nsDir, { withFileTypes: true })) {
-            if (!entry.isDirectory())
-                continue;
-            const journalPath = path.join(nsDir, entry.name, "journal.json");
-            let mtimeMs;
-            try {
-                mtimeMs = fs.statSync(journalPath).mtimeMs;
-            }
-            catch {
-                continue; // no journal.json here, or it vanished mid-scan
-            }
-            try {
-                const journal = readJournal(journalPath);
-                if (predicate(journal))
-                    matches.push({ journal, mtimeMs });
-            }
-            catch {
-                unreadableMtimes.push(mtimeMs);
-            }
-        }
-    }
-    return { matches, unreadableMtimes };
-}

package/dist/core/lexical-score.js

@@ -1,25 +0,0 @@
-// This Source Code Form is subject to the terms of the Mozilla Public
-// License, v. 2.0. If a copy of the MPL was not distributed with this
-// file, You can obtain one at https://mozilla.org/MPL/2.0/.
-/** Dependency-safe fixed FTS5 calibration shared by storage and ranking. */
-const SCORE_FLOOR = 0.3;
-const PARENT_CEILING = 0.8;
-// Fragment BM25 is from a distinct FTS population. Its separately calibrated
-// ceiling is an explicit evidence policy, not a cross-table comparability claim:
-// when a body fragment independently proves the query, retain that actionable
-// selector beside the same parent's length-penalized whole-body row. Metadata
-// and cross-fragment conjunctions cannot enter this population.
-const FRAGMENT_CEILING = 0.8;
-const BM25_REFERENCE = 0.000001;
-const LOG_SHAPE = 3;
-export function stableFtsScore(bm25Score, population = "parent") {
-    const ceiling = population === "fragment" ? FRAGMENT_CEILING : PARENT_CEILING;
-    if (bm25Score === Number.NEGATIVE_INFINITY)
-        return ceiling;
-    if (!Number.isFinite(bm25Score) || bm25Score >= 0)
-        return SCORE_FLOOR;
-    const scaled = Math.log1p(-bm25Score / BM25_REFERENCE);
-    if (!Number.isFinite(scaled))
-        return ceiling;
-    return SCORE_FLOOR + (ceiling - SCORE_FLOOR) * (scaled / (scaled + LOG_SHAPE));
-}

package/dist/core/maintenance-barrier.js

@@ -1,167 +0,0 @@
-// This Source Code Form is subject to the terms of the Mozilla Public
-// License, v. 2.0. If a copy of the MPL was not distributed with this
-// file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { AsyncLocalStorage } from "node:async_hooks";
-import { randomUUID } from "node:crypto";
-import fs from "node:fs";
-import path from "node:path";
-import { sleepSync } from "../runtime.js";
-import { backoffDelay } from "./common.js";
-import { ConfigError, TransientError } from "./errors.js";
-import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync } from "./file-lock.js";
-import { getMaintenanceBarrierPath } from "./paths.js";
-const heldBarrierContext = new AsyncLocalStorage();
-/**
- * The barrier is meant to be held only for the short critical section that
- * registers one lock/lease/activity — a process that still holds it past
- * this age is wedged (crashed mid-section, deadlocked, killed without
- * cleanup), not doing legitimate long-running work. Without an age bound, a
- * probe only reclaims a lock whose holder PID has verifiably died; a wedged
- * — but still-alive — holder (or a PID a container/namespace boundary
- * reused, making `isProcessAlive` see the wrong process as live) locked
- * every other akm invocation out of ANY maintenance registration forever,
- * with no recovery but killing the holder by hand.  5 minutes matches the
- * stale-lock window already used for the improve extract-session lock
- * (`commands/improve/extract.ts`).
- */
-const MAINTENANCE_BARRIER_STALE_AFTER_MS = 5 * 60 * 1000;
-/**
- * The barrier normally holds for one lock-file write — sub-millisecond on
- * any real filesystem. Two akm processes racing to register a lock in the
- * very same instant (e.g. two `akm index` runs a scheduler launched back to
- * back) can still collide on it; retrying briefly resolves that ordinary
- * case instead of failing a legitimate concurrent invocation outright
- * (field follow-up to #956, G1). Five seconds matches the async and
- * synchronous-activity registration paths below and tolerates a holder being
- * descheduled under heavy process-shard load; the barrier's normal hold time
- * remains sub-millisecond. The bound still surfaces a genuinely wedged holder
- * promptly and never applies to the rebuild lock itself, which stays
- * non-blocking (#872).
- */
-const MAINTENANCE_BARRIER_BUSY_RETRY_BOUND_MS = 5_000;
-let busyRetryBoundMsForTests;
-/** Test-only override for {@link MAINTENANCE_BARRIER_BUSY_RETRY_BOUND_MS}, so a unit test can exercise the
- * exhausted-retry throw without a real ~1.5s wait. Restored via tests/_helpers/seams.ts's resetAllSeams(). */
-export function _setMaintenanceBarrierBusyRetryBoundMsForTests(ms) {
-    busyRetryBoundMsForTests = ms;
-}
-/**
- * Serialize the short critical section that creates each long-lived AKM lock,
- * lease, or state activity. The operation keeps its own ownership record; this
- * barrier is released immediately after acquisition.
- */
-export function tryAcquireMaintenanceBarrier() {
-    const lockPath = getMaintenanceBarrierPath();
-    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
-    for (let attempt = 0; attempt < 2; attempt += 1) {
-        const ownership = tryAcquireLockSync(lockPath, createLockPayload({ purpose: "maintenance-start" }));
-        if (ownership) {
-            return () => releaseLock(ownership);
-        }
-        const probe = probeLock(lockPath, { staleAfterMs: MAINTENANCE_BARRIER_STALE_AFTER_MS });
-        if (probe.state !== "stale" || !reclaimStaleLock(lockPath, probe))
-            return undefined;
-    }
-    return undefined;
-}
-export function acquireMaintenanceBarrier() {
-    const boundMs = busyRetryBoundMsForTests ?? MAINTENANCE_BARRIER_BUSY_RETRY_BOUND_MS;
-    const deadline = Date.now() + boundMs;
-    for (let attempt = 0;; attempt += 1) {
-        const release = tryAcquireMaintenanceBarrier();
-        if (release)
-            return release;
-        const remainingMs = deadline - Date.now();
-        if (remainingMs <= 0)
-            break;
-        sleepSync(Math.min(backoffDelay(attempt), remainingMs));
-    }
-    throw new TransientError(`AKM maintenance is in progress (barrier ${getMaintenanceBarrierPath()}); retry shortly. ` +
-        `A sentinel older than ${MAINTENANCE_BARRIER_STALE_AFTER_MS / 60_000} minute(s) is reclaimed automatically on the next attempt.`, "MAINTENANCE_BARRIER_BUSY");
-}
-export function withMaintenanceStartBarrier(run) {
-    if (heldBarrierContext.getStore()?.active)
-        return run();
-    const release = acquireMaintenanceBarrier();
-    const ownership = { active: true };
-    try {
-        return heldBarrierContext.run(ownership, run);
-    }
-    finally {
-        ownership.active = false;
-        release();
-    }
-}
-/** Run while holding the start barrier, or return undefined when it is busy. */
-export function tryWithMaintenanceStartBarrier(run) {
-    if (heldBarrierContext.getStore()?.active)
-        return run();
-    const release = tryAcquireMaintenanceBarrier();
-    if (!release)
-        return undefined;
-    const ownership = { active: true };
-    try {
-        return heldBarrierContext.run(ownership, run);
-    }
-    finally {
-        ownership.active = false;
-        release();
-    }
-}
-async function acquireMaintenanceBarrierAsync() {
-    const deadline = Date.now() + 5_000;
-    while (true) {
-        const release = tryAcquireMaintenanceBarrier();
-        if (release)
-            return release;
-        if (Date.now() >= deadline)
-            return acquireMaintenanceBarrier();
-        await new Promise((resolve) => setTimeout(resolve, 5));
-    }
-}
-export async function withMaintenanceStartBarrierAsync(run) {
-    if (heldBarrierContext.getStore()?.active)
-        return run();
-    const release = await acquireMaintenanceBarrierAsync();
-    const ownership = { active: true };
-    try {
-        return await heldBarrierContext.run(ownership, run);
-    }
-    finally {
-        ownership.active = false;
-        release();
-    }
-}
-function withMaintenanceStartBarrierSyncWait(run) {
-    if (heldBarrierContext.getStore()?.active)
-        return run();
-    const deadline = Date.now() + 5_000;
-    let release = tryAcquireMaintenanceBarrier();
-    while (!release && Date.now() < deadline) {
-        sleepSync(5);
-        release = tryAcquireMaintenanceBarrier();
-    }
-    if (!release)
-        release = acquireMaintenanceBarrier();
-    const ownership = { active: true };
-    try {
-        return heldBarrierContext.run(ownership, run);
-    }
-    finally {
-        ownership.active = false;
-        release();
-    }
-}
-/** Synchronous activity registration for synchronous database handle lifetimes. */
-export function acquireMaintenanceActivitySync(name) {
-    return withMaintenanceStartBarrierSyncWait(() => {
-        const directory = path.join(path.dirname(getMaintenanceBarrierPath()), "maintenance-activities");
-        fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
-        const lockPath = path.join(directory, `${name}-${process.pid}-${randomUUID()}.lock`);
-        const ownership = tryAcquireLockSync(lockPath, createLockPayload({ purpose: name }));
-        if (!ownership) {
-            throw new ConfigError(`Could not register AKM maintenance activity at ${lockPath}.`, "INVALID_CONFIG_FILE");
-        }
-        return () => releaseLock(ownership);
-    });
-}