Factory docs, home
Page navigation

Pre-release documentation. Proposed designs are labelled in the page; acceptance evidence is maintained in the build review. Local paths appear as placeholders. Current state: Build review.

This private draft package exposes software-factory/branch-health. It records bounded observations of a GitHub branch and retains a failure episode until evidence closes it. Independent Astra review passed, and it was accepted locally on 1 October 2026 (owner-designated acceptance reviewer, after independent Opus 5.5 and Fable 5.1 reviews); it is not a published release or a live monitoring service.

Use Node.js 26.8.1 or later. Obtain the reviewed private tarball, then install that exact local tarball in your ESM application. The package has no runtime npm dependencies. It includes declarations that typecheck without Node type declarations. The Command journal adoption guide covers the caller-owned SQLite store.

Supply identities and a reader

import { CommandJournal } from 'software-factory/command-journal';
import { BranchHealth, readBranchHealth, type GitHubReader } from 'software-factory/branch-health';

// Replace this with your explicitly chosen read-only transport.
// An unavailable source is unknown; it must never become an empty successful response.
const reader: GitHubReader = {
  async get(path) {
    return { kind: 'failed', reason: 'unavailable' };
  },
};
const journal = CommandJournal.open('./my-branch-health.sqlite');
const health = new BranchHealth(journal, {
  reader,
  watch: [{ productId: 'my-app', repository: 'my-team/my-app', branch: 'main' }],
  now: () => Date.now(),
});
try {
  const report = await health.poll();
  console.log(report.products[0]?.state); // unknown with this unavailable reader
  console.log(readBranchHealth(journal, 'my-app'));
} finally {
  journal.close();
}

No Portfolio registration or local Git checkout is required. watch binds 1–16 distinct Product IDs to distinct GitHub repositories and branches; IDs follow the existing lowercase identifier rules. Construction validates inputs but does not read the clock, call the reader, open a store, authenticate, start a process or schedule work. You open the journal and choose when to call poll(). The compiled closure contains the existing passive GitHub helper, including its optional CLI-reader implementation, but no Factory Portfolio, Repository or Dashboard code. No CLI reader entry point is offered.

get(path) is asynchronous. It receives the existing bounded GitHub read plan's relative GET paths. Return either {kind: 'failed', reason} or {kind: 'response', status, next, rateLimitExhausted, body}. Preserve response status, completeness and identity; never replace a refusal with a successful empty listing. This port is trusted host code, not a network sandbox. Branch health does not choose or grant transport authority.

Green requires complete passing evidence on the current head and no open episode. Passing checks alone do not close an episode: every failing job must pass in an eligible run on that head. Unavailable, incomplete and malformed evidence remains unknown or retains the existing failure. Reads are bounded; no background polling is installed.

Optionally mirror blocker observations

Omit mirror, or set it to null, to keep only the Branch health journal. A caller-owned synchronous mirror can record each supplied BlockerObservation:

import type { BranchHealthMirror } from 'software-factory/branch-health';

const mirror: BranchHealthMirror = {
  record(observation) {
    // Commit to your own durable store before acknowledging. This example refuses explicitly.
    return { state: 'refused', code: 'UNAVAILABLE', message: 'Caller store is offline' };
  },
};

For success return exactly {state: 'mirrored', source: {productId, collector, recordId, revision}, recorded, corrected}. Echo the supplied source identity, with each count 0 or 1 and their sum at most 1. Zero counts acknowledge an idempotently processed observation; they do not establish that it replaced a newer source revision. The host must decide truthful persistence and obsolete-revision behaviour. Never invent a success acknowledgement for work still pending.

A refusal is exactly {state: 'refused', code, message}: an uppercase symbolic code of at most 40 characters and a message of at most 1,000 characters. It marks that episode's mirror as failed and allows unrelated episodes to proceed. A malformed, stale or asynchronous acknowledgement throws TypeError; unexpected adapter exceptions propagate unchanged. Either aborts the poll. Replayed Products are mirrored first; then each freshly read Product is recorded and mirrored in watch-list order. Products up to and including the last committed one are recorded; later Products are not, although GitHub was already read for them. They gain no command, record or event at this poll instant. A Product never polled has no record (readBranchHealth returns null). A Product polled before keeps its earlier record, whose lastPoll.pollId is older than this poll's instant, so its stored state, green included, is not this poll's finding: compare lastPoll.pollId with the poll instant before treating that state as current. A replayed Product the poll did not reach keeps its record but is not mirrored again. Retry at the same instant to bring every Product to it. Errors are not converted into successful evidence.

The mirror method must be a data method, including an inherited class method; accessors are refused without invocation. It is captured once with its original receiver, supporting private fields. Replacing the method later does not change a watch already constructed. Results must be plain data with exact fields, without accessors or thenables. Prototype traversal is bounded and refuses cycles.

Retry and retain history

The clock supplies whole milliseconds from 2000 through 2999. After an uncertain acknowledgement, repeat the same poll instant with the same repository and branch. The journal replays each Product that poll recorded without fetching GitHub again and retries its mirrors; Products the interrupted poll did not record are read again. Reopening the journal preserves that behaviour. A different binding on that instant conflicts. A later instant performs a new bounded read.

Every episode keeps its original identity. blockerSource retains the existing source-revision rollover; (productId, collector, recordId) is the mirror key, not recordId alone. Closed episodes remain in bounded current state and immutable journal history. openedSince exposes opening events; blockerObservation produces the recorded episode's current blocker revision. The stored protocol stays sf-branch-health/2, with no migration or record rewrite.

readBranchHealth refuses corrupt stored data. Polling reports the corrupt Product and leaves it untouched while other Products proceed. Journal errors other than the existing command/version conflicts propagate. A supplied adapter may throw after some Products have committed, so recovery must inspect or replay that same poll instant rather than blindly invent a new command.

Factory source consumers keep src/branch-health.ts and its existing portfolio option/default. That facade alone constructs Portfolio and translates its PortfolioError into the mirror refusal, after the original constructor validation order. The public package core has no portfolio option.

The package tests exercise caller-owned identities, red → retained episode → green closure, absent/refused/lost mirrors, process restart, exact pre-extraction records and receipts, Product isolation, corruption, declaration checking and passive import. All storage and responses are disposable fixtures. Live GitHub, unattended scheduling and production adoption remain unproved.

Source: docs/how-to/adopt-branch-health.md