trellis
Version:
Agentic State Engine — event-sourced causal graph with branching, decision traces, and realtime sync for AI-native applications
50 lines • 2.55 kB
TypeScript
/**
* Persisted integration materialization snapshot.
*
* Stores EAV state at a journal tail hash so CLI cold starts replay only
* ops appended since the last snapshot instead of the full integration journal.
*/
import type { CatalogEntry, Fact, Link } from '../core/store/eav-store.js';
import type { EAVStore } from '../core/store/eav-store.js';
import type { VcsOp } from './types.js';
export declare const INTEGRATION_SNAPSHOT_FILE = "integration-snapshot.json";
/**
* Snapshot version — a **projection** version, not a file-format version.
*
* A snapshot is derived state: it is only valid for the `decompose` that built
* it. Bumping this on a format change alone is not enough, because changing what
* `decompose` PROJECTS leaves the container shape identical, so a stale snapshot
* is accepted and the new facts never appear. Worse, `materializeIntegration`
* re-saves the snapshot on every open, so a snapshot written by older projection
* logic can never self-heal — there is nothing left to replay, and each open
* rewrites the stale state. The op log says one thing and the store says another,
* permanently.
*
* Seen for real: ADR 0026 added an `issueType` fact to `vcs:issueCreate`; ops
* carried it, `decompose` projected it, and `trellis issue list --type epic`
* still returned nothing. Only `TRELLIS_NO_SNAPSHOT=1` showed the truth.
*
* **BUMP THIS WHENEVER `decompose` CHANGES WHAT IT EMITS.** A mismatch returns
* null from `loadPersistedSnapshot`, which falls through to a full replay and
* re-saves at the current version — the same v1/v2 grandfathering ADR 0021 uses
* for op preimages, applied to derived state.
*
* 2 — ADR 0026: `issueType` on issues.
*/
export declare const INTEGRATION_SNAPSHOT_VERSION = 2;
export interface PersistedIntegrationSnapshot {
version: typeof INTEGRATION_SNAPSHOT_VERSION;
tailHash: string;
store: {
facts: Fact[];
links: Link[];
catalog: CatalogEntry[];
};
}
export declare function integrationSnapshotPath(trellisDir: string): string;
export declare function snapshotsEnabled(): boolean;
/** Find the last journal index whose op hash equals `tailHash`. */
export declare function findTailIndex(ops: VcsOp[], tailHash: string): number;
export declare function loadPersistedSnapshot(snapshotPath: string): PersistedIntegrationSnapshot | null;
export declare function savePersistedSnapshot(snapshotPath: string, tailHash: string | undefined, store: EAVStore): void;
//# sourceMappingURL=integration-snapshot.d.ts.map