@microdelta/history 0.0.0 → 0.2.0

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

@@ -0,0 +1,456 @@
+/**
+ * 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
+ */
+
+/* Excluded from this release type: AttemptConflictError */
+
+/* Excluded from this release type: AttemptStateError */
+
+/**
+ * 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';
+
+/* Excluded from this release type: HistoryClockError */
+
+/* Excluded from this release type: HistoryIntegrityError */
+
+/* Excluded from this release type: HistorySchemaError */
+
+/* Excluded from this release type: IAbandonRequest */
+
+/* Excluded from this release type: IAcceptanceRecord */
+
+/* Excluded from this release type: IAcceptanceRequest */
+
+/* Excluded from this release type: IAddressSegment */
+
+/* Excluded from this release type: IAttemptRecord */
+
+/* Excluded from this release type: IAttemptRequest */
+
+/* Excluded from this release type: IAttemptState */
+
+/* Excluded from this release type: IClockCapability */
+
+/* Excluded from this release type: ICompletedEnvelope */
+
+/* Excluded from this release type: ICompletedNavigationReader */
+
+/* Excluded from this release type: ICompletedProjectionReader */
+
+/* Excluded from this release type: ICompletedResultReader */
+
+/* Excluded from this release type: ICompletedResultReference */
+
+/**
+ * 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;
+};
+
+/* Excluded from this release type: IDurableHistory */
+
+/* Excluded from this release type: IDurableHistoryOptions */
+
+/* Excluded from this release type: IHistoryScope */
+
+/* Excluded from this release type: IJournalAddress */
+
+/* Excluded from this release type: IJournalCommit */
+
+/* Excluded from this release type: IJournalDeclaration */
+
+/* Excluded from this release type: IJournalFormat */
+
+/* Excluded from this release type: IJournalQuery */
+
+/* Excluded from this release type: IJournalRecord */
+
+/* Excluded from this release type: IJournalWrite */
+
+/** 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);
+}
+
+/* Excluded from this release type: IOperation */
+
+/* Excluded from this release type: IOperationJournal */
+
+/* Excluded from this release type: IPromotionQuery */
+
+/* Excluded from this release type: IPromotionRecord */
+
+/* Excluded from this release type: IPromotionRequest */
+
+/* Excluded from this release type: IRecoveryOutcome */
+
+/* Excluded from this release type: IResultVerification */
+
+/* Excluded from this release type: IScopedSubject */
+
+/* Excluded from this release type: ISelectedFact */
+
+/* Excluded from this release type: ISelectedFingerprintRequest */
+
+/* Excluded from this release type: ISelectedFingerprintResolution */
+
+/* Excluded from this release type: ISelectedNode */
+
+/* Excluded from this release type: ISelectedReadRequest */
+
+/* Excluded from this release type: ISha256Capability */
+
+/**
+ * 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;
+}
+
+/* Excluded from this release type: ISqliteCapability */
+
+/* Excluded from this release type: ISqliteConnection */
+
+/* Excluded from this release type: ISqliteRow */
+
+/* Excluded from this release type: ISqliteRunResult */
+
+/* Excluded from this release type: ISqliteStatement */
+
+/* Excluded from this release type: ISqliteSynchronousResult */
+
+/* Excluded from this release type: ISqliteValue */
+
+/* Excluded from this release type: IStageRequest */
+
+/* Excluded from this release type: IValueProjectionDescriptor */
+
+/* Excluded from this release type: IValueProjectionFact */
+
+/* Excluded from this release type: IValueProjectionMember */
+
+/* Excluded from this release type: IValueProjectionTraversal */
+
+/* Excluded from this release type: IVersionedRecord */
+
+/* Excluded from this release type: IVersionedSubject */
+
+/* Excluded from this release type: IWriterAcquisition */
+
+/* Excluded from this release type: IWriterAcquisitionRequest */
+
+/* Excluded from this release type: IWriterContention */
+
+/* Excluded from this release type: IWriterLease */
+
+/* Excluded from this release type: IWriterRenewal */
+
+/* Excluded from this release type: JournalConflictError */
+
+/* Excluded from this release type: JournalVersionError */
+
+/** 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);
+}
+
+/* Excluded from this release type: openDurableHistory */
+
+/** 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;
+};
+
+/* Excluded from this release type: StaleWriterError */
+
+/**
+ * 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 { }