voratiq 0.1.0-beta.2 → 0.1.0-beta.21

package/dist/persistence/error-mapping.d.ts

@@ -0,0 +1,19 @@
+import { RunHistoryLockTimeoutError } from "../domain/run/model/errors.js";
+import { SessionHistoryLockTimeoutError, SessionOptionValidationError, SessionRecordMutationError, SessionRecordNotFoundError, SessionRecordParseError } from "./errors.js";
+type FileSystemError = NodeJS.ErrnoException & {
+    code: string;
+};
+type HistoryLockTimeoutError = RunHistoryLockTimeoutError | SessionHistoryLockTimeoutError;
+export interface SessionStoreErrorMapper {
+    readonly optionValidation: (error: SessionOptionValidationError) => Error;
+    readonly recordParse: (error: SessionRecordParseError) => Error;
+    readonly recordNotFound: (error: SessionRecordNotFoundError) => Error;
+    readonly recordMutation: (error: SessionRecordMutationError) => Error;
+    readonly historyLockTimeout: (error: HistoryLockTimeoutError) => Error;
+    readonly fileSystem: (error: FileSystemError) => Error;
+    readonly error: (error: Error) => Error;
+    readonly unknown: (error: unknown) => Error;
+}
+export declare function mapSessionStoreError(error: unknown, mapper: SessionStoreErrorMapper): Error;
+export declare const sessionStoreErrorMapper: SessionStoreErrorMapper;
+export {};

package/dist/persistence/error-mapping.js

@@ -0,0 +1,44 @@
+import { RunHistoryLockTimeoutError } from "../domain/run/model/errors.js";
+import { toErrorMessage } from "../utils/errors.js";
+import { isFileSystemError } from "../utils/fs.js";
+import { SessionHistoryLockTimeoutError, SessionOptionValidationError, SessionRecordMutationError, SessionRecordNotFoundError, SessionRecordParseError, } from "./errors.js";
+export function mapSessionStoreError(error, mapper) {
+    if (error instanceof SessionOptionValidationError) {
+        return mapper.optionValidation(error);
+    }
+    if (error instanceof SessionRecordParseError) {
+        return mapper.recordParse(error);
+    }
+    if (error instanceof SessionRecordNotFoundError) {
+        return mapper.recordNotFound(error);
+    }
+    if (error instanceof SessionRecordMutationError) {
+        return mapper.recordMutation(error);
+    }
+    if (error instanceof SessionHistoryLockTimeoutError ||
+        error instanceof RunHistoryLockTimeoutError) {
+        return mapper.historyLockTimeout(error);
+    }
+    if (isFileSystemError(error)) {
+        return mapper.fileSystem(error);
+    }
+    if (error instanceof Error) {
+        return mapper.error(error);
+    }
+    return mapper.unknown(error);
+}
+export const sessionStoreErrorMapper = {
+    optionValidation: (error) => error,
+    recordParse: (error) => error,
+    recordNotFound: (error) => error,
+    recordMutation: (error) => error,
+    historyLockTimeout: (error) => {
+        if (error instanceof SessionHistoryLockTimeoutError) {
+            return error;
+        }
+        return new SessionHistoryLockTimeoutError(error.lockPath);
+    },
+    fileSystem: (error) => new SessionRecordMutationError(toErrorMessage(error)),
+    error: (error) => error,
+    unknown: (error) => new Error(toErrorMessage(error)),
+};

package/dist/persistence/errors.d.ts

@@ -0,0 +1,26 @@
+import { DisplayableError } from "../utils/errors.js";
+export declare abstract class SessionHistoryError extends DisplayableError {
+    constructor(message: string);
+}
+export declare class SessionRecordParseError extends SessionHistoryError {
+    readonly displayPath: string;
+    readonly details: string;
+    constructor(displayPath: string, details: string);
+}
+export declare class SessionRecordNotFoundError extends SessionHistoryError {
+    readonly sessionId: string;
+    constructor(sessionId: string);
+}
+export declare class SessionRecordMutationError extends SessionHistoryError {
+    readonly detail: string;
+    constructor(detail: string);
+}
+export declare class SessionHistoryLockTimeoutError extends SessionHistoryError {
+    readonly lockPath: string;
+    constructor(lockPath: string);
+}
+export declare class SessionOptionValidationError extends SessionHistoryError {
+    readonly option: string;
+    readonly detail: string;
+    constructor(option: string, detail: string);
+}

package/dist/persistence/errors.js

