@struktoai/mirage-core/dist/cache/context.d.ts

A Unified Virtual Filesystem For AI Agents

import type { StaleWriteError } from '../errors/types.ts';
import type { PathSpec } from '../types.ts';
import { type ConditionSupport, type CacheContextState, type CacheInvalidator, type KnownVersions, type LiveVersion, type Measured, OwnRead, type WriteCondition, type WriteContext, type WriteBinding, type WriteKind } from './types.ts';
/**
 * Run `fn` with `manager` active for the current async context.
 * Mirrors `runWithRevisions`: the mount entry point wraps command
 * dispatch.
 */
export declare function runWithCacheManager<T>(manager: CacheInvalidator | null, fn: () => Promise<T>): Promise<T>;
/**
 * Return the active cache manager for the current async context.
 *
 * Serves the read-through paths, so a wrong manager is worse than
 * none: a warm hit from another mount's cache is another mount's
 * bytes, where a miss just reads the backend. On an isolating runtime
 * one binding is live and answers as bound; on the fallback storage
 * the manager answers only while every live frame agrees on it, and a
 * disagreement (overlapping commands on different mounts) reads as no
 * manager, failing toward the cold read.
 */
export declare function activeCacheManager(): CacheInvalidator | null;
/**
 * Run `op`, then `settle`, also when `op` fails.
 *
 * An op that fails partway (a paginated delete, a folder copy that merged
 * some children) has already changed the backend, so its record is owed
 * either way. `settle` gets the op's result, or undefined when the op
 * failed. After a failed op a settle error is reported, not thrown, so the
 * caller still learns why the op failed. Failure records invalidate shared
 * caches but preserve session versions for untouched files. Mirrors Python's `settle_after`.
 *
 * Args:
 *   op: the backend change.
 *   settle: records what the op changed, given its result.
 */
export declare function settleAfter<T>(op: () => Promise<T>, settle: (result: T | undefined) => Promise<void>): Promise<T>;
/** A fetch collecting the tokens its bytes carried. */
export interface ReadFacts {
    path: string;
    facts: WeakMap<Uint8Array, (string | null)[]>;
}
/** Collect tokens belonging to the exact bytes returned by a fetch. */
export declare function captureRead<T>(path: string, fetch: () => Promise<T>): Promise<[T, (string | null)[]]>;
/** Publish a backend-verified token without activating observation. */
export declare function publishRead(path: string, data: Uint8Array, fingerprint: string | null): void;
declare module '../context/session_context.ts' {
    interface Caller {
        readonly cache: CacheContextState | null;
        readonly readFacts: ReadFacts | null;
        readonly write: WriteBinding | null;
    }
}
/** Run `fn` with `context` bound as the write context of the mount at `prefix`. */
export declare function runWithWriteContext<T>(prefix: string, context: WriteContext | null, fn: () => Promise<T>): Promise<T>;
export declare function conditionVersion(condition: WriteCondition | null): string | null;
/**
 * What a write's condition asked for: a version, ABSENT for a create. Mirrors
 * Python's `condition_basis`.
 */
export declare function conditionBasis(condition: WriteCondition | null): Measured | null;
export declare function requireSupported(support: ConditionSupport, vfs: string, path: PathSpec, kind: WriteKind, condition: WriteCondition): void;
/**
 * Run a read and return its bytes with the token they carried: the one its
 * backend published for these exact bytes, null when it published none or
 * two that disagree. Mirrors Python's `read_versioned`.
 */
export declare function readVersioned<T>(path: PathSpec, fetch: () => Promise<T>): Promise<[T, string | null]>;
/**
 * Resolve explicit read evidence and mount policy into a destination condition.
 * PUT returns Any, Absent, or Match; copy and delete return null outside
 * conditional policy. Mirrors Python's `write_condition`.
 *
 * @throws a stale-write error when the op found removed a file the mount saw
 * @throws an ENOTSUP error when the backend cannot condition this op
 */
