Factory docs, home
Page navigation

The Factory bet's module M3 (roadmap FB-H7r): three frozen guardrail templates and a pure evaluation that turns caller-supplied read results into one presence fact per Product and template. It answers "is the prevention for this recorded failure cause in place here?" with present, absent, exempted, not-applicable or unknown and the causes, never with a default pass. Increment 2 records results and owner exemptions durably in a caller-supplied command journal, and reads repository visibility through Branch health's GET-only reader, so the runner template need not stay unknown: visibility unread.

Status: In progress. The first increment (evaluation) was integrated in wave 1. Increment 2 (recording and the visibility read) was integrated on 2 October 2026 after independent review (Opus 5.5 pass with notes; Astra pass in round 3); its draft evidence awaits acceptance. No rollouts (FB-H7), no package entry and no live read. Nothing here is accepted.

Intelligence: none — Guardrail facts are fixed template rules over caller-supplied reads and dated owner exemptions; a model would guess presence where only read evidence counts.

  • Source: src/prevention-register.ts (pure evaluation), src/prevention-register-records.ts (journal records) and readVisibility in src/branch-health-github.ts (the visibility read)
  • Tests: test/prevention-register.test.ts, test/prevention-register-records.test.ts; the closures, edges and journal namespace in test/module-graph.test.ts
  • Fixtures: the recorded branch-health capture in test/fixtures/branch-health/ (listings, workflow IDs from replay.json, job runners), read unchanged; test/fixtures/prevention-register/derived.json, whose one workflow text is a labelled synthetic stand-in because the capture holds no workflow file; and test/fixtures/prevention-register/visibility.json, labelled synthetic repository answers, because the capture holds no read of a repository itself
  • Design: <local evidence archive> §3 (M3); roadmap row 23 (FB-H7r) and row 77 (FB-H7)
  • Evidence drafts: docs/prevention-register-draft.json (increment 1) and docs/prevention-register-recording-draft.json (increment 2)
  • Human page: guide

