@opentermsarchive/engine 16.0.1 → 16.1.0

package/src/archivist/tracking-results/index.js

@@ -0,0 +1,233 @@
+import events from 'events';
+import { createRequire } from 'module';
+
+import config from 'config';
+import mime from 'mime';
+
+import { GitObjectNotFoundError } from '../../git/index.js';
+import { getCollection } from '../collection/index.js';
+import { ExtractDocumentError } from '../extract/index.js';
+import { FetchDocumentError } from '../fetcher/index.js';
+import * as declaredServices from '../services/index.js';
+import Service from '../services/service.js';
+
+import { MissingCollectionIdError, UnreadableRunError } from './errors.js';
+import TrackingResultsRecorder from './recorder.js';
+import TrackingResultsRepository from './repository.js';
+import { STATUSES } from './terms-result/index.js';
+
+export { MissingCollectionIdError } from './errors.js';
+export { RUN_ID_TRAILER_KEY } from './recorder.js';
+
+const require = createRequire(import.meta.url);
+const { version: PACKAGE_VERSION } = require('../../../package.json');
+
+export default class TrackingResults extends events.EventEmitter {
+  static async create(trackingResultsConfig) { // Resolves the engine-side wiring (collection identity, schedule, engine version) so the caller does not need to know it
+    if (trackingResultsConfig.storage.type !== 'git') { // Git is the only supported backend, as the audit trail relies on its tamper-evident properties
+      throw new Error(`Unsupported tracking-results storage type "${trackingResultsConfig.storage.type}"; only "git" is supported`);
+    }
+
+    const collection = await getCollection();
+    const collectionId = collection.metadata?.id; // getCollection always resolves to a Collection instance; metadata stays undefined when the metadata file is absent, which is exactly the missing-id case reported below
+
+    if (!collectionId) {
+      throw new MissingCollectionIdError('Collection metadata "id" is required to record tracking-results, as it identifies the collection in every persisted run. Add an "id" field to the collection metadata file.');
+    }
+
+    const repository = new TrackingResultsRepository(trackingResultsConfig.storage.git);
+    const recorder = new TrackingResultsRecorder({
+      repository,
+      collectionId,
+      schedule: config.get('@opentermsarchive/engine.trackingSchedule'),
+      engineVersion: PACKAGE_VERSION,
+    });
+
+    return new TrackingResults({ recorder });
+  }
+
+  constructor({ recorder }) {
+    super();
+    this.recorder = recorder;
+    this.ready = false;
+  }
+
+  async initialize() {
+    await this.ensureReady(); // Attempted as early as possible so readers of the repository see the previous run finalized without waiting for the next tracking run
+  }
+
+  async finalize() {
+    if (!this.ready) { // Nothing was recorded, and the repository may not even be initialized
+      return;
+    }
+
+    try {
+      await this.recorder.finalize();
+    } catch (error) {
+      this.emit('warn', { message: `Could not finalize the tracking-results repository: ${error.message}; recorded commits are kept locally and the finalization will be retried at the next run` }); // Everything is already committed locally, so a failed push or commit-graph update loses nothing: the next successful finalize pushes all accumulated commits
+    }
+  }
+
+  get hasRunInProgress() {
+    return Boolean(this.recorder.currentRun);
+  }
+
+  get currentRunId() {
+    return this.recorder.currentRun?.runId ?? null;
+  }
+
+  async getDeclarationsCommit() { // Meant to be called right before the declarations are loaded, so that the commit identifies the declarations applied by every run of this process, whatever happens to their repository afterwards
+    try {
+      const declarationsCommit = await declaredServices.getDeclarationsCommit();
+
+      if (!declarationsCommit) { // The audit trail premise (tamper-evident declarations commit) cannot be honoured
+        this.emit('warn', { message: 'The declarations directory is not a Git repository; tracking-results runs will not be recorded' });
+      }
+
+      return declarationsCommit;
+    } catch (error) { // An actual git failure, distinct from "declarations is not a Git repository" which is reported as null
+      this.emit('warn', { message: `Could not read the declarations commit: ${error.message}; tracking-results runs will not be recorded` });
+
+      return null;
+    }
+  }
+
+  async startRun({ services, declarationsCommit, selectedServicesIds, selectedTermsTypes }) {
+    if (!await this.ensureReady()) { // A new Start run commit would hide the crashed run's reference SHA and make its recovery impossible forever
+      return;
+    }
+
+    if (!declarationsCommit) { // Already reported by getDeclarationsCommit
+      return;
+    }
+
+    const servicesIds = Object.keys(services).sort((a, b) => a.localeCompare(b)); // Sorted so the persisted skipped list is deterministic
+
+    try {
+      await this.recorder.startRun({
+        declarationsCommit,
+        servicesCount: servicesIds.length, // Declared counts always cover the full declarations, whatever subset this run processes; coverage.skipped carries the difference so the coverage proof (declared = processed + skipped) stays derivable
+        termsCount: Service.getNumberOfTerms(services, servicesIds, []),
+        skippedTerms: unselectedTerms(services, servicesIds, { selectedServicesIds, selectedTermsTypes }),
+      });
+    } catch (error) {
+      this.emit('warn', { message: `Could not start the tracking-results run: ${error.message}; tracking-results is disabled for this run` }); // Like every other tracking-results failure, a failed run-start commit degrades the audit trail, never the tracking itself
+    }
+  }
+
+  recordSuccess(terms, { transientErrors } = {}) {
+    return this.record(terms, { status: STATUSES.ok, transientErrorReasons: transientErrors?.length ? categorizeReasons(transientErrors) : undefined });
+  }
+
+  recordFailure(terms, errors) {
+    return this.record(terms, { status: STATUSES.failed, reasons: categorizeReasons(errors) });
+  }
+
+  async record(terms, { status, reasons, transientErrorReasons }) {
+    if (!this.hasRunInProgress) { // No tracking-results run is active (technical upgrades, run start skipped or failed); nothing to record
+      return;
+    }
+
+    await this.recorder.recordTermsOutcome({
+      serviceId: terms.service.id,
+      termsType: terms.type,
+      serviceName: terms.service.name,
+      sourceDocuments: terms.sourceDocuments.map(sourceDocument => ({
+        id: sourceDocument.id,
+        ...sourceDocument.toPersistence(),
+        mimeType: normalizeMimeType(sourceDocument.mimeType),
+        snapshotId: sourceDocument.snapshotId ?? null,
+      })),
+      status,
+      reasons,
+      transientErrorReasons,
+    });
+  }
+
+  completeRun() {
+    return this.recorder.completeRun();
+  }
+
+  async ensureReady() { // Returns true when it is safe to write a new run-start commit: the repository is initialized and a pending in_progress run.json has been finalized. Success is memoised, and a failure is retried at the next call so a long-lived scheduled process self-heals without a restart
+    if (this.ready) {
+      return true;
+    }
+
+    try {
+      await this.recorder.initialize(); // Repeated at each attempt, as it also drops what a failed attempt may have left uncommitted
+
+      const recovered = await this.recorder.recoverCrashedRunIfAny({ getDeclaredTermsAtCommit: commit => this.declaredTermsAtCommit(commit) });
+
+      this.ready = true;
+
+      if (recovered) {
+        this.emit('warn', { message: `Recovered crashed run ${recovered.shortRunId}: persisted ${recovered.coverage.processed} processed terms and ${recovered.coverage.skipped.length} skipped terms before the new run starts` });
+      }
+
+      return true;
+    } catch (error) {
+      if (error instanceof UnreadableRunError) { // A stale or incompatible run.json cannot be recovered by construction: proceed, the next startRun will overwrite it with a valid one
+        this.ready = true;
+        this.emit('warn', { message: `Could not read previous tracking-results state: ${error.message}. The previous run.json may be from an incompatible engine version; it will be overwritten by the next run.` });
+
+        return true;
+      }
+
+      this.emit('warn', { message: `Could not prepare the tracking-results repository: ${error.message}; tracking-results is disabled for this run and the preparation will be retried at the next one. If this warning persists across runs, inspect or delete the repository at "${this.recorder.repository.path}" so it can be recreated` }); // An auxiliary audit trail must not prevent tracking itself, be it at initialization
+
+      return false;
+    }
+  }
+
+  async declaredTermsAtCommit(commit) {
+    try {
+      return await declaredServices.getDeclaredTermsAtCommit(commit);
+    } catch (error) {
+      if (error instanceof GitObjectNotFoundError) { // The commit is unreachable forever (shallow clone, rewritten declarations history): fall back to the currently declared terms so the crashed run can still be finalized, and surface the approximation
+        this.emit('warn', { message: `Declarations commit ${commit} is not reachable; crash recovery coverage falls back to the currently declared terms` });
+
+        return declaredServices.getDeclaredTerms();
+      }
+
+      throw error;
+    }
+  }
+}
+
+function normalizeMimeType(mimeType) { // Fetchers report the raw Content-Type header while Git snapshots report the type derived from their file extension; aligned on the latter, so that a parameter or an alias is not recorded as a MIME type change
+  if (!mimeType) {
+    return null;
+  }
+
+  return mime.getType(mime.getExtension(mimeType) || '') || mimeType.split(';')[0].trim().toLowerCase();
+}
+
+function categorizeReasons(errors) { // Tags each reason with [fetch], [extraction] or [internal] so that commit subjects and consumers of the persisted reasons can split by category without sniffing error types
+  return errors.map(error => {
+    if (error instanceof FetchDocumentError) {
+      return `[fetch] ${error.message}`;
+    }
+
+    if (error instanceof ExtractDocumentError) {
+      return `[extraction] ${error.message}`;
+    }
+
+    return '[internal] Unexpected engine error'; // The message of an unexpected error may expose server paths or git output, which must not enter a published history that cannot be rewritten; the details are in the logs
+  });
+}
+
+function unselectedTerms(services, servicesIds, { selectedServicesIds, selectedTermsTypes }) { // Enumerates the declared terms that this run will not process, so partial runs (CLI-filtered services or terms types) record them as explicitly skipped
+  const skipped = [];
+
+  for (const serviceId of servicesIds) {
+    const selectedTypes = new Set(selectedServicesIds.includes(serviceId) ? services[serviceId].getTermsTypes(selectedTermsTypes) : []);
+
+    for (const termsType of services[serviceId].getTermsTypes()) {
+      if (!selectedTypes.has(termsType)) {
+        skipped.push({ serviceId, termsType, reason: 'not selected for this run' });
+      }
+    }
+  }
+
+  return skipped;
+}

