@microdelta/history 0.1.0 → 0.3.0

package/README.md

@@ -14,9 +14,21 @@ single-file schema, distinct from the legacy Store, with:
 - never-reused attempt identities with stable keys and intent digests;
 - staging and one-commit atomic publication with a current pointer per scoped subject;
 - immutable completed results with an exact scoped selected reader generated from their canonical payload;
-- separate acceptance records.
+- separate acceptance records, namespaced by the explicitly named environment that recorded them;
+- environment namespaces within one store, so a trial run's attempts, heads,
+  candidates, acceptances and journal records never satisfy production;
+- recorded, fenced promotions that admit named exact results of one environment
+  into another of the same analysis, without moving or rewriting either one's history;
+- Run Supervision's operation journal: opaque versioned records per environment,
+  owner-named collection and key, committed atomically by compare-and-set under
+  writer fencing, with undeclared record formats and versions refused.
 
-It stores Resolution's provenance as a versioned opaque record and never decides
-reuse eligibility or freshness. See the
+It stores Resolution's provenance and Supervision's journal records as
+versioned opaque records and never decides reuse eligibility, freshness or
+operation meaning. The durable schema is at version 3, which rejects replacement
+of immutable records through primary keys, secondary unique keys and SQLite row
+identity aliases. Existing version 1 and version 2 durable files, and files at
+any other unsupported version, are explicitly rejected; no migration is
+provided. The separate legacy Store schema is unchanged. See the
 [package map](../../docs/package-map.md) and the
 [durable History evidence record](../../docs/validation/m3-durable-history-2026-09-27.md).

package/dist/api/history.alpha.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.alpha.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.alpha.js';
+export { AttemptConflictError, AttemptStateError, DuplicateRowError, FingerprintAlgorithmMismatchError, HistoryBusyError, HistoryClockError, HistoryIntegrityError, HistorySchemaError, InvalidStorePatchError, JournalConflictError, JournalVersionError, MissingRowError, StaleWriterError, createMemoryStore, openDurableHistory } from './history.shared.alpha.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, ISqliteOpenOptions, 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.alpha.js';

package/dist/api/history.root.raw.alpha.d.ts

@@ -2,8 +2,10 @@
  * Result History & Publication. This entry exposes the existing row Store,
  * its memory adapter and compatibility schema unchanged, the exact
  * completed-result reading ports, and the project-private alpha durable
- * authority that owns attempts, the single logical writer, atomic publication
- * and acceptance records. It never decides candidate validity or freshness.
+ * authority that owns attempts, the single logical writer, atomic publication,
+ * acceptance records, environment namespaces, recorded promotions and Run
+ * Supervision's opaque operation journal. It never decides candidate validity
+ * or freshness and never interprets journal records.
  * @packageDocumentation
  */
 