@@ -0,0 +1,49 @@
+import { DisplayableError } from "../utils/errors.js";
+export class SessionHistoryError extends DisplayableError {
+    constructor(message) {
+        super(message);
+    }
+}
+export class SessionRecordParseError extends SessionHistoryError {
+    displayPath;
+    details;
+    constructor(displayPath, details) {
+        super(`Failed to parse \`${displayPath}\`: ${details}`);
+        this.displayPath = displayPath;
+        this.details = details;
+        this.name = "SessionRecordParseError";
+    }
+}
+export class SessionRecordNotFoundError extends SessionHistoryError {
+    sessionId;
+    constructor(sessionId) {
+        super(`Session \`${sessionId}\` not found.`);
+        this.sessionId = sessionId;
+        this.name = "SessionRecordNotFoundError";
+    }
+}
+export class SessionRecordMutationError extends SessionHistoryError {
+    detail;
+    constructor(detail) {
+        super(detail);
+        this.detail = detail;
+        this.name = "SessionRecordMutationError";
+    }
+}
+export class SessionHistoryLockTimeoutError extends SessionHistoryError {
+    lockPath;
+    constructor(lockPath) {
+        super(`Timed out acquiring history lock at \`${lockPath}\`.`);
+        this.lockPath = lockPath;
+        this.name = "SessionHistoryLockTimeoutError";
+    }
+}
+export class SessionOptionValidationError extends SessionHistoryError {
+    option;
+    detail;
+    constructor(option, detail) {
+        super(`Invalid option \`${option}\`: ${detail}`);
+        this.option = option;
+        this.detail = detail;
+    }
+}

package/dist/persistence/extra-context.d.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+export declare const persistedExtraContextPathSchema: z.ZodString;
+export declare const stagedExtraContextPathSchema: z.ZodString;
+export declare const extraContextSourcePathSchema: z.ZodString;
+export declare const extraContextMetadataEntrySchema: z.ZodObject<{
+    stagedPath: z.ZodString;
+    sourcePath: z.ZodString;
+}, z.core.$strip>;
+export type ExtraContextMetadataEntry = z.infer<typeof extraContextMetadataEntrySchema>;

package/dist/persistence/extra-context.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { assertExtraContextSourcePath, assertExtraContextStagedPath, } from "../extra-context/contract.js";
+import { assertRepoRelativePath } from "../utils/path.js";
+function validateLegacyOrStagedExtraContextPath(value, ctx) {
+    try {
+        assertExtraContextStagedPath(value);
+        return;
+    }
+    catch {
+        // Fall through to legacy repo-relative parsing for backwards compatibility.
+    }
+    try {
+        assertRepoRelativePath(value);
+    }
+    catch {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'Path must be a staged session-relative path under "../context/" or a legacy repo-relative path.',
+        });
+    }
+}
+function validateExtraContextStagedPath(value, ctx) {
+    try {
+        assertExtraContextStagedPath(value);
+    }
+    catch (error) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: error instanceof Error
+                ? error.message
+                : 'Path must be staged under "../context/".',
+        });
+    }
+}
+function validateExtraContextSourcePath(value, ctx) {
+    try {
+        assertExtraContextSourcePath(value);
+    }
+    catch (error) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: error instanceof Error
+                ? error.message
+                : "Path must be a non-empty normalized source path.",
+        });
+    }
+}
+export const persistedExtraContextPathSchema = z
+    .string()
+    .superRefine((value, ctx) => validateLegacyOrStagedExtraContextPath(value, ctx));
+export const stagedExtraContextPathSchema = z
+    .string()
+    .superRefine((value, ctx) => validateExtraContextStagedPath(value, ctx));
+export const extraContextSourcePathSchema = z
+    .string()
+    .superRefine((value, ctx) => validateExtraContextSourcePath(value, ctx));
+export const extraContextMetadataEntrySchema = z.object({
+    stagedPath: stagedExtraContextPathSchema,
+    sourcePath: extraContextSourcePathSchema,
+});

package/dist/{records → persistence}/history-lock.js

@@ -3,7 +3,7 @@ import { open, readFile, stat } from "node:fs/promises";
 import process from "node:process";
 import { setTimeout as delay } from "node:timers/promises";
 import { isFileSystemError, safeUnlink } from "../utils/fs.js";
-import { RunHistoryLockTimeoutError } from "./errors.js";
+import { SessionHistoryLockTimeoutError } from "./errors.js";
 const DEFAULT_TIMEOUT_MS = 10_000;
 const DEFAULT_MIN_DELAY_MS = 25;
 const DEFAULT_MAX_DELAY_MS = 750;
