# Census: db region forward, plan 1 (the box side and the wire, dark)

Status: ACCEPTED in full by the census owner on #280, 2026-10-22, as
`census-ruling-db-region-forward-1`. Every row now carries
`rev3=census-ruling-db-region-forward-1`, and the H3 removal names
`census-ruling-db-region-forward-1 (accepted by the census owner on #280,
2026-10-22)`. The ruling covers every row below: the H3 retirement of
`runQueryContext`, the J1/J4 legacy rows, the diagnostic probe row, the two
external unit rows, the re-frozen and re-pinned changed units (including the
shared `ensureSystemArmed`), the 9B8 nonrecord puts and the re-pinned
envelopes.

The census owner's rationale: every new read runs as the agent (carlos) or
the sandboxed DynamicUser worker, not root. The only root change is
`ensureSystemUnits` installing two fixed embedded units. The worker reads
only the files the agent sent and its private scratch. `SelfView`'s open of
host.env only confirms that the sandbox hides it.

The branch is `db-region-forward-1`, cut from `design-db-region-forward`
(e765d57d, which already holds main at 5f341f33). It builds plan 1 of
`docs/superpowers/specs/2026-10-22-db-region-forward-design.md` (rev 6):
`internal/dbquery` (the query runner moved out of `db.go`),
`internal/dbreads` (the wire, the box's db-reads agent and the db-read
worker), `dbdoor` planning over any replica reader, the two
`carlos-dbread` units installed and armed by `ensureSystemUnits`, and the
`db-read-1` capability. Nothing runs unless a console asks, and no console
asks until plan 2.

It adds one root-read overlay,
`internal/provision/testdata/plan14-root-reads-db-region-forward-1.tsv`,
loaded last in `TestPlan14RootReadCensus`, after `console-brand-name` (the
overlay main loads last at 5f341f33). Its record-write entries are layered
on `plans2WriteCensusInventory` in
`internal/provision/db_region_forward_census_test.go`.

## Root reads

Executing identities, named once:

- **the agent**: `/opt/carlos/carlos agent`, `carlos-edge.service`, user `carlos`.
- **the worker**: `carlos system db-worker`, `carlos-dbread@.service`, a
  `DynamicUser` with `PrivateNetwork=yes`, `RestrictAddressFamilies=AF_UNIX`,
  its own `PrivateTmp`, `/data`, `/var/lib`, `/opt/carlos` and `/run/carlos`
  empty, `/etc/carlos` inaccessible. It reads only the files the agent sent
  and its own scratch.
- **the CLI**: `carlos db query` on a person's machine, as the person.

| unit | change | executing identity | proposed disposition |
|---|---|---|---|
| `db.go` `runQueryContext` | still declared; reads nothing now: a one-line call to `dbquery.RunContext` | the CLI | retired: `@remove` plus `@removed ... H3 census-ruling-db-region-forward-1`, the form the carlos-run H3 removal used |
| `internal/dbquery/dbquery.go` `RunContext` | new: `runQueryContext`'s body moved unchanged but for the `immutable=1` open option the worker passes | the CLI and the worker; neither is root | legacy, accepted-legacy, J4 (`basis=root-input`, main's footing for the same body), both callers named |
| `internal/dbreads/agent.go` `nonce` | new: 16 bytes from `crypto/rand` for `picked`'s attempt nonce (the scanner reads `rand.Read` as a read) | the agent | legacy, J1/J4 route-and-input, as the offline move's agent units |
| `internal/dbreads/read.go` `sendFile` | new: reads one planned LTX file whole from the box's own region replica (read-only reader), between identity checks A and B, and frames it to the worker undecoded | the agent | legacy, J1/J4 route-and-input |
| `internal/dbreads/seal.go` `open` | new: AES-GCM open of a sealed chunk or summary (`cipher.AEAD.Open`, read by the scanner as `Open`) | the CLI (plan 2); no production caller in plan 1 | legacy, J4 |
| `internal/dbreads/worker.go` `SelfView` | new: `/proc/self/net/dev`, a listing of `/data`, an open of `/etc/carlos/host.env`, only to report what the sandbox hides | the worker | legacy, J4 |
| `internal/dbreads/worker.go` `ServeWorker` | new: stats the restored copy in its private `/var/tmp` for the size cap | the worker | legacy, J4 |
| `internal/dbreads/worker.go` `receiveFile` | new: creates each planned file, exclusively, under its private `/var/tmp` | the worker | legacy, J4 |
| `internal/host/dbreads_linux.go` `dbReadUnits` | new: `systemctl list-units 'carlos-dbread@*.service'`, readable without privilege, for the orphan rule | the agent | legacy, J4 |
| `internal/host/dbreads_linux.go` `varTmpFree` | new: one `Statfs` of `/var/tmp` for the disk reservation | the agent | legacy, J4 |
| `internal/host/units/carlos-dbread.socket` `external` | new unit file | written by root's `ensureSystemUnits`; bound by PID 1, owned by carlos | legacy external unit, as `carlos-instance-cmd@.service` took |
| `internal/host/units/carlos-dbread@.service` `external` | new unit file | the worker's unit | legacy external unit |
| `internal/dbreads/agent.go` `Agent.probe` | new: the readiness probe, a hello on its own worker connection; the scanner names no read in it, so this is a declaration row | the agent | **diagnostic**, J4: decides only whether the box publishes `db-read-1` |
| `internal/host/edgesfile.go` `edgesFileLoop` | changed legacy: `db-read-1` joins the capabilities while the armed loop's probe passes; the published draining flag is stored for the loop; read site unchanged, offset moved | the agent | re-frozen at main's disposition (`census-ruling-moves-offline`) with the change appended |
| `internal/host/agent.go` `fastConvergeLoop` | changed authority: the serial pass nudges the db-reads loop after the runs pass (a channel send) | the agent | re-pinned at main's B3 |
| `internal/host/agent.go` `runAgent` | changed authority: `armDBReads` beside `armRunsPass` in the activator's Configure step | the agent | re-pinned at main's B,C,D,F |
| `internal/host/systemunits.go` `ensureSystemUnits` | changed authority: installs the two units, asks one more `is-active`, arms the socket (never the template); the armed list is now `ensureSystemArmed`, which the claim census reads too | root (the adopt pass) | re-pinned at main's F,J4 |
| `system.go` `runSystem`, `systemVerb` | changed declarations (no reads): dispatch `carlos system db-worker` | the operator CLI and the worker unit | re-pinned at main's authority rows |

