@indigoai-us/hq-cli 5.126.0 → 5.127.0

package/dist/lib/lanes/store.d.ts

@@ -7,7 +7,7 @@
  * compare-and-set on `version`. Histories are capped at 50 at the append site.
  */
 import * as fs from "node:fs";
-import { type AttributionHistoryEntry, type LaneRecord, type QuestionRecord, type RoutingHistoryEntry, type SeniorHistoryEntry } from "./types.js";
+import { type AttributionHistoryEntry, type LaneRecord, type LaneWriter, type QuestionRecord, type RoutingHistoryEntry, type SeniorHistoryEntry } from "./types.js";
 export declare const LANES_STORE_REL: string;
 export declare const LANE_RECORDS_DIR = "lanes";
 export declare const QUESTION_RECORDS_DIR = "questions";
@@ -27,7 +27,7 @@ export interface StoreDeps {
     fsyncSync: typeof fs.fsyncSync;
     chmodSync: typeof fs.chmodSync;
 }
-export declare function resolveStoreHqRoot(hqRoot?: string): string;
+export declare function resolveStoreHqRoot(hqRoot?: string, env?: NodeJS.ProcessEnv, cwd?: string): string;
 export declare function lanesStoreRoot(hqRoot?: string): string;
 export declare function laneRecordPath(hqRoot: string, laneId: string): string;
 export declare function questionRecordPath(hqRoot: string, questionId: string): string;
@@ -53,7 +53,11 @@ export declare function readLane(hqRoot: string, laneId: string, deps?: StoreDep
 export declare function tryReadQuestion(hqRoot: string, questionId: string, deps?: StoreDeps): QuestionRecord | null;
 export declare function readQuestion(hqRoot: string, questionId: string, deps?: StoreDeps): QuestionRecord;
 export declare function createLane(hqRoot: string, init: Omit<LaneRecord, "schema_version" | "lane_id" | "version" | "created_at" | "updated_at"> & Partial<Pick<LaneRecord, "schema_version" | "lane_id" | "version" | "created_at" | "updated_at">>, deps?: StoreDeps): LaneRecord;
-export declare function updateLane(hqRoot: string, laneId: string, expectedVersion: number, updater: (current: LaneRecord) => LaneRecord, deps?: StoreDeps): LaneRecord;
+export declare function updateLane(hqRoot: string, laneId: string, expectedVersion: number, writer: LaneWriter, updater: (current: LaneRecord) => LaneRecord, deps?: StoreDeps): LaneRecord;
+/** Compare-and-set with conflict retry. Callers that race a concurrent writer re-read. */
+export declare function retryUpdateLane(hqRoot: string, laneId: string, writer: LaneWriter, updater: (current: LaneRecord) => LaneRecord, deps?: StoreDeps, attempts?: number): LaneRecord;
+/** Compare-and-set with conflict retry for question records (spec §6.2). */
+export declare function retryUpdateQuestion(hqRoot: string, questionId: string, updater: (current: QuestionRecord) => QuestionRecord, deps?: StoreDeps, attempts?: number): QuestionRecord;
 export declare function appendLaneSeniorHistory(hqRoot: string, laneId: string, expectedVersion: number, entry: SeniorHistoryEntry, deps?: StoreDeps): LaneRecord;
 export declare function appendLaneAttribution(hqRoot: string, laneId: string, expectedVersion: number, entry: AttributionHistoryEntry, deps?: StoreDeps): LaneRecord;
 export declare function createQuestion(hqRoot: string, init: Omit<QuestionRecord, "schema_version" | "question_id" | "version"> & Partial<Pick<QuestionRecord, "schema_version" | "question_id" | "version">>, deps?: StoreDeps): QuestionRecord;

package/dist/lib/lanes/store.js

@@ -11,9 +11,9 @@ 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 { findHqRoot } from "../../utils/manifest.js";
-import { LaneNotFoundError, LaneSchemaError, LaneVersionConflict, LanesError, } from "./errors.js";
-import { HISTORY_CAP, HOST_KINDS, LANE_SCHEMA_VERSION, QUESTION_SCHEMA_VERSION, SENIOR_KINDS, isHostKind, isLaneProvider, isLaneState, isQuestionStatus, isSeniorKind, parseMajorSchema, } from "./types.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";
@@ -38,8 +38,8 @@ function defaultStoreDeps() {
         chmodSync: fs.chmodSync.bind(fs),
     };
 }