@@ -108,6 +110,21 @@ export declare interface GenerationRow {
 /** Retained lifecycle states interpreted by repository and claim, not by storage. @public */
 export declare type GenerationState = 'claimed' | 'current' | 'superseded' | 'abandoned';
 
+/**
+ * A History-owned SQLite operation exhausted Machine's bounded busy wait.
+ * The exact host failure is retained as `cause`, so callers can distinguish
+ * contention from corruption or a stale writer without losing host detail.
+ * History wraps only failures raised at its SQLite capability boundary, never
+ * an application callback that happened to throw a Machine busy error.
+ * @alpha
+ */
+export declare class HistoryBusyError extends Error {
+    /** The exact Machine failure that History received. */
+    readonly cause: SqliteBusyError;
+    /** Create History's boundary failure while retaining the original host error. */
+    constructor(message: string, cause: SqliteBusyError);
+}
+
 /**
  * The injected clock failed to produce a nonnegative safe-integer epoch
  * millisecond reading, so the time-dependent operation was refused unchanged.
@@ -158,6 +175,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. */
@@ -178,8 +197,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. */
@@ -371,6 +404,17 @@ 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
+ * History-owned SQLite operation, including opening and reads, fails with
+ * `HistoryBusyError` whose cause is the exact Machine `SqliteBusyError`.
+ * Callback-thrown failures retain their identity and do not become contention
+ * outcomes. Whether to try again is always the caller's policy, never History's.
  * @alpha
  */
 export declare interface IDurableHistory {
@@ -378,11 +422,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;
@@ -405,9 +458,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;
@@ -415,8 +476,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;
 }
@@ -445,7 +523,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 {
@@ -455,14 +536,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
@@ -566,7 +831,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 = 
@@ -628,21 +894,23 @@ 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 {
     /** Open or create the database file at `location` and return its owned connection. */
-    openSqlite(location: string): ISqliteConnection;
+    openSqlite(location: string, options?: ISqliteOpenOptions): 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
+ * configuration for every connection: selected persistent journaling, 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
@@ -677,6 +945,18 @@ export declare interface ISqliteConnection {
     close(): void;
 }
 
+/** Host journal selection for dedicated storage; schema and retention remain caller-owned. @alpha */
+export declare interface ISqliteOpenOptions {
+    /**
+     * WAL is the default. DELETE uses rollback journaling with FULL synchronous
+     * commits, allowing side-effect-free readers but permitting reader/writer
+     * contention. DELETE refuses existing WAL files instead of changing them.
+     * Cooperative owners must keep the pathname and journal layout stable from
+     * preflight through opening and for the lifetime of every handle.
+     */
+    readonly journalMode: 'wal' | 'delete';
+}
+
 /**
  * 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
@@ -836,7 +1116,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 = {
@@ -851,7 +1131,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 {
@@ -861,6 +1141,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,
@@ -879,6 +1181,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. */
@@ -956,6 +1298,23 @@ export declare type ResultKey = {
     subjectHash: string;
 };
 
+/**
+ * The SQLite capability gave up waiting for another connection, possibly in
+ * another process, to release a lock it needs. A host raises it, instead of
+ * any driver-specific error, when its bounded busy wait is exhausted while
+ * opening a store or running a statement or transaction. The failed operation
+ * had no effect, so the caller may retry it or report contention to its own
+ * caller; telling a busy store apart from a broken one is the purpose of this
+ * type. Hosts never use it for corruption, misuse or other failures.
+ * @alpha
+ */
+declare class SqliteBusyError extends Error {
+    /** How long, in milliseconds, the host waited before giving up. */
+    readonly waitedMilliseconds: number;
+    /** Create a busy-exhaustion failure that records the wait that was spent. */
+    constructor(message: string, waitedMilliseconds: number, options?: ErrorOptions);
+}
+
 /**
  * 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

package/dist/api/history.root.raw.beta.d.ts

@@ -2,8 +2,10 @@
  * Result History & Publication. This entry exposes the existing row Store,
  * its memory adapter and compatibility schema unchanged, the exact
  * completed-result reading ports, and the project-private alpha durable
- * authority that owns attempts, the single logical writer, atomic publication
- * and acceptance records. It never decides candidate validity or freshness.
+ * authority that owns attempts, the single logical writer, atomic publication,
+ * acceptance records, environment namespaces, recorded promotions and Run
+ * Supervision's opaque operation journal. It never decides candidate validity
+ * or freshness and never interprets journal records.
  * @packageDocumentation
  */
 
@@ -92,6 +94,8 @@ export declare interface GenerationRow {
 /** 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: HistoryBusyError */
+
 /* Excluded from this release type: HistoryClockError */
 
 /* Excluded from this release type: HistoryIntegrityError */
@@ -153,6 +157,20 @@ export declare type Identity = {
 
 /* 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 */
@@ -161,6 +179,14 @@ export declare class InvalidStorePatchError extends Error {
 
 /* 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 */
@@ -199,6 +225,8 @@ declare interface ISnapshotCapability {
 
 /* Excluded from this release type: ISqliteConnection */
 
+/* Excluded from this release type: ISqliteOpenOptions */
+
 /* Excluded from this release type: ISqliteRow */
 
 /* Excluded from this release type: ISqliteRunResult */
@@ -227,8 +255,16 @@ declare interface ISnapshotCapability {
 
 /* 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. */
@@ -300,6 +336,8 @@ export declare type ResultKey = {
     subjectHash: string;
 };
 
+/* Excluded from this release type: SqliteBusyError */
+
 /* Excluded from this release type: StaleWriterError */
 
 /**