/miroir/miroir.yaml in the world image. For a worked example, see
Write the manifest.
It is YAML, read strictly:
- An unknown key is an error. Every error names the field path and the fix, such as
processes[2].cwd: 'app' must be an absolute path, such as /app. - Commands are lists,
[program, arg, ...], run without a shell. Write[sh, -c, "..."]when you need one.
Top-level keys
Processes
Each entry ofprocesses is a long-running process. At least one must have datastore: true,
and every datastore comes before the other processes.
Database
Dates
A world is seeded once, at build time, but tasks talk about “overdue” invoices or deals “stale for 30 days”. To keep those true, every boot moves the database’s dates from the bake to the day of the trial:
These values stay where they are:
- columns listed in
database.time.exclude; - generated columns;
- values on or after
9000-01-01, such as9999-12-31for “never”; - Unix times of 0 or less.
updated_at does not
fire.
Whole days and calendar days differ for part of each day. An image baked at 23:00 UTC and booted
at 01:00 the next day moves dates by 1 and timestamps by 0. That is why a check never compares a
date column with a timestamp column (authoring rules).
If a constraint refuses a moved value, the boot fails and names the table. List the column in
database.time.exclude.
Restored data
database.time.captured is for data restored from a dump. The bake moves the restored rows from
that time to the bake’s start, so a dump taken weeks before the build keeps its relative ages. The
seed’s writes come after and are not moved. A captured time later than the bake’s start is
refused.
Sinks
The product cannot reach the internet: its compose network isinternal: true. Instead, point its
outgoing mail and HTTP at the sinks, recorders that listen on loopback. What they record becomes
the sent_emails and sent_requests tables of the evidence.
- SMTP records each email: the sender, the
toandccrecipients, the envelope recipients missing from the headers (asbcc), the subject, the text and the HTML. Point the product’s SMTP settings at127.0.0.1:<port>; the fixture setsSMTP_URL=smtp://127.0.0.1:2525. - HTTP records each request: method, path, query parameters, headers (names lower-case,
authorizationdropped) and body (JSON as JSON, other text as a JSON string, an empty body asnull). Point base URLs athttp://127.0.0.1:<port>. The fixture setsSTRIPE_API_BASE=http://127.0.0.1:9000/stripe, and Gitea allows webhooks to127.0.0.1:9000. - Responses are keyed
"[METHOD ]/path[*]", each{status, json | body, headers}. An exact path beats a prefix (a key ending in*), a longer prefix beats a shorter one, and a key with a method beats one without. Unmatched requests get 200 with an empty body.
sink fault. The sinks answer during the bake but record only from the boot, and the boot clears
what start-up sent.
Quiet
Products do work in the background: a queued email, a webhook delivery, a search index.quiet is
a command that exits 0 when that work is done, so the evidence holds everything the agent’s
requests set off.
Miroir waits until quiet passes twice in a row, within 30 s, at bake, at boot and at collect. At
bake and boot a timeout fails; at collect it is recorded as a quiet_timeout fault. The fixture
checks two Redis queue lengths; Gitea runs gitea manager flush-queues.
- Turn schedulers and cron off in
env(SCHEDULER_ENABLED: "false"), so nothing changes while the world idles: a run where the agent does nothing must change nothing. - Don’t leave a background process holding the command’s output open. Miroir reads the command’s stderr to explain a failure, so such a run waits out the full 30 s.