-export function resolveStoreHqRoot(hqRoot) {
-    return hqRoot ?? findHqRoot();
+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);
@@ -250,12 +250,35 @@ function requireInt(value, 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");
@@ -270,11 +293,7 @@ export function parseLaneRecord(raw, filePath) {
     if (!isLaneProvider(raw.provider)) {
         throw new LaneSchemaError(`Unknown provider ${JSON.stringify(raw.provider)}`, { path: filePath, value: raw.provider });
     }
-    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");
+    parseOptionalCompanyField(raw, filePath);
     if (!isPlainObject(raw.senior)) {
         throw new LaneSchemaError("senior must be an object", { path: filePath });
     }
@@ -330,6 +349,7 @@ export function parseQuestionRecord(raw, filePath) {
     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 });
     }
@@ -338,6 +358,13 @@ export function parseQuestionRecord(raw, filePath) {
             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;
 }
 /**
@@ -378,9 +405,13 @@ function canonicalJson(value) {
     return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(obj[key])}`).join(",")}}`;
 }
 function historyTimestamp(entry) {
-    if (!isPlainObject(entry) || typeof entry.at !== "string")
+    if (!isPlainObject(entry))
         return "";
-    return entry.at;
+    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).
@@ -395,6 +426,12 @@ function attributionIdentity(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) {
@@ -438,6 +475,7 @@ export function mergeQuestionRecords(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),
     };
 }
@@ -487,6 +525,17 @@ export function readQuestion(hqRoot, questionId, deps = defaultStoreDeps()) {
         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);
@@ -503,6 +552,9 @@ function casWrite(filePath, expectedVersion, parse, merge, updater, deps) {
             });
         }
         const updated = updater(current);
+        if (recordsEquivalentAsideFromClock(current, updated)) {
+            return current;
+        }
         const next = {
             ...current,
             ...updated,
@@ -536,17 +588,76 @@ export function createLane(hqRoot, init, deps = defaultStoreDeps()) {
         return record;
     });
 }
-export function updateLane(hqRoot, laneId, expectedVersion, updater, deps = defaultStoreDeps()) {
-    return casWrite(laneRecordPath(hqRoot, laneId), expectedVersion, parseLaneRecord, mergeLaneRecords, updater, deps);
+/** 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, (current) => ({
+    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, (current) => ({
+    return updateLane(hqRoot, laneId, expectedVersion, "command", (current) => ({
         ...current,
         attribution_history: appendCappedHistory(current.attribution_history, entry),
     }), deps);
@@ -600,28 +711,35 @@ export function appendQuestionRouting(hqRoot, questionId, expectedVersion, entry
         routing_history: appendCappedHistory(current.routing_history, entry),
     }), deps);
 }
-export function listLaneIds(hqRoot, deps = defaultStoreDeps()) {
-    const dir = path.join(lanesStoreRoot(hqRoot), LANE_RECORDS_DIR);
-    if (!deps.existsSync(dir))
-        return [];
-    return deps
-        .readdirSync(dir)
+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()) {
-    const dir = path.join(lanesStoreRoot(hqRoot), QUESTION_RECORDS_DIR);
-    if (!deps.existsSync(dir))
-        return [];
-    return deps
-        .readdirSync(dir)
-        .filter((name) => typeof name === "string" &&
-        name.endsWith(".json") &&
-        !name.startsWith(".") &&
-        !name.includes(".conflict-"))
-        .map((name) => name.slice(0, -".json".length));
+    return listRecordIds(path.join(lanesStoreRoot(hqRoot), QUESTION_RECORDS_DIR), "question", deps);
 }
 //# sourceMappingURL=store.js.map