export declare function writeCondition(path: PathSpec, kind: 'put', own?: string | OwnRead | null): Promise<WriteCondition>;
export declare function writeCondition(path: PathSpec, kind: 'copy' | 'delete', own?: string | OwnRead | null): Promise<WriteCondition | null>;
/**
 * The condition a delete of `path` carries, null when unconditional: a
 * delete needs no read of its own, only that nobody wrote since, so the
 * version the mount holds, else the one its own lookup found. Mirrors
 * Python's `delete_condition`.
 *
 * @throws a stale-write error when the session found no file there, and one
 * has appeared since
 * @throws an ENOTSUP error when the backend cannot condition a delete
 */
export declare function deleteCondition(path: PathSpec, lookedUp: string | null): Promise<WriteCondition | null>;
/**
 * The conditions a move carries: the copy onto `dst` and the source's pin,
 * both versions from one store lookup. Null and null when unconditional.
 * Mirrors Python's `move_condition`.
 *
 * @throws a stale-write error when the op found removed a file the mount saw
 * @throws an ENOTSUP error when the backend cannot condition the move
 */
export declare function moveCondition(src: PathSpec, dst: PathSpec): Promise<[WriteCondition | null, string | null]>;
/**
 * The native token a write sends in place of the held content token, null when
 * the write goes plain. Mirrors Python's `native_condition`.
 */
export declare function nativeCondition(path: PathSpec, cond: WriteCondition | null, live: LiveVersion | null, kind: WriteKind): Promise<string | null>;
/**
 * Keep the version of every file a walk left behind; refuse the first. Mirrors
 * Python's `keep_refused`.
 */
export declare function keepRefused(lost: readonly (readonly [PathSpec, string | null])[]): Promise<StaleWriteError | null>;
/**
 * The version the mount holds for each path, in one store round trip. Mirrors
 * Python's `held_versions`.
 */
export declare function heldVersions(paths: readonly PathSpec[]): Promise<(string | null)[]>;
/**
 * Whether the mount that owns `path` is a `write: conditional` one; true while
 * overlapping lines leave the owner unclear. Mirrors Python's
 * `writes_conditioned`.
 */
export declare function writesConditioned(path: PathSpec): boolean;
/**
 * Whether a `kind` on `path` goes out conditioned, for a prefix walk, which
 * conditions each key itself and needs no version for the operand. Mirrors
 * Python's `conditioned`.
 *
 * @throws an ENOTSUP error when the backend cannot condition this op
 */
export declare function conditioned(path: PathSpec, kind: 'copy' | 'delete'): boolean;
/**
 * Drop the write context's cached copy of `path`, if there is one. `keep` is
 * the version to keep without bytes, ABSENT for a refused create.
 */
export declare function dropCached(path: PathSpec, keep?: Measured | null): Promise<void>;
/**
 * Drop `path`'s cached copy, keeping what a refused write sent. The condition
 * stays, so a retry without a read sends it again and is refused again. That
 * holds for a file found gone too: a peer may create it again before the
 * retry. `version` is the version the write sent, ABSENT for a create; null
 * keeps what the session last saw. Mirrors Python's `keep_sent`.
 */
export declare function keepSent(path: PathSpec, version?: Measured | null): Promise<void>;
/**
 * The refusal for a lost condition, after `keepSent`. `landed` marks a move
 * whose copy landed before its source's delete lost, which `mv` reports as a
 * failed removal; `version` is the one the write sent, ABSENT for a create,
 * when the line no longer names it (a move retracts both paths). Mirrors
 * Python's `stale`.
 */
export declare function stale(path: PathSpec, options?: {
    landed?: boolean;
    version?: Measured | null;
}): Promise<StaleWriteError>;
/**
 * The versions a prefix walk under `root` measures its keys against: a key
 * the agent read is held to the version it read, and the walk's own listing
 * only stands in for keys it never saw. Mirrors Python's `known_versions`.
 */
export declare function knownVersions(root: PathSpec, keyPrefix: string): KnownVersions;
//# sourceMappingURL=context.d.ts.map