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

package/dist/domain/run/model/types.js

@@ -0,0 +1,192 @@
+import { z } from "zod";
+import { agentIdSchema } from "../../../configs/agents/types.js";
+import { extraContextMetadataEntrySchema, persistedExtraContextPathSchema, } from "../../../persistence/extra-context.js";
+import { repoRelativeRecordPathSchema } from "../../../persistence/record-path-schema.js";
+import { agentStatusSchema, applyStatusSchema as applyStatusValueSchema, IN_PROGRESS_AGENT_STATUSES, runStatusSchema, TERMINAL_AGENT_STATUSES, TERMINAL_RUN_STATUSES, } from "../../../status/index.js";
+import { validateOperationLifecycleTimestamps, validateRecordLifecycleTimestamps, } from "../../shared/lifecycle.js";
+export { agentStatusSchema, IN_PROGRESS_AGENT_STATUSES, TERMINAL_AGENT_STATUSES, };
+export const runSpecDescriptorSchema = z.object({
+    path: repoRelativeRecordPathSchema,
+});
+const CHAT_ARTIFACT_FORMATS = [
+    "json",
+    "jsonl",
+];
+export const CHAT_USAGE_PROVIDER_IDS = ["claude", "codex", "gemini"];
+const WATCHDOG_TRIGGERS = [
+    "silence",
+    "wall-clock",
+    "fatal-pattern",
+    "sandbox-denial",
+];
+const FAIL_FAST_OPERATIONS = [
+    "network-connect",
+    "file-read",
+    "file-write",
+];
+const QUEUED_RUN_STATUSES = ["queued"];
+const RUNNING_RUN_STATUSES = ["running"];
+export const watchdogMetadataSchema = z.object({
+    /** Silence timeout in milliseconds that was enforced. */
+    silenceTimeoutMs: z.number(),
+    /** Wall-clock cap in milliseconds that was enforced. */
+    wallClockCapMs: z.number(),
+    /** Which watchdog trigger caused termination, if any. */
+    trigger: z.enum(WATCHDOG_TRIGGERS).optional(),
+});
+export const chatUsageProviderIdSchema = z.enum(CHAT_USAGE_PROVIDER_IDS);
+const billingTokenCountSchema = z.number().int().nonnegative();
+const AT_LEAST_ONE_USAGE_FIELD_MESSAGE = "At least one billing-relevant usage field is required.";
+function withAtLeastOneUsageField(shape) {
+    return z
+        .object(shape)
+        .strict()
+        .refine((value) => Object.values(value).some((field) => field !== undefined), {
+        message: AT_LEAST_ONE_USAGE_FIELD_MESSAGE,
+    });
+}
+export const claudeExtractedTokenUsageSchema = withAtLeastOneUsageField({
+    input_tokens: billingTokenCountSchema.optional(),
+    output_tokens: billingTokenCountSchema.optional(),
+    cache_read_input_tokens: billingTokenCountSchema.optional(),
+    cache_creation_input_tokens: billingTokenCountSchema.optional(),
+});
+export const codexExtractedTokenUsageSchema = withAtLeastOneUsageField({
+    input_tokens: billingTokenCountSchema.optional(),
+    cached_input_tokens: billingTokenCountSchema.optional(),
+    output_tokens: billingTokenCountSchema.optional(),
+    reasoning_output_tokens: billingTokenCountSchema.optional(),
+    total_tokens: billingTokenCountSchema.optional(),
+});
+export const geminiExtractedTokenUsageSchema = withAtLeastOneUsageField({
+    input: billingTokenCountSchema.optional(),
+    output: billingTokenCountSchema.optional(),
+    cached: billingTokenCountSchema.optional(),
+    thoughts: billingTokenCountSchema.optional(),
+    tool: billingTokenCountSchema.optional(),
+    total: billingTokenCountSchema.optional(),
+});
+export const extractedTokenUsageSchemaByProvider = {
+    claude: claudeExtractedTokenUsageSchema,
+    codex: codexExtractedTokenUsageSchema,
+    gemini: geminiExtractedTokenUsageSchema,
+};
+export const extractedTokenUsageSchema = z.union([
+    claudeExtractedTokenUsageSchema,
+    codexExtractedTokenUsageSchema,
+    geminiExtractedTokenUsageSchema,
+]);
+export const agentArtifactStateSchema = z.object({
+    diffAttempted: z.boolean().optional(),
+    diffCaptured: z.boolean().optional(),
+    stdoutCaptured: z.boolean().optional(),
+    stderrCaptured: z.boolean().optional(),
+    summaryCaptured: z.boolean().optional(),
+    chatCaptured: z.boolean().optional(),
+    chatFormat: z.enum(CHAT_ARTIFACT_FORMATS).optional(),
+});
+export const agentInvocationRecordSchema = z
+    .object({
+    agentId: agentIdSchema,
+    model: z.string(),
+    status: agentStatusSchema,
+    startedAt: z.string().optional(),
+    completedAt: z.string().optional(),
+    commitSha: z.string().optional(),
+    artifacts: agentArtifactStateSchema.optional(),
+    error: z.string().optional(),
+    warnings: z.array(z.string()).optional(),
+    diffStatistics: z.string().optional(),
+    tokenUsage: extractedTokenUsageSchema.optional(),
+    watchdog: watchdogMetadataSchema.optional(),
+    failFastTriggered: z.boolean().optional(),
+    failFastTarget: z.string().optional(),
+    failFastOperation: z.enum(FAIL_FAST_OPERATIONS).optional(),
+})
+    .superRefine((data, ctx) => {
+    validateOperationLifecycleTimestamps({
+        status: data.status,
+        startedAt: data.startedAt,
+        completedAt: data.completedAt,
+    }, ctx, {
+        queued: ["queued"],
+        running: ["running"],
+        terminal: TERMINAL_AGENT_STATUSES,
+    });
+    if (data.failFastTriggered) {
+        if (!data.failFastTarget) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["failFastTarget"],
+                message: "failFastTarget is required when failFastTriggered is true",
+            });
+        }
+        if (!data.failFastOperation) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["failFastOperation"],
+                message: "failFastOperation is required when failFastTriggered is true",
+            });
+        }
+    }
+});
+export const applyStatusSchema = z.object({
+    agentId: agentIdSchema,
+    status: applyStatusValueSchema,
+    appliedAt: z.string(),
+    ignoredBaseMismatch: z.boolean(),
+    appliedCommitSha: z.string().min(1).optional(),
+    detail: z.string().max(256).nullable().optional(),
+});
+export const AUTO_TERMINAL_STATUS_VALUES = [
+    "succeeded",
+    "failed",
+    "action_required",
+];
+export const autoTerminalStatusSchema = z.enum(AUTO_TERMINAL_STATUS_VALUES);
+export const AUTO_APPLY_STATUS_VALUES = [
+    "succeeded",
+    "failed",
+    "skipped",
+];
+export const autoApplyStatusSchema = z.enum(AUTO_APPLY_STATUS_VALUES);
+export const autoOutcomeSchema = z.object({
+    status: autoTerminalStatusSchema,
+    completedAt: z.string(),
+    detail: z.string().max(256).nullable().optional(),
+    apply: z.object({
+        status: autoApplyStatusSchema,
+        agentId: agentIdSchema.optional(),
+        detail: z.string().max(256).nullable().optional(),
+    }),
+});
+export const runRecordSchema = z
+    .object({
+    runId: z.string(),
+    baseRevisionSha: z.string(),
+    rootPath: repoRelativeRecordPathSchema,
+    spec: runSpecDescriptorSchema,
+    extraContext: z.array(persistedExtraContextPathSchema).optional(),
+    extraContextMetadata: z.array(extraContextMetadataEntrySchema).optional(),
+    status: runStatusSchema,
+    createdAt: z.string(),
+    startedAt: z.string().optional(),
+    completedAt: z.string().optional(),
+    agents: z.array(agentInvocationRecordSchema),
+    applyStatus: applyStatusSchema.optional(),
+    auto: autoOutcomeSchema.optional(),
+    deletedAt: z.string().nullable().optional(),
+})
+    .superRefine((record, ctx) => {
+    // Enforce the canonical queued/running/terminal timestamp contract.
+    validateRecordLifecycleTimestamps({
+        status: record.status,
+        createdAt: record.createdAt,
+        startedAt: record.startedAt,
+        completedAt: record.completedAt,
+    }, ctx, {
+        queued: QUEUED_RUN_STATUSES,
+        running: RUNNING_RUN_STATUSES,
+        terminal: TERMINAL_RUN_STATUSES,
+    });
+});

