Task: Model virtual books
Table of Contents
This page documents a task in the Add sandboxes and virtual books story. It captures the goal, current status, acceptance, and any notes or results.
1. Goal
Give sandbox trades somewhere to be booked that no official process can reach.
2. Status
| Field | Value |
|---|---|
| State | DONE |
| Parent story | Add sandboxes and virtual books |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-10-03 |
3. Acceptance
- A book belongs to the same sandbox as its parent portfolio, or both to none; a book in a sandbox is virtual.
- A virtual book has no ledger reference and is not a sweep target.
- A sandbox's books are read and written only by those who may see the sandbox.
4. Plan
- A book carries the sandbox it belongs to, optional and fixed, as a portfolio does. A book is virtual exactly when it has one, so no separate flag can disagree with the tree.
- The book trigger keeps a book in its parent portfolio's sandbox, or both in none, and refuses a write into an archived sandbox.
- A check gives a virtual book no ledger reference and refuses it as a sweep target.
- The sandbox isolation policy that portfolios carry applies to books too.
5. Measurements
Every number this task claims about a tree, with the command that produced it
and the commit it was measured at. A number without both is not a measurement,
because a clean-up record describes a tree and trunk moves under a branch: a
consumer count, a gate's component count and a suite's size all change with no
code changing, and the reader of a bare number cannot tell which tree it came
from. Where the raw output matters, put it in an evidence/ file beside the
task and name that file in the Command column.
| What | Value | Command | Commit |
|---|---|---|---|
6. Notes
7. Test Scenarios
Manual QA scenarios (scaffolded via compass add test_scenario)
that verify this task. Link
new ones here as they're created; the scenario doc itself links back
via its "Verifies task" field.
| Scenario | State | Notes |
|---|---|---|
8. PRs
| PR | Title |
|---|---|
| #2552 | [refdata] Model virtual books |
9. Review
| # | Comment summary | File | Decision | Notes |
|---|---|---|---|---|
| 1 | Archived rule may block deleting books | book | Keep | A delete is the soft-delete rule, which the insert trigger does not see; only new versions are refused. |
| 2 | Missing parent skips the sandbox rule | book | Keep | The generated foreign key check refuses a missing parent before the custom block runs. |
| 3 | Shell argument for the new column | shell | Keep | The tangled scripts pass the empty marker for an official book; the shell command tests pass. |
| 4 | Mapper include | book_mapper.cpp | Keep | Generated, as for portfolio; the build is clean. |
| 5 | Blank line before the next comment | SQL | Keep | Cosmetic. |
| 6 | No automated test of the rules | pgTAP | Fix | projects/ores.sql/test/refdata_sandbox_test.sql: 24 pgTAP cases over the story's rights, sandbox, tree, virtual book, visibility and row-security rules. |
10. Result
bookgainssandbox_id, fixed; a book with one is a virtual book.- In Postgres, in a transaction that rolled back:
- a virtual book in its sandbox's tree was accepted;
- a virtual book with a ledger reference, and one marked as a sweep target, were refused by the check (23514);
- a real book under a sandbox portfolio, and a virtual book under an official portfolio, were refused by the trigger (23514);
- as the refdata service role, the sandbox owner saw the virtual book, and another account and a session with no actor saw none.
- The book shell scripts are tangled with the new column.
- Build clean; ctest 89 of 89 on a recreated database.
refdata_sandbox_test.sql(pgTAP): 24 of 24 pass against the recreated database.