@microdelta/history 0.0.0 → 0.1.0

package/dist/api/history.untrimmed.d.ts

@@ -0,0 +1,3 @@
+/** Entry-specific exports preserve one History type identity per release tier. */
+export { AttemptConflictError, AttemptStateError, DuplicateRowError, FingerprintAlgorithmMismatchError, HistoryClockError, HistoryIntegrityError, HistorySchemaError, InvalidStorePatchError, MissingRowError, StaleWriterError, createMemoryStore, openDurableHistory } from './history.shared.untrimmed.js';
+export type { Divergence, FieldRow, Fingerprint, GenerationPatch, GenerationRow, GenerationState, IAbandonRequest, IAcceptanceRecord, IAcceptanceRequest, IAddressSegment, IAttemptRecord, IAttemptRequest, IAttemptState, IClockCapability, ICompletedEnvelope, ICompletedNavigationReader, ICompletedProjectionReader, ICompletedResultReader, ICompletedResultReference, IDurableHistory, IDurableHistoryOptions, IHistoryScope, IOperation, IRecoveryOutcome, IResultVerification, IScopedSubject, ISelectedFact, ISelectedFingerprintRequest, ISelectedFingerprintResolution, ISelectedNode, ISelectedReadRequest, ISha256Capability, ISqliteCapability, ISqliteConnection, ISqliteRow, ISqliteRunResult, ISqliteStatement, ISqliteSynchronousResult, ISqliteValue, IStageRequest, IValueProjectionDescriptor, IValueProjectionFact, IValueProjectionMember, IValueProjectionTraversal, IVersionedRecord, IVersionedSubject, IWriterAcquisition, IWriterAcquisitionRequest, IWriterLease, Identity, MemoryStoreOptions, Outcome, Path, RecordedRead, ResultKey, Store, StoreMetadata, Subject, SubjectPatch, SubjectRow } from './history.shared.untrimmed.js';

package/dist/api/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.59.2"
+    }
+  ]
+}

