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.

Use these commands with an existing Factory journal and a prepared JSON request. They expose the accepted local Branch health, Owner policy and Owner digest modules. Live polling and ask import still need their separate commission. Running any of them against <local Portfolio journal> appends to the live journal, so it needs the owner's commission too.

Prepare the inputs

Use Node 26.8.1 or later from the repository root. Keep the journal and request files on trusted local storage. Each input must be a regular UTF-8 JSON file of at most 65,536 bytes. Final symlinks, devices and pipes are refused. The commands never create a journal, register a Product or send a message.

Keep request files private: subjects and rules retain the words supplied. Use the owner's stated words and times; missing facts stay unknown. See the module references for watch targets and ledger requests. Those references own the input contracts.

Poll branch health once

Prepare a watch file containing the Products, repositories and branches to read:

[
  { "productId": "example", "repository": "owner/example", "branch": "main" }
]

Choose the poll's actual start time in UTC, including milliseconds. Save that instant with the watch file before running:

npm run factory:bet -- branch-health poll \
  --journal /path/to/existing.sqlite \
  --watch /path/to/watch.json \
  --gh /absolute/path/to/gh \
  --at 2026-09-30T12:00:00.000Z

Replace the example time and paths. The executable must be an absolute path to the intended gh; sign-in remains outside this command. The reader uses the existing filtered environment and GET-only transport. There is no automatic retry or schedule.

If the outcome is uncertain, retry with the same instant and watch file. Recorded Products replay without fetching again; pending Portfolio mirrors can retry. A changed repository or branch at the same instant returns a conflict for that Product. A poll records each Product separately, so its report can contain both completed and refused Products. Do not change the instant merely to bypass a conflict.

Record an ask, answer, update or weekly note

Prepare the corresponding request from the Owner policy contract, then choose its action:

npm run factory:bet -- owner-policy channels --journal /path/to/existing.sqlite --input /path/to/channels.json
npm run factory:bet -- owner-policy ask --journal /path/to/existing.sqlite --input /path/to/ask.json
npm run factory:bet -- owner-policy answer --journal /path/to/existing.sqlite --input /path/to/answer.json
npm run factory:bet -- owner-policy update --journal /path/to/existing.sqlite --input /path/to/update.json
npm run factory:bet -- owner-policy note --journal /path/to/existing.sqlite --input /path/to/note.json

Record the first channel list before asks or updates. Its zone defines the ledger's weeks; its live flag has the meaning specified by the contract. A weekly note covers a week that has ended and was not already over when the ledger opened.

Retries use the same request, including its identity and timestamps. Changed content under an existing identity is a conflict. Recording a rule neither applies it nor grants permission to act. Recording an update does not send it.

Read the ask ledger

These views open the journal read-only and write nothing, so they are safe to repeat:

npm run factory:bet -- owner-policy view --journal /path/to/existing.sqlite
npm run factory:bet -- owner-policy asks --journal /path/to/existing.sqlite --state open --limit 20
npm run factory:bet -- owner-policy week --journal /path/to/existing.sqlite --week 2026-W40
npm run factory:bet -- owner-policy kr1 --journal /path/to/existing.sqlite
npm run factory:bet -- owner-policy classes --journal /path/to/existing.sqlite
npm run factory:bet -- owner-policy rules --journal /path/to/existing.sqlite --class deploy --product example
  • view shows the ledger's summary and every channel list, oldest first.
  • asks shows one page of asks in the order they were put. Filter with --state open|answered|all, --week YYYY-Www, --product <id> (or --product - for asks about no Product) and --limit 1-100 (default 100). When next is not null, pass it as --after for the next page.
  • week counts one ISO week in the ledger's zone. kr1 shows the frozen measurement windows, each counted, or frozen: null with a reason until the first live ask. Both read the host clock unless --at gives an instant, and both report readAt. The blocker classes are not built, so resolvedClasses is null and the class half of a repeat stays unknown.
  • classes lists the classes given in answers, with rehearsal answers counted apart.
  • rules lists the rules recorded with answers, filtered by --class and by --product (a rule for every Product covers each). A rule recorded while the ledger rehearsed shows standing: "none" and why. A rule is the owner's recorded words: no command applies it.