package/dist/{records/persistence.d.ts → domain/run/persistence/adapter.d.ts}

@@ -1,5 +1,5 @@
-import { type RunRecord } from "./types.js";
-export { HISTORY_LOCK_STALE_GRACE_MS } from "./history-lock.js";
+import { type RunRecord } from "../model/types.js";
+export { HISTORY_LOCK_STALE_GRACE_MS } from "../../../persistence/history-lock.js";
 export type RunRecordPredicate = (record: RunRecord) => boolean;
 export interface RunRecordWarningMissing {
     kind: "missing-record";
@@ -27,6 +27,12 @@ export interface RewriteRunRecordOptions {
     runsFilePath: string;
     runId: string;
     mutate: (record: RunRecord) => RunRecord;
+    /**
+     * When true, forces an immediate flush of the rewritten record even if the
+     * run is still active. This is useful for callers (like apply) that must
+     * persist state before the process exits.
+     */
+    forceFlush?: boolean;
 }
 export interface RunQueryFilters {
     runId?: string;
@@ -56,12 +62,12 @@ export interface RunIndexPayload {
     version: number;
     sessions: RunIndexEntry[];
 }
-export declare const RUN_RECORD_FILENAME = "record.json";
 export type RunRecordBufferSnapshotEntry = {
     key: string;
     runId: string;
     hasFlushTimer: boolean;
 };
+export declare const RUN_RECORD_FILENAME = "record.json";
 export declare function readRunRecords(options: ReadRunRecordsOptions): Promise<RunRecord[]>;
 export declare function appendRunRecord(options: AppendRunRecordOptions): Promise<void>;
 export declare function rewriteRunRecord(options: RewriteRunRecordOptions): Promise<RunRecord>;

package/dist/domain/run/persistence/adapter.js

@@ -0,0 +1,340 @@
+import { dirname, join } from "node:path";
+import { mapSessionStoreError } from "../../../persistence/error-mapping.js";
+import { SessionRecordParseError } from "../../../persistence/errors.js";
+import { acquireHistoryLock } from "../../../persistence/history-lock.js";
+import { createSessionStore, } from "../../../persistence/session-store.js";
+import { assertTestHookRegistrationEnabled } from "../../../testing/test-hooks.js";
+import { isFileSystemError } from "../../../utils/fs.js";
+import { RunRecordNotFoundError, RunRecordParseError, } from "../model/errors.js";
+import { runRecordSchema, } from "../model/types.js";
+import { runStoreErrorMapper } from "./error-mapping.js";
+export { HISTORY_LOCK_STALE_GRACE_MS } from "../../../persistence/history-lock.js";
+const RUN_INDEX_VERSION = 2;
+export const RUN_RECORD_FILENAME = "record.json";
+const HISTORY_LOCK_FILENAME = "history.lock";
+const runPersistence = createSessionStore({
+    recordFilename: RUN_RECORD_FILENAME,
+    indexVersion: RUN_INDEX_VERSION,
+    acquireLock: acquireHistoryLock,
+    parseRecord: ({ path, raw }) => {
+        const parsed = JSON.parse(raw);
+        const result = runRecordSchema.safeParse(parsed);
+        if (!result.success) {
+            const issues = result.error.issues
+                .map((issue) => issue.message)
+                .join(", ");
+            throw new SessionRecordParseError(path, issues);
+        }
+        return result.data;
+    },
+    mergeRecordOnFlush: (buffered, disk) => mergeRunMetaStatus(buffered, disk),
+    buildIndexEntry: (record) => ({
+        runId: record.runId,
+        createdAt: record.createdAt,
+        status: record.status,
+    }),
+    getIndexEntryId: (entry) => entry.runId,
+    shouldForceFlush: (record) => shouldForceFlush(record.status),
+    getRecordId: (record) => record.runId,
+    getRecordStatus: (record) => record.status,
+    readIndexEntries: (parsed) => {
+        const payload = parsed;
+        return Array.isArray(payload.sessions) ? payload.sessions : [];
+    },
+});
+const readRunRecordsInternal = async (options) => {
+    const { root, runsFilePath, limit, predicate, onWarning } = options;
+    const paths = buildRunPaths(root, runsFilePath);
+    try {
+        return await runPersistence.readRecords({
+            paths,
+            limit,
+            predicate,
+            onWarning: onWarning
+                ? (warning) => onWarning(mapWarning(warning))
+                : undefined,
+        });
+    }
+    catch (error) {
+        throw mapSessionStoreError(error, runStoreErrorMapper);
+    }
+};
+let readRunRecordsImpl = readRunRecordsInternal;
+function setReadRunRecordsImplementation(implementation) {
+    readRunRecordsImpl = implementation;
+}
+function resetReadRunRecordsImplementation() {
+    readRunRecordsImpl = readRunRecordsInternal;
+}
+export async function readRunRecords(options) {
+    return readRunRecordsImpl(options);
+}
+export async function appendRunRecord(options) {
+    const { root, runsFilePath, record } = options;
+    const paths = buildRunPaths(root, runsFilePath);
+    try {
+        await runPersistence.appendRecord({ paths, record });
+    }
+    catch (error) {
+        throw mapSessionStoreError(error, runStoreErrorMapper);
+    }
+}
+export async function rewriteRunRecord(options) {
+    const { root, runsFilePath, runId, mutate, forceFlush = false } = options;
+    const paths = buildRunPaths(root, runsFilePath);
+    try {
+        return await runPersistence.rewriteRecord({
+            paths,
+            sessionId: runId,
+            mutate,
+            forceFlush,
+        });
+    }
+    catch (error) {
+        throw mapSessionStoreError(error, runStoreErrorMapper);
+    }
+}
+export async function getRunRecordSnapshot(options) {
+    const { runsFilePath, runId } = options;
+    const paths = buildRunPaths("", runsFilePath);
+    try {
+        return await runPersistence.getRecordSnapshot({
+            paths,
+            sessionId: runId,
+        });
+    }
+    catch (error) {
+        throw mapSessionStoreError(error, runStoreErrorMapper);
+    }
+}
+export async function flushAllRunRecordBuffers() {
+    await runPersistence.flushAllRecordBuffers();
+}
+export async function disposeRunRecordBuffer(options) {
+    const { runsFilePath, runId } = options;
+    const paths = buildRunPaths("", runsFilePath);
+    await runPersistence.disposeRecordBuffer({ paths, sessionId: runId });
+}
+export async function flushRunRecordBuffer(options) {
+    const { runsFilePath, runId } = options;
+    const paths = buildRunPaths("", runsFilePath);
+    await runPersistence.flushRecordBuffer({ paths, sessionId: runId });
+}
+export function buildRunPredicate(filters = {}) {
+    const predicates = [];
+    if (filters.runId) {
+        const runId = filters.runId;
+        predicates.push((record) => record.runId === runId);
+    }
+    if (filters.agentId) {
+        const agentId = filters.agentId;
+        predicates.push((record) => record.agents.some((agent) => agent.agentId === agentId));
+    }
+    if (filters.specPath) {
+        const specPath = filters.specPath;
+        predicates.push((record) => record.spec.path === specPath);
+    }
+    if (filters.activeOnly || !filters.includeDeleted) {
+        predicates.push((record) => record.status !== "pruned");
+    }
+    return (record) => predicates.every((predicate) => predicate(record));
+}
+export async function fetchRuns(input) {
+    const warnings = [];
+    const predicate = buildRunPredicate(input.filters ?? {});
+    const records = await readRunRecords({
+        root: input.root,
+        runsFilePath: input.runsFilePath,
+        limit: input.limit,
+        predicate,
+        onWarning: (warning) => warnings.push(warning),
+    });
+    return { records, warnings };
+}
+export async function fetchRunsSafely(input) {
+    const { runId, filters, ...rest } = input;
+    const augmentedFilters = { ...(filters ?? {}), ...(runId ? { runId } : {}) };
+    const result = await fetchRuns({
+        ...rest,
+        filters: augmentedFilters,
+    }).catch((error) => {
+        if (runId && isFileSystemError(error) && error.code === "ENOENT") {
+            throw new RunRecordNotFoundError(runId);
+        }
+        throw error;
+    });
+    if (runId) {
+        const warning = result.warnings.find((entry) => entry.runId === runId);
+        if (warning) {
+            if (warning.kind === "parse-error") {
+                throw new RunRecordParseError(warning.displayPath, warning.details);
+            }
+            throw new RunRecordNotFoundError(runId);
+        }
+        if (result.records.length === 0) {
+            throw new RunRecordNotFoundError(runId);
+        }
+    }
+    return result;
+}
+function shouldForceFlush(status) {
+    return status !== "running" && status !== "queued";
+}
+function mergeRunMetaStatus(buffered, disk) {
+    const latest = pickLatestApplyStatus(buffered.applyStatus, disk?.applyStatus);
+    const latestAuto = pickLatestAutoOutcome(buffered.auto, disk?.auto);
+    let merged = buffered;
+    if (latest) {
+        const bufferedStatus = buffered.applyStatus;
+        if (!bufferedStatus || !areSameApplyStatus(bufferedStatus, latest)) {
+            merged = {
+                ...merged,
+                applyStatus: { ...latest },
+            };
+        }
+    }
+    if (latestAuto) {
+        const bufferedAuto = merged.auto;
+        if (!bufferedAuto || !areSameAutoOutcome(bufferedAuto, latestAuto)) {
+            merged = {
+                ...merged,
+                auto: {
+                    ...latestAuto,
+                    apply: {
+                        ...latestAuto.apply,
+                    },
+                },
+            };
+        }
+    }
+    return merged;
+}
+function pickLatestApplyStatus(buffered, disk) {
+    if (!buffered) {
+        return disk;
+    }
+    if (!disk) {
+        return buffered;
+    }
+    return compareApplyStatus(buffered, disk) >= 0 ? buffered : disk;
+}
+function compareApplyStatus(a, b) {
+    const aTime = Date.parse(a.appliedAt);
+    const bTime = Date.parse(b.appliedAt);
+    const aValid = Number.isFinite(aTime);
+    const bValid = Number.isFinite(bTime);
+    if (aValid && bValid) {
+        return aTime - bTime;
+    }
+    if (aValid) {
+        return 1;
+    }
+    if (bValid) {
+        return -1;
+    }
+    return a.appliedAt.localeCompare(b.appliedAt);
+}
+function areSameApplyStatus(a, b) {
+    return (a.agentId === b.agentId &&
+        a.status === b.status &&
+        a.appliedAt === b.appliedAt &&
+        a.ignoredBaseMismatch === b.ignoredBaseMismatch &&
+        a.appliedCommitSha === b.appliedCommitSha &&
+        (a.detail ?? undefined) === (b.detail ?? undefined));
+}
+function pickLatestAutoOutcome(buffered, disk) {
+    if (!buffered) {
+        return disk;
+    }
+    if (!disk) {
+        return buffered;
+    }
+    return compareAutoOutcome(buffered, disk) >= 0 ? buffered : disk;
+}
+function compareAutoOutcome(a, b) {
+    const aTime = Date.parse(a.completedAt);
+    const bTime = Date.parse(b.completedAt);
+    const aValid = Number.isFinite(aTime);
+    const bValid = Number.isFinite(bTime);
+    if (aValid && bValid) {
+        return aTime - bTime;
+    }
+    if (aValid) {
+        return 1;
+    }
+    if (bValid) {
+        return -1;
+    }
+    return a.completedAt.localeCompare(b.completedAt);
+}
+function areSameAutoOutcome(a, b) {
+    return (a.status === b.status &&
+        a.completedAt === b.completedAt &&
+        (a.detail ?? undefined) === (b.detail ?? undefined) &&
+        a.apply.status === b.apply.status &&
+        (a.apply.agentId ?? undefined) === (b.apply.agentId ?? undefined) &&
+        (a.apply.detail ?? undefined) === (b.apply.detail ?? undefined));
+}
+function buildRunPaths(root, runsFilePath) {
+    const runsRoot = getRunsDirectory(runsFilePath);
+    return {
+        root,
+        indexPath: runsFilePath,
+        sessionsDir: getSessionsDirectory(runsFilePath),
+        lockPath: join(runsRoot, HISTORY_LOCK_FILENAME),
+    };
+}
+function getRunsDirectory(runsFilePath) {
+    return dirname(runsFilePath);
+}
+function getSessionsDirectory(runsFilePath) {
+    return join(getRunsDirectory(runsFilePath), "sessions");
+}
+function mapWarning(warning) {
+    if (warning.kind === "parse-error") {
+        const parseWarning = warning;
+        return {
+            kind: "parse-error",
+            runId: parseWarning.sessionId,
+            recordPath: parseWarning.recordPath,
+            displayPath: parseWarning.displayPath,
+            details: parseWarning.details,
+        };
+    }
+    const missingWarning = warning;
+    return {
+        kind: "missing-record",
+        runId: missingWarning.sessionId,
+        recordPath: missingWarning.recordPath,
+        displayPath: missingWarning.displayPath,
+    };
+}
+const RUN_RECORDS_TEST_HOOKS = Symbol.for("voratiq.records.persistence.testHooks");
+function registerRunRecordsTestHooks() {
+    const registry = globalThis;
+    registry[RUN_RECORDS_TEST_HOOKS] = {
+        setImplementation: setReadRunRecordsImplementation,
+        resetImplementation: resetReadRunRecordsImplementation,
+        getBufferSnapshot: snapshotRunRecordBuffers,
+    };
+}
+function snapshotRunRecordBuffers() {
+    return runPersistence.snapshotRecordBuffers().map((entry) => ({
+        key: entry.key,
+        runId: entry.sessionId,
+        hasFlushTimer: entry.hasFlushTimer,
+    }));
+}
+let runRecordsTestHooksRegistered = false;
+export function enableRunRecordsTestHooks() {
+    assertTestHookRegistrationEnabled("records persistence");
+    if (runRecordsTestHooksRegistered) {
+        return;
+    }
+    registerRunRecordsTestHooks();
+    runRecordsTestHooksRegistered = true;
+}
+export function areRunRecordsTestHooksRegistered() {
+    return runRecordsTestHooksRegistered;
+}
+export { RUN_RECORDS_TEST_HOOKS };

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

@@ -0,0 +1,2 @@
+import { type SessionStoreErrorMapper } from "../../../persistence/error-mapping.js";
+export declare const runStoreErrorMapper: SessionStoreErrorMapper;

package/dist/domain/run/persistence/error-mapping.js

@@ -0,0 +1,17 @@
+import { toErrorMessage } from "../../../utils/errors.js";
+import { RunHistoryLockTimeoutError, RunOptionValidationError, RunRecordMutationError, RunRecordNotFoundError, RunRecordParseError, } from "../model/errors.js";
+export const runStoreErrorMapper = {
+    optionValidation: (error) => new RunOptionValidationError(error.option, error.detail),
+    recordParse: (error) => new RunRecordParseError(error.displayPath, error.details),
+    recordNotFound: (error) => new RunRecordNotFoundError(error.sessionId),
+    recordMutation: (error) => new RunRecordMutationError(error.detail),
+    historyLockTimeout: (error) => {
+        if (error instanceof RunHistoryLockTimeoutError) {
+            return error;
+        }
+        return new RunHistoryLockTimeoutError(error.lockPath);
+    },
+    fileSystem: (error) => new RunRecordMutationError(toErrorMessage(error)),
+    error: (error) => error,
+    unknown: (error) => new Error(toErrorMessage(error)),
+};

package/dist/domain/shared/lifecycle.d.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+export interface LifecycleStatusGroups<TStatus extends string> {
+    queued: readonly TStatus[];
+    running: readonly TStatus[];
+    terminal: readonly TStatus[];
+}
+interface TimestampLifecycleRecord<TStatus extends string> {
+    status: TStatus;
+    startedAt?: string;
+    completedAt?: string;
+}
+export interface LifecycleExecutionDurationInput<TStatus extends string> {
+    status: TStatus;
+    startedAt?: string;
+    completedAt?: string;
+}
+interface RecordTimestampLifecycle<TStatus extends string> extends TimestampLifecycleRecord<TStatus> {
+    createdAt: string;
+}
+export declare function resolveLifecycleExecutionDurationMs<TStatus extends string>(lifecycle: LifecycleExecutionDurationInput<TStatus>, options: {
+    statusGroups: Pick<LifecycleStatusGroups<TStatus>, "running" | "terminal">;
+    now?: number;
+}): number | undefined;
+export declare function validateRecordLifecycleTimestamps<TStatus extends string>(record: RecordTimestampLifecycle<TStatus>, ctx: z.RefinementCtx, groups: LifecycleStatusGroups<TStatus>): void;
+export declare function validateOperationLifecycleTimestamps<TStatus extends string>(record: TimestampLifecycleRecord<TStatus>, ctx: z.RefinementCtx, groups: LifecycleStatusGroups<TStatus>): void;
+export declare function buildLifecycleStartFields(options: {
+    existingStartedAt: string | undefined;
+    timestamp?: string;
+}): {
+    startedAt: string;
+};
+export declare function buildRecordLifecycleCompleteFields(options: {
+    existing: {
+        startedAt?: string;
+        completedAt?: string;
+    };
+    startedAt?: string;
+    completedAt?: string;
+}): {
+    startedAt: string;
+    completedAt: string;
+};
+export declare function buildOperationLifecycleCompleteFields(options: {
+    existing: {
+        startedAt?: string;
+        completedAt?: string;
+    };
+    startedAt?: string;
+    completedAt?: string;
+}): {
+    startedAt: string;
+    completedAt: string;
+};
+export {};