@indigoai-us/hq-cli 5.125.0 → 5.127.0

package/dist/lib/lanes/store.js

@@ -0,0 +1,745 @@
+/**
+ * File-backed lane / question record store (spec §10, §10.1).
+ *
+ * Root: workspace/lanes/ under the HQ root. One stable path per record;
+ * `status` is the pending/answered discriminator — files are never moved
+ * between directories. Every mutation is temp-file-plus-rename and a
+ * compare-and-set on `version`. Histories are capped at 50 at the append site.
+ */
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { generateUlid } from "../mesh/live/ulid.js";
+import { resolveLanesHqRoot } from "./hq-root.js";
+import { LaneNotFoundError, LaneSchemaError, LaneVersionConflict, LanesError, isLaneVersionConflict, } from "./errors.js";
+import { HISTORY_CAP, HOST_KINDS, LANE_SCHEMA_VERSION, QUESTION_SCHEMA_VERSION, SENIOR_KINDS, isHostKind, isLaneProvider, isLaneState, isQuestionStatus, isSeniorKind, parseMajorSchema, REQUIRED_LANE_RECORD_FIELDS, LANE_FIELD_WRITERS, LANE_WRITERS, } from "./types.js";
+export const LANES_STORE_REL = path.join("workspace", "lanes");
+export const LANE_RECORDS_DIR = "lanes";
+export const QUESTION_RECORDS_DIR = "questions";
+export const PENDING_INDEX_DIR = path.join("questions", "index", "pending");
+const LOCK_STALE_MS = 30_000;
+const LOCK_RETRY_MS = 10;
+const LOCK_TIMEOUT_MS = 5_000;
+function defaultStoreDeps() {
+    return {
+        now: () => new Date(),
+        hostname: () => os.hostname(),
+        mkdirSync: fs.mkdirSync.bind(fs),
+        readFileSync: fs.readFileSync.bind(fs),
+        writeFileSync: fs.writeFileSync.bind(fs),
+        renameSync: fs.renameSync.bind(fs),
+        unlinkSync: fs.unlinkSync.bind(fs),
+        existsSync: fs.existsSync.bind(fs),
+        readdirSync: fs.readdirSync.bind(fs),
+        openSync: fs.openSync.bind(fs),
+        closeSync: fs.closeSync.bind(fs),
+        fsyncSync: fs.fsyncSync.bind(fs),
+        chmodSync: fs.chmodSync.bind(fs),
+    };
+}
+export function resolveStoreHqRoot(hqRoot, env = process.env, cwd) {
+    return hqRoot ?? resolveLanesHqRoot({ env, cwd });
+}
+export function lanesStoreRoot(hqRoot) {
+    return path.join(resolveStoreHqRoot(hqRoot), LANES_STORE_REL);
+}
+export function laneRecordPath(hqRoot, laneId) {
+    return path.join(lanesStoreRoot(hqRoot), LANE_RECORDS_DIR, `${laneId}.json`);
+}
+export function questionRecordPath(hqRoot, questionId) {
+    return path.join(lanesStoreRoot(hqRoot), QUESTION_RECORDS_DIR, `${questionId}.json`);
+}
+export function pendingMarkerPath(hqRoot, questionId) {
+    return path.join(lanesStoreRoot(hqRoot), PENDING_INDEX_DIR, questionId);
+}
+export function sanitizeHostComponent(hostname) {
+    const cleaned = hostname
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return (cleaned || "host").slice(0, 32);
+}
+/** Collision-safe across machines: ULID plus a host component. */
+export function mintLaneId(deps = defaultStoreDeps()) {
+    const host = sanitizeHostComponent(deps.hostname());
+    return `${generateUlid(deps.now().getTime())}_${host}`;
+}
+export function mintQuestionId(deps = defaultStoreDeps()) {
+    const host = sanitizeHostComponent(deps.hostname());
+    const extra = randomBytes(2).toString("hex");
+    return `q_${generateUlid(deps.now().getTime())}_${host}_${extra}`;
+}
+export function appendCappedHistory(history, entry, cap = HISTORY_CAP) {
+    const next = [...history, entry];
+    if (next.length <= cap)
+        return next;
+    return next.slice(next.length - cap);
+}
+function ensureDir(dir, deps) {
+    deps.mkdirSync(dir, { recursive: true });
+}
+function fsyncDir(dir, deps) {
+    try {
+        const fd = deps.openSync(dir, "r");
+        try {
+            deps.fsyncSync(fd);
+        }
+        finally {
+            deps.closeSync(fd);
+        }
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "EISDIR" || code === "EINVAL" || code === "ENOTSUP")
+            return;
+        // Directory fsync is best-effort on platforms that reject it; log once.
+        process.stderr.write(`lanes store: directory fsync failed for ${dir}: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+}
+function atomicWriteJson(target, value, deps) {
+    const dir = path.dirname(target);
+    ensureDir(dir, deps);
+    const tmp = path.join(dir, `.${path.basename(target)}.tmp.${process.pid}.${Date.now()}.${randomBytes(4).toString("hex")}`);
+    let fd;
+    try {
+        fd = deps.openSync(tmp, "wx");
+        const buf = Buffer.from(`${JSON.stringify(value, null, 2)}\n`, "utf8");
+        fs.writeSync(fd, buf);
+        deps.fsyncSync(fd);
+        deps.closeSync(fd);
+        fd = undefined;
+        deps.renameSync(tmp, target);
+        fsyncDir(dir, deps);
+        try {
+            deps.chmodSync(target, 0o600);
+        }
+        catch (err) {
+            process.stderr.write(`lanes store: chmod 0600 failed for ${target}: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    }
+    catch (err) {
+        if (fd !== undefined) {
+            try {
+                deps.closeSync(fd);
+            }
+            catch (closeErr) {
+                process.stderr.write(`lanes store: close failed for ${tmp}: ${closeErr instanceof Error ? closeErr.message : String(closeErr)}\n`);
+            }
+        }
+        try {
+            deps.unlinkSync(tmp);
+        }
+        catch (unlinkErr) {
+            const code = unlinkErr.code;
+            if (code !== "ENOENT") {
+                process.stderr.write(`lanes store: unlink tmp failed for ${tmp}: ${unlinkErr instanceof Error ? unlinkErr.message : String(unlinkErr)}\n`);
+            }
+        }
+        throw err;
+    }
+}
+function wait(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function lockPathFor(recordPath) {
+    return `${recordPath}.lock`;
+}
+function withRecordLock(recordPath, deps, fn) {
+    const lockPath = lockPathFor(recordPath);
+    ensureDir(path.dirname(recordPath), deps);
+    const started = Date.now();
+    while (true) {
+        let fd;
+        try {
+            fd = deps.openSync(lockPath, "wx");
+            try {
+                fs.writeSync(fd, Buffer.from(`${process.pid}\n${Date.now()}\n`, "utf8"));
+            }
+            catch (err) {
+                deps.closeSync(fd);
+                fd = undefined;
+                throw err;
+            }
+            try {
+                return fn();
+            }
+            finally {
+                try {
+                    deps.closeSync(fd);
+                }
+                catch (err) {
+                    process.stderr.write(`lanes store: lock close failed for ${lockPath}: ${err instanceof Error ? err.message : String(err)}\n`);
+                }
+                try {
+                    deps.unlinkSync(lockPath);
+                }
+                catch (err) {
+                    const code = err.code;
+                    if (code !== "ENOENT") {
+                        process.stderr.write(`lanes store: lock unlink failed for ${lockPath}: ${err instanceof Error ? err.message : String(err)}\n`);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "EEXIST")
+                throw err;
+            if (Date.now() - started > LOCK_TIMEOUT_MS) {
+                throw new LanesError("store_lock_timeout", `Timed out waiting for lock ${lockPath}`, { path: lockPath });
+            }
+            try {
+                const raw = deps.readFileSync(lockPath, "utf8");
+                const tsLine = raw.split("\n")[1];
+                const ts = tsLine ? Number(tsLine) : NaN;
+                if (Number.isFinite(ts) && Date.now() - ts > LOCK_STALE_MS) {
+                    try {
+                        deps.unlinkSync(lockPath);
+                    }
+                    catch (unlinkErr) {
+                        const unlinkCode = unlinkErr.code;
+                        if (unlinkCode !== "ENOENT")
+                            throw unlinkErr;
+                    }
+                    continue;
+                }
+            }
+            catch (statErr) {
+                const statCode = statErr.code;
+                if (statCode !== "ENOENT") {
+                    process.stderr.write(`lanes store: stale-lock probe failed for ${lockPath}: ${statErr instanceof Error ? statErr.message : String(statErr)}\n`);
+                }
+            }
+            wait(LOCK_RETRY_MS);
+        }
+    }
+}
+function readJsonFile(filePath, deps) {
+    let text;
+    try {
+        text = deps.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return null;
+        throw err;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        throw new LaneSchemaError(`Invalid JSON in ${filePath}: ${err instanceof Error ? err.message : String(err)}`, { path: filePath });
+    }
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function requireString(value, field) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new LaneSchemaError(`Expected non-empty string for ${field}`, {
+            field,
+        });
+    }
+    return value;
+}
+function requireInt(value, field) {
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+        throw new LaneSchemaError(`Expected integer for ${field}`, { field });
+    }
+    return value;
+}
+/**
+ * Company on a lane/question record is either a slug+uid pair or JSON `null`.
+ * Absence (omitted key) is normalised to `null`. Empty strings stay a schema
+ * error so a no-company lane cannot be confused with a broken company object.
+ */
+function parseOptionalCompanyField(raw, filePath) {
+    if (raw.company === undefined) {
+        raw.company = null;
+        return;
+    }
+    if (raw.company === null)
+        return;
+    if (!isPlainObject(raw.company)) {
+        throw new LaneSchemaError("company must be an object", { path: filePath });
+    }
+    requireString(raw.company.slug, "company.slug");
+    requireString(raw.company.uid, "company.uid");
+}
+export function parseLaneRecord(raw, filePath) {
+    if (!isPlainObject(raw)) {
+        throw new LaneSchemaError("Lane record must be a JSON object", {
+            path: filePath,
+        });
+    }
+    for (const field of REQUIRED_LANE_RECORD_FIELDS) {
+        if (!(field in raw)) {
+            throw new LaneSchemaError(`Missing required lane record field ${field}`, { path: filePath, field });
+        }
+    }
+    const schema_version = requireString(raw.schema_version, "schema_version");
+    parseMajorSchema(schema_version, "hq-lane", 1);
+    requireString(raw.lane_id, "lane_id");
+    requireInt(raw.version, "version");
+    requireInt(raw.depth, "depth");
+    requireInt(raw.priority, "priority");
+    requireString(raw.project_id, "project_id");
+    requireString(raw.story_id, "story_id");
+    if (!isLaneState(raw.state)) {
+        throw new LaneSchemaError(`Unknown lane state ${JSON.stringify(raw.state)}`, { path: filePath, value: raw.state });
+    }
+    if (!isLaneProvider(raw.provider)) {
+        throw new LaneSchemaError(`Unknown provider ${JSON.stringify(raw.provider)}`, { path: filePath, value: raw.provider });
+    }
+    parseOptionalCompanyField(raw, filePath);
+    if (!isPlainObject(raw.senior)) {
+        throw new LaneSchemaError("senior must be an object", { path: filePath });
+    }
+    if (!isSeniorKind(raw.senior.kind)) {
+        throw new LaneSchemaError(`Unknown senior kind ${JSON.stringify(raw.senior.kind)}`, {
+            path: filePath,
+            field: "senior.kind",
+            value: raw.senior.kind,
+            accepted: [...SENIOR_KINDS],
+        });
+    }
+    if (raw.senior.kind !== "user") {
+        requireString(raw.senior.id, "senior.id");
+    }
+    if (!isPlainObject(raw.host)) {
+        throw new LaneSchemaError("host must be an object", { path: filePath });
+    }
+    if (!isHostKind(raw.host.kind)) {
+        throw new LaneSchemaError(`Unknown host kind ${JSON.stringify(raw.host.kind)}`, {
+            path: filePath,
+            field: "host.kind",
+            value: raw.host.kind,
+            accepted: [...HOST_KINDS],
+        });
+    }
+    requireString(raw.host.id, "host.id");
+    if (!Array.isArray(raw.senior_history)) {
+        throw new LaneSchemaError("senior_history must be an array", {
+            path: filePath,
+        });
+    }
+    if (!Array.isArray(raw.attribution_history)) {
+        throw new LaneSchemaError("attribution_history must be an array", {
+            path: filePath,
+        });
+    }
+    // Spread-preserving: return the original object so unknown keys survive
+    // a parse/rewrite cycle (spec §5.1 field-preservation).
+    return raw;
+}
+export function parseQuestionRecord(raw, filePath) {
+    if (!isPlainObject(raw)) {
+        throw new LaneSchemaError("Question record must be a JSON object", {
+            path: filePath,
+        });
+    }
+    const schema_version = requireString(raw.schema_version, "schema_version");
+    parseMajorSchema(schema_version, "hq-lane-question", 1);
+    if (!isQuestionStatus(raw.status)) {
+        throw new LaneSchemaError(`Unknown question status ${JSON.stringify(raw.status)}`, { path: filePath, value: raw.status });
+    }
+    requireString(raw.question_id, "question_id");
+    requireString(raw.lane_id, "lane_id");
+    requireInt(raw.version, "version");
+    requireInt(raw.hop, "hop");
+    parseOptionalCompanyField(raw, filePath);
+    if (!isPlainObject(raw.body)) {
+        throw new LaneSchemaError("body must be an object", { path: filePath });
+    }
+    if (!Array.isArray(raw.routing_history)) {
+        throw new LaneSchemaError("routing_history must be an array", {
+            path: filePath,
+        });
+    }
+    // Optional on the record, but merge-on-read spreads it; a non-array from a
+    // synced sidecar must fail here, inside the per-sidecar skip, not later.
+    if (raw.answer_history !== undefined && !Array.isArray(raw.answer_history)) {
+        throw new LaneSchemaError("answer_history must be an array when present", {
+            path: filePath,
+        });
+    }
+    return raw;
+}
+/**
+ * HQ Sync sibling-twin grammar from `@indigoai-us/hq-cloud` `buildConflictPath`:
+ * `<file>.json.conflict-<ISO-with-dashes>-<machine>.json`
+ * (legacy twins; current engines park losers under `.hq/conflict-backups/`,
+ * but merge-on-read still has to recover the ones already on disk).
+ */
+export function isConflictSidecarName(recordBasename, name) {
+    if (name === recordBasename || name.startsWith("."))
+        return false;
+    return name.startsWith(`${recordBasename}.conflict-`);
+}
+function sidecarPathsFor(recordPath, deps) {
+    const dir = path.dirname(recordPath);
+    const base = path.basename(recordPath);
+    if (!deps.existsSync(dir))
+        return [];
+    const names = deps.readdirSync(dir);
+    const sidecars = [];
+    for (const name of names) {
+        if (typeof name !== "string")
+            continue;
+        if (!isConflictSidecarName(base, name))
+            continue;
+        sidecars.push(path.join(dir, name));
+    }
+    return sidecars;
+}
+function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
+    }
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(obj[key])}`).join(",")}}`;
+}
+function historyTimestamp(entry) {
+    if (!isPlainObject(entry))
+        return "";
+    if (typeof entry.at === "string")
+        return entry.at;
+    if (typeof entry.answered_at === "string")
+        return entry.answered_at;
+    return "";
+}
+/**
+ * Attribution identity is the message that caused the re-point (spec §2).
+ * Senior and routing entries have no named id; union is by canonical entry.
+ */
+function attributionIdentity(entry) {
+    if (typeof entry.message_id === "string" && entry.message_id.length > 0) {
+        return `message_id:${entry.message_id}`;
+    }
+    return `entry:${canonicalJson(entry)}`;
+}
+function entryIdentity(entry) {
+    return canonicalJson(entry);
+}
+function questionAnswerHistory(record) {
+    return [
+        ...(record.answer_history ?? []),
+        ...(record.answer ? [record.answer] : []),
+    ];
+}
+function unionHistory(lists, identity, preferred) {
+    const map = new Map();
+    for (const entry of preferred) {
+        map.set(identity(entry), entry);
+    }
+    for (const list of lists) {
+        for (const entry of list) {
+            const id = identity(entry);
+            if (!map.has(id))
+                map.set(id, entry);
+        }
+    }
+    const merged = [...map.values()].sort((a, b) => historyTimestamp(a).localeCompare(historyTimestamp(b)));
+    if (merged.length <= HISTORY_CAP)
+        return merged;
+    return merged.slice(merged.length - HISTORY_CAP);
+}
+function higherVersionRecord(live, others) {
+    let best = live;
+    for (const other of others) {
+        if (other.version > best.version)
+            best = other;
+    }
+    return best;
+}
+export function mergeLaneRecords(live, sidecars) {
+    if (sidecars.length === 0)
+        return live;
+    const all = [live, ...sidecars];
+    const base = higherVersionRecord(live, sidecars);
+    return {
+        ...base,
+        senior_history: unionHistory(all.map((record) => record.senior_history), entryIdentity, base.senior_history),
+        attribution_history: unionHistory(all.map((record) => record.attribution_history), attributionIdentity, base.attribution_history),
+    };
+}
+export function mergeQuestionRecords(live, sidecars) {
+    if (sidecars.length === 0)
+        return live;
+    const all = [live, ...sidecars];
+    const base = higherVersionRecord(live, sidecars);
+    return {
+        ...base,
+        answer_history: unionHistory(all.map(questionAnswerHistory), entryIdentity, questionAnswerHistory(base)),
+        routing_history: unionHistory(all.map((record) => record.routing_history), entryIdentity, base.routing_history),
+    };
+}
+function loadSidecarRecords(recordPath, parse, deps) {
+    const paths = sidecarPathsFor(recordPath, deps);
+    const records = [];
+    for (const sidecarPath of paths) {
+        try {
+            const raw = readJsonFile(sidecarPath, deps);
+            if (raw === null)
+                continue;
+            records.push(parse(raw, sidecarPath));
+        }
+        catch (err) {
+            process.stderr.write(`lanes store: skipping unreadable conflict sidecar ${sidecarPath}: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    }
+    return records;
+}
+function readMergedRecord(filePath, parse, merge, deps) {
+    const raw = readJsonFile(filePath, deps);
+    if (raw === null)
+        return null;
+    const live = parse(raw, filePath);
+    const sidecars = loadSidecarRecords(filePath, parse, deps);
+    if (sidecars.length === 0)
+        return live;
+    return merge(live, sidecars);
+}
+export function tryReadLane(hqRoot, laneId, deps = defaultStoreDeps()) {
+    const filePath = laneRecordPath(hqRoot, laneId);
+    return readMergedRecord(filePath, parseLaneRecord, mergeLaneRecords, deps);
+}
+export function readLane(hqRoot, laneId, deps = defaultStoreDeps()) {
+    const record = tryReadLane(hqRoot, laneId, deps);
+    if (!record)
+        throw new LaneNotFoundError("lane", laneId);
+    return record;
+}
+export function tryReadQuestion(hqRoot, questionId, deps = defaultStoreDeps()) {
+    const filePath = questionRecordPath(hqRoot, questionId);
+    return readMergedRecord(filePath, parseQuestionRecord, mergeQuestionRecords, deps);
+}
+export function readQuestion(hqRoot, questionId, deps = defaultStoreDeps()) {
+    const record = tryReadQuestion(hqRoot, questionId, deps);
+    if (!record)
+        throw new LaneNotFoundError("question", questionId);
+    return record;
+}
+function recordsEquivalentAsideFromClock(current, updated) {
+    if (updated === current)
+        return true;
+    const strip = (record) => {
+        const copy = { ...record };
+        delete copy.version;
+        delete copy.updated_at;
+        return copy;
+    };
+    return JSON.stringify(strip(current)) === JSON.stringify(strip(updated));
+}
+function casWrite(filePath, expectedVersion, parse, merge, updater, deps) {
+    return withRecordLock(filePath, deps, () => {
+        const current = readMergedRecord(filePath, parse, merge, deps);
+        if (current === null) {
+            throw new LaneSchemaError(`Record disappeared under lock: ${filePath}`, {
+                path: filePath,
+            });
+        }
+        if (current.version !== expectedVersion) {
+            throw new LaneVersionConflict({
+                path: filePath,
+                expectedVersion,
+                actualVersion: current.version,
+            });
+        }
+        const updated = updater(current);
+        if (recordsEquivalentAsideFromClock(current, updated)) {
+            return current;
+        }
+        const next = {
+            ...current,
+            ...updated,
+            version: current.version + 1,
+            updated_at: deps.now().toISOString(),
+        };
+        atomicWriteJson(filePath, next, deps);
+        return next;
+    });
+}
+export function createLane(hqRoot, init, deps = defaultStoreDeps()) {
+    const now = deps.now().toISOString();
+    const lane_id = init.lane_id ?? mintLaneId(deps);
+    const filePath = laneRecordPath(hqRoot, lane_id);
+    const record = {
+        ...init,
+        schema_version: init.schema_version ?? LANE_SCHEMA_VERSION,
+        lane_id,
+        version: 1,
+        created_at: init.created_at ?? now,
+        updated_at: init.updated_at ?? now,
+        senior_history: init.senior_history ?? [],
+        attribution_history: init.attribution_history ?? [],
+    };
+    parseLaneRecord(record, filePath);
+    return withRecordLock(filePath, deps, () => {
+        if (deps.existsSync(filePath)) {
+            throw new LanesError("lane_exists", `Lane ${lane_id} already exists`, { lane_id });
+        }
+        atomicWriteJson(filePath, record, deps);
+        return record;
+    });
+}
+/** Value equality over JSON-shaped record fields; the clone breaks reference identity. */
+function fieldUnchanged(before, after) {
+    if (Object.is(before, after))
+        return true;
+    if (before === undefined || after === undefined)
+        return false;
+    return JSON.stringify(before) === JSON.stringify(after);
+}
+export function updateLane(hqRoot, laneId, expectedVersion, writer, updater, deps = defaultStoreDeps()) {
+    if (!LANE_WRITERS.includes(writer)) {
+        throw new LanesError("lane_writer_unknown", `Unknown lane writer ${String(writer)}`, { writer });
+    }
+    return casWrite(laneRecordPath(hqRoot, laneId), expectedVersion, parseLaneRecord, mergeLaneRecords, (current) => {
+        // `current` is the pre-update snapshot and stays untouched: the updater
+        // receives a deep clone, so mutating its argument in place cannot reach
+        // the record the ownership check compares against.
+        const updated = updater(structuredClone(current));
+        for (const key of Object.keys(updated)) {
+            if (key === "version" || key === "updated_at" || fieldUnchanged(current[key], updated[key]))
+                continue;
+            const allowedWriters = LANE_FIELD_WRITERS[key];
+            // Unknown forward-version fields are preserved, never assigned an
+            // ownership rule by a v1 reader.
+            if (allowedWriters && !allowedWriters.includes(writer)) {
+                throw new LanesError("lane_writer_unauthorized", `Writer ${writer} cannot write lane field ${key}`, { writer, field: key });
+            }
+        }
+        return updated;
+    }, deps);
+}
+/** Compare-and-set with conflict retry. Callers that race a concurrent writer re-read. */
+export function retryUpdateLane(hqRoot, laneId, writer, updater, deps = defaultStoreDeps(), attempts = 5) {
+    let last;
+    for (let i = 0; i < attempts; i += 1) {
+        try {
+            const current = readLane(hqRoot, laneId, deps);
+            return updateLane(hqRoot, laneId, current.version, writer, updater, deps);
+        }
+        catch (err) {
+            last = err;
+            if (!isLaneVersionConflict(err) || i === attempts - 1)
+                throw err;
+        }
+    }
+    throw last;
+}
+/** Compare-and-set with conflict retry for question records (spec §6.2). */
+export function retryUpdateQuestion(hqRoot, questionId, updater, deps = defaultStoreDeps(), attempts = 5) {
+    let last;
+    for (let i = 0; i < attempts; i += 1) {
+        try {
+            const current = readQuestion(hqRoot, questionId, deps);
+            return updateQuestion(hqRoot, questionId, current.version, updater, deps);
+        }
+        catch (err) {
+            last = err;
+            if (!isLaneVersionConflict(err) || i === attempts - 1)
+                throw err;
+        }
+    }
+    throw last;
+}
+export function appendLaneSeniorHistory(hqRoot, laneId, expectedVersion, entry, deps = defaultStoreDeps()) {
+    return updateLane(hqRoot, laneId, expectedVersion, "command", (current) => ({
+        ...current,
+        senior_history: appendCappedHistory(current.senior_history, entry),
+    }), deps);
+}
+export function appendLaneAttribution(hqRoot, laneId, expectedVersion, entry, deps = defaultStoreDeps()) {
+    return updateLane(hqRoot, laneId, expectedVersion, "command", (current) => ({
+        ...current,
+        attribution_history: appendCappedHistory(current.attribution_history, entry),
+    }), deps);
+}
+function syncPendingMarker(hqRoot, question, deps) {
+    const marker = pendingMarkerPath(hqRoot, question.question_id);
+    if (question.status === "pending") {
+        ensureDir(path.dirname(marker), deps);
+        if (!deps.existsSync(marker)) {
+            deps.writeFileSync(marker, "", { encoding: "utf8" });
+        }
+        return;
+    }
+    try {
+        deps.unlinkSync(marker);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT")
+            throw err;
+    }
+}
+export function createQuestion(hqRoot, init, deps = defaultStoreDeps()) {
+    const question_id = init.question_id ?? mintQuestionId(deps);
+    const filePath = questionRecordPath(hqRoot, question_id);
+    const record = {
+        ...init,
+        schema_version: init.schema_version ?? QUESTION_SCHEMA_VERSION,
+        question_id,
+        version: 1,
+        routing_history: init.routing_history ?? [],
+    };
+    parseQuestionRecord(record, filePath);
+    return withRecordLock(filePath, deps, () => {
+        if (deps.existsSync(filePath)) {
+            throw new LanesError("question_exists", `Question ${question_id} already exists`, { question_id });
+        }
+        atomicWriteJson(filePath, record, deps);
+        syncPendingMarker(hqRoot, record, deps);
+        return record;
+    });
+}
+export function updateQuestion(hqRoot, questionId, expectedVersion, updater, deps = defaultStoreDeps()) {
+    const next = casWrite(questionRecordPath(hqRoot, questionId), expectedVersion, parseQuestionRecord, mergeQuestionRecords, updater, deps);
+    syncPendingMarker(hqRoot, next, deps);
+    return next;
+}
+export function appendQuestionRouting(hqRoot, questionId, expectedVersion, entry, deps = defaultStoreDeps()) {
+    return updateQuestion(hqRoot, questionId, expectedVersion, (current) => ({
+        ...current,
+        routing_history: appendCappedHistory(current.routing_history, entry),
+    }), deps);
+}
+function jsonRecordIds(names) {
+    return names
+        .filter((name) => typeof name === "string" &&
+        name.endsWith(".json") &&
+        !name.startsWith(".") &&
+        !name.includes(".conflict-"))
+        .map((name) => name.slice(0, -".json".length));
+}
+/**
+ * Absent directory → empty list. A path that exists but cannot be listed
+ * (ENOTDIR, EACCES, …) is unknown, not empty — throw `store_unreadable`.
+ */
+function listRecordIds(dir, label, deps) {
+    let names;
+    try {
+        names = deps.readdirSync(dir);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return [];
+        throw new LanesError("store_unreadable", `Failed to read ${label} directory ${dir}: ${err instanceof Error ? err.message : String(err)}`, { path: dir });
+    }
+    return jsonRecordIds(names);
+}
+export function listLaneIds(hqRoot, deps = defaultStoreDeps()) {
+    return listRecordIds(path.join(lanesStoreRoot(hqRoot), LANE_RECORDS_DIR), "lane", deps);
+}
+export function listQuestionIds(hqRoot, deps = defaultStoreDeps()) {
+    return listRecordIds(path.join(lanesStoreRoot(hqRoot), QUESTION_RECORDS_DIR), "question", deps);
+}
+//# sourceMappingURL=store.js.map