With no ledger in the journal, every view answers no-ledger with a reason, never zero asks. Malformed filters are refused as usual. A ledger that changes while a view reads it is refused with CONTENDED (exit 75); run the view again.

Form an exception batch or the Monday digest

Prepare the owner's signed digest commission. It must match the Owner digest contract exactly; nothing falls back to the proposed defaults:

{ "protocol": "sf-digest-commission/1", "zone": "Europe/London", "batchTimes": ["09:00", "13:00", "18:00"], "digestTime": "07:00" }

Choose the instant the command acts at, in UTC with milliseconds, and keep it with the commission. Run a health poll first, so the batch and digest read current health:

npm run factory:bet -- owner-digest batch \
  --journal /path/to/existing.sqlite \
  --commission /path/to/commission.json \
  --at 2026-10-05T08:05:00.000Z
npm run factory:bet -- owner-digest digest \
  --journal /path/to/existing.sqlite \
  --commission /path/to/commission.json \
  --at 2026-10-05T08:20:00.000Z

The outcome is one of these:

  • quiet: the instant is between 22:00 and 07:00 in the commission's zone.
  • not-due: no batch time has passed today, or this week's digest is not due until dueAt.
  • empty: this batch slot has nothing new and nothing it cannot vouch for.
  • formed: the result carries the text, its word count and citations, and the full record. replayed is true when that slot or week was already formed.

Formed text is recorded in the journal, and the dashboard's Digest page reads it. Nothing is sent, scheduled or delivered.

The digest takes its asks from the ask ledger in the same journal. The ledger keeps only its latest state, so it cannot show the asks as they stood at an earlier instant. With no ledger, one still in rehearsal, or one holding a record that claims an instant later than --at, the asks line shows a dash and a fixed reason, and the digest never says nothing needs you. Otherwise it lists the subjects of open live asks and cites the ledger's version and channel-list revision.

The count is exact only when the ledger's own coverage rule shows a complete channel list. Every channel must write. No record may come through a channel the list omits, and the ledger must not be full. That must hold in every week from the first live list until --at. Otherwise the line says "at least". The command reads at most 104 such weeks; over a longer span the count also says "at least". More than 1,000 open asks are refused with LIMIT. Nothing is recorded or shortened.

If the outcome is uncertain, retry with the same instant and commission. A formed slot or week replays the recorded text and writes nothing new. Asks are read only when a new digest forms, so a replay never depends on the ledger's current asks. Do not change the instant merely to get a different answer.

Record that a digest was sent

Nothing sends the digest. When it has been sent another way, record that against the ask ledger, so its words count as the owner's reading for that week:

npm run factory:bet -- owner-digest sent \
  --journal /path/to/existing.sqlite \
  --week 2026-W41 \
  --sent-at 2026-10-05T08:30:00.000Z \
  --channel email \
  --recorded-by owner

To record a new send, the week must already have a formed digest in the journal; otherwise the command refuses with DIGEST_NOT_FORMED (exit 66) and writes nothing. Only the last eight digests are kept, so a week that is not yet recorded and is older than those refuses the same way. A send stated before the digest was formed is refused with SENT_BEFORE_FORMED. The channel must be a channel ID; whether the ledger's list names it is for the ledger's coverage to report.

The record is the ledger's digest update with ID digest-<week> and the digest's own word count. Once a week is recorded, a retry is answered from the ledger's record and receipt, with the word count the ledger recorded, even after the digest itself is no longer kept: the same flags replay and write nothing; a changed instant, channel or recorder for that week is a conflict (exit 65).

owner-policy update accepts any update ID, so the ledger can hold a digest-<week> update that this command did not record. Before replaying, the command checks the ledger's record against the digest module's own formation event for that week, which is kept after the digest itself is not. With no formed digest it refuses with DIGEST_NOT_FORMED. It refuses with NOT_DIGEST_RECORD (exit 65) a record that is not a digest update, lacks the formed digest's word count, or was recorded before the digest was formed. While the digest is kept, a record whose send is stated before formation is refused the same way. Neither refusal writes anything. A record carrying exactly what this command would have recorded cannot be told apart from it and replays.