What it hides

  • Templates as data. PREVENTION_TEMPLATES holds three frozen sf-prevention-template/1 values. Each names the recorded failure cause, where it was recorded, what present means, which inputs it reads, and a rule with every pattern, state and label the evaluation uses. templateDigest is SHA-256 over the template's canonical JSON, so any edit to any field changes the digest. Every fact carries its template's version and digest, and PREVENTION_CATALOGUE_DIGEST covers all three. The test pins each digest, so an edit must update the pins in review.
  • Reading a dispatcher. dispatcherFile(text) is a lexical scan of one workflow file's own text. It skips whole-line # comments, removes a trailing # comment from each other line and looks for a dispatch: gh workflow run, a /dispatches API path, createWorkflowDispatch, createDispatchEvent, or a known dispatch action. The scan does not know whether a line is a YAML plain scalar (where a # after a space always starts a comment) or shell in a block scalar (where a quoted # does not), so it reads each line both ways. The quoted reading models ordinary single quotes, read twice because the scan does not know the language either: once with the backslash literal, as a shell reads them, and once with backslash escapes, as a JavaScript or Python string does. It also models ANSI-C $'...' (with its backslash escapes, opened only by a $ that no backslash escaped), double quotes and backslash escapes, and the JavaScript template literal of an actions/github-script step. A dispatch before the first such # counts; one that any quoted reading keeps out of a comment, or that follows a quote any reading leaves open on its line, is dispatch-ambiguous, never a silent pass; one that every reading puts in a comment does not count. Only # comments are recognised: a dispatch in a JavaScript // comment counts as a dispatch, which errs towards absent rather than hiding one. Each line is read alone: a quote opened on an earlier line is not carried over, so a dispatch on a later line that starts with #, or that only such a quote keeps out of a comment, is not seen, and quoting outside the modelled forms can hide one the same way. A dispatching file declares its breaker with the marker comment # sf-guardrail: dispatcher-circuit-breaker/1 max-failures-per-head=<1-10>. A marker that claims the breaker but does not match, or two markers that disagree, is marker-malformed, never a pass. The marker is a declaration: whether the breaker trips is not checked here.
  • Classifying a runner. runnerKind(job) is self-hosted when a label is self-hosted, or when a named runner that is not GitHub Actions <n> served labels outside GitHub's hosted images; github-hosted when every label is a hosted image (ubuntu-*, macos-*, windows-*); otherwise unclassified, which is a gap, not a guess.
  • Never present by default. present and not-applicable need complete reads. absent needs a complete read of the evidence that shows it: a whole workflow file without its breaker on a complete workflow listing, a complete job listing with a self-hosted job on a public repository, or an item of a complete workflow listing disabled for inactivity. A truncated listing is unknown whatever it shows (workflows-incomplete), with what it shows kept in findings. A refused (401, 403, 429), failed or timed-out read, a malformed reply, an unclassified runner, an ambiguous dispatch line or a malformed marker is unknown with its cause. A Product with nothing read is unknown for every template, and the result has no overall verdict.
  • Exemptions. An owner exemption binds one Product, one template and that template's digest, with the day decided and the owner's own words. It makes an absent or unknown fact exempted, keeping observed and the findings beside it, and is counted apart from present. A fact seen present or not-applicable keeps its state and shows the exemption on record. An exemption whose digest is not the template's now (template-changed), or whose Product was not read (product-not-read), is not applied and is listed in unappliedExemptions.
  • Bounds. PREVENTION_REGISTER_LIMITS: 16 Products, 200 workflows and 200 files a Product, 262,144 bytes a file and 16 MiB of files in all, 22 job listings of 300 jobs, 32 labels, 512 characters a name, 256 exemptions, 1,000 characters of owner words. An input over any bound is refused whole (LIMIT), never cut short; a result over the canonical JSON bound is refused too.
  • Strict input. Every object must be a plain object of own data properties with exactly its keys. Product IDs, repositories (owner/name), instants (UTC with milliseconds), days and digests are checked. Duplicate Products, workflow IDs or paths, file paths, run IDs or exemptions are refused (CONFLICT), as is an exemption dated after asOf.
  • Write-once records (increment 2). src/prevention-register-records.ts records into a journal the caller supplies. A result is keyed by the instant its reads were taken (asOf) and the IDs of the Products it covers (sorted); an exemption by its Product, template and template digest. Each key is the SHA-256 of that identity, so a retry derives the same IDs: command prevention-register/result/<key> on aggregate prevention-register:result:<key>, or prevention-register/exemption/<key> on prevention-register:exemption:<key>, each written once at version 1. A repeat with the same content replays (the decision does not run again). A result's command carries the input's identity digest and at, never the result: the digest (checkRegisterInput) covers the input's protocol, asOf, each Product's ID and reads digest in input order, and its exemptions, and reads no template. A catalogue change since the record therefore leaves an identical retry a replay, and the replay answers with the result recorded then (catalogueCurrent: false once the catalogue has changed), never a fresh evaluation. The same key with any other content (other reads or exemptions for the same asOf and Products, other owner words or day, another source, another recording instant, the same Products in another order) is refused CONFLICT and nothing changes; a record is never replaced. After a lost acknowledgement the caller repeats the same call and lets the replay answer.
  • The register's own result. recordRegisterResult takes the input, not a result: it checks the input whole first and evaluates it itself, only when no record exists, so a hand-built result is never stored. Fresh or replayed, it answers with the stored record read back checked, and refuses CORRUPT when that record does not hold the input digest, instant and result digest its receipt names. Every record carries at, the caller's recording instant (the module reads no clock); a result's at must not be before its asOf.
  • Exemptions bind the template as it stands. recordExemption checks the exemption as the evaluation does, with decidedOn no later than the day of at, and refuses one whose digest is not its template's now (CONFLICT). The check runs only for a new record, so a retry after a template change still replays. Fresh or replayed, it answers with the stored exemption read back checked, and refuses CORRUPT when the record is missing, fails its checks, has moved past version 1, or does not hold the exemption and at the call names; a receipt alone never vouches for the record. A recorded exemption under an earlier digest stays in the journal as history: readRecordedExemption finds it by that digest (templateCurrent: false), recordedExemptions does not offer it, and an evaluation handed it lists it as template-changed.
  • Stored records are checked, never repaired. Every read re-checks a record: version 1, exact fields, protocol sf-prevention-register-record/1, its kind, its key recomputed from its content, its instant, and for a result the form of its input digest, its digest recomputed over the result (which finds a record changed without its digest, not one forged with a fresh digest) and its Products and asOf matching the key. A defect is CORRUPT; so is a record aggregate that exists without this command's receipt. recordedExemptions refuses rather than skipping a corrupt record. A result made under an older catalogue is returned with catalogueCurrent: false: history, not a current fact.
  • Visibility read. readVisibility(reader, repository) in branch health's GitHub module is one gh api --method GET of repos/<owner>/<name> through the same GitHubReader. It uses only full_name, visibility and private: an answer naming another repository (owner and name compare without case), a private flag that disagrees with visibility, or a value other than public, private or internal is malformed; a refused or failed read keeps branch health's reason. Its result is the register's VisibilityRead as it stands. A Branch health poll does not call it.

The templates

