@microdelta/history 0.1.0 → 0.3.0

package/dist/src/durable/index.js

@@ -1,41 +1,15 @@
 import { decodeSnapshot, encodeSnapshot } from '@microdelta/value';
-import { AttemptConflictError, AttemptStateError, HistoryClockError, HistoryIntegrityError, StaleWriterError, } from './errors.js';
+import { AttemptConflictError, AttemptStateError, HistoryClockError, HistoryBusyError, HistoryIntegrityError, StaleWriterError, } from './errors.js';
 import { parseReference, referenceFor } from './locator.js';
+import { createJournalStore } from './journal.js';
+import { historyScope, integer, loadRecord, requireName, requireNonnegative, requirePositive, safeSum, storeRecord, text } from './records.js';
 import { initializeSchema } from './schema.js';
+import { isHistorySqliteBoundaryBusy, openHistorySqlite } from './sqlite-boundary.js';
 import { buildIndex, createSelectedIndex, indexVersion } from './selected-index.js';
 /** Identity tag for embedded SQL; the text is passed through unchanged. */
 const sql = String.raw;
 /** The only payload encoding History stores for completed results. */
 const payloadEncoding = 'MDS1';
-/** Require a non-empty string argument. */
-function requireName(value, name) {
-    if (typeof value !== 'string' || value.length === 0) {
-        throw new TypeError(`${name} must be a non-empty string`);
-    }
-    return value;
-}
-/** Require a positive safe-integer argument. */
-function requirePositive(value, name) {
-    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
-        throw new TypeError(`${name} must be a positive safe integer`);
-    }
-    return value;
-}
-/** Require a nonnegative safe-integer argument. */
-function requireNonnegative(value, name) {
-    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
-        throw new TypeError(`${name} must be a nonnegative safe integer`);
-    }
-    return value;
-}
-/** Add two safe integers or fail rather than round. */
-function safeSum(left, right, name) {
-    const sum = left + right;
-    if (!Number.isSafeInteger(sum)) {
-        throw new RangeError(`${name} exceeds the safe integer range`);
-    }
-    return sum;
-}
 /** Copy and validate a scoped subject argument. */
 function scopedSubject(value) {
     return { analysis: requireName(value.analysis, 'analysis'), environment: requireName(value.environment, 'environment'), subject: requireName(value.subject, 'subject') };
@@ -52,44 +26,6 @@ function attemptRequest(value) {
 function leaseArgument(lease) {
     return { holder: requireName(lease.holder, 'lease holder'), fence: requirePositive(lease.fence, 'lease fence'), expiresAt: requireNonnegative(lease.expiresAt, 'lease expiry') };
 }
-/** Validate and canonicalize an owner-defined versioned record. */
-function storeRecord(record, name) {
-    return {
-        format: requireName(record.format, `${name} format`),
-        formatVersion: requirePositive(record.formatVersion, `${name} format version`),
-        content: encodeSnapshot(record.content),
-    };
-}
-/** Decode a stored versioned record into frozen data, or fail as corruption. */
-function loadRecord(format, formatVersion, content, name) {
-    if (typeof format !== 'string' || format.length === 0 || typeof formatVersion !== 'number' || !Number.isSafeInteger(formatVersion) || formatVersion <= 0 || typeof content !== 'string') {
-        throw new HistoryIntegrityError(`Stored ${name} has a malformed version tag`);
-    }
-    let decoded;
-    try {
-        decoded = decodeSnapshot(content);
-    }
-    catch (error) {
-        throw new HistoryIntegrityError(`Stored ${name} is not canonical MDS1: ${error instanceof Error ? error.message : String(error)}`);
-    }
-    return Object.freeze({ format, formatVersion, content: decoded });
-}
-/** Narrow a stored cell to text. */
-function text(row, column) {
-    const value = row[column];
-    if (typeof value !== 'string') {
-        throw new HistoryIntegrityError(`Stored History column ${column} is not text`);
-    }
-    return value;
-}
-/** Narrow a stored cell to a safe integer. */
-function integer(row, column) {
-    const value = row[column];
-    if (typeof value !== 'number' || !Number.isSafeInteger(value)) {
-        throw new HistoryIntegrityError(`Stored History column ${column} is not an integer`);
-    }
-    return value;
-}
 /** Narrow a stored attempt state. */
 function attemptState(row) {
     const state = text(row, 'state');
@@ -107,22 +43,36 @@ function attemptState(row) {
 export function openDurableHistory(options) {
     const logicalStore = requireName(options.logicalStore, 'logicalStore');
     const clock = options.clock;
-    const connection = options.sqlite.openSqlite(options.location);
-    try {
-        initializeSchema(connection, logicalStore);
-    }
-    catch (error) {
-        connection.close();
-        throw error;
+    const connection = openHistorySqlite(options.sqlite, options.location);
+    /** Close a partly opened History handle without hiding the original opening failure. */
+    function duringOpening(operation) {
+        try {
+            return operation();
+        }
+        catch (error) {
+            try {
+                connection.close();
+            }
+            catch { /* The opening failure is the diagnostic owed to the caller. */ }
+            throw error;
+        }
     }
-    const statements = {
+    duringOpening(() => initializeSchema(connection, logicalStore));
+    const statements = duringOpening(() => ({
         writer: connection.prepare(sql `/* writer */ SELECT last_fence, holder, expires_at, time_high_water FROM history_writer WHERE singleton = 1`),
         observeTime: connection.prepare(sql `/* writer */ UPDATE history_writer SET time_high_water = ? WHERE singleton = 1`),
+        // Only a grant writes the fence. Renewal and release leave last_fence as
+        // they found it rather than writing back the presented lease's fence: the
+        // holder guard has already proved the two equal, and never assigning the
+        // column there means no future weakening of that guard could regress it.
         setHolder: connection.prepare(sql `/* writer */ UPDATE history_writer SET last_fence = ?, holder = ?, expires_at = ? WHERE singleton = 1`),
-        sequences: connection.prepare(sql `/* sequence */ SELECT last_attempt, last_publication, last_acceptance FROM history_sequences WHERE singleton = 1`),
+        extendHolder: connection.prepare(sql `/* writer */ UPDATE history_writer SET expires_at = ? WHERE singleton = 1`),
+        clearHolder: connection.prepare(sql `/* writer */ UPDATE history_writer SET holder = NULL, expires_at = ? WHERE singleton = 1`),
+        sequences: connection.prepare(sql `/* sequence */ SELECT last_attempt, last_publication, last_acceptance, last_promotion FROM history_sequences WHERE singleton = 1`),
         setAttemptSequence: connection.prepare(sql `/* allocate */ UPDATE history_sequences SET last_attempt = ? WHERE singleton = 1`),
         setPublicationSequence: connection.prepare(sql `/* publish */ UPDATE history_sequences SET last_publication = ? WHERE singleton = 1`),
         setAcceptanceSequence: connection.prepare(sql `/* accept */ UPDATE history_sequences SET last_acceptance = ? WHERE singleton = 1`),
+        setPromotionSequence: connection.prepare(sql `/* promote */ UPDATE history_sequences SET last_promotion = ? WHERE singleton = 1`),
         attemptByKey: connection.prepare(sql `/* attempt */ SELECT * FROM history_attempts WHERE analysis = ? AND environment = ? AND subject = ? AND attempt_key = ?`),
         attemptById: connection.prepare(sql `/* attempt */ SELECT * FROM history_attempts WHERE attempt_id = ?`),
         insertAttempt: connection.prepare(sql `/* allocate */ INSERT INTO history_attempts
@@ -147,20 +97,52 @@ export function openDurableHistory(options) {
       FROM history_results r LEFT JOIN history_attempts a ON a.attempt_id = r.result_id WHERE r.result_id = ?`),
         envelope: connection.prepare(sql `/* envelope */ SELECT result_id, analysis, environment, subject, version, publication, encoding, index_version,
       provenance_format, provenance_version, provenance FROM history_results WHERE result_id = ?`),
-        candidates: connection.prepare(sql `/* candidates */ SELECT result_id, analysis, environment, subject, version, publication, encoding, index_version,
-      provenance_format, provenance_version, provenance FROM history_results
-      WHERE analysis = ? AND environment = ? AND subject = ? AND version = ? ORDER BY publication DESC`),
+        // The local arm seeks the complete subject index. The promotion arm must
+        // visit target promotions before their results: its CROSS JOIN order avoids
+        // an analysis-wide result scan when no promotion exists. UNION removes a
+        // result admitted twice while retaining every distinct eligible result.
+        candidates: connection.prepare(sql `/* candidates */ WITH requested(analysis, environment, subject, version) AS (VALUES (?, ?, ?, ?))
+      SELECT * FROM (
+        SELECT r.result_id, r.analysis, r.environment, r.subject, r.version, r.publication, r.encoding, r.index_version,
+          r.provenance_format, r.provenance_version, r.provenance FROM requested s JOIN history_results r
+          ON r.analysis = s.analysis AND r.environment = s.environment AND r.subject = s.subject AND r.version = s.version
+        UNION
+        SELECT r.result_id, r.analysis, r.environment, r.subject, r.version, r.publication, r.encoding, r.index_version,
+          r.provenance_format, r.provenance_version, r.provenance FROM requested s CROSS JOIN history_promotions p
+          CROSS JOIN history_promotion_results pr CROSS JOIN history_results r
+          WHERE p.analysis = s.analysis AND p.environment = s.environment
+            AND pr.promotion_id = p.promotion_id AND r.result_id = pr.result_id
+            AND r.analysis = s.analysis AND r.subject = s.subject AND r.version = s.version
+      ) ORDER BY publication DESC`),
         dependencies: connection.prepare(sql `/* envelope */ SELECT d.position, d.dependency_id, r.result_id AS present, r.analysis, r.environment
       FROM history_dependencies d LEFT JOIN history_results r ON r.result_id = d.dependency_id WHERE d.attempt_id = ? ORDER BY d.position`),
         current: connection.prepare(sql `/* current */ SELECT c.result_id, r.result_id AS present
       FROM history_current c LEFT JOIN history_results r ON r.result_id = c.result_id AND r.analysis = c.analysis AND r.environment = c.environment AND r.subject = c.subject
       WHERE c.analysis = ? AND c.environment = ? AND c.subject = ?`),
-        insertAcceptance: connection.prepare(sql `/* accept */ INSERT INTO history_acceptances (acceptance_id, result_id, fence, evidence_format, evidence_version, evidence) VALUES (?, ?, ?, ?, ?, ?)`),
+        insertAcceptance: connection.prepare(sql `/* accept */ INSERT INTO history_acceptances (acceptance_id, result_id, environment, fence, evidence_format, evidence_version, evidence)
+      VALUES (?, ?, ?, ?, ?, ?, ?)`),
         insertAcceptanceDependency: connection.prepare(sql `/* accept */ INSERT INTO history_acceptance_dependencies (acceptance_id, position, dependency_id) VALUES (?, ?, ?)`),
-        acceptances: connection.prepare(sql `/* acceptance */ SELECT acceptance_id, fence, evidence_format, evidence_version, evidence FROM history_acceptances WHERE result_id = ? ORDER BY acceptance_id`),
+        // An insertion is acknowledged by its exact identity within the intended result and environment, never by a history scan or newest-row guess.
+        acceptanceById: connection.prepare(sql `/* acceptance */ SELECT acceptance_id, result_id, environment, fence, evidence_format, evidence_version, evidence FROM history_acceptances
+      WHERE acceptance_id = ? AND result_id = ? AND environment = ?`),
+        // Explicit historical inspection remains complete and ordered, independently of the acknowledgement hot path.
+        acceptances: connection.prepare(sql `/* acceptance */ SELECT acceptance_id, environment, fence, evidence_format, evidence_version, evidence FROM history_acceptances
+      WHERE result_id = ? AND environment = ? ORDER BY acceptance_id`),
         acceptanceDependencies: connection.prepare(sql `/* acceptance */ SELECT d.position, d.dependency_id, r.result_id AS present, r.analysis, r.environment
       FROM history_acceptance_dependencies d LEFT JOIN history_results r ON r.result_id = d.dependency_id WHERE d.acceptance_id = ? ORDER BY d.position`),
-    };
+        promoted: connection.prepare(sql `/* promotion */ SELECT 1 AS present FROM history_promotion_results pr JOIN history_promotions p ON p.promotion_id = pr.promotion_id
+      WHERE pr.result_id = ? AND p.analysis = ? AND p.environment = ? LIMIT 1`),
+        insertPromotion: connection.prepare(sql `/* promote */ INSERT INTO history_promotions (promotion_id, analysis, environment, fence, evidence_format, evidence_version, evidence)
+      VALUES (?, ?, ?, ?, ?, ?, ?)`),
+        insertPromotionResult: connection.prepare(sql `/* promote */ INSERT INTO history_promotion_results (promotion_id, position, result_id) VALUES (?, ?, ?)`),
+        promotion: connection.prepare(sql `/* promotion */ SELECT * FROM history_promotions WHERE promotion_id = ?`),
+        promotions: connection.prepare(sql `/* promotion */ SELECT * FROM history_promotions WHERE analysis = ? AND environment = ? ORDER BY promotion_id`),
+        promotionsNaming: connection.prepare(sql `/* promotion */ SELECT p.* FROM history_promotions p
+      WHERE p.analysis = ? AND p.environment = ? AND EXISTS (SELECT 1 FROM history_promotion_results pr WHERE pr.promotion_id = p.promotion_id AND pr.result_id = ?)
+      ORDER BY p.promotion_id`),
+        promotionResults: connection.prepare(sql `/* promotion */ SELECT pr.position, pr.result_id, r.result_id AS present, r.analysis, r.environment
+      FROM history_promotion_results pr LEFT JOIN history_results r ON r.result_id = pr.result_id WHERE pr.promotion_id = ? ORDER BY pr.position`),
+    }));
     /**
      * Resolve an exact reference to a completed result of this store: the
      * locator grammar, logical store, analysis, environment, existence,
@@ -190,11 +172,44 @@ export function openDurableHistory(options) {
         }
         return { resultId: parts.resultId, scope: { analysis: parts.analysis, environment: parts.environment } };
     }
-    const index = createSelectedIndex(connection, options.sha256, (reference) => resolveResult(reference).resultId);
+    const index = duringOpening(() => createSelectedIndex(connection, options.sha256, (reference) => resolveResult(reference).resultId));
     /** Issue the exact reference for a stored result row. */
     function referenceOf(resultId, scope) {
         return referenceFor({ logicalStore, analysis: scope.analysis, environment: scope.environment, resultId });
     }
+    /** Whether a recorded promotion names a result for the environment `scope` (RUN-017). */
+    function isPromotedInto(resultId, scope) {
+        return statements.promoted.get(resultId, scope.analysis, scope.environment) !== undefined;
+    }
+    /**
+     * Resolve an exact reference that must be admissible in `scope`: published
+     * in that environment, or of the same analysis and named by a promotion into
+     * it. Anything else is an integrity failure, never a miss; the returned
+     * scope is the result's own publishing scope.
+     */
+    function resolveAdmissible(reference, scope) {
+        const resolved = resolveResult(reference);
+        const published = resolved.scope;
+        if (published.analysis !== scope.analysis || (published.environment !== scope.environment && !isPromotedInto(resolved.resultId, scope))) {
+            throw new HistoryIntegrityError(`Completed result ${reference.locator} is not admissible in environment ${scope.environment} of analysis ${scope.analysis}: it was not published there and no promotion names it there`);
+        }
+        return resolved;
+    }
+    /**
+     * The namespace an acceptance is recorded or read in, always named by the
+     * caller: the result's publishing environment, or another environment of
+     * the same analysis that a promotion admits the result into.
+     */
+    function acceptanceScope(reference, resultId, published, environment) {
+        if (environment === published.environment) {
+            return published;
+        }
+        const scope = { analysis: published.analysis, environment };
+        if (!isPromotedInto(resultId, scope)) {
+            throw new HistoryIntegrityError(`Completed result ${reference.locator} is not admissible in environment ${environment} of analysis ${published.analysis}: it was not published there and no promotion names it there`);
+        }
+        return scope;
+    }
     /** Read the singleton writer row. */
     function readWriter() {
         const row = statements.writer.get();
@@ -212,8 +227,8 @@ export function openDurableHistory(options) {
      * of a valid host reading and the persisted high-water, which is then
      * persisted. A host failure or invalid reading aborts the transaction.
      */
-    function observeTime(writer) {
-        const reading = clock.currentEpochMilliseconds();
+    function observeTime(writer, readClock = () => clock.currentEpochMilliseconds()) {
+        const reading = readClock();
         if (!Number.isSafeInteger(reading) || reading < 0) {
             throw new HistoryClockError(`Clock reading ${String(reading)} is not a nonnegative safe integer of epoch milliseconds`);
         }
@@ -223,19 +238,68 @@ export function openDurableHistory(options) {
         }
         return now;
     }
+    /**
+     * The contention outcome of a lease operation whose transaction could not
+     * take SQLite's write lock (PUB-005). The recorded writer is read without
+     * the write lock; a read that is itself busy leaves it undefined rather than
+     * guessed, while any other read failure, such as a missing writer row, is
+     * thrown as the failure it is.
+     */
+    function contention(busy) {
+        let writer;
+        try {
+            const recorded = readWriter();
+            writer = recorded.holder === null ? undefined : Object.freeze({ holder: recorded.holder, fence: recorded.lastFence, expiresAt: recorded.expiresAt });
+        }
+        catch (error) {
+            if (!isHistorySqliteBoundaryBusy(error)) {
+                throw error;
+            }
+        }
+        return Object.freeze({ kind: 'contended', writer, detail: busy.message });
+    }
+    /**
+     * Run a lease operation that a waiter repeats, reporting SQLite contention
+     * as History's typed outcome. A clock callback's exact exception remains a
+     * callback failure even if it contains a busy error from this or another
+     * History handle; only boundary errors outside that callback qualify.
+     */
+    function orContended(operation) {
+        let callbackFailed = false;
+        let callbackError;
+        const readClock = () => {
+            try {
+                return clock.currentEpochMilliseconds();
+            }
+            catch (error) {
+                callbackFailed = true;
+                callbackError = error;
+                throw error;
+            }
+        };
+        try {
+            return operation(readClock);
+        }
+        catch (error) {
+            if ((callbackFailed && error === callbackError) || !isHistorySqliteBoundaryBusy(error)) {
+                throw error;
+            }
+            return contention(error);
+        }
+    }
     /**
      * Run one ownership-sensitive mutation. Inside one transaction the time is
      * observed and holder, fence and unexpired lease are checked before
      * `operation` runs. A stale lease commits only the time observation and then
      * fails with {@link StaleWriterError}; any other failure rolls everything back.
      */
-    function asHolder(presented, operation) {
+    function asHolder(presented, operation, readClock = () => clock.currentEpochMilliseconds()) {
         const lease = leaseArgument(presented);
         let outcome;
         let stale;
         connection.transaction(() => {
             const writer = readWriter();
-            const now = observeTime(writer);
+            const now = observeTime(writer, readClock);
             if (writer.holder !== lease.holder || writer.lastFence !== lease.fence) {
                 stale = `Writer lease ${lease.holder}/${String(lease.fence)} is not the current holder`;
             }
@@ -252,6 +316,8 @@ export function openDurableHistory(options) {
         }
         return outcome.value;
     }
+    /** Run Supervision's journal ports share this connection and writer check. */
+    const journals = duringOpening(() => createJournalStore(connection, asHolder));
     /** Read one attempt row by identity inside the caller's transaction. */
     function requireAttemptRow(attemptId) {
         const row = statements.attemptById.get(attemptId);
@@ -281,9 +347,25 @@ export function openDurableHistory(options) {
             outcome,
         });
     }
+    /**
+     * A stored dependency published outside the dependent's environment is
+     * valid only when it is of the same analysis and a promotion admits it into
+     * the dependent's environment. Its reference keeps its own publishing scope
+     * and must resolve exactly like any other.
+     */
+    function promotedDependency(dependencyId, row, scope) {
+        const published = { analysis: text(row, 'analysis'), environment: text(row, 'environment') };
+        if (published.analysis !== scope.analysis || !isPromotedInto(dependencyId, scope)) {
+            throw new HistoryIntegrityError(`Stored dependency on result ${String(dependencyId)} is outside the dependent's scope`);
+        }
+        const exact = referenceOf(dependencyId, published);
+        resolveResult(exact, published);
+        return exact;
+    }
     /**
      * Read an attempt's or acceptance's dependency rows and verify each still
-     * names a stored result in the same scope, in contiguous recorded order.
+     * names a stored result admissible in the dependent's scope (published
+     * there or promoted into it), in contiguous recorded order.
      */
     function dependenciesOf(rows, scope) {
         return Object.freeze(rows.map((row, position) => {
@@ -295,7 +377,7 @@ export function openDurableHistory(options) {
                 throw new HistoryIntegrityError(`Stored dependency on result ${String(dependencyId)} is dangling`);
             }
             if (row.analysis !== scope.analysis || row.environment !== scope.environment) {
-                throw new HistoryIntegrityError(`Stored dependency on result ${String(dependencyId)} is outside the dependent's scope`);
+                return promotedDependency(dependencyId, row, scope);
             }
             // A returned dependency must satisfy the same exact contract as any reference: completed, in scope, supported.
             const reference = referenceOf(dependencyId, scope);
@@ -322,9 +404,9 @@ export function openDurableHistory(options) {
             dependencies: dependenciesOf(statements.dependencies.all(resultId), scope),
         });
     }
-    /** Resolve each dependency reference to a stored result in `scope`, inside the caller's transaction. */
+    /** Resolve each dependency reference to a stored result admissible in `scope`, inside the caller's transaction. */
     function dependencyIds(references, scope) {
-        return references.map((reference) => resolveResult(reference, scope).resultId);
+        return references.map((reference) => resolveAdmissible(reference, scope).resultId);
     }
     /**
      * Every path that reports an attempt's durable outcome to a caller
@@ -370,12 +452,16 @@ export function openDurableHistory(options) {
             throw new AttemptConflictError(`Attempt key ${request.attemptKey} already identifies a different execution intent or version`);
         }
     }
-    /** Read and convert one acceptance record's dependencies. */
+    /** Read and convert one acceptance record, recorded in `scope`, with its dependencies. */
     function acceptanceOf(row, reference, scope) {
         const acceptanceId = integer(row, 'acceptance_id');
+        if (text(row, 'environment') !== scope.environment) {
+            throw new HistoryIntegrityError(`Stored acceptance ${String(acceptanceId)} belongs to another environment`);
+        }
         return Object.freeze({
             acceptanceId,
             reference,
+            environment: scope.environment,
             fence: integer(row, 'fence'),
             evidence: loadRecord(row.evidence_format, row.evidence_version, row.evidence, 'acceptance evidence'),
             dependencies: dependenciesOf(statements.acceptanceDependencies.all(acceptanceId), scope),
@@ -387,7 +473,44 @@ export function openDurableHistory(options) {
         if (row === undefined) {
             throw new HistoryIntegrityError('History sequence row is missing');
         }
-        return { lastAttempt: integer(row, 'last_attempt'), lastPublication: integer(row, 'last_publication'), lastAcceptance: integer(row, 'last_acceptance') };
+        return {
+            lastAttempt: integer(row, 'last_attempt'),
+            lastPublication: integer(row, 'last_publication'),
+            lastAcceptance: integer(row, 'last_acceptance'),
+            lastPromotion: integer(row, 'last_promotion'),
+        };
+    }
+    /**
+     * Convert one stored promotion row to its frozen record. Every named result
+     * must still resolve exactly, belong to the promotion's analysis and have
+     * been published outside its target environment.
+     */
+    function promotionOf(row) {
+        const promotionId = integer(row, 'promotion_id');
+        const target = Object.freeze({ analysis: text(row, 'analysis'), environment: text(row, 'environment') });
+        const references = statements.promotionResults.all(promotionId).map((named, position) => {
+            const resultId = integer(named, 'result_id');
+            if (integer(named, 'position') !== position || named.present === null) {
+                throw new HistoryIntegrityError(`Stored promotion ${String(promotionId)} names a missing result or is out of order`);
+            }
+            const published = { analysis: text(named, 'analysis'), environment: text(named, 'environment') };
+            if (published.analysis !== target.analysis || published.environment === target.environment) {
+                throw new HistoryIntegrityError(`Stored promotion ${String(promotionId)} names result ${String(resultId)} outside its analysis or from its own target`);
+            }
+            const exact = referenceOf(resultId, published);
+            resolveResult(exact, published);
+            return exact;
+        });
+        if (references.length === 0) {
+            throw new HistoryIntegrityError(`Stored promotion ${String(promotionId)} names no result`);
+        }
+        return Object.freeze({
+            promotionId,
+            target,
+            fence: integer(row, 'fence'),
+            evidence: loadRecord(row.evidence_format, row.evidence_version, row.evidence, 'promotion evidence'),
+            references: Object.freeze(references),
+        });
     }
     const history = {
         logicalStore,
@@ -396,9 +519,9 @@ export function openDurableHistory(options) {
             const holder = requireName(request.holder, 'holder');
             const leaseMilliseconds = requirePositive(request.leaseMilliseconds, 'leaseMilliseconds');
             let acquisition;
-            connection.transaction(() => {
+            const busy = orContended((readClock) => connection.transaction(() => {
                 const writer = readWriter();
-                const now = observeTime(writer);
+                const now = observeTime(writer, readClock);
                 if (writer.holder !== null && writer.expiresAt > now) {
                     acquisition = Object.freeze({ kind: 'held', holder: writer.holder, expiresAt: writer.expiresAt });
                     return undefined;
@@ -408,7 +531,10 @@ export function openDurableHistory(options) {
                 statements.setHolder.run(fence, holder, expiresAt);
                 acquisition = Object.freeze({ kind: 'acquired', lease: Object.freeze({ holder, fence, expiresAt }) });
                 return undefined;
-            });
+            }));
+            if (busy !== undefined) {
+                return busy;
+            }
             if (acquisition === undefined) {
                 throw new HistoryIntegrityError('Writer acquisition produced no outcome');
             }
@@ -416,16 +542,18 @@ export function openDurableHistory(options) {
         },
         renewWriter(lease, leaseMilliseconds) {
             const duration = requirePositive(leaseMilliseconds, 'leaseMilliseconds');
-            return asHolder(lease, (now) => {
+            // Read caller-owned lease properties before classifying storage contention.
+            const presented = leaseArgument(lease);
+            return orContended((readClock) => asHolder(presented, (now) => {
                 const expiresAt = safeSum(now, duration, 'lease expiry');
-                statements.setHolder.run(lease.fence, lease.holder, expiresAt);
-                return Object.freeze({ holder: lease.holder, fence: lease.fence, expiresAt });
-            });
+                statements.extendHolder.run(expiresAt);
+                return Object.freeze({ kind: 'renewed', lease: Object.freeze({ holder: presented.holder, fence: presented.fence, expiresAt }) });
+            }, readClock));
         },
         releaseWriter(lease) {
             asHolder(lease, (now) => {
-                // Release clears the holder but never resets the fence counter.
-                statements.setHolder.run(lease.fence, null, now);
+                // Release clears the holder but never touches the fence counter.
+                statements.clearHolder.run(now);
             });
         },
         currentWriter() {
@@ -560,26 +688,86 @@ export function openDurableHistory(options) {
         recordAcceptance(lease, request) {
             const evidence = storeRecord(request.evidence, 'acceptance evidence');
             const references = [...request.dependencies];
+            const environment = requireName(request.environment, 'acceptance environment');
             return asHolder(lease, () => {
-                const { resultId, scope } = resolveResult(request.reference);
+                const { resultId, scope: published } = resolveResult(request.reference);
+                // The acceptance and its dependencies belong to the named accepting environment's namespace.
+                const scope = acceptanceScope(request.reference, resultId, published, environment);
                 const dependencies = dependencyIds(references, scope);
                 const acceptanceId = safeSum(readSequences().lastAcceptance, 1, 'acceptance identity');
                 statements.setAcceptanceSequence.run(acceptanceId);
-                statements.insertAcceptance.run(acceptanceId, resultId, lease.fence, evidence.format, evidence.formatVersion, evidence.content);
+                statements.insertAcceptance.run(acceptanceId, resultId, scope.environment, lease.fence, evidence.format, evidence.formatVersion, evidence.content);
                 dependencies.forEach((dependencyId, position) => {
                     statements.insertAcceptanceDependency.run(acceptanceId, position, dependencyId);
                 });
-                const row = statements.acceptances.all(resultId).find((candidate) => candidate.acceptance_id === acceptanceId);
+                const row = statements.acceptanceById.get(acceptanceId, resultId, scope.environment);
                 if (row === undefined) {
                     throw new HistoryIntegrityError('Recorded acceptance is not readable');
                 }
-                return acceptanceOf(row, referenceOf(resultId, scope), scope);
+                // The returned row must attest to this transaction's inserted identity, scope, fence, and evidence;
+                // a stale or mis-scoped row is not a successful acceptance even if the backend returned one row.
+                if (integer(row, 'acceptance_id') !== acceptanceId || integer(row, 'result_id') !== resultId
+                    || text(row, 'environment') !== scope.environment || integer(row, 'fence') !== lease.fence
+                    || text(row, 'evidence_format') !== evidence.format || integer(row, 'evidence_version') !== evidence.formatVersion
+                    || text(row, 'evidence') !== evidence.content) {
+                    throw new HistoryIntegrityError('Recorded acceptance readback does not match the inserted record');
+                }
+                return acceptanceOf(row, referenceOf(resultId, published), scope);
+            });
+        },
+        readAcceptances(reference, presentedEnvironment) {
+            const environment = requireName(presentedEnvironment, 'acceptance environment');
+            const { resultId, scope: published } = resolveResult(reference);
+            const scope = acceptanceScope(reference, resultId, published, environment);
+            const exact = referenceOf(resultId, published);
+            return Object.freeze(statements.acceptances.all(resultId, scope.environment).map((row) => acceptanceOf(row, exact, scope)));
+        },
+        promoteResults(lease, request) {
+            const target = historyScope(request.target);
+            const evidence = storeRecord(request.evidence, 'promotion evidence');
+            const presented = request.references;
+            if (!Array.isArray(presented) || presented.length === 0) {
+                throw new TypeError('A promotion needs at least one completed-result reference');
+            }
+            const references = [...request.references];
+            return asHolder(lease, () => {
+                const resultIds = references.map((reference) => {
+                    const { resultId, scope: published } = resolveResult(reference);
+                    // A reference that cannot be promoted into the target is one integrity class, like any wrong-scope reference.
+                    if (published.analysis !== target.analysis) {
+                        throw new HistoryIntegrityError(`Completed result ${reference.locator} belongs to another analysis; promotion never crosses analyses`);
+                    }
+                    if (published.environment === target.environment) {
+                        throw new HistoryIntegrityError(`Completed result ${reference.locator} was published in ${target.environment}; only results of other environments can be promoted into it`);
+                    }
+                    return resultId;
+                });
+                if (new Set(resultIds).size !== resultIds.length) {
+                    throw new TypeError('A promotion names each completed result at most once');
+                }
+                const promotionId = safeSum(readSequences().lastPromotion, 1, 'promotion identity');
+                statements.setPromotionSequence.run(promotionId);
+                statements.insertPromotion.run(promotionId, target.analysis, target.environment, lease.fence, evidence.format, evidence.formatVersion, evidence.content);
+                resultIds.forEach((resultId, position) => {
+                    statements.insertPromotionResult.run(promotionId, position, resultId);
+                });
+                const row = statements.promotion.get(promotionId);
+                if (row === undefined) {
+                    throw new HistoryIntegrityError('Recorded promotion is not readable');
+                }
+                return promotionOf(row);
             });
         },
-        readAcceptances(reference) {
-            const { resultId, scope } = resolveResult(reference);
-            const exact = referenceOf(resultId, scope);
-            return Object.freeze(statements.acceptances.all(resultId).map((row) => acceptanceOf(row, exact, scope)));
+        readPromotions(query) {
+            const target = historyScope(query.target);
+            if (query.reference === undefined) {
+                return Object.freeze(statements.promotions.all(target.analysis, target.environment).map(promotionOf));
+            }
+            const { resultId } = resolveResult(query.reference);
+            return Object.freeze(statements.promotionsNaming.all(target.analysis, target.environment, resultId).map(promotionOf));
+        },
+        openJournal(declaration) {
+            return journals.open(declaration);
         },
         close() {
             connection.close();