Scanner notes for the ruling:

- `internal/dbdoor` `ListLevel`, `PlanFrom`, `finishPlan`, `listing.*` and
  `RestoreLocal`, which the plan expected to need rows, are not named by the
  scanner (their I/O goes through replica-client methods it does not
  match), so they have none. Their package envelope is re-pinned.
- `internal/console/apidb.go` `listReplicaLevel` and `dbClassRefusal` now
  delegate to `dbdoor.ListLevel` and `dbreads.ClassRefusal`; the scanner
  names neither, and the `internal/console` envelope is re-pinned.

Envelopes re-pinned: `.`, `internal/console`, `internal/dbdoor`,
`internal/dbquery` (new), `internal/dbreads` (new),
`internal/dbreads/dbreadstest` (new), `internal/host`, `internal/host/units`.

Seal: console-brand-name's `78e18e222a8178bbe16b638c5e3811b8f64c4c2664ffd6649eb4273e72fae24e`
is checked first; with this overlay's 12 frozen declarations it becomes
`fc73854854f9e75d122ebd0eacf330d126201aa9d5c4295c634cc1c204a9168d` with the
accepted ruling's markers (it was `20d70361...` while proposed, and
`d57f153e...` before the round 1 fixes below).

## Record writes (9B8)

| site | class | why |
|---|---|---|
| `internal/dbreads/agent.go` `Agent.elect` | nonrecord | the create-only `db-reads/<id>/picked` in the deployment bucket |
| `internal/dbreads/chunks.go` `putCreateOnly` | nonrecord | create-only sealed chunks and `result.json` under `db-reads/<id>/` |
| `internal/dbreads/dbreadstest/dbreadstest.go` `Submit` | testsupport | test support imported only by `_test.go` files: the console's two creates for a test with no console, as leasetest's sites are |

No record writer and no `Delete` site is added.

## Not in this plan

The console route (`registerCLIRoutes` key-site, `claim-routes.txt`) and its
creates (`request.json`, the queue entry, `cancel`) are plan 2's.

## Round 1 fixes (Astra, 1760ea5f)

Three rows changed with the fixes; each keeps its disposition and appends a
`round 1` clause:

| unit | change | disposition |
|---|---|---|
| `internal/host/units/carlos-dbread.socket` `external` | listens at `/run/carlos/dbread/worker.sock`, under the `/run/carlos` tree every tenant unit hides (tenants run as carlos, the uid the worker serves), and is armed only where host.env arms db reads | re-frozen, legacy external unit |
| `internal/dbreads/worker.go` `ServeWorker` | refuses, before writing anything, a plan whose restored-size cap is above its own LimitFSIZE or whose files total more than twice that cap | re-frozen, legacy J4 |
| `internal/host/systemunits.go` `ensureSystemUnits` | arms the socket only when the installed host.env arms db reads (same rule as the capability) and stops and disables it elsewhere | re-pinned at main's F,J4 |

One read the census does not see, named for the ruling:
`internal/host/dbreads.go` `dbReadsSocketWanted` reads `/etc/carlos/host.env`
as root (from `ensureSystemUnits`, the adopt pass) through the
`readClaimUnitFile` variable, which the scanner does not match, so it has no
row. It reads six db-reads keys and decides only whether the db-read socket
is armed; it refuses (keeps the socket dark) on anything it cannot read or
parse. The claim unit settings already read the same file the same way.

The check-B fix (`afterCheckB`) and the deadline fix (`serve`) add no read
the scanner names; the `internal/dbreads` and `internal/host` envelopes are
re-pinned.