With the current code every new guidance save writes a version-2 revision, even one of six or fewer values, an unchanged list or an empty one. The first such save on a journal cannot be undone: once a Product has a version-2 revision, older dashboard servers and worktrees report its guidance as corrupt and refuse to edit it. Rehearse before that first save, whatever its value count, including the first eight-value save. This page shows how to rehearse it on a copy of the journal first, so the live save can be authorised against one reviewed report. The report gives the exact revision, digest and pin before and after, and shows that the source journal was not changed.
The rehearsal is local and read-only for the source. It starts no server, reads nothing from the network and installs nothing. It does not perform or authorise the live save, which remains a separate owner decision. Project guidance v2 and the website permit eight values. Local migration rehearsal does not commission migration of a live journal; historical v1 revisions retain their six-value parser.
Stop older servers
List the processes holding the journal:
lsof <local-portfolio-journal>
Stop every Dashboard server and worktree process that uses the journal, including any started from an older checkout. After the live save, only code that includes the E34 reader can read the Product's guidance. Restart only upgraded servers afterwards.
Back up the journal
With those processes stopped, copy the journal to storage outside the repository and outside .factory, and record its hash:
mkdir -p <local-evidence-archive>
cp -p <local-portfolio-journal> <local-evidence-archive>
shasum -a 256 <local-portfolio-journal> <local-evidence-archive>
The two hashes must match. If portfolio.sqlite-wal or portfolio.sqlite-shm still exists, a process still has the journal open or was stopped abruptly; find it before copying. Keep the backup until the live save has been read back and accepted.
Prepare the values file
Write the complete list of values, in order, to a JSON file outside the repository. Use the revision you reviewed as expectedRevision, and a new command ID that starts with guidance-:
{
"commandId": "guidance-eight-values-2026-10-01",
"expectedRevision": 1,
"values": [
{ "id": "value-one", "statement": "First value", "application": "How it decides between options." }
]
}
Keep the value IDs of existing values when rewording them. Leave out provenance: the Dashboard records direct entry and refuses a provenance field, so the rehearsed digest matches the live save only without one. The file must be a regular UTF-8 JSON file of at most 24,576 bytes holding exactly these fields. That is the Dashboard's limit for a guidance request body, so the same file can be sent unchanged for the live save; a larger file is refused with INPUT_TOO_LARGE, even when its values would fit once compacted. More than eight values, a malformed value or an unknown field refuses the whole file; nothing is truncated.
Run the rehearsal
Choose an output directory that does not exist yet, outside the journal's directory and outside any .factory directory:
node scripts/factory-guidance.ts rehearse \
--journal <local-portfolio-journal> \
--product example \
--values /path/to/values.json \
--out <local-evidence-archive>
Replace example with the registered Product ID, and replace the paths. The command reads the journal and its -wal and -shm files with plain read-only file access; it never opens the source with SQLite, which would create or update those side files. It copies the database and write-ahead log into the output directory and accepts the copy only when every source file hashes the same before the copy, during it and after the run, and no rollback journal (portfolio.sqlite-journal) exists before or after any of those hashes. A rollback journal means a write is in progress or was interrupted, so the database file may hold uncommitted pages. It then reads the copy with the current Factory reader, saves the values on the copy against expectedRevision, reads the result back through a fresh connection, and resolves both the previous pin and the new pin.
The output directory holds rehearsal.sqlite and rehearsal-report.json. While the command runs it also holds INCOMPLETE.json. A rehearsal is complete only when the report exists and INCOMPLETE.json does not. If the command is interrupted, the marker stays: do not use that directory, and rehearse again into a new one.
Read the report
The report is canonical JSON. Its reportDigest is the SHA-256 of the canonical report without that field, so the same journal and values file give the same report and digest on every rerun. Check:
source.beforeequalssource.after, andsource.unchangedis true. Each file is listed with its size and hash, or as absent.beforenames the current revision, its protocol (product-guidance/1for the existing six values), value count, digest and pin.afternames revision n+1 with protocolproduct-guidance/2, the new value count, digest and pin. ItsrehearsalRecordedAtis a fixed placeholder; the live save records its own time, which no digest or pin includes.pinsshows both pins resolved on the rehearsed copy, andhistorylists every revision with its protocol and digest.liveSave.expectedPinis the pin the live save should produce.
The command prints one JSON result. Errors also write a short code to standard error.
| Exit | Meaning |
|---|---|
| 0 | Rehearsed and read back. The live save is still not authorised. |
| 64 | Invalid arguments, values file or output directory. |
| 65 | expectedRevision is not current, or the command ID is already recorded. |
| 66 | The journal, values file, output parent or Product is unavailable or unregistered. |
| 70 | The journal is corrupt, changed during the run, or the read-back disagreed. |
| 75 | More than eight values or another size limit, such as a values file over 24,576 bytes, or the source has a rollback journal. |
Refusals of the request, the Product or the source leave no output directory, or leave an existing empty one empty. A source that changed during the run, an unexpected error or an interruption leaves the output marked incomplete. The source journal is never written in any case.
Make the live save, separately authorised
Only after the owner has reviewed the report and authorised the live append:
- Confirm the journal's hash still matches the report's
source.before.db.sha256. If it does not, rehearse again. - Start one upgraded Dashboard server against the journal, for example
node src/dashboard-server.ts --journal <local Portfolio journal> --port 4317. - Send the same values file as the save command, replacing
examplewith the Product ID. The body must be exactly the rehearsed file; the rehearsal has already checked that it is within the Dashboard's 24,576-byte limit:
TOKEN=$(curl -s http://127.0.0.1:4317/api/session | node -e 'process.stdin.on("data", d => process.stdout.write(JSON.parse(d).token))')
curl -s -X POST \
-H "Origin: http://127.0.0.1:4317" \
-H "Content-Type: application/json" \
-H "X-Factory-Token: $TOKEN" \
--data-binary @/path/to/values.json \
http://127.0.0.1:4317/api/products/example/guidance
- Read it back:
curl -s http://127.0.0.1:4317/api/products/example/guidancemust show the revision and digest ofliveSave.expectedPin. Then read the previous revision, using the number in the report'sbeforesection, for examplecurl -s http://127.0.0.1:4317/api/products/example/guidance/revisions/1; it must show the digest in that section.
If the save's outcome is uncertain, send the same file again: a committed save replays with replayed: true, and another save that landed first returns STALE. Never resend the change under a new command ID until the first one is resolved. If the read-back differs from the report, stop and keep the backup; do not try to repair the journal.
What this does not establish
The rehearsal shows that the current reader can save and read eight values on a copy of this journal. It does not show that the live save succeeded, that any planner uses the values, or that E34 is accepted. Recording the live save, its read-back and any website change belongs to E34's own evidence. See the guidance contract and the save project values page.