package/src/archivist/tracking-results/index.test.js

@@ -0,0 +1,406 @@
+import { expect, use } from 'chai';
+import sinon from 'sinon';
+import sinonChai from 'sinon-chai';
+
+import Git from '../../git/index.js';
+import { ExtractDocumentError } from '../extract/index.js';
+import { FetchDocumentError } from '../fetcher/index.js';
+import { getDeclaredTerms } from '../services/index.js';
+import SourceDocument from '../services/sourceDocument.js';
+
+import { UnreadableRunError } from './errors.js';
+
+import TrackingResults from './index.js';
+
+use(sinonChai);
+
+const DECLARATIONS_COMMIT = 'c0ffee1234567890c0ffee1234567890c0ffee12';
+
+function makeRecorder(overrides = {}) {
+  return {
+    currentRun: null,
+    repository: { path: '/data/tracking-results' },
+    initialize: sinon.stub().resolves(),
+    finalize: sinon.stub().resolves(),
+    startRun: sinon.stub().resolves(),
+    recordTermsOutcome: sinon.stub().resolves(),
+    completeRun: sinon.stub().resolves(),
+    recoverCrashedRunIfAny: sinon.stub().resolves(null),
+    ...overrides,
+  };
+}
+
+function makeServices() { // Minimal stand-ins for the loaded services map, exposing the getTermsTypes(filter) and getNumberOfTerms(filter) contracts used by the run start
+  const service = termsTypes => {
+    const getTermsTypes = filter => (filter?.length ? termsTypes.filter(type => filter.includes(type)) : termsTypes);
+
+    return { getTermsTypes, getNumberOfTerms: filter => getTermsTypes(filter).length };
+  };
+
+  return {
+    'Service A': service([ 'Terms of Service', 'Privacy Policy' ]),
+    'Service B': service(['Terms of Service']),
+  };
+}
+
+function makeTerms() {
+  const sourceDocument = new SourceDocument({ location: 'https://example.com/terms', contentSelectors: 'body' });
+
+  sourceDocument.mimeType = 'text/html';
+  sourceDocument.snapshotId = 'abc123';
+
+  return { service: { id: 'Service A', name: 'Service A' }, type: 'Terms of Service', sourceDocuments: [sourceDocument] };
+}
+
+describe('TrackingResults', () => {
+  let recorder;
+  let subject;
+  let warnings;
+
+  beforeEach(() => {
+    recorder = makeRecorder();
+    subject = new TrackingResults({ recorder });
+    warnings = [];
+    subject.on('warn', ({ message }) => warnings.push(message));
+  });
+
+  describe('.create', () => {
+    context('when the configured storage type is not git', () => {
+      it('throws an error stating the supported type', async () => {
+        const error = await TrackingResults.create({ storage: { type: 'mongo', mongo: {} } }).catch(error => error);
+
+        expect(error.message).to.include('only "git" is supported');
+      });
+    });
+  });
+
+  describe('#initialize', () => {
+    it('initialises the recorder and attempts crash recovery', async () => {
+      await subject.initialize();
+
+      expect(recorder.initialize).to.have.been.calledOnce;
+      expect(recorder.recoverCrashedRunIfAny).to.have.been.calledOnce;
+    });
+
+    context('when a crashed run has been recovered', () => {
+      beforeEach(() => {
+        recorder.recoverCrashedRunIfAny.resolves({ shortRunId: 'ota-run-f47ac10b', coverage: { processed: 2, skipped: [{ serviceId: 'Service B', termsType: 'Terms of Service', reason: 'no outcome recorded before the engine crashed' }] } });
+      });
+
+      it('announces it', async () => {
+        await subject.initialize();
+
+        expect(warnings.join('\n')).to.include('Recovered crashed run ota-run-f47ac10b: persisted 2 processed terms and 1 skipped terms');
+      });
+    });
+
+    context('when the declarations commit of the crashed run is not reachable', () => {
+      let declaredTerms;
+
+      beforeEach(() => {
+        recorder.recoverCrashedRunIfAny.callsFake(async ({ getDeclaredTermsAtCommit }) => {
+          declaredTerms = await getDeclaredTermsAtCommit('deadbeef'.repeat(5)); // Well-formed but unknown commit
+
+          return null;
+        });
+      });
+
+      it('falls back to the currently declared terms and reports the approximation', async () => {
+        await subject.initialize();
+
+        expect(declaredTerms).to.have.deep.members(await getDeclaredTerms());
+        expect(warnings.join('\n')).to.include('is not reachable');
+      });
+    });
+
+    context('when the repository cannot be initialized', () => {
+      beforeEach(() => {
+        recorder.initialize.onFirstCall().rejects(new Error('Unable to create index.lock'));
+      });
+
+      it('degrades with a warning instead of failing the engine initialization', async () => {
+        await subject.initialize();
+
+        expect(recorder.recoverCrashedRunIfAny).to.not.have.been.called;
+        expect(warnings.join('\n')).to.include('Unable to create index.lock');
+      });
+
+      it('points operators to the repository to inspect if the warning persists', async () => {
+        await subject.initialize();
+
+        expect(warnings.join('\n')).to.include('inspect or delete the repository at "/data/tracking-results"');
+      });
+
+      it('retries the initialization at the next run', async () => {
+        await subject.initialize();
+        await subject.startRun({ services: makeServices(), declarationsCommit: DECLARATIONS_COMMIT, selectedServicesIds: ['Service A'], selectedTermsTypes: [] });
+
+        expect(recorder.initialize).to.have.been.calledTwice;
+        expect(recorder.startRun).to.have.been.calledOnce;
+      });
+    });
+  });
+
+  describe('#getDeclarationsCommit', () => {
+    afterEach(() => Git.getHeadSha.restore());
+
+    it('resolves to the commit of the declarations repository', async () => {
+      sinon.stub(Git, 'getHeadSha').resolves(DECLARATIONS_COMMIT);
+
+      expect(await subject.getDeclarationsCommit()).to.equal(DECLARATIONS_COMMIT);
+      expect(warnings).to.be.empty;
+    });
+
+    context('when the declarations are not versioned', () => {
+      it('resolves to null and reports it', async () => {
+        sinon.stub(Git, 'getHeadSha').resolves(null);
+
+        expect(await subject.getDeclarationsCommit()).to.be.null;
+        expect(warnings.join('\n')).to.include('is not a Git repository');
+      });
+    });
+
+    context('when the commit cannot be read', () => {
+      it('resolves to null and reports it', async () => {
+        sinon.stub(Git, 'getHeadSha').rejects(new Error('git failure'));
+
+        expect(await subject.getDeclarationsCommit()).to.be.null;
+        expect(warnings.join('\n')).to.include('Could not read the declarations commit: git failure');
+      });
+    });
+  });
+
+  describe('#startRun', () => {
+    it('starts a recorder run with the full declared counts and the unselected terms as skips', async () => {
+      const services = makeServices();
+
+      await subject.startRun({ services, declarationsCommit: DECLARATIONS_COMMIT, selectedServicesIds: ['Service A'], selectedTermsTypes: [] });
+
+      expect(recorder.startRun).to.have.been.calledOnce;
+
+      const { declarationsCommit, servicesCount, termsCount, skippedTerms } = recorder.startRun.firstCall.args[0];
+
+      expect(declarationsCommit).to.equal(DECLARATIONS_COMMIT);
+      expect(servicesCount).to.equal(2);
+      expect(termsCount).to.equal(3);
+      expect(skippedTerms).to.deep.equal([{ serviceId: 'Service B', termsType: 'Terms of Service', reason: 'not selected for this run' }]);
+    });
+
+    it('narrows the skips to the selected terms types', async () => {
+      const services = makeServices();
+
+      await subject.startRun({ services, declarationsCommit: DECLARATIONS_COMMIT, selectedServicesIds: [ 'Service A', 'Service B' ], selectedTermsTypes: ['Privacy Policy'] });
+
+      const { skippedTerms } = recorder.startRun.firstCall.args[0];
+
+      expect(skippedTerms).to.deep.equal([
+        { serviceId: 'Service A', termsType: 'Terms of Service', reason: 'not selected for this run' },
+        { serviceId: 'Service B', termsType: 'Terms of Service', reason: 'not selected for this run' },
+      ]);
+    });
+
+    context('when the declarations commit is unknown', () => {
+      it('does not start a recorder run', async () => {
+        await subject.startRun({ services: makeServices(), declarationsCommit: null, selectedServicesIds: ['Service A'], selectedTermsTypes: [] });
+
+        expect(recorder.startRun).to.not.have.been.called;
+      });
+    });
+
+    context('when the recorder cannot start the run', () => {
+      beforeEach(() => {
+        recorder.startRun.rejects(new Error('Run start commit failed'));
+      });
+
+      it('degrades with a warning instead of failing the tracking run', async () => {
+        await subject.startRun({ services: makeServices(), declarationsCommit: DECLARATIONS_COMMIT, selectedServicesIds: ['Service A'], selectedTermsTypes: [] });
+
+        expect(subject.hasRunInProgress).to.be.false;
+        expect(warnings.join('\n')).to.include('tracking-results is disabled for this run');
+      });
+    });
+
+    context('when crash recovery keeps failing', () => {
+      beforeEach(() => {
+        recorder.recoverCrashedRunIfAny.rejects(new Error('transient git failure'));
+      });
+
+      it('does not start a recorder run', async () => { // A new Start run commit would hide the crashed run's reference SHA and make its recovery impossible forever
+        await subject.startRun({ services: makeServices(), declarationsCommit: DECLARATIONS_COMMIT, selectedServicesIds: ['Service A'], selectedTermsTypes: [] });
+
+        expect(recorder.startRun).to.not.have.been.called;
+        expect(warnings.join('\n')).to.include('will be retried at the next one');
+      });
+
+      it('retries the recovery at the next run', async () => {
+        await subject.startRun({ services: makeServices(), declarationsCommit: DECLARATIONS_COMMIT, selectedServicesIds: ['Service A'], selectedTermsTypes: [] });
+        await subject.startRun({ services: makeServices(), declarationsCommit: DECLARATIONS_COMMIT, selectedServicesIds: ['Service A'], selectedTermsTypes: [] });
+
+        expect(recorder.recoverCrashedRunIfAny).to.have.been.calledTwice;
+      });
+    });
+
+    context('when the previous run.json is unreadable', () => {
+      beforeEach(() => {
+        recorder.recoverCrashedRunIfAny.rejects(new UnreadableRunError('Could not parse JSON'));
+      });
+
+      it('proceeds and announces the file will be overwritten', async () => {
+        await subject.startRun({ services: makeServices(), declarationsCommit: DECLARATIONS_COMMIT, selectedServicesIds: ['Service A'], selectedTermsTypes: [] });
+
+        expect(recorder.startRun).to.have.been.calledOnce;
+        expect(warnings.join('\n')).to.include('it will be overwritten by the next run');
+      });
+    });
+
+    context('when recovery already succeeded', () => {
+      it('does not attempt it again', async () => {
+        await subject.initialize();
+        await subject.startRun({ services: makeServices(), declarationsCommit: DECLARATIONS_COMMIT, selectedServicesIds: ['Service A'], selectedTermsTypes: [] });
+
+        expect(recorder.recoverCrashedRunIfAny).to.have.been.calledOnce;
+      });
+    });
+  });
+
+  describe('#recordSuccess', () => {
+    context('when a run is in progress', () => {
+      beforeEach(() => {
+        recorder.currentRun = {};
+      });
+
+      it('maps the terms to the recorder payload', async () => {
+        await subject.recordSuccess(makeTerms());
+
+        expect(recorder.recordTermsOutcome).to.have.been.calledOnce;
+        expect(recorder.recordTermsOutcome.firstCall.args[0]).to.deep.equal({
+          serviceId: 'Service A',
+          termsType: 'Terms of Service',
+          serviceName: 'Service A',
+          sourceDocuments: [{
+            id: 'terms',
+            fetch: 'https://example.com/terms',
+            select: 'body',
+            remove: undefined,
+            filter: undefined,
+            executeClientScripts: undefined,
+            mimeType: 'text/html',
+            snapshotId: 'abc123',
+          }],
+          status: 'ok',
+          reasons: undefined,
+          transientErrorReasons: undefined,
+        });
+      });
+
+      it('normalises the MIME type reported by the fetcher', async () => {
+        const terms = makeTerms();
+
+        terms.sourceDocuments[0].mimeType = 'text/html; charset=utf-8';
+        await subject.recordSuccess(terms);
+
+        expect(recorder.recordTermsOutcome.firstCall.args[0].sourceDocuments[0].mimeType).to.equal('text/html');
+      });
+
+      it('records a missing MIME type as null', async () => {
+        const terms = makeTerms();
+
+        terms.sourceDocuments[0].mimeType = undefined;
+        await subject.recordSuccess(terms);
+
+        expect(recorder.recordTermsOutcome.firstCall.args[0].sourceDocuments[0].mimeType).to.be.null;
+      });
+
+      it('categorises the transient errors', async () => {
+        await subject.recordSuccess(makeTerms(), { transientErrors: [new FetchDocumentError('HTTP code 503')] });
+
+        expect(recorder.recordTermsOutcome.firstCall.args[0].transientErrorReasons).to.deep.equal(['[fetch] Fetch failed: HTTP code 503']);
+      });
+    });
+
+    context('when no run is in progress', () => {
+      it('records nothing', async () => {
+        await subject.recordSuccess(makeTerms());
+
+        expect(recorder.recordTermsOutcome).to.not.have.been.called;
+      });
+    });
+  });
+
+  describe('#recordFailure', () => {
+    beforeEach(() => {
+      recorder.currentRun = {};
+    });
+
+    it('categorises each error by origin', async () => {
+      await subject.recordFailure(makeTerms(), [
+        new FetchDocumentError('HTTP code 500'),
+        new ExtractDocumentError('CSS selector has no match'),
+        new Error('Could not commit /home/ota/data/snapshots/Service/Terms.html'),
+      ]);
+
+      expect(recorder.recordTermsOutcome.firstCall.args[0].status).to.equal('failed');
+      expect(recorder.recordTermsOutcome.firstCall.args[0].reasons).to.deep.equal([
+        '[fetch] Fetch failed: HTTP code 500',
+        '[extraction] Extract failed: CSS selector has no match',
+        '[internal] Unexpected engine error',
+      ]);
+    });
+  });
+
+  describe('#completeRun and #finalize', () => {
+    it('delegate to the recorder', async () => {
+      await subject.initialize();
+      await subject.completeRun();
+      await subject.finalize();
+
+      expect(recorder.completeRun).to.have.been.calledOnce;
+      expect(recorder.finalize).to.have.been.calledOnce;
+    });
+
+    context('when the repository could not be initialized', () => {
+      beforeEach(() => {
+        recorder.initialize.rejects(new Error('Unable to create index.lock'));
+      });
+
+      it('does not finalize it', async () => {
+        await subject.initialize();
+        await subject.finalize();
+
+        expect(recorder.finalize).to.not.have.been.called;
+      });
+    });
+
+    context('when the push fails at finalize', () => {
+      beforeEach(() => {
+        recorder.finalize.rejects(new Error('remote rejected'));
+      });
+
+      it('degrades with a warning, as the commits remain local', async () => {
+        await subject.initialize();
+        await subject.finalize();
+
+        expect(warnings.join('\n')).to.include('recorded commits are kept locally');
+      });
+    });
+  });
+
+  describe('#hasRunInProgress', () => {
+    it('reflects the recorder state', () => {
+      expect(subject.hasRunInProgress).to.be.false;
+      recorder.currentRun = {};
+      expect(subject.hasRunInProgress).to.be.true;
+    });
+  });
+
+  describe('#currentRunId', () => {
+    it('returns null when no run is in progress', () => {
+      expect(subject.currentRunId).to.be.null;
+    });
+
+    it('returns the id of the run in progress', () => {
+      recorder.currentRun = { runId: 'ota-run-f47ac10b-58cc-4372-a567-0e02b2c3d479' };
+      expect(subject.currentRunId).to.equal('ota-run-f47ac10b-58cc-4372-a567-0e02b2c3d479');
+    });
+  });
+});