package/dist/src/completed-results.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Exact completed-snapshot reading contracts used by Materialization. These
+ * interfaces locate immutable results but neither implement a backend nor decide
+ * freshness, publication, authorization, or candidate eligibility.
+ * @packageDocumentation
+ */
+import type { IAddressSegment, IOperation, ISelectedFact, ISelectedNode, IValueProjectionDescriptor, IValueProjectionFact } from '@microdelta/value';
+/**
+ * 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 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;
+}
+/** A selected Value-owned scalar fact requested at an exact retained address. @alpha */
+export interface ISelectedReadRequest {
+    /** The literal operation whose fact is requested. */
+    readonly operation: IOperation;
+    /** Container-aware path within this selected result value. */
+    readonly address: readonly IAddressSegment[];
+}
+/**
+ * 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 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 type ISelectedFingerprintResolution = {
+    readonly kind: 'compatible';
+    readonly fingerprint: string;
+} | {
+    readonly kind: 'unavailable';
+} | {
+    readonly kind: 'incompatible';
+} | {
+    readonly kind: 'ambiguous';
+};
+/**
+ * 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 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;
+}
+/**
+ * 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 interface ICompletedProjectionReader {
+    /** Read only the projection's requested address and keyed selected values. */
+    readProjection(reference: ICompletedResultReference, descriptor: IValueProjectionDescriptor): IValueProjectionFact;
+}
+/**
+ * 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 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;
+}
+//# sourceMappingURL=completed-results.d.ts.map

package/dist/src/completed-results.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completed-results.d.ts","sourceRoot":"","sources":["../../src/completed-results.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EACV,eAAe,EACf,UAAU,EACV,aAAa,EACb,aAAa,EACb,0BAA0B,EAC1B,oBAAoB,EACrB,MAAM,mBAAmB,CAAC;AAE3B;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACxC,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,wFAAwF;AACxF,MAAM,WAAW,oBAAoB;IACnC,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;IAC/B,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;CAC9C;AAED;;;;;GAKG;AACH,MAAM,MAAM,2BAA2B,GACnC;IACE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,0BAA0B,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEN,2FAA2F;AAC3F,MAAM,MAAM,8BAA8B,GACtC;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAAE,GAChC;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GACjC;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC;AAEnC;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,+EAA+E;IAC/E,YAAY,CAAC,SAAS,EAAE,yBAAyB,EAAE,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAAC;IACjG,oFAAoF;IACpF,kBAAkB,CAChB,SAAS,EAAE,yBAAyB,EACpC,OAAO,EAAE,2BAA2B,GACnC,8BAA8B,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC,8EAA8E;IAC9E,cAAc,CACZ,SAAS,EAAE,yBAAyB,EACpC,UAAU,EAAE,0BAA0B,GACrC,oBAAoB,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,0BAA0B;IACzC,yFAAyF;IACzF,QAAQ,CAAC,SAAS,EAAE,yBAAyB,EAAE,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,aAAa,CAAC;IACnG;;;OAGG;IACH,WAAW,CAAC,SAAS,EAAE,yBAAyB,EAAE,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,OAAO,CAAC;CACjG"}

package/dist/src/completed-results.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=completed-results.js.map

package/dist/src/completed-results.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"completed-results.js","sourceRoot":"","sources":["../../src/completed-results.ts"],"names":[],"mappings":""}

package/dist/src/durable/contracts.d.ts

@@ -0,0 +1,339 @@
+/**
+ * Contracts of History's durable authority: the one consistency owner for
+ * immutable completed results, attempt history, the single logical writer,
+ * atomic publication, current pointers and separate acceptance records
+ * (PUB-001, ARC-007). These are project-private alpha shapes. They carry
+ * Resolution's provenance and evidence as versioned opaque records and never
+ * interpret Definition, Tracking or Resolution meaning; deciding whether a
+ * result is currently acceptable remains Resolution's responsibility.
+ * @packageDocumentation
+ */
+import type { IClockCapability, ISha256Capability, ISqliteCapability } from '@microdelta/machine';
+import type { ICompletedNavigationReader, ICompletedResultReader, ICompletedResultReference } from '../completed-results.js';
+/**
+ * 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 interface IHistoryScope {
+    /** The analysis whose history this is. */
+    readonly analysis: string;
+    /** The logical environment within that analysis. */
+    readonly environment: 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 interface IScopedSubject extends IHistoryScope {
+    /** The author's complete subject string, compared by exact string equality. */
+    readonly subject: string;
+}
+/**
+ * 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 interface IVersionedSubject extends IScopedSubject {
+    /** The positive safe-integer compatibility group. */
+    readonly version: number;
+}
+/**
+ * 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 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;
+}
+/**
+ * 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 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;
+}
+/**
+ * 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 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 interface IWriterAcquisitionRequest {
+    /** The opaque non-empty identity of the prospective holder. */
+    readonly holder: string;
+    /** Positive safe-integer lease duration in milliseconds. */
+    readonly leaseMilliseconds: number;
+}
+/**
+ * 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 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 type IAttemptState = 'allocated' | 'staged' | 'completed' | 'failed' | 'interrupted';
+/**
+ * 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 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;
+}
+/**
+ * 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 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[];
+}
+/** Ends an incomplete attempt without a result, preserving its evidence. @alpha */
+export 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;
+}
+/**
+ * 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 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;
+};
+/**
+ * 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 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[];
+}
+/**
+ * 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 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[];
+}
+/** One immutable current-acceptance record, separate from the result it names. @alpha */
+export 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[];
+}
+/**
+ * Result of regenerating a completed result's selected index from its stored
+ * canonical payload and comparing it with the stored index.
+ * @alpha
+ */
+export type IResultVerification = {
+    readonly kind: 'consistent';
+} | {
+    readonly kind: 'inconsistent';
+    readonly detail: string;
+};
+/**
+ * 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 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;
+}
+/**
+ * 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 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;
+}
+//# sourceMappingURL=contracts.d.ts.map

package/dist/src/durable/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../../src/durable/contracts.ts"],"names":[],"mappings":"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"}

package/dist/src/durable/contracts.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contracts.js.map

package/dist/src/durable/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../../src/durable/contracts.ts"],"names":[],"mappings":""}

package/dist/src/durable/errors.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Distinct failure classes of the durable History authority. Diagnostics must
+ * distinguish stale ownership, conflicting execution identity, invalid
+ * lifecycle transitions, unsupported storage and integrity failures rather
+ * than report a generic miss (execution.md, required validation fixtures).
+ * None of these classes extends `TypeError`, so a reader never mistakes a
+ * storage failure for Value's rejection of a selection's shape.
+ * @packageDocumentation
+ */
+/**
+ * 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);
+}
+/**
+ * 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);
+}
+/**
+ * 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);
+}
+/**
+ * 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);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/durable/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/durable/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;GAOG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,6DAA6D;gBAC1C,OAAO,EAAE,MAAM;CAInC;AAED;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,2DAA2D;gBACxC,OAAO,EAAE,MAAM;CAInC;AAED;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,oEAAoE;gBACjD,OAAO,EAAE,MAAM;CAInC;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,uEAAuE;gBACpD,OAAO,EAAE,MAAM;CAInC;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,wEAAwE;gBACrD,OAAO,EAAE,MAAM;CAInC;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,wDAAwD;gBACrC,OAAO,EAAE,MAAM;CAInC"}

package/dist/src/durable/errors.js

@@ -0,0 +1,87 @@
+/**
+ * Distinct failure classes of the durable History authority. Diagnostics must
+ * distinguish stale ownership, conflicting execution identity, invalid
+ * lifecycle transitions, unsupported storage and integrity failures rather
+ * than report a generic miss (execution.md, required validation fixtures).
+ * None of these classes extends `TypeError`, so a reader never mistakes a
+ * storage failure for Value's rejection of a selection's shape.
+ * @packageDocumentation
+ */
+/**
+ * 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 class HistoryIntegrityError extends Error {
+    /** Create an integrity failure with a diagnostic message. */
+    constructor(message) {
+        super(message);
+        this.name = 'HistoryIntegrityError';
+    }
+}
+/**
+ * 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 class HistorySchemaError extends Error {
+    /** Create a schema rejection with a diagnostic message. */
+    constructor(message) {
+        super(message);
+        this.name = 'HistorySchemaError';
+    }
+}
+/**
+ * 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 class StaleWriterError extends Error {
+    /** Create a stale-ownership rejection with a diagnostic message. */
+    constructor(message) {
+        super(message);
+        this.name = 'StaleWriterError';
+    }
+}
+/**
+ * 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 class AttemptConflictError extends Error {
+    /** Create an execution-identity conflict with a diagnostic message. */
+    constructor(message) {
+        super(message);
+        this.name = 'AttemptConflictError';
+    }
+}
+/**
+ * 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 class AttemptStateError extends Error {
+    /** Create an invalid-transition rejection with a diagnostic message. */
+    constructor(message) {
+        super(message);
+        this.name = 'AttemptStateError';
+    }
+}
+/**
+ * The injected clock failed to produce a nonnegative safe-integer epoch
+ * millisecond reading, so the time-dependent operation was refused unchanged.
+ * @alpha
+ */
+export class HistoryClockError extends Error {
+    /** Create a clock refusal with a diagnostic message. */
+    constructor(message) {
+        super(message);
+        this.name = 'HistoryClockError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/durable/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/durable/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;GAOG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C,6DAA6D;IAC7D,YAAmB,OAAe;QAChC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,2DAA2D;IAC3D,YAAmB,OAAe;QAChC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzC,oEAAoE;IACpE,YAAmB,OAAe;QAChC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,uEAAuE;IACvE,YAAmB,OAAe;QAChC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,wEAAwE;IACxE,YAAmB,OAAe;QAChC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,wDAAwD;IACxD,YAAmB,OAAe;QAChC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF"}