@struktoai/mirage-core/dist/observe/record.d.ts

A Unified Virtual Filesystem For AI Agents

import type { Clock } from '../utils/clock.ts';
export declare const READ_FINGERPRINT_OPS: ReadonlySet<string>;
export declare const WRITE_FINGERPRINT_OPS: ReadonlySet<string>;
export declare const STAMP_FINGERPRINT_OPS: ReadonlySet<string>;
export declare const CONTENT_CHANGING_OPS: ReadonlySet<string>;
export declare const RETRACT_FINGERPRINT_OPS: ReadonlySet<string>;
export declare const REMOVAL_OPS: ReadonlySet<string>;
export declare const VERSION_OPS: ReadonlySet<string>;
export declare const SUBTREE_RETRACT_OPS: ReadonlySet<string>;
/**
 * A line's records indexed as they arrive, for per-path version lookups.
 * Each lookup first takes in the records appended since the last one, so a
 * record added while a caller awaits is seen, and no record is read twice.
 * The records are only ever appended to. Mirrors Python's `RecordIndex`.
 */
export declare class RecordIndex {
    private readonly records;
    private seen;
    private readonly at;
    private readonly subtree;
    constructor(records: readonly OpRecord[]);
    private absorb;
    /**
     * The newest record that says which version of `key` the line knows: one
     * at the path that stamps or retracts a version, or one at an ancestor
     * that moved the whole subtree, which took `key` with it. Mirrors
     * Python's `RecordIndex.newest_version`.
     */
    newestVersion(key: string): OpRecord | null;
}
export declare class OpRecord {
    /** In-process transfer lifecycle; excluded from serialized observations. */
    complete: boolean;
    readonly executionId: string | null;
    readonly op: string;
    readonly path: string;
    readonly source: string;
    bytes: number;
    readonly timestamp: number;
    durationMs: number;
    fingerprint: string | null;
    revision: string | null;
    readonly mountId: string | null;
    constructor(init: Pick<OpRecord, 'op' | 'path' | 'source' | 'bytes' | 'timestamp' | 'durationMs'> & Partial<Pick<OpRecord, 'executionId' | 'fingerprint' | 'revision' | 'mountId'>>);
    get isCache(): boolean;
    toJSON(): Record<string, unknown>;
    toDict(): Record<string, unknown>;
}
/**
 * A line's recording: its records, the mount serving them, the workspace
 * ledger the line hands its records to when it ends (null for a file call's
 * own recording, which no other call joins), and the workspace clock every
 * op recorded here is timed and stamped on.
 */
export interface Recorder {
    records: OpRecord[];
    mountId: string | null;
    ledger: OpRecord[] | null;
    clock: Clock;
}
/**
 * Per-task revision pins. Independent of the recording context so that
 * direct {@link Workspace.dispatch} calls (which run outside
 * {@link runWithRecording}) still honour installed pins.
 */
export interface RevisionsState {
    map: Map<string, string> | null;
}
/** One lost path's mark. Mirrors Python's `LostMark`. */
export interface LostMark {
    /** Where in the line's records it was lost. */
    readonly at: number;
    /** Its place among the line's marks, from 1. */
    readonly order: number;
    /** The version its write lost on, if any. */
    readonly version: string | null;
}
/**
 * The paths whose conditional write lost on a line. A lost path's cached
 * copy was dropped; nothing the line read of it before the loss may be
 * cached again. The version the write lost on is the one a retry sends, so
 * it is refused again until a read. A read or write of the path after the
 * loss names the bytes now there, and lifts the mark. Mirrors Python's
 * `LostPaths`, which rides the recorder; here it is keyed by the line's
 * records, since `keepVersions` runs after the recording scope ends.
 */
export declare class LostPaths {
    private readonly records;
    readonly marks: Map<string, LostMark>;
    /** The marks made so far. */
    count: number;
    constructor(records: readonly OpRecord[]);
    mark(key: string, version?: string | null): void;
    /**
     * Lift the marks a removal or move of `key` (and, with `subtree`, below it)
     * ended: only those made by the time it began (`upto`, the `count` then), so
     * a refusal another command of the line made while it ran stays.
     */
    lift(key: string, upto: number, subtree?: boolean): void;
    /** The version a write to `key` lost on, while it is still lost. */
    version(key: string): string | null;
    holds(key: string): boolean;
}
//# sourceMappingURL=record.d.ts.map