@microdelta/history 0.1.0 → 0.2.0

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

@@ -156,6 +156,8 @@ export declare interface IAcceptanceRecord {
     readonly acceptanceId: number;
     /** The accepted exact result. */
     readonly reference: ICompletedResultReference;
+    /** The environment namespace whose verification recorded this acceptance. */
+    readonly environment: string;
     /** The writer fence under which the acceptance was recorded. */
     readonly fence: number;
     /** Resolution's acceptance evidence, decoded and frozen. */
@@ -176,8 +178,22 @@ export declare interface IAcceptanceRequest {
     readonly reference: ICompletedResultReference;
     /** Resolution's versioned acceptance evidence. */
     readonly evidence: IVersionedRecord;
-    /** Exact completed results the current verification followed. */
+    /**
+     * Exact completed results the current verification followed. Each must be
+     * admissible in the accepting environment: published there, or named by a
+     * promotion into it.
+     */
     readonly dependencies: readonly ICompletedResultReference[];
+    /**
+     * The environment, within the result's analysis, whose current verification
+     * accepted the result. It is always explicit and never inferred from the
+     * reference: the caller names its own run environment. It may be the
+     * environment that published the result, or another environment into which
+     * a recorded promotion admits the result. The acceptance then belongs to
+     * that environment's namespace alone and never satisfies a lookup in any
+     * other environment.
+     */
+    readonly environment: string;
 }
 
 /** @alpha A path segment whose kind follows the container's operation semantics. */
@@ -369,6 +385,15 @@ export declare type Identity = {
  * 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.
+ *
+ * Storage contention: every mutation, including acquisition, is one IMMEDIATE
+ * SQLite transaction. When another connection, possibly in another process,
+ * holds SQLite's write lock past the host's bounded busy wait, nothing
+ * changes. Acquisition and renewal, the lease operations a waiter repeats,
+ * report it as their `contended` outcome ({@link IWriterContention}), so
+ * contention is never mistaken for ownership or staleness (PUB-005). Any other
+ * operation fails with Machine's `SqliteBusyError`. Whether to try again is
+ * always the caller's policy, never History's.
  * @alpha
  */
 export declare interface IDurableHistory {
@@ -376,11 +401,20 @@ export declare interface IDurableHistory {
     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. */
+    /**
+     * Acquire the single logical writer, or report the observed unexpired
+     * holder, or report storage contention with the recorded writer. Any other
+     * failure, such as damaged storage or an unusable clock, is thrown.
+     */
     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. */
+    /**
+     * Extend a still-valid lease, or report storage contention, which leaves the
+     * lease as it was. A stale or expired lease is rejected with
+     * `StaleWriterError`. Only the expiry changes: the durable fence is left as
+     * it is, never rewritten from the presented lease.
+     */
+    renewWriter(lease: IWriterLease, leaseMilliseconds: number): IWriterRenewal;
+    /** End a still-valid lease; the durable fence is left as it is, so the next grant still advances it. */
     releaseWriter(lease: IWriterLease): void;
     /** Inspect the recorded holder, if any, without granting authority. */
     currentWriter(): IWriterLease | undefined;
@@ -403,9 +437,17 @@ export declare interface IDurableHistory {
     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. */
+    /**
+     * Completed results admissible for one scoped subject and version, latest
+     * publication first: those published in the subject's environment and those
+     * a recorded promotion admits into it. A promoted result keeps its own exact
+     * reference and envelope scope; nothing from any other environment appears.
+     */
     findCandidates(subject: IVersionedSubject): readonly ICompletedEnvelope[];
-    /** The scoped subject's latest publication, if any; never rewound by acceptance. */
+    /**
+     * The scoped subject's latest publication in its own environment, if any;
+     * never rewound by acceptance and never moved by a promotion.
+     */
     readCurrent(subject: IScopedSubject): ICompletedResultReference | undefined;
     /** Read one exact result's metadata without loading its payload. */
     readEnvelope(reference: ICompletedResultReference): ICompletedEnvelope;
@@ -413,8 +455,25 @@ export declare interface IDurableHistory {
     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[];
+    /**
+     * Acceptance records naming one exact result that were recorded in the
+     * named environment, in record order. The environment is always explicit:
+     * the publishing environment, or one a promotion admits the result into.
+     */
+    readAcceptances(reference: ICompletedResultReference, environment: string): readonly IAcceptanceRecord[];
+    /**
+     * In one commit, record a promotion that admits exact results of other
+     * environments into the target environment. Nothing already recorded changes.
+     */
+    promoteResults(lease: IWriterLease, request: IPromotionRequest): IPromotionRecord;
+    /** Promotion records into one environment, in record order. */
+    readPromotions(query: IPromotionQuery): readonly IPromotionRecord[];
+    /**
+     * Open Run Supervision's operation journal over this store, bound to the
+     * declared record formats and versions. The port shares this authority's
+     * connection, writer lease and lifetime.
+     */
+    openJournal(declaration: IJournalDeclaration): IOperationJournal;
     /** Release the SQLite file; later calls fail. */
     close(): void;
 }
@@ -443,7 +502,10 @@ export declare interface IDurableHistoryOptions {
  * 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.
+ * opaque non-empty strings compared by exact equality. An environment is a
+ * namespace within one store (RUN-017): a trial and a production run of the
+ * same analysis use different environments of the same file, selected per
+ * call rather than process-wide.
  * @alpha
  */
 export declare interface IHistoryScope {
@@ -453,14 +515,198 @@ export declare interface IHistoryScope {
     readonly environment: string;
 }
 
+/**
+ * Locates one journal record: its environment namespace, owner-named
+ * collection and owner-defined key. The record's identity is exactly this
+ * address; its format tag may change between revisions only by
+ * compare-and-set.
+ * @alpha
+ */
+export declare interface IJournalAddress extends IHistoryScope {
+    /** The owner-named non-empty collection, such as Supervision's operations. */
+    readonly collection: string;
+    /** The owner-defined non-empty key, unique within the namespace and collection. */
+    readonly key: string;
+}
+
+/**
+ * One atomic journal commit in one environment namespace: every write lands
+ * in the same transaction, or none does.
+ * @alpha
+ */
+export declare interface IJournalCommit extends IHistoryScope {
+    /** At least one write, each collection and key pair at most once. */
+    readonly writes: readonly IJournalWrite[];
+}
+
+/**
+ * The formats a journal port is bound to. A stored record of an undeclared
+ * format or version is refused rather than returned or overwritten, so a
+ * caller never acts on, or clobbers, a record it does not understand.
+ * @alpha
+ */
+export declare interface IJournalDeclaration {
+    /** At least one declared format, each format named once. */
+    readonly formats: readonly IJournalFormat[];
+}
+
+/**
+ * One owner-defined journal record format and the exact format versions a
+ * journal port can read and write. A format is only a record's version tag:
+ * it never identifies a record or its collection. History compares the tag
+ * and versions for exact equality and never interprets the content.
+ * @alpha
+ */
+export declare interface IJournalFormat {
+    /** The owner-defined non-empty format identity. */
+    readonly format: string;
+    /** The positive safe-integer versions of that format this port understands. */
+    readonly versions: readonly number[];
+}
+
+/**
+ * Selects every record of one collection in one environment namespace.
+ * @alpha
+ */
+export declare interface IJournalQuery extends IHistoryScope {
+    /** The owner-named collection to list. */
+    readonly collection: string;
+}
+
+/**
+ * One immutable revision of a journal record. Revisions of an address start
+ * at 1 and increase by one per committed write; earlier revisions are retained
+ * and never rewritten.
+ * @alpha
+ */
+export declare interface IJournalRecord extends IHistoryScope {
+    /** The owner-named collection. */
+    readonly collection: string;
+    /** The owner-defined key. */
+    readonly key: string;
+    /** This revision's number within its address, starting at 1. */
+    readonly revision: number;
+    /** Store-wide never-reused journal write identity, increasing in commit order. */
+    readonly sequence: number;
+    /** The writer fence under which this revision was committed. */
+    readonly fence: number;
+    /** The owner-defined record, decoded and frozen, with this revision's version tag. */
+    readonly record: IVersionedRecord;
+}
+
+/**
+ * One compare-and-set write of a journal commit. The expected revision is the
+ * revision the caller last read at this address; `0` asserts that the key has
+ * never been written in the collection, under any format. The record's
+ * format and version are its version tag and must be declared by the port.
+ * @alpha
+ */
+export declare interface IJournalWrite {
+    /** The owner-named non-empty collection. */
+    readonly collection: string;
+    /** The owner-defined non-empty key. */
+    readonly key: string;
+    /** The current revision the write replaces, or `0` for a new key. */
+    readonly expectedRevision: number;
+    /** The new owner-defined record. */
+    readonly record: IVersionedRecord;
+}
+
 /** 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';
+/**
+ * A supported observation operation with its own fact meaning. `container-kind`
+ * answers record, array or scalar without consuming any container member or
+ * scalar content; ordinary scalar reads still retain their literal values.
+ * @alpha
+ */
+export declare type IOperation = 'value' | 'own' | 'membership' | 'length' | 'keys' | 'container-kind';
+
+/**
+ * Run Supervision's operation journal, stored by History (RUN-011/012). It
+ * keeps owner-defined operation and deferral records, such as an intent
+ * committed before a send or a "not before" deferral, atomically and under
+ * writer fencing, without interpreting them: History owns only namespacing,
+ * collections, revisions, fencing and the declared-version check. A commit
+ * needs the current writer lease and checks holder, fence and unexpired lease
+ * in the same transaction as its compare-and-set checks and writes; reads
+ * need no lease and never see an uncommitted write.
+ * @alpha
+ */
+export declare interface IOperationJournal {
+    /** The frozen formats and versions this port was opened with. */
+    readonly formats: readonly IJournalFormat[];
+    /**
+     * Commit every write in one transaction. The whole commit is refused,
+     * unchanged, for a stale lease, an undeclared format or version, a current
+     * revision whose stored format or version this port does not understand
+     * (checked first, since such a caller cannot have read it), or an expected
+     * revision that is not the address's current revision.
+     */
+    commit(lease: IWriterLease, request: IJournalCommit): readonly IJournalRecord[];
+    /** The current revision at one address, or undefined if the key was never written there. */
+    read(address: IJournalAddress): IJournalRecord | undefined;
+    /** The current revision of every key in one collection, in order of first write. */
+    list(query: IJournalQuery): readonly IJournalRecord[];
+}
+
+/**
+ * Selects promotion records into one target environment, optionally only
+ * those naming one exact result.
+ * @alpha
+ */
+export declare interface IPromotionQuery {
+    /** The analysis and environment whose admitting promotions to read. */
+    readonly target: IHistoryScope;
+    /** When present, only promotions that name this exact result. */
+    readonly reference?: ICompletedResultReference;
+}
+
+/**
+ * One immutable promotion record. It admits the named results as candidates,
+ * dependencies and acceptance targets in its target environment and changes
+ * nothing else: each result keeps its exact reference, envelope, provenance
+ * and acceptances, and no current head moves in any environment. The target
+ * environment's later verifications record their own acceptances.
+ * @alpha
+ */
+export declare interface IPromotionRecord {
+    /** Store-wide never-reused promotion identity, increasing in record order. */
+    readonly promotionId: number;
+    /** The analysis and environment the results were admitted into. */
+    readonly target: IHistoryScope;
+    /** The writer fence under which the promotion was recorded. */
+    readonly fence: number;
+    /** The promoter's evidence, decoded and frozen. */
+    readonly evidence: IVersionedRecord;
+    /** The admitted exact results, each in its own publishing scope, in recorded order. */
+    readonly references: readonly ICompletedResultReference[];
+}
+
+/**
+ * Asks History to admit exact completed results of other environments into
+ * one target environment of the same analysis (RUN-017). A trial result
+ * satisfies a production lookup only through such a recorded promotion. The
+ * target names where the results are admitted; each reference keeps naming
+ * its own publishing environment. The evidence is the promoter's versioned
+ * record of who promoted what and why; History stores it opaquely.
+ * @alpha
+ */
+export declare interface IPromotionRequest {
+    /** The analysis and environment the results are admitted into. */
+    readonly target: IHistoryScope;
+    /**
+     * Distinct exact completed results of the target's analysis, none published
+     * in the target environment, in the promoter's order.
+     */
+    readonly references: readonly ICompletedResultReference[];
+    /** The promoter's versioned evidence for this promotion. */
+    readonly evidence: IVersionedRecord;
+}
 
 /**
  * Read-only recovery of one identified execution. Recovery reports what
@@ -564,7 +810,8 @@ export declare type ISelectedFingerprintResolution = {
  * 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}.
+ * Shape envelopes are never placed inside {@link ISelectedFact.fact}; Tracking
+ * may separately observe the bounded `container-kind` discriminant.
  * @alpha
  */
 export declare type ISelectedNode = 
@@ -626,7 +873,8 @@ declare interface ISnapshotCapability {
  * 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.
+ * host's durable configuration. Processes that open one new store at the same
+ * time all succeed within the bounded busy wait or fail with `SqliteBusyError`.
  * @alpha
  */
 export declare interface ISqliteCapability {
@@ -640,7 +888,8 @@ export declare interface ISqliteCapability {
  * 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.
+ * knowledge of what the tables mean. A statement, exec or transaction that
+ * cannot get a lock within the bounded wait fails with `SqliteBusyError`.
  *
  * Transactions are synchronous, top-level and IMMEDIATE: the write lock is
  * taken before the callback runs, the callback's writes commit together when
@@ -834,7 +1083,7 @@ export declare interface IVersionedSubject extends IScopedSubject {
 /**
  * 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.
+ * grants nothing; `contended` reports that storage was too busy to decide.
  * @alpha
  */
 export declare type IWriterAcquisition = {
@@ -849,7 +1098,7 @@ export declare type IWriterAcquisition = {
     readonly holder: string;
     /** When that holder's lease expires, in History's clock domain. */
     readonly expiresAt: number;
-};
+} | IWriterContention;
 
 /** A request for the writer lease. @alpha */
 export declare interface IWriterAcquisitionRequest {
@@ -859,6 +1108,28 @@ export declare interface IWriterAcquisitionRequest {
     readonly leaseMilliseconds: number;
 }
 
+/**
+ * Storage contention on a lease operation: another connection, possibly in
+ * another process, held SQLite's write lock past the host's bounded busy wait,
+ * so History could not decide and changed nothing, not even the clock
+ * high-water. It is a fact about storage, never about ownership (PUB-005): it
+ * neither grants nor refuses, and whether to try again is the caller's policy.
+ * @alpha
+ */
+export declare interface IWriterContention {
+    /** History could not take SQLite's write lock in time. */
+    readonly kind: 'contended';
+    /**
+     * The writer recorded at that moment, read without the write lock: its
+     * holder, fence and expiry as stored, whether or not the lease has expired.
+     * Undefined when no holder is recorded, or when that read was itself busy;
+     * History never guesses a holder.
+     */
+    readonly writer: IWriterLease | undefined;
+    /** The host's diagnostic of the contention; it carries no stored values. */
+    readonly detail: string;
+}
+
 /**
  * Proof of current single-logical-writer ownership. The holder is an opaque
  * caller identity; the fence is the store-wide token issued at acquisition,
@@ -877,6 +1148,46 @@ export declare interface IWriterLease {
     readonly expiresAt: number;
 }
 
+/**
+ * The outcome of renewing a lease the caller holds: `renewed` with the later
+ * expiry, or `contended` when storage was too busy to decide, in which case
+ * the lease is exactly as it was and is neither renewed nor refused. A stale
+ * or expired lease is not an outcome but a refusal (`StaleWriterError`).
+ * @alpha
+ */
+export declare type IWriterRenewal = {
+    /** The lease was extended. */
+    readonly kind: 'renewed';
+    /** The same holder and fence with the new expiry. */
+    readonly lease: IWriterLease;
+} | IWriterContention;
+
+/**
+ * A journal commit's compare-and-set expectation does not hold: the presented
+ * expected revision is not the key's current revision (a new-key expectation
+ * met an existing key, or an update met a later or absent revision). The
+ * whole commit was rolled back unchanged; the caller must re-read before
+ * deciding again.
+ * @alpha
+ */
+export declare class JournalConflictError extends Error {
+    /** Create a compare-and-set rejection with a diagnostic message. */
+    constructor(message: string);
+}
+
+/**
+ * A journal record's format or format version is not one the journal port
+ * declared. On a write the record is refused; on a read or list the stored
+ * record is refused rather than returned; a commit over a current revision of
+ * an undeclared version is refused rather than overwriting it. History never
+ * interprets or converts the content of another format version.
+ * @alpha
+ */
+export declare class JournalVersionError extends Error {
+    /** Create an undeclared-version refusal with a diagnostic message. */
+    constructor(message: string);
+}
+
 /** Options for the isolated, non-durable test backend. @public */
 export declare interface MemoryStoreOptions {
     /** Metadata compatibility identifier; the initial store format uses sha256. */

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

@@ -1,3 +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';
+export { AttemptConflictError, AttemptStateError, DuplicateRowError, FingerprintAlgorithmMismatchError, HistoryClockError, HistoryIntegrityError, HistorySchemaError, InvalidStorePatchError, JournalConflictError, JournalVersionError, 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, IJournalAddress, IJournalCommit, IJournalDeclaration, IJournalFormat, IJournalQuery, IJournalRecord, IJournalWrite, IOperation, IOperationJournal, IPromotionQuery, IPromotionRecord, IPromotionRequest, 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, IWriterContention, IWriterLease, IWriterRenewal, Identity, MemoryStoreOptions, Outcome, Path, RecordedRead, ResultKey, Store, StoreMetadata, Subject, SubjectPatch, SubjectRow } from './history.shared.untrimmed.js';