Record a delight or frustration note

Prepare the note with its own command ID. outsideAskMinutes may be null, and text is optional:

{ "commandId": "note-2026-10-01", "feeling": "delight", "outsideAskMinutes": 25, "text": "The red build was caught early." }
npm run factory:bet -- owner-digest note \
  --journal /path/to/existing.sqlite \
  --commission /path/to/commission.json \
  --at 2026-10-01T09:00:00.000Z \
  --input /path/to/note.json

The note counts in the week of --at, in the commission's zone. A retry with the same command ID and content replays at any instant. Changed content under that ID is a conflict. The next Monday digest counts the week's notes.

Read the result

The command writes one JSON result. For machine use, run node scripts/factory-bet.ts with the same arguments to avoid npm's own banners. Errors also write a short code to standard error, without copying the input. Use --help for the command summary.

ExitMeaning
0Command completed. Health can still be red or unknown, and a batch or digest can be quiet, not due or empty; inspect the result.
2Partial poll: inspect every Product's outcome and mirror status.
64Invalid arguments or input.
65Command conflict or revision mismatch, including a digest-<week> update that is not a formed digest's record.
66Input or journal unavailable, or no formed digest for the week given to owner-digest sent.
70Other error; inspect the code.
75Limit or contention, including too many open asks for a digest or an ask ledger that changed while it was read.

An error's effect is not-started before the journal opens, none for a ledger view (its journal is opened read-only), otherwise conservatively unknown. It is not proof that a write happened. Keep the original identity while resolving uncertainty. Missing, empty, foreign and unsupported journals are refused without initialising them. File checks do not defend against a hostile process replacing paths concurrently.

Delivery operator commands

From the Factory checkout run npm run factory:delivery -- --help. The command accepts each stage separately with --journal, --root and --input. The input is a bounded regular UTF-8 JSON file containing exactly the typed stage fields. Paths and IDs are caller-owned; the command does not register Products or authorise itself. Preserve request files across restart.

For example, run npm run factory:delivery -- verify --journal /caller/journal.sqlite --root /caller/delivery --input /caller/verify.json, where the request contains productId, sliceRef and candidate. Pass its returned proof to an integration request containing those fields plus proof, action: {id, occurrence} and dispatchId. The Action ID is actionIdOf(productId, sliceRef) from the Product gate; retain an original positive occurrence and unique 32-character hexadecimal dispatch ID.

An externally sealed Candidate uses npm run factory:delivery -- verify-external --journal /caller/journal.sqlite --root /caller/delivery --input /caller/external-check.json. Retain exactly {productId, sliceRef, candidate, repository} in that file; repository is the original caller-bound physical Repository identity. The Candidate must already match the frozen Slice and native seal. This stage uses the same Product owner and check allowance. Repeat the original file to reconcile or replay its proof without another collector. A different store or internal/external provenance refuses; no production record is invented. The verify verb continues to require existing Delivery production.

The run command accepts {bind, grant, plan, proposalPath, integration}. The first three are the exact typed stage inputs for one Product and grant; integration contains only the original action and dispatchId. It calls bind, grant, plan, produce, verify, integrate and assess in order, feeding each returned Candidate and proof to the next stage. Before replaying planning or production, it reconciles an unfinished original integration from authenticated gate metadata under the same Action occurrence and dispatch ID. A confirmed original receipt then permits replay of all preceding stage contracts; an unknown remains stopped without another submission. It stops on any refusal, failed check, unknown effect or cancellation, reports the completed stages and adds no competing journal, owner, allowance or automatic retry. Repeat the original file after an uncertain result; inspect retained state before choosing a new occurrence. Repeating completed stages consumes no new production/check/integration allowance, although existing fence acquisition can add gate history. Assessment is recomputed read-only.

Exit codes and structured JSON distinguish failed checks (1), inconclusive or unknown (2), invalidated proof (3), withheld dispatch (5), invalid request (64), conflicts or denied authority (65), missing input (66), unexpected errors (70) and exhausted allowance (75). A stage exception reports effect unknown because earlier durable writes or Git effects may already exist.

Source: docs/how-to/run-factory-commands.md