TemplatePresentAbsentNot applicableUnknown, for example
dispatcher-circuit-breaker (Pasta's 264 failed dispatched Alpha builds on one head)the listing is complete, every examined file was read, and every examined file whose text matches a dispatch pattern declares the breakerthe listing is complete, and a whole file read whose text matches a dispatch pattern lacks the breakerthe listing is complete, every examined file was read, and no examined file has a line that the scan reads as a dispatch, or as possibly one, outside a commentworkflows-unread, workflows-incomplete (findings kept), file-unread (with not-supplied or the read's reason), marker-malformed, dispatch-ambiguous
self-hosted-runner-public-repository (Tally, Pasta; tally/X4)never: job listings are samples of runs, so no complete read shows that no job is self-hostedvisibility read public, and a complete job listing shows a self-hosted jobvisibility read private or internalvisibility-unread (the caller supplies visibility, for example from readVisibility; a poll does not read it), jobs-unread, jobs-incomplete, runner-unclassified, runner-coverage-partial
schedule-disabled-for-inactivity (Tally's smoke tests, tally/C1)the listing is complete and no workflow is disabled_inactivitythe listing is complete and a listed workflow is disabled_inactivitynot usedworkflows-unread, workflows-incomplete (findings kept)

The dispatcher template examines workflows that are active or disabled_inactivity and have a file (not dynamic/…). A file supplied for any other path is reported in unusedFiles and not used. Unknown visibility is never absent, whatever the jobs show; their self-hosted findings are still listed.

Public interface

src/prevention-register.ts (no package entry yet):

NameWhat
evaluatePreventionRegister(input)validates an sf-prevention-register-input/1 value whole, then returns a frozen sf-prevention-register-result/1: per Product its readsDigest (file texts replaced by their SHA-256), one GuardrailFact per template and unusedFiles; per template the counts of each state; unappliedExemptions; digest over the rest
RegisterInput{protocol, asOf, products, exemptions}; asOf is when the reads were taken (the module reads no clock)
ProductReads{productId, repository, visibility, workflows, files, jobs}: workflows is a ListingRead<WorkflowItem> ({state: "read", items, complete} or {state: "unknown", reason}), files pairs a path with {state: "read", text} or an unknown read, jobs pairs a run ID with a ListingRead<JobItem>, and visibility is read, unknown or not-read
WorkflowItem, JobItemthe fields of branch health's Workflow (id, name, path, state) and Job (name, runnerName, labels) the register uses; the test checks that branch health's values map onto them and that both use the same workflow states
Exemption{productId, templateId, templateDigest, decidedOn, ownerWords, source}
GuardrailFact{templateId, templateVersion, templateDigest, state, observed, findings, unknown, exemption}
PREVENTION_TEMPLATES, templateDigest, PREVENTION_TEMPLATE_DIGESTS, PREVENTION_CATALOGUE_DIGESTthe frozen catalogue and its digests
dispatcherFile(text, rule?), runnerKind(job, rule?)the two readings, exported for callers and tests
PREVENTION_REGISTER_LIMITS, PreventionRegisterErrorthe bounds, and the refusal: code is INVALID, LIMIT or CONFLICT, with the input path; the recording side adds CORRUPT
checkExemption(value, latestDay, path?, latest?)one exemption checked as the evaluation checks it, with its day no later than latestDay (the recording side's check)
checkRegisterInput(input)the input checked whole as evaluatePreventionRegister checks it, without evaluating it: {input, digest}, a fresh checked copy and its identity digest (protocol, asOf, each Product's ID and reads digest in input order, exemptions; no template, so a catalogue change leaves it unchanged)

src/prevention-register-records.ts (increment 2, no package entry):

NameWhat
recordRegisterResult(journal, input, at)checks input, and evaluates it and records the result only when no record exists; returns {commandId, aggregateId, key, replayed, result, catalogueCurrent}, where result is the stored one (on a replay, the one recorded then)
recordExemption(journal, exemption, at)records one owner exemption once; returns {commandId, aggregateId, key, replayed, exemption}, where exemption is the stored one, read back checked
readRecordedResult(journal, asOf, productIds)the checked result record, {key, at, inputDigest, result, catalogueCurrent}, or null
readRecordedExemption(journal, productId, templateId, templateDigest)the checked exemption record, {key, at, exemption, templateCurrent}, or null
recordedExemptions(journal, productIds)the recorded exemptions binding these Products under each template's digest now, ready for an evaluation's exemptions
resultKey(asOf, productIds), exemptionKey(productId, templateId, templateDigest), PREVENTION_RECORD_PREFIXES, PREVENTION_RECORD_PROTOCOLthe derived keys (64 hex), the journal namespaces and the record protocol

src/branch-health-github.ts adds readVisibility(reader, repository), githubPaths.repository, VisibilityRead and RepositoryVisibility; the reader now accepts the bare repos/<owner>/<name> path and still refuses every other shape outside its grammar.

Stored layout. Each record is one command and one aggregate at version 1. A result's payload is {protocol: "sf-prevention-register-record/1", kind: "result", key, at, inputDigest} and its state adds result; its receipt is {kind, key, inputDigest, digest}, with the result's digest. An exemption's state and payload are both {protocol, kind: "exemption", key, at, exemption}, and its receipt is {kind, key}. Events: prevention-register.result-recorded (key, asOf, productIds, inputDigest, catalogueDigest, digest, counts, at) and prevention-register.exemption-recorded (key, the exemption's fields, at). The payload and the state must each fit the journal's canonical JSON bound (1 MiB); a larger one is refused LIMIT, never cut short.

The unknown-read reasons are branch health's UnknownReason vocabulary, imported from the pure branch-health-contract.ts. The evaluation's runtime closure is that contract, canonical-json.ts and errors.ts, with Node's buffer and crypto: no reader, journal, Portfolio, process or network (asserted in test/module-graph.test.ts, where the module is a pure root). The records module adds only journal.ts and crypto: no reader, process, network or Portfolio (asserted there too, with its journal namespace). Importing either defines frozen values and computes digests; nothing else runs.

Not built and not established

  • Recording beyond write-once records. Results and exemptions are journalled (increment 2), but nothing mirrors them to Portfolio or the Dashboard, there is no listing of every record (reads are by key), and an exemption cannot be withdrawn: a template edit is the only thing that stops one applying. No journal path is chosen for live use.
  • Reading. Visibility can be read through Branch health's reader, but no caller composes the reads into an evaluation yet, and no poll or schedule runs it. Branch health keeps no workflow file text; a caller must read and supply it. No live read has been made: the visibility tests use the fake gh over synthetic answers.
  • Rollouts (FB-H7). No template has been rolled out to any Product, no workflow file has been changed, and nothing is granted. Rollouts need each Product's grant.
  • Packaging. There is no software-factory/prevention-register entry. This is a tracked adoption gap: the distribution harness is being rewritten separately, so the entry waits for it.
  • Dispatches outside the file text. The dispatcher template reads only each listed workflow file's own text against its five patterns. A dispatch made from a repository script, a local composite action or an action outside the listed ones, or written in a form outside those patterns, is not detected, so present and not-applicable cannot rule one out.
  • Behaviour of a breaker. A marker shows a declaration, not a breaker that trips; the self-hosted template can never show present from job samples.
  • Acceptance. Independent Astra review of increment 2, the build-review row and the factory model's module-map row are pending. The three fixtures reproduce recorded causes from one capture of 29 September 2026, and the visibility answers are synthetic; no Product's guardrail state or visibility today is established.

Tests and helpers

test/prevention-register-records.test.ts records results and exemptions in a temporary journal: derived IDs, replay of a repeat, CONFLICT for every other content under the same key with nothing changed, refusal of refused input, of a recording before its reads and of an exemption under another digest or decided after it is recorded, a replay after a template change, a result retry after a catalogue change that replays the result recorded then while changed input is still refused, CORRUPT for a replay whose record does not match its receipt (for an exemption: a record changed, removed or moved past version 1 after its receipt), LIMIT for a record whose evaluation fits but whose record exceeds the journal bound, CORRUPT for every defect of a stored record, and the namespaces. It reads visibility through the real gh reader running the fake gh (GET only, the repository's own path), shows the runner template move from unknown: visibility unread to absent, not-applicable or a refused read's reason, covers every malformed answer, and checks that a poll's read plan never reads visibility.

test/prevention-register.test.ts pins the template digests and edits every field of every template to show each edit changes its digest. On inputs derived from the recorded capture it reproduces the three cases: Pasta's dispatcher without a breaker is absent, Tally's smoke tests disabled for inactivity are flagged, and Family Watch's self-hosted jobs with unread visibility stay unknown. It then covers present and not-applicable, the marker grammar, comments and quoted # on a dispatch line (shell and ANSI-C quotes, JavaScript and Python single quotes holding an escaped quote, an even run of backslashes before $', and a JavaScript template literal), every unknown cause (a truncated listing stays unknown even where it shows the concern), exemptions applied, refused and unapplied, every bound refused whole, strict input, and the result's digest and freezing.

Shared value implementation: common contracts. Owning errors, limits, stored identities and authority remain as specified above.

Source: docs/agents/prevention-register.md