@microdelta/history 0.0.0 → 0.1.0

package/dist/api/history.shared.alpha.d.ts

@@ -0,0 +1,1091 @@
+/**
+ * One declaration identity contains History's root and Store conformance APIs.
+ * This build-only entry does not define a runtime module or add conformance
+ * behavior to the public root export.
+ * @packageDocumentation
+ */
+
+/**
+ * An attempt key is already bound to a different execution intent, version
+ * or scoped subject. The key identifies one execution; it cannot serve another.
+ * @alpha
+ */
+export declare class AttemptConflictError extends Error {
+    /** Create an execution-identity conflict with a diagnostic message. */
+    constructor(message: string);
+}
+
+/**
+ * A lifecycle operation was requested from a state that does not permit it,
+ * such as staging a completed attempt or publishing one that was never staged.
+ * @alpha
+ */
+export declare class AttemptStateError extends Error {
+    /** Create an invalid-transition rejection with a diagnostic message. */
+    constructor(message: string);
+}
+
+/**
+ * Create a memory Store with linearizable CAS in a single JavaScript isolate.
+ * Each mutation snapshots its arguments before checking and changing the maps;
+ * the qualifying check and write have no await or caller callback between them.
+ * Values and fingerprints have separate indexes, so verification never touches
+ * payloads. The injected snapshot capability owns its supported value domain
+ * and failure behavior. This is a test backend, not durable or shared across
+ * processes.
+ *
+ * Only row storage is implemented here. Publication across multiple rows,
+ * generation allocation, lease ownership, and reclamation belong to higher layers.
+ * @public
+ */
+export declare function createMemoryStore(capability: ISnapshotCapability, options?: MemoryStoreOptions): Store;
+
+/** The first observed difference in a persisted read or a nested verification. @public */
+export declare type Divergence = {
+    read: RecordedRead;
+    was: Fingerprint;
+    now: Fingerprint | 'missing';
+} | {
+    read: Extract<RecordedRead, {
+        kind: 'memo';
+    }>;
+    nested: Divergence;
+};
+
+/** Insert-only storage encountered an existing complete tuple. @public */
+export declare class DuplicateRowError extends Error {
+    /** Identify an insert conflict without modifying the retained row. @public */
+    constructor(message?: string);
+}
+
+/** An immutable value node and its caller-computed fingerprint. @public */
+export declare interface FieldRow {
+    key: ResultKey;
+    generation: number;
+    path: Path;
+    fingerprint: Fingerprint;
+    value: unknown;
+}
+
+/**
+ * Compatibility shapes for the scaffold row Store. Their names and string paths
+ * describe that storage port, not the target Value Semantics or identity model.
+ */
+/** Opaque, stable, hex-encoded content digest; equality is string equality. @public */
+export declare type Fingerprint = string & {
+    readonly __fp: unique symbol;
+};
+
+/** Stored fingerprints cannot be compared with this runtime's algorithm. @public */
+export declare class FingerprintAlgorithmMismatchError extends Error {
+    /** Name both identifiers so migrations are explicit rather than silent misses. @public */
+    constructor(storedAlgorithm: string, runtimeAlgorithm: string);
+}
+
+/** Writable generation columns; tuple identity cannot change after insertion. @public */
+export declare type GenerationPatch = Partial<Omit<GenerationRow, 'key' | 'generation'>>;
+
+/** A retained attempt, with lifecycle and numbering supplied by its caller. @public */
+export declare interface GenerationRow {
+    key: ResultKey;
+    generation: number;
+    state: GenerationState;
+    reads: RecordedRead[];
+    identity: Identity | undefined;
+    startedAt: number;
+    endedAt: number | null;
+    cost: Record<string, number>;
+    arrival: string;
+    abandonReason?: 'error' | 'lease-expired' | 'refused';
+    error?: {
+        message: string;
+        stack?: string;
+    };
+}
+
+/** Retained lifecycle states interpreted by repository and claim, not by storage. @public */
+export declare type GenerationState = 'claimed' | 'current' | 'superseded' | 'abandoned';
+
+/**
+ * The injected clock failed to produce a nonnegative safe-integer epoch
+ * millisecond reading, so the time-dependent operation was refused unchanged.
+ * @alpha
+ */
+export declare class HistoryClockError extends Error {
+    /** Create a clock refusal with a diagnostic message. */
+    constructor(message: string);
+}
+
+/**
+ * The store's contents contradict History's invariants or the caller's exact
+ * reference: a malformed, missing or wrong-scope reference, a dangling
+ * dependency, or index/payload content that does not match its digests.
+ * History never repairs such a failure by following a current pointer or
+ * recomputing.
+ * @alpha
+ */
+export declare class HistoryIntegrityError extends Error {
+    /** Create an integrity failure with a diagnostic message. */
+    constructor(message: string);
+}
+
+/**
+ * The SQLite file does not hold exactly History's supported schema for the
+ * requested logical store: unknown, incomplete, foreign or differently
+ * versioned storage is rejected before any work rather than migrated by guess.
+ * @alpha
+ */
+export declare class HistorySchemaError extends Error {
+    /** Create a schema rejection with a diagnostic message. */
+    constructor(message: string);
+}
+
+/** Ends an incomplete attempt without a result, preserving its evidence. @alpha */
+export declare interface IAbandonRequest {
+    /** The incomplete attempt to end. */
+    readonly attemptId: number;
+    /** Whether execution failed or was interrupted. */
+    readonly outcome: 'failed' | 'interrupted';
+    /** Owner-defined evidence of what happened. */
+    readonly evidence: IVersionedRecord;
+}
+
+/** One immutable current-acceptance record, separate from the result it names. @alpha */
+export declare interface IAcceptanceRecord {
+    /** Store-wide never-reused acceptance identity, increasing in record order. */
+    readonly acceptanceId: number;
+    /** The accepted exact result. */
+    readonly reference: ICompletedResultReference;
+    /** The writer fence under which the acceptance was recorded. */
+    readonly fence: number;
+    /** Resolution's acceptance evidence, decoded and frozen. */
+    readonly evidence: IVersionedRecord;
+    /** Exact results the verification followed, in recorded order. */
+    readonly dependencies: readonly ICompletedResultReference[];
+}
+
+/**
+ * Records that an existing completed result was accepted by a current
+ * verification. It needs writer ownership to write, but no attempt: a valid
+ * hit claims no execution. The evidence names the current dependencies the
+ * verification followed, which may differ from the original provenance.
+ * @alpha
+ */
+export declare interface IAcceptanceRequest {
+    /** The exact completed result that was accepted. */
+    readonly reference: ICompletedResultReference;
+    /** Resolution's versioned acceptance evidence. */
+    readonly evidence: IVersionedRecord;
+    /** Exact completed results the current verification followed. */
+    readonly dependencies: readonly ICompletedResultReference[];
+}
+
+/** @alpha A path segment whose kind follows the container's operation semantics. */
+export declare type IAddressSegment = 
+/** A literal string-keyed record lookup, including keys containing punctuation. */
+    {
+    readonly kind: 'property';
+    readonly key: string;
+}
+/** A positional array lookup; it does not designate a logical member identity. */
+| {
+    readonly kind: 'index';
+    readonly index: number;
+};
+
+/**
+ * One durable attempt as History records it. The attempt identity is issued
+ * from a store-wide counter that never reissues a value, including after
+ * abandonment or process death (PUB-003).
+ * @alpha
+ */
+export declare interface IAttemptRecord extends IAttemptRequest {
+    /** The never-reused store-wide attempt identity. */
+    readonly attemptId: number;
+    /** The current lifecycle state. */
+    readonly state: IAttemptState;
+    /** The fence of the lease that allocated this attempt. */
+    readonly allocatedFence: number;
+    /** The fence that completed, failed or interrupted it; null while incomplete. */
+    readonly endedFence: number | null;
+    /** The exact completed result, present only in the `completed` state. */
+    readonly result: ICompletedResultReference | null;
+    /** Owner-defined evidence of a failed or interrupted attempt, otherwise null. */
+    readonly outcome: IVersionedRecord | null;
+}
+
+/**
+ * Identifies one admitted execution for allocation or recovery. The attempt
+ * key is a stable caller-derived identity for exactly one execution, scoped by
+ * logical store, analysis, environment and subject; it is not a subject-level
+ * cache key. The intent digest is an opaque digest Resolution computes from
+ * the complete invocation it intends to run; History compares it only for
+ * exact equality, so a reused key with a different intent is a conflict.
+ * @alpha
+ */
+export declare interface IAttemptRequest extends IVersionedSubject {
+    /** The stable key of one admitted execution. */
+    readonly attemptKey: string;
+    /** Resolution's opaque digest of that execution's complete intent. */
+    readonly intentDigest: string;
+}
+
+/**
+ * Durable attempt lifecycle. `allocated` and `staged` are incomplete;
+ * `completed` produced exactly one published result; `failed` and
+ * `interrupted` ended without a result. Staged content is attempt evidence,
+ * never a completed result.
+ * @alpha
+ */
+export declare type IAttemptState = 'allocated' | 'staged' | 'completed' | 'failed' | 'interrupted';
+
+/**
+ * Reads the host's current wall-clock time. Each reading is one observation in
+ * whole UTC milliseconds since the Unix epoch, always a finite safe integer.
+ * Readings are not monotonic: the host clock can move backwards or jump
+ * forwards between readings, and the capability reports that movement
+ * unchanged. Deciding how such movement affects leases or other ownership is
+ * the consumer's policy, not the clock's.
+ * @alpha
+ */
+export declare interface IClockCapability {
+    /** Return the current UTC epoch time in whole milliseconds, or throw if the host cannot provide one. */
+    currentEpochMilliseconds(): number;
+}
+
+/**
+ * Framework metadata of one immutable completed result, readable without
+ * loading its author payload. Provenance and dependencies are the historical
+ * truth recorded at publication; later acceptance never rewrites them (RES-007).
+ * @alpha
+ */
+export declare interface ICompletedEnvelope extends IVersionedSubject {
+    /** The exact scoped reference of this result. */
+    readonly reference: ICompletedResultReference;
+    /** The attempt that produced this result; a result has exactly one. */
+    readonly attemptId: number;
+    /** Store-wide publication order; later publications have larger values. */
+    readonly publication: number;
+    /** The supported Value snapshot encoding of the stored payload. */
+    readonly encoding: 'MDS1';
+    /** Resolution's execution provenance, decoded and frozen. */
+    readonly provenance: IVersionedRecord;
+    /** Exact completed results this execution depended on, in recorded order. */
+    readonly dependencies: readonly ICompletedResultReference[];
+}
+
+/**
+ * Optional capability for readers that can navigate one exact completed
+ * snapshot node by node, for lazy nested views. A navigation answer is the
+ * scalar value fact or the record/array shape at exactly the requested address;
+ * answering it must not read the root payload, a sibling or an unrequested
+ * descendant. Presence and key-order facts at nested addresses are answered by
+ * the same reader's {@link ICompletedResultReader.readSelected}. Every answer is
+ * synchronous: storage that can only load asynchronously cannot implement this
+ * capability. Scalar-only readers need not implement it.
+ * @alpha
+ */
+export declare interface ICompletedNavigationReader {
+    /** Navigate to exactly one node of this reference, never following a current pointer. */
+    readNode(reference: ICompletedResultReference, address: readonly IAddressSegment[]): ISelectedNode;
+    /**
+     * Return the complete supported data of one container subtree, only for an
+     * explicit output request. Record key order must be the snapshot's order.
+     */
+    readSubtree(reference: ICompletedResultReference, address: readonly IAddressSegment[]): unknown;
+}
+
+/**
+ * Optional capability for readers that can supply an exact keyed projection as
+ * selected member values. Scalar readers do not need to implement projections.
+ * @alpha
+ */
+export declare interface ICompletedProjectionReader {
+    /** Read only the projection's requested address and keyed selected values. */
+    readProjection(reference: ICompletedResultReference, descriptor: IValueProjectionDescriptor): IValueProjectionFact;
+}
+
+/**
+ * Synchronous scalar access and fingerprint-only resolution for one exact
+ * completed snapshot. A compatible fingerprint answer must be backed by the
+ * same semantics as a selected read; resolving metadata never reads payload.
+ * @alpha
+ */
+export declare interface ICompletedResultReader {
+    /** Read the requested fact from exactly this reference, never from current. */
+    readSelected(reference: ICompletedResultReference, request: ISelectedReadRequest): ISelectedFact;
+    /** Resolve matching metadata only; unavailable metadata does not trigger a read. */
+    resolveFingerprint(reference: ICompletedResultReference, request: ISelectedFingerprintRequest): ISelectedFingerprintResolution;
+}
+
+/**
+ * A caller-visible locator for one completed immutable snapshot. The opaque
+ * locator carries whatever analysis and environment scope its reader requires;
+ * it is never a payload or a request to follow a current pointer.
+ * @alpha
+ */
+export declare interface ICompletedResultReference {
+    /** Dispatches resolution to the completed-result contract. */
+    readonly kind: 'completed-result';
+    /** Opaque exact snapshot locator interpreted only by its injected reader. */
+    readonly locator: string;
+}
+
+/**
+ * Compatibility identity shape stored in scaffold rows. It does not establish
+ * target subject identity, binding correspondence, or collection semantics.
+ * @public
+ */
+export declare type Identity = {
+    kind: 'type';
+    type: string;
+    key: string;
+} | {
+    kind: 'step';
+    name: string;
+    inputs: readonly Identity[];
+} | {
+    kind: 'member';
+    of: Identity;
+    path: Path;
+} | {
+    kind: 'collection';
+    step: string;
+    source: Identity;
+};
+
+/**
+ * History's durable authority over one logical store. Every mutation except
+ * acquisition requires the current writer lease and checks holder, fence and
+ * unexpired lease inside its own transaction. Exact reads never consult a
+ * current pointer, and a missing or wrong-scope reference is an integrity
+ * failure, never a miss to be repaired by recomputation.
+ *
+ * Clock policy: each holder operation evaluates time as the larger of the
+ * host reading and a persisted store-wide high-water, then persists that value,
+ * including when the operation is rejected. Backward host movement therefore
+ * delays expiry and a forward jump can expire a lease early; neither lets an
+ * old fence act after a successor acquires, because every successor receives a
+ * larger fence. A host reading that is not a nonnegative safe integer fails
+ * the operation without any change. This is a local single-file policy, not a
+ * distributed-time or liveness guarantee.
+ * @alpha
+ */
+export declare interface IDurableHistory {
+    /** The logical store identity this authority holds. */
+    readonly logicalStore: string;
+    /** Exact selected reads over completed results, answered from their generated index. */
+    readonly reader: ICompletedResultReader & ICompletedNavigationReader;
+    /** Acquire the single logical writer, or report the observed unexpired holder. */
+    acquireWriter(request: IWriterAcquisitionRequest): IWriterAcquisition;
+    /** Extend a still-valid lease; a stale or expired lease is rejected. */
+    renewWriter(lease: IWriterLease, leaseMilliseconds: number): IWriterLease;
+    /** End a still-valid lease without resetting the fence. */
+    releaseWriter(lease: IWriterLease): void;
+    /** Inspect the recorded holder, if any, without granting authority. */
+    currentWriter(): IWriterLease | undefined;
+    /**
+     * Durably allocate one attempt in its own commit before any staging. The
+     * same key with the same intent returns the existing attempt in whatever
+     * state it reached; the same key with a different intent or version rejects.
+     */
+    allocateAttempt(lease: IWriterLease, request: IAttemptRequest): IAttemptRecord;
+    /** Persist candidate content for an allocated attempt without publishing it. */
+    stageAttempt(lease: IWriterLease, request: IStageRequest): IAttemptRecord;
+    /**
+     * In one commit, install the staged payload, its generated selected index
+     * and fingerprints, provenance, dependencies, the completed attempt state
+     * and the scoped current pointer. Publishing an already completed attempt
+     * returns its existing reference.
+     */
+    publishAttempt(lease: IWriterLease, attemptId: number): ICompletedResultReference;
+    /** End an incomplete attempt as failed or interrupted, retaining its evidence. */
+    abandonAttempt(lease: IWriterLease, request: IAbandonRequest): IAttemptRecord;
+    /** Report what durably happened to one identified execution, read-only. */
+    recoverAttempt(request: IAttemptRequest): IRecoveryOutcome;
+    /** Completed results for one scoped subject and version, latest publication first. */
+    findCandidates(subject: IVersionedSubject): readonly ICompletedEnvelope[];
+    /** The scoped subject's latest publication, if any; never rewound by acceptance. */
+    readCurrent(subject: IScopedSubject): ICompletedResultReference | undefined;
+    /** Read one exact result's metadata without loading its payload. */
+    readEnvelope(reference: ICompletedResultReference): ICompletedEnvelope;
+    /** Regenerate and compare one exact result's index from its canonical payload. */
+    verifyResult(reference: ICompletedResultReference): IResultVerification;
+    /** Record a current acceptance of an existing result without touching it or the current pointer. */
+    recordAcceptance(lease: IWriterLease, request: IAcceptanceRequest): IAcceptanceRecord;
+    /** Acceptance records naming one exact result, in record order. */
+    readAcceptances(reference: ICompletedResultReference): readonly IAcceptanceRecord[];
+    /** Release the SQLite file; later calls fail. */
+    close(): void;
+}
+
+/**
+ * Host capabilities and identity for opening a durable History store. Node
+ * access stays behind the injected SQLite and clock capabilities. The logical
+ * store identity is independent of the file location: a moved file keeps its
+ * identity, and a file holding another logical store is rejected.
+ * @alpha
+ */
+export declare interface IDurableHistoryOptions {
+    /** Opens the persistent SQLite file; History owns every statement and schema. */
+    readonly sqlite: ISqliteCapability;
+    /** Supplies wall-clock observations for History's lease policy. */
+    readonly clock: IClockCapability;
+    /** Computes content fingerprints for the selected index. */
+    readonly sha256: ISha256Capability;
+    /** The host location of the SQLite file, passed only to `sqlite`. */
+    readonly location: string;
+    /** The logical store identity this file must hold, or is created to hold. */
+    readonly logicalStore: string;
+}
+
+/**
+ * The analysis and environment that scope every subject, attempt and result
+ * within one logical store. The same subject text in another analysis or
+ * environment is a different scoped subject (RES-001/002). Both are complete
+ * opaque non-empty strings compared by exact equality.
+ * @alpha
+ */
+export declare interface IHistoryScope {
+    /** The analysis whose history this is. */
+    readonly analysis: string;
+    /** The logical environment within that analysis. */
+    readonly environment: string;
+}
+
+/** A patch attempted to modify an immutable address or managed CAS version. @public */
+export declare class InvalidStorePatchError extends Error {
+    /** Identify a structurally forbidden patch before any columns are changed. @public */
+    constructor(message?: string);
+}
+
+/** @alpha A supported JavaScript observation operation with its own fact meaning. */
+export declare type IOperation = 'value' | 'own' | 'membership' | 'length' | 'keys';
+
+/**
+ * Read-only recovery of one identified execution. Recovery reports what
+ * durably happened and never executes, publishes or records acceptance:
+ * `absent` means the key was never allocated in this scope, `incomplete` an
+ * allocated or staged attempt, `unsuccessful` a failed or interrupted one and
+ * `completed` the exact result that execution published.
+ * @alpha
+ */
+export declare type IRecoveryOutcome = {
+    readonly kind: 'absent';
+} | {
+    readonly kind: 'incomplete';
+    readonly attempt: IAttemptRecord;
+} | {
+    readonly kind: 'unsuccessful';
+    readonly attempt: IAttemptRecord;
+} | {
+    readonly kind: 'completed';
+    readonly attempt: IAttemptRecord;
+    /** The exact result that this identified execution published. */
+    readonly reference: ICompletedResultReference;
+};
+
+/**
+ * Result of regenerating a completed result's selected index from its stored
+ * canonical payload and comparing it with the stored index.
+ * @alpha
+ */
+export declare type IResultVerification = {
+    readonly kind: 'consistent';
+} | {
+    readonly kind: 'inconsistent';
+    readonly detail: string;
+};
+
+/**
+ * One scoped subject: the author's complete opaque subject string inside its
+ * analysis/environment scope. History never derives, prefixes or reinterprets
+ * the subject; it identifies a history of work, not one exact result.
+ * @alpha
+ */
+export declare interface IScopedSubject extends IHistoryScope {
+    /** The author's complete subject string, compared by exact string equality. */
+    readonly subject: string;
+}
+
+/**
+ * One immediate lookup result for a caller-supplied root, address, and
+ * operation. The fact may be the selected object reference itself, so it is
+ * neither a detached snapshot nor retained Tracking evidence. Tracking adds
+ * binding and capture relationships and decides what data to encode as evidence.
+ * @alpha
+ */
+export declare interface ISelectedFact {
+    /** The literal access whose result was selected. */
+    readonly operation: IOperation;
+    /** Ordered container-aware steps from the supplied root to the selected location. */
+    readonly address: readonly IAddressSegment[];
+    /** The selected value or structural fact; an object value remains the source reference. */
+    readonly fact: unknown;
+}
+
+/**
+ * Metadata lookup is scoped to the exact result reference and full requested
+ * selection. The encoding tag prevents an indexed digest from another semantic
+ * version being mistaken for this selection.
+ * @alpha
+ */
+export declare type ISelectedFingerprintRequest = {
+    readonly kind: 'selected';
+    readonly operation: IOperation;
+    readonly address: readonly IAddressSegment[];
+    readonly encoding: 'MDO1';
+} | {
+    readonly kind: 'projection';
+    readonly descriptor: IValueProjectionDescriptor;
+    readonly encoding: 'MDP1';
+} | {
+    readonly kind: 'materialized-output';
+    readonly address: readonly IAddressSegment[];
+    readonly encoding: 'MDS1';
+};
+
+/** Explicit results keep absent or incompatible metadata from implying equality. @alpha */
+export declare type ISelectedFingerprintResolution = {
+    readonly kind: 'compatible';
+    readonly fingerprint: string;
+} | {
+    readonly kind: 'unavailable';
+} | {
+    readonly kind: 'incompatible';
+} | {
+    readonly kind: 'ambiguous';
+};
+
+/**
+ * The kind of node that one exact structured address selects. A scalar leaf is
+ * its ordinary `value` selected fact. A record or array is described only by
+ * its container shape: navigating through a container is transport metadata for
+ * a lazy view, never a whole-object observation, so no member, identity or
+ * serialized subtree is implied. Array length is carried so a view need not ask
+ * again, but it becomes observation evidence only when a consumer reads it.
+ * Shapes are never placed inside {@link ISelectedFact.fact}.
+ * @alpha
+ */
+export declare type ISelectedNode = 
+/** A supported scalar (undefined, null, boolean, number or string) read at the address. */
+    {
+    readonly kind: 'scalar';
+    readonly selected: ISelectedFact;
+}
+/** A string-keyed plain-data record, possibly with a supported custom prototype chain. */
+| {
+    readonly kind: 'record';
+    readonly address: readonly IAddressSegment[];
+}
+/** A standard array; `length` counts slots including holes. */
+| {
+    readonly kind: 'array';
+    readonly address: readonly IAddressSegment[];
+    readonly length: number;
+};
+
+/** A selected Value-owned scalar fact requested at an exact retained address. @alpha */
+export declare interface ISelectedReadRequest {
+    /** The literal operation whose fact is requested. */
+    readonly operation: IOperation;
+    /** Container-aware path within this selected result value. */
+    readonly address: readonly IAddressSegment[];
+}
+
+/**
+ * Computes SHA-256 over the UTF-8 bytes of supplied canonical evidence.
+ * Machine supplies hashing only; callers define the meaning and framing of
+ * the input before it crosses this host boundary.
+ * @alpha
+ */
+export declare interface ISha256Capability {
+    /** Return the lowercase hexadecimal SHA-256 digest of the input text. */
+    sha256(input: string): string;
+}
+
+/**
+ * Produces a synchronous detached copy of primitives, arrays, ordinary objects'
+ * enumerable string-keyed properties, Date, RegExp, Map, Set, ArrayBuffer, and
+ * typed-array/DataView contents. It preserves cycles and repeated references
+ * within one copy and isolates both input and returned snapshots. Functions,
+ * symbols, and raw SharedArrayBuffer values fail. Getters may run; nonenumerable
+ * and symbol-keyed properties and arbitrary class prototypes are not preserved.
+ * This contract defines neither durable encoding nor canonical identity. It is
+ * public because History's direct memory-store constructor requires injection.
+ * @public
+ */
+declare interface ISnapshotCapability {
+    /** Return a detached copy or throw before a caller mutates owned state. */
+    snapshot<T>(value: T): T;
+}
+
+/**
+ * Opens persistent local SQLite databases for a consumer that owns its own
+ * SQL and schema, such as History's durable authority. Opening fails for a
+ * directory, a missing parent directory, a file that is not a SQLite database,
+ * or a location that cannot hold a persistent write-ahead-logged database,
+ * including `:memory:` and the empty path. Opening never silently weakens the
+ * host's durable configuration.
+ * @alpha
+ */
+export declare interface ISqliteCapability {
+    /** Open or create the database file at `location` and return its owned connection. */
+    openSqlite(location: string): ISqliteConnection;
+}
+
+/**
+ * An open connection to one persistent local SQLite database file. The caller
+ * that opened it owns it and must close it. The host selects durable
+ * configuration for every connection: write-ahead logging, FULL synchronous
+ * commits, enforced foreign keys and a bounded wait on a locked database.
+ * Callers supply every SQL statement and schema; the connection has no
+ * knowledge of what the tables mean.
+ *
+ * Transactions are synchronous, top-level and IMMEDIATE: the write lock is
+ * taken before the callback runs, the callback's writes commit together when
+ * it returns, and all of them roll back when it throws. Nesting is refused
+ * rather than given savepoint semantics. Calls through the connection or its
+ * statements made by asynchronous work that a callback left behind fail after
+ * the transaction ends. This protects only this connection's storage: it does
+ * not prevent other effects of that leftover JavaScript.
+ * @alpha
+ */
+export declare interface ISqliteConnection {
+    /** Execute SQL text that takes no bound values, such as schema statements. */
+    exec(sql: string): void;
+    /** Prepare one statement for repeated execution with bound values. */
+    prepare(sql: string): ISqliteStatement;
+    /**
+     * Run `operation` inside one IMMEDIATE transaction and return its result.
+     * A value thrown by `operation` rolls back every write and is rethrown
+     * unchanged. A Promise or thenable result, or a returned object or function
+     * whose `then` cannot be inspected, rolls back and fails with `TypeError`;
+     * an error raised while inspecting that `then` is not rethrown. A call made
+     * while this connection's transaction callback is running fails without
+     * invoking `operation`.
+     */
+    transaction<T>(operation: () => T & ISqliteSynchronousResult<T>): T;
+    /**
+     * Release the database file. Closing again has no effect; any later use of
+     * the connection or its statements fails. Closing from inside a transaction
+     * callback fails, which rolls that transaction back if the failure propagates,
+     * and work that outlived a transaction callback cannot close the connection.
+     */
+    close(): void;
+}
+
+/**
+ * One result row keyed by result column name. Rows are transport data owned by
+ * the caller; they carry no driver type, prototype behavior or live link to
+ * stored content.
+ * @alpha
+ */
+export declare interface ISqliteRow {
+    /** The value SQLite returned for the named result column. */
+    readonly [column: string]: ISqliteValue;
+}
+
+/**
+ * The only mutation fact a statement run reports. Row identifiers and other
+ * driver details stay inside the host.
+ * @alpha
+ */
+export declare interface ISqliteRunResult {
+    /** Rows inserted, updated or deleted directly by the statement. */
+    readonly changes: number;
+}
+
+/**
+ * One prepared SQL statement bound to the connection that prepared it. Values
+ * are always bound positionally and never interpolated into SQL text. Every
+ * call fails once the owning connection is closed, and fails when it is made by
+ * work inherited from an already ended transaction callback.
+ * @alpha
+ */
+export declare interface ISqliteStatement {
+    /** Execute the statement for its effect and report how many rows changed. */
+    run(...values: readonly ISqliteValue[]): ISqliteRunResult;
+    /** Return the first result row, or `undefined` when the statement yields none. */
+    get(...values: readonly ISqliteValue[]): ISqliteRow | undefined;
+    /** Return every result row in the order SQLite produced them. */
+    all(...values: readonly ISqliteValue[]): readonly ISqliteRow[];
+}
+
+/**
+ * Makes a transaction callback's return type unusable when it is, or may be, a
+ * Promise or other thenable. A transaction commits when its callback returns;
+ * an asynchronous callback would return before its awaited work, so such
+ * results are rejected at compile time and, independently, at runtime.
+ *
+ * Any union constituent with a callable `then` rejects the whole result, so
+ * `number | Promise<number>` is refused like `Promise<number>`. Results the
+ * compiler cannot classify, `any` and `unknown`, are left to the runtime check
+ * rather than rejecting ordinary untyped data.
+ * @alpha
+ */
+export declare type ISqliteSynchronousResult<T> = 0 extends 1 & T ? unknown : [Extract<T, {
+    readonly then: (...parameters: never[]) => unknown;
+}>] extends [never] ? unknown : never;
+
+/**
+ * One value that crosses the SQLite host boundary, either as a bound parameter
+ * or as a returned cell: text, a finite number, SQL NULL, or a BLOB copied into
+ * a plain `Uint8Array`. A returned INTEGER is exact because values outside the
+ * safe-integer range fail instead of being rounded. Booleans, bigints,
+ * `undefined`, non-finite numbers and objects are outside the domain and are
+ * refused at runtime even when a caller bypasses these types.
+ * @alpha
+ */
+export declare type ISqliteValue = string | number | null | Uint8Array;
+
+/**
+ * Candidate content for an allocated attempt. The payload must be supported
+ * Value data with a record or array root; the provenance is Resolution's
+ * versioned record; dependencies are exact references to completed results in
+ * the same store and scope that this execution consumed.
+ * @alpha
+ */
+export declare interface IStageRequest {
+    /** The allocated attempt to stage. */
+    readonly attemptId: number;
+    /** The author result data, copied into canonical MDS1 form. */
+    readonly payload: unknown;
+    /** Resolution's execution provenance for this attempt. */
+    readonly provenance: IVersionedRecord;
+    /** Exact completed results this execution depends on, in the caller's order. */
+    readonly dependencies: readonly ICompletedResultReference[];
+}
+
+/**
+ * The Value-owned meaning of a selected keyed projection, independent of its
+ * composition binding or collection policy.
+ * @alpha
+ */
+export declare interface IValueProjectionDescriptor {
+    /** Relative path from each member to the selected value. */
+    readonly address: readonly IAddressSegment[];
+    /** Projection content selects member values, never member identity or presence. */
+    readonly operation: 'value';
+    /** States whether all members were promised or only an exact visited subset was read. */
+    readonly traversal: IValueProjectionTraversal;
+}
+
+/**
+ * A content fact whose caller-owned binding remains outside Value's encoding.
+ * @alpha
+ */
+export declare interface IValueProjectionFact {
+    /** Selection and coverage whose meaning governs every supplied member value. */
+    readonly descriptor: IValueProjectionDescriptor;
+    /** Unique collection-scoped keys paired with their selected content; key order is not ordered consumption evidence. */
+    readonly members: readonly IValueProjectionMember[];
+}
+
+/**
+ * One unique stable member key and the selected supported value for that member.
+ * @alpha
+ */
+export declare type IValueProjectionMember = readonly [key: string, value: unknown];
+
+/**
+ * Coverage semantics for one keyed projection. Exhaustive coverage is a source
+ * promise; a visited traversal retains the exact ordered set of observed keys.
+ * @alpha
+ */
+export declare type IValueProjectionTraversal = {
+    readonly kind: 'exhaustive';
+    readonly complete: true;
+} | {
+    readonly kind: 'visited';
+    readonly complete: false;
+    readonly keys: readonly string[];
+};
+
+/**
+ * A versioned record whose meaning another owner defines, such as
+ * Resolution's execution provenance, current acceptance evidence or an
+ * attempt's failure evidence. History validates only that the format tag is a
+ * non-empty string, the format version is a positive safe integer and the
+ * content is supported Value data; it stores the content in canonical MDS1
+ * form and returns it decoded and frozen, never interpreting it.
+ * @alpha
+ */
+export declare interface IVersionedRecord {
+    /** The owner-defined format identity, for example a Resolution schema name. */
+    readonly format: string;
+    /** The owner-defined positive safe-integer version of that format. */
+    readonly formatVersion: number;
+    /** Supported Value data; its meaning belongs to the format's owner. */
+    readonly content: unknown;
+}
+
+/**
+ * A scoped subject narrowed to one compatibility group (REUSE-008): a positive
+ * safe integer chosen by the author per memoized step. Candidate lookup filters
+ * by it before Resolution validates current evidence.
+ * @alpha
+ */
+export declare interface IVersionedSubject extends IScopedSubject {
+    /** The positive safe-integer compatibility group. */
+    readonly version: number;
+}
+
+/**
+ * The outcome of asking for the single logical writer. `held` reports an
+ * observed unexpired holder, not a failed compare-and-swap (PUB-005), and
+ * grants nothing.
+ * @alpha
+ */
+export declare type IWriterAcquisition = {
+    /** The caller now owns the store's writer lease. */
+    readonly kind: 'acquired';
+    /** The new lease with its freshly issued fence. */
+    readonly lease: IWriterLease;
+} | {
+    /** Another unexpired holder owns the store. */
+    readonly kind: 'held';
+    /** The observed holder identity. */
+    readonly holder: string;
+    /** When that holder's lease expires, in History's clock domain. */
+    readonly expiresAt: number;
+};
+
+/** A request for the writer lease. @alpha */
+export declare interface IWriterAcquisitionRequest {
+    /** The opaque non-empty identity of the prospective holder. */
+    readonly holder: string;
+    /** Positive safe-integer lease duration in milliseconds. */
+    readonly leaseMilliseconds: number;
+}
+
+/**
+ * Proof of current single-logical-writer ownership. The holder is an opaque
+ * caller identity; the fence is the store-wide token issued at acquisition,
+ * which only increases; `expiresAt` is the lease boundary in History's
+ * clock domain (epoch milliseconds). Presenting a lease authorizes storage
+ * mutation only while holder, fence and unexpired lease still match the durable
+ * writer state; it never authorizes author execution.
+ * @alpha
+ */
+export declare interface IWriterLease {
+    /** The opaque identity that acquired the lease. */
+    readonly holder: string;
+    /** The fencing token issued for this acquisition. */
+    readonly fence: number;
+    /** The first effective time at which the lease is no longer valid. */
+    readonly expiresAt: number;
+}
+
+/** Options for the isolated, non-durable test backend. @public */
+export declare interface MemoryStoreOptions {
+    /** Metadata compatibility identifier; the initial store format uses sha256. */
+    fingerprintAlgorithm?: string;
+    /* Excluded from this release type: _onValueRead */
+}
+
+/** An update targeted a generation that has never been inserted. @public */
+export declare class MissingRowError extends Error {
+    /** Identify an absent update target; updates never implicitly insert. @public */
+    constructor(message?: string);
+}
+
+/**
+ * Open (creating when empty) the durable History store for one logical store.
+ * The file is rejected before any work unless it is empty or holds exactly
+ * this schema version for this logical store.
+ * @alpha
+ */
+export declare function openDurableHistory(options: IDurableHistoryOptions): IDurableHistory;
+
+/** Observable call outcomes; an unmemoized named execution has no storage key. @public */
+export declare type Outcome = {
+    kind: 'served';
+    key: ResultKey;
+    generation: number;
+} | {
+    kind: 'executed';
+    key: ResultKey;
+    generation: number;
+} | {
+    kind: 'checked';
+    key: ResultKey;
+    wouldExecute: boolean;
+    divergence?: Divergence;
+} | {
+    kind: 'refused';
+    key: ResultKey;
+    reason: unknown;
+} | {
+    kind: 'failed';
+    key: ResultKey;
+    error: unknown;
+} | {
+    kind: 'abandoned';
+    key: ResultKey;
+    reason: 'error' | 'lease-expired' | 'refused';
+} | {
+    kind: 'ran';
+};
+
+/** A legacy row-storage address, not the future structured semantic path. @public */
+export declare type Path = string;
+
+/** Legacy persisted read rows; target observation encoding remains undecided. @public */
+export declare type RecordedRead = {
+    kind: 'field';
+    arg: number;
+    path: Path;
+    fingerprint: Fingerprint;
+} | {
+    kind: 'whole';
+    arg: number;
+    fingerprint: Fingerprint;
+} | {
+    kind: 'memo';
+    key: ResultKey;
+    generation: number;
+};
+
+/** Complete storage tuple. Backends must preserve boundaries between all three parts. @public */
+export declare type ResultKey = {
+    step: string;
+    revision: number;
+    subjectHash: string;
+};
+
+/**
+ * A presented writer lease no longer matches the durable holder, fence or
+ * unexpired lease, so the mutation was rejected with no change other than the
+ * observed clock high-water (PUB-002).
+ * @alpha
+ */
+export declare class StaleWriterError extends Error {
+    /** Create a stale-ownership rejection with a diagnostic message. */
+    constructor(message: string);
+}
+
+/**
+ * Storage mechanism for independent rows, with linearizable subject CAS.
+ * All inputs and returned rows are detached snapshots: caller mutation cannot
+ * alter persisted data. Values may only change by inserting another generation.
+ * There is no transaction spanning these methods; callers must not infer atomic
+ * claim/generation publication from the per-row CAS guarantee.
+ * @public
+ */
+export declare interface Store {
+    /** Return detached format metadata; opening code must reject algorithm mismatches. */
+    meta(): Promise<StoreMetadata>;
+    /** Read a detached subject snapshot, or undefined for an absent tuple. */
+    getSubject(key: ResultKey): Promise<SubjectRow | undefined>;
+    /** Insert only; duplicate tuples reject, as do versions outside safe integers. */
+    putSubject(row: SubjectRow): Promise<void>;
+    /**
+     * Atomically apply a shallow column patch only when the stored version matches.
+     * Success increments that version once, even for an empty patch; a missing or
+     * stale row returns false without changes. Key/version properties reject at
+     * runtime, including extras passed from untyped JavaScript callers.
+     * An exhausted MAX_SAFE_INTEGER version rejects rather than reporting success
+     * without advancing the token. Neither rejection changes the stored row.
+     */
+    casSubject(key: ResultKey, expectedVersion: number, patch: SubjectPatch): Promise<boolean>;
+    /** Read a detached generation, or undefined for an absent tuple. */
+    getGeneration(key: ResultKey, generation: number): Promise<GenerationRow | undefined>;
+    /** Return detached rows for exactly this complete key; ordering is unspecified. */
+    listGenerations(key: ResultKey): Promise<GenerationRow[]>;
+    /** Insert only; generation numbers are supplied, never allocated by storage. */
+    putGeneration(row: GenerationRow): Promise<void>;
+    /** Patch an existing row; missing tuples and attempts to change its key reject. */
+    updateGeneration(key: ResultKey, generation: number, patch: GenerationPatch): Promise<void>;
+    /**
+     * Insert an atomic batch of immutable fields. Duplicate addresses, within the
+     * batch or already stored, reject the whole batch without inserting anything.
+     * This proposed storage refinement enforces retained-value immutability.
+     */
+    putFields(rows: FieldRow[]): Promise<void>;
+    /** Return requested field snapshots; absent paths are omitted. */
+    getFields(key: ResultKey, generation: number, paths: Path[]): Promise<FieldRow[]>;
+    /** Return requested fingerprints without reading/deserializing any field value. */
+    getFingerprints(key: ResultKey, generation: number, paths: Path[]): Promise<Map<Path, Fingerprint>>;
+    /**
+     * Query leases strictly less than now, oldest first, with at most limit rows.
+     * Zero limit returns no rows. This query never sweeps or changes a claim.
+     */
+    expiredClaims(now: number, limit: number): Promise<SubjectRow[]>;
+    /** Release resources owned by this store. */
+    close(): Promise<void>;
+}
+
+/**
+ * Register reusable backend qualification tests for SA-1 through SA-7.
+ * Register this from a Jest test module; the suite imports no concrete backend.
+ * Mutation tests enforce rev 9's retained-value isolation at the storage seam.
+ * This suite does not assert atomicity across subject, generation, and field rows:
+ * the supplied Store contract does not provide that operation.
+ * @public
+ */
+export declare function storeConformance(name: string, options: StoreConformanceOptions): void;
+
+/**
+ * Opens a fresh store for each test. The optional algorithm models persisted metadata
+ * at open time; factories must reject a mismatch with their runtime algorithm.
+ * Instrumentation is optional for third-party backends, but both shipped backends
+ * must provide it to qualify SA-3 without relying on wall-clock timing.
+ * @public
+ */
+export declare interface StoreConformanceOptions {
+    create(options?: {
+        fingerprintAlgorithm?: string;
+    }): Store | Promise<Store>;
+    fingerprintAlgorithm: string;
+    probeValueReads?(store: Store): ValueReadProbe;
+}
+
+/** Persisted format identifiers, checked before using a store's fingerprints. @public */
+export declare interface StoreMetadata {
+    schemaVersion: number;
+    fingerprintAlgorithm: string;
+}
+
+/** Legacy row subject shape; future author-supplied subject identity is separate. @public */
+export declare type Subject = Extract<Identity, {
+    kind: 'step';
+}>;
+
+/** Writable subject columns; the complete key and CAS token cannot be patched. @public */
+export declare type SubjectPatch = Partial<Omit<SubjectRow, 'key' | 'version'>>;
+
+/**
+ * One compare-and-set row per complete result key. Repository owns generation
+ * meaning; claim owns lease meaning. Storage only preserves and patches columns.
+ * @public
+ */
+export declare interface SubjectRow {
+    key: ResultKey;
+    subject: Subject;
+    /** Nonnegative safe-integer CAS token, incremented once per successful CAS. */
+    version: number;
+    currentGeneration: number | null;
+    claim: null | {
+        generation: number;
+        holder: string;
+        leaseUntil: number;
+        progress: {
+            fingerprint: Fingerprint;
+            value: unknown;
+        } | null;
+    };
+    durations: number[];
+}
+
+/**
+ * A backend's test-only counter at its actual value-read/deserialization boundary.
+ * The suite resets it after insertion and verifies a positive control with getFields.
+ * @public
+ */
+export declare interface ValueReadProbe {
+    reset(): void;
+    count(): number;
+}
+
+export { }