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) andreadVisibilityinsrc/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 intest/module-graph.test.ts - Fixtures: the recorded branch-health capture in
test/fixtures/branch-health/(listings, workflow IDs fromreplay.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; andtest/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) anddocs/prevention-register-recording-draft.json(increment 2) - Human page: guide
What it hides
- Templates as data.
PREVENTION_TEMPLATESholds three frozensf-prevention-template/1values. Each names the recorded failure cause, where it was recorded, whatpresentmeans, which inputs it reads, and arulewith every pattern, state and label the evaluation uses.templateDigestis 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, andPREVENTION_CATALOGUE_DIGESTcovers 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/dispatchesAPI 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 anactions/github-scriptstep. 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, isdispatch-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, ismarker-malformed, never a pass. The marker is a declaration: whether the breaker trips is not checked here. - Classifying a runner.
runnerKind(job)isself-hostedwhen a label isself-hosted, or when a named runner that is notGitHub Actions <n>served labels outside GitHub's hosted images;github-hostedwhen every label is a hosted image (ubuntu-*,macos-*,windows-*); otherwiseunclassified, which is a gap, not a guess. - Never present by default.
presentandnot-applicableneed complete reads.absentneeds 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 isunknownwhatever it shows (workflows-incomplete), with what it shows kept infindings. A refused (401, 403, 429), failed or timed-out read, a malformed reply, an unclassified runner, an ambiguous dispatch line or a malformed marker isunknownwith its cause. A Product with nothing read isunknownfor 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
absentorunknownfactexempted, keepingobservedand the findings beside it, and is counted apart frompresent. A fact seenpresentornot-applicablekeeps 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 inunappliedExemptions. - 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 afterasOf. - Write-once records (increment 2).
src/prevention-register-records.tsrecords 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: commandprevention-register/result/<key>on aggregateprevention-register:result:<key>, orprevention-register/exemption/<key>onprevention-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 andat, 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: falseonce the catalogue has changed), never a fresh evaluation. The same key with any other content (other reads or exemptions for the sameasOfand Products, other owner words or day, another source, another recording instant, the same Products in another order) is refusedCONFLICTand 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.
recordRegisterResulttakes 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 refusesCORRUPTwhen that record does not hold the input digest, instant and result digest its receipt names. Every record carriesat, the caller's recording instant (the module reads no clock); a result'satmust not be before itsasOf. - Exemptions bind the template as it stands.
recordExemptionchecks the exemption as the evaluation does, withdecidedOnno later than the day ofat, 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 refusesCORRUPTwhen the record is missing, fails its checks, has moved past version 1, or does not hold the exemption andatthe call names; a receipt alone never vouches for the record. A recorded exemption under an earlier digest stays in the journal as history:readRecordedExemptionfinds it by that digest (templateCurrent: false),recordedExemptionsdoes not offer it, and an evaluation handed it lists it astemplate-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 andasOfmatching the key. A defect isCORRUPT; so is a record aggregate that exists without this command's receipt.recordedExemptionsrefuses rather than skipping a corrupt record. A result made under an older catalogue is returned withcatalogueCurrent: false: history, not a current fact. - Visibility read.
readVisibility(reader, repository)in branch health's GitHub module is onegh api --method GETofrepos/<owner>/<name>through the sameGitHubReader. It uses onlyfull_name,visibilityandprivate: an answer naming another repository (owner and name compare without case), aprivateflag that disagrees withvisibility, or a value other thanpublic,privateorinternalismalformed; a refused or failed read keeps branch health's reason. Its result is the register'sVisibilityReadas it stands. A Branch health poll does not call it.
The templates
| Template | Present | Absent | Not applicable | Unknown, 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 breaker | the listing is complete, and a whole file read whose text matches a dispatch pattern lacks the breaker | the 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 comment | workflows-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-hosted | visibility read public, and a complete job listing shows a self-hosted job | visibility read private or internal | visibility-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_inactivity | the listing is complete and a listed workflow is disabled_inactivity | not used | workflows-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):
| Name | What |
|---|---|
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, JobItem | the 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_DIGEST | the frozen catalogue and its digests |
dispatcherFile(text, rule?), runnerKind(job, rule?) | the two readings, exported for callers and tests |
PREVENTION_REGISTER_LIMITS, PreventionRegisterError | the 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):
| Name | What |
|---|---|
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_PROTOCOL | the 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
ghover 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-registerentry. 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
presentandnot-applicablecannot rule one out. - Behaviour of a breaker. A marker shows a declaration, not a breaker that trips; the self-hosted template can never show
presentfrom 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.