@@ -44,7 +44,7 @@ export async function acquireHistoryLock(lockPath, options = {}) {
 }
 function ensureWithinTimeout(lockPath, startedAt, timeoutMs) {
     if (Date.now() - startedAt >= timeoutMs) {
-        throw new RunHistoryLockTimeoutError(lockPath);
+        throw new SessionHistoryLockTimeoutError(lockPath);
     }
 }
 function computeBackoffDelay(attempt, minDelayMs, maxDelayMs) {

package/dist/persistence/record-path-schema.d.ts

@@ -0,0 +1,3 @@
+import { z } from "zod";
+export declare function validateRepoRelativeRecordPath(value: string, ctx: z.RefinementCtx): void;
+export declare const repoRelativeRecordPathSchema: z.ZodString;

package/dist/persistence/record-path-schema.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import { assertRepoRelativePath } from "../utils/path.js";
+export function validateRepoRelativeRecordPath(value, ctx) {
+    try {
+        assertRepoRelativePath(value);
+    }
+    catch (error) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: error instanceof Error ? error.message : "invalid repo-relative path",
+        });
+    }
+}
+export const repoRelativeRecordPathSchema = z
+    .string()
+    .superRefine((value, ctx) => validateRepoRelativeRecordPath(value, ctx));

package/dist/persistence/session-store.d.ts

@@ -0,0 +1,92 @@
+export interface SessionStorePaths {
+    root: string;
+    indexPath: string;
+    sessionsDir: string;
+    lockPath: string;
+}
+export interface SessionRecordWarningMissing {
+    kind: "missing-record";
+    sessionId: string;
+    recordPath: string;
+    displayPath: string;
+}
+export interface SessionRecordWarningParse {
+    kind: "parse-error";
+    sessionId: string;
+    recordPath: string;
+    displayPath: string;
+    details: string;
+}
+export type SessionRecordWarning = SessionRecordWarningMissing | SessionRecordWarningParse;
+export interface ReadSessionRecordsOptions<RecordType> {
+    paths: SessionStorePaths;
+    limit?: number;
+    predicate?: (record: RecordType) => boolean;
+    onWarning?: (warning: SessionRecordWarning) => void;
+}
+export interface AppendSessionRecordOptions<RecordType> {
+    paths: SessionStorePaths;
+    record: RecordType;
+}
+export interface RewriteSessionRecordOptions<RecordType> {
+    paths: SessionStorePaths;
+    sessionId: string;
+    mutate: (record: RecordType) => RecordType;
+    forceFlush?: boolean;
+}
+export interface SessionIndexPayload<Entry> {
+    version: number;
+    sessions: Entry[];
+}
+export type SessionRecordBufferSnapshotEntry = {
+    key: string;
+    sessionId: string;
+    hasFlushTimer: boolean;
+};
+export interface SessionStoreConfig<RecordType, IndexEntry, StatusType> {
+    recordFilename: string;
+    indexVersion: number;
+    acquireLock: (lockPath: string) => Promise<() => Promise<void>>;
+    parseRecord: (input: {
+        path: string;
+        raw: string;
+    }) => RecordType;
+    serializeRecord?: (record: RecordType) => string;
+    buildIndexEntry: (record: RecordType) => IndexEntry;
+    getIndexEntryId: (entry: IndexEntry) => string;
+    mergeIndexEntry?: (existing: IndexEntry, incoming: IndexEntry) => IndexEntry;
+    /**
+     * Optional hook to merge buffered state with the latest on-disk record before
+     * persisting. This is useful when multiple processes can update the same
+     * record (for example, apply operations updating run metadata while a run is
+     * still active in another process).
+     */
+    mergeRecordOnFlush?: (buffered: RecordType, disk: RecordType | undefined) => RecordType;
+    shouldForceFlush: (record: RecordType) => boolean;
+    getRecordId: (record: RecordType) => string;
+    getRecordStatus: (record: RecordType) => StatusType;
+    readIndexEntries?: (parsed: unknown) => IndexEntry[];
+    buildIndexPayload?: (entries: IndexEntry[], version: number) => unknown;
+    extractIdFromRecordPath?: (path: string) => string;
+}
+export declare function createSessionStore<RecordType, IndexEntry, StatusType>(config: SessionStoreConfig<RecordType, IndexEntry, StatusType>): {
+    readRecords: (options: ReadSessionRecordsOptions<RecordType>) => Promise<RecordType[]>;
+    appendRecord: (options: AppendSessionRecordOptions<RecordType>) => Promise<void>;
+    rewriteRecord: (options: RewriteSessionRecordOptions<RecordType>) => Promise<RecordType>;
+    getRecordSnapshot: (options: {
+        paths: SessionStorePaths;
+        sessionId: string;
+    }) => Promise<RecordType | undefined>;
+    flushAllRecordBuffers: () => Promise<void>;
+    disposeRecordBuffer: (options: {
+        paths: SessionStorePaths;
+        sessionId: string;
+    }) => Promise<void>;
+    flushRecordBuffer: (options: {
+        paths: SessionStorePaths;
+        sessionId: string;
+    }) => Promise<void>;
+    snapshotRecordBuffers: () => SessionRecordBufferSnapshotEntry[];
+    setReadRecordsImplementation: (implementation: (options: ReadSessionRecordsOptions<RecordType>) => Promise<RecordType[]>) => void;
+    resetReadRecordsImplementation: () => void;
+};