Task: Add the immutable structure
Table of Contents
This page documents a task in the Model trade structures story. It captures the goal, current status, acceptance, and any notes or results.
1. Goal
A structure is an immutable row with its own identity, parties, kind and template.
2. Status
| Field | Value |
|---|---|
| State | DONE |
| Parent story | Model trade structures |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-10-05 |
3. Acceptance
- structure is insert-only with tenant, id, party, counterparty, kind, template and parent_structure_id; the purge passes its guard only through the immutable purge switch.
- A structure with a parent has no children, so structures nest one level at most; a pgTAP test refuses a second level.
4. Plan
(Implementation strategy. Written when work starts; key decisions
are distilled into the parent story's * Decisions at close, but the
plan itself stays — it is the historical record of what we did.)
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 |
|---|---|---|---|
| static checks on this branch | 6 of 6 pass | compass check --only handler-permissions --only create-reachability --only model-drift --only cmake-sources --only sql-hygiene --only populate-refs |
feature/structure-anchor |
| pgTAP cases written for the structure | 6, never executed | pg_prove test/trading_structures_test.sql |
feature/structure-anchor |
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
9. Review
| Comment summary | File | Decision | Notes |
|---|---|---|---|
10. Result
structure is the immutable anchor of a composed deal: party, counterparty,
kind, an optional template and an optional parent, with no audit tail. The
parent is a database foreign key to the table itself, because the parent is
immutable too, and the insert trigger refuses a leg of a leg and a structure
that is its own parent — one level of nesting, no more.
Ten pgTAP cases cover that rule, the two catalogue references, the nullable template a package rests on, and the refusal of every update and delete.
The task closed on static validation alone, with the cases written and never executed. A follow-up ran them against a rebuilt database: all ten pass, so the nesting rule is now proven by execution rather than by reading the generated trigger. Update and delete are refused with 55000, the state rather than a value, which is the immutability rule itself.
No build and no ctest ran on this task. The hourly build and test on main belongs to swift curie.