@indigoai-us/hq-cli 5.125.0 → 5.127.0

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

@@ -0,0 +1,68 @@
+/**
+ * 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 * as fs from "node:fs";
+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";
+export declare const PENDING_INDEX_DIR: string;
+export interface StoreDeps {
+    now: () => Date;
+    hostname: () => string;
+    mkdirSync: typeof fs.mkdirSync;
+    readFileSync: typeof fs.readFileSync;
+    writeFileSync: typeof fs.writeFileSync;
+    renameSync: typeof fs.renameSync;
+    unlinkSync: typeof fs.unlinkSync;
+    existsSync: typeof fs.existsSync;
+    readdirSync: typeof fs.readdirSync;
+    openSync: typeof fs.openSync;
+    closeSync: typeof fs.closeSync;
+    fsyncSync: typeof fs.fsyncSync;
+    chmodSync: typeof fs.chmodSync;
+}
+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;
+export declare function pendingMarkerPath(hqRoot: string, questionId: string): string;
+export declare function sanitizeHostComponent(hostname: string): string;
+/** Collision-safe across machines: ULID plus a host component. */
+export declare function mintLaneId(deps?: Pick<StoreDeps, "now" | "hostname">): string;
+export declare function mintQuestionId(deps?: Pick<StoreDeps, "now" | "hostname">): string;
+export declare function appendCappedHistory<T>(history: readonly T[], entry: T, cap?: number): T[];
+export declare function parseLaneRecord(raw: unknown, filePath?: string): LaneRecord;
+export declare function parseQuestionRecord(raw: unknown, filePath?: string): QuestionRecord;
+/**
+ * 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 declare function isConflictSidecarName(recordBasename: string, name: string): boolean;
+export declare function mergeLaneRecords(live: LaneRecord, sidecars: readonly LaneRecord[]): LaneRecord;
+export declare function mergeQuestionRecords(live: QuestionRecord, sidecars: readonly QuestionRecord[]): QuestionRecord;
+export declare function tryReadLane(hqRoot: string, laneId: string, deps?: StoreDeps): LaneRecord | null;
+export declare function readLane(hqRoot: string, laneId: string, deps?: StoreDeps): LaneRecord;
+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, 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;
+export declare function updateQuestion(hqRoot: string, questionId: string, expectedVersion: number, updater: (current: QuestionRecord) => QuestionRecord, deps?: StoreDeps): QuestionRecord;
+export declare function appendQuestionRouting(hqRoot: string, questionId: string, expectedVersion: number, entry: RoutingHistoryEntry, deps?: StoreDeps): QuestionRecord;
+export declare function listLaneIds(hqRoot: string, deps?: StoreDeps): string[];
+export declare function listQuestionIds(hqRoot: string, deps?: StoreDeps): string[];
+//# sourceMappingURL=store.d.ts.map