@microdelta/history 0.1.0 → 0.2.0

package/dist/src/durable/index.js

@@ -1,41 +1,51 @@
+/**
+ * History's durable SQLite authority: the single consistency owner for
+ * attempts, the single logical writer, atomic publication, current pointers,
+ * immutable completed results, separate acceptance records, recorded
+ * promotions and Run Supervision's operation journal (PUB-001–004,
+ * RES-002–007, ARC-007, RUN-011/012/017). It owns every SQL statement and
+ * lifecycle decision over injected Machine capabilities; Node access stays in
+ * the host adapter.
+ *
+ * Every record lives in one environment namespace of one analysis. A result
+ * is admissible in the environment that published it and, only through a
+ * recorded promotion, in another environment of the same analysis: there it
+ * may be a candidate, a dependency or an acceptance target, while keeping its
+ * own exact reference, and nothing else crosses environments.
+ *
+ * Transition and recovery outcomes (each row is one IMMEDIATE transaction):
+ *
+ * | Transition | Durable change | Death before commit | Death after commit |
+ * | --- | --- | --- | --- |
+ * | acquire | new holder, fence + 1, expiry | no change | lease held until expiry |
+ * | renew | later expiry; fence unchanged | lease unchanged | lease extended |
+ * | release | no holder; fence unchanged | lease held until expiry | next grant needs no expiry |
+ * | allocate | attempt counter + 1, `allocated` attempt with key and intent | identity never issued | identity consumed, no result |
+ * | stage | `staged` content and dependencies | attempt stays `allocated` | candidate evidence only, never a result |
+ * | publish | result, index, provenance, `completed`, current pointer | attempt stays `staged` | complete result; recover by key |
+ * | abandon | `failed`/`interrupted` with evidence | attempt unchanged | attempt ended without result |
+ * | accept | acceptance record in the accepting environment naming an existing result | no change | record retained; result untouched |
+ * | promote | promotion record naming exact results for a target environment | no change, identity never issued | results admitted there; nothing else changes |
+ * | journal commit | one immutable revision per write (see `journal.ts`) | no revision, no sequence issued | every revision durable |
+ *
+ * It decides no reuse eligibility or freshness and interprets no provenance,
+ * promotion evidence or journal record.
+ * This is single-file process-termination scope, not a concurrency, power-loss
+ * or distributed-time guarantee.
+ * @packageDocumentation
+ */
+import { SqliteBusyError } from '@microdelta/machine';
 import { decodeSnapshot, encodeSnapshot } from '@microdelta/value';
 import { AttemptConflictError, AttemptStateError, HistoryClockError, 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 { 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 +62,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');
@@ -118,11 +90,18 @@ export function openDurableHistory(options) {
     const statements = {
         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,19 +126,37 @@ 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 = ?`),
+        // Results admissible in the subject's environment: published there, or named by a promotion into it.
         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`),
+      provenance_format, provenance_version, provenance FROM history_results r
+      WHERE r.analysis = ? AND r.subject = ? AND r.version = ?
+        AND (r.environment = ? OR EXISTS (SELECT 1 FROM history_promotion_results pr JOIN history_promotions p ON p.promotion_id = pr.promotion_id
+          WHERE pr.result_id = r.result_id AND p.analysis = r.analysis AND p.environment = ?))
+      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`),
+        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
@@ -195,6 +192,39 @@ export function openDurableHistory(options) {
     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();
@@ -223,6 +253,42 @@ 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 (!(error instanceof SqliteBusyError)) {
+                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. Only the host's busy failure qualifies, and it
+     * guarantees the transaction changed nothing; every other failure is thrown.
+     */
+    function orContended(operation) {
+        try {
+            return operation();
+        }
+        catch (error) {
+            if (!(error instanceof SqliteBusyError)) {
+                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
@@ -252,6 +318,8 @@ export function openDurableHistory(options) {
         }
         return outcome.value;
     }
+    /** Run Supervision's journal ports share this connection and writer check. */
+    const journals = 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 +349,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 +379,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 +406,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 +454,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 +475,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,7 +521,7 @@ export function openDurableHistory(options) {
             const holder = requireName(request.holder, 'holder');
             const leaseMilliseconds = requirePositive(request.leaseMilliseconds, 'leaseMilliseconds');
             let acquisition;
-            connection.transaction(() => {
+            const busy = orContended(() => connection.transaction(() => {
                 const writer = readWriter();
                 const now = observeTime(writer);
                 if (writer.holder !== null && writer.expiresAt > now) {
@@ -408,7 +533,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 +544,16 @@ export function openDurableHistory(options) {
         },
         renewWriter(lease, leaseMilliseconds) {
             const duration = requirePositive(leaseMilliseconds, 'leaseMilliseconds');
-            return asHolder(lease, (now) => {
+            return orContended(() => asHolder(lease, (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: lease.holder, fence: lease.fence, expiresAt }) });
+            }));
         },
         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() {
@@ -529,7 +657,7 @@ export function openDurableHistory(options) {
         },
         findCandidates(presented) {
             const subject = versionedSubject(presented);
-            return Object.freeze(statements.candidates.all(subject.analysis, subject.environment, subject.subject, subject.version).map(envelopeOf));
+            return Object.freeze(statements.candidates.all(subject.analysis, subject.subject, subject.version, subject.environment, subject.environment).map(envelopeOf));
         },
         readCurrent(presented) {
             const subject = scopedSubject(presented);
@@ -560,26 +688,78 @@ 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.acceptances.all(resultId, scope.environment).find((candidate) => candidate.acceptance_id === acceptanceId);
                 if (row === undefined) {
                     throw new HistoryIntegrityError('Recorded acceptance is not readable');
                 }
-                return acceptanceOf(row, referenceOf(resultId, scope), scope);
+                return acceptanceOf(row, referenceOf(resultId, published), scope);
             });
         },
-        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)));
+        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);
+            });
+        },
+        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();