Rounds 2 and 3 of the roadmap: feature/round-2 into main

.github/workflows/hosted.yml

@@ -0,0 +1,67 @@
+name: Hosted
+# The native backend tier on the one hosted deployment, by npm run test:hosted. It runs on a
+# schedule and on dispatch. GitHub runs a schedule from the default branch, and the environment
+# hosted admits the default branch only, so a dispatch from another branch gets no key. No other
+# workflow waits on this one, and its failure fails no other check.
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 3 * * 1,4"
+permissions:
+  contents: read
+# One run at a time on the deployment; a queued run waits and no running run is cancelled.
+concurrency:
+  group: hosted
+  cancel-in-progress: false
+jobs:
+  hosted:
+    runs-on: ubuntu-latest
+    environment: hosted
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          cache: npm
+      # The install runs before any step is given the key.
+      - run: npm ci
+      # GitHub masks the whole key; the part after the | and both URL-encoded forms are masked too.
+      - name: Mask the deploy key's forms
+        env:
+          HOSTED_DEPLOY_KEY: ${{ secrets.HOSTED_DEPLOY_KEY }}
+        run: |
+          node -e '
+            const key = process.env.HOSTED_DEPLOY_KEY ?? "";
+            const secret = key.slice(key.indexOf("|") + 1);
+            for (const form of [key, secret, encodeURIComponent(key), encodeURIComponent(secret)])
+              if (form !== "") console.log("::add-mask::" + form);
+          '
+      # The run's output goes to a file. The log is printed and the record uploaded only after the
+      # record check finds no form of the key in either.
+      - name: Native run on the hosted deployment
+        id: run
+        env:
+          HOSTED_DEPLOYMENT_URL: ${{ vars.HOSTED_DEPLOYMENT_URL }}
+          HOSTED_DEPLOY_KEY: ${{ secrets.HOSTED_DEPLOY_KEY }}
+          HOSTED_DEPLOY_KEY_NAME: ${{ vars.HOSTED_DEPLOY_KEY_NAME }}
+          HOSTED_PLAN: ${{ vars.HOSTED_PLAN }}
+        run: |
+          set +e
+          npm run test:hosted > "$RUNNER_TEMP/hosted.log" 2>&1
+          echo "code=$?" >> "$GITHUB_OUTPUT"
+      - name: Record check
+        env:
+          HOSTED_DEPLOY_KEY: ${{ secrets.HOSTED_DEPLOY_KEY }}
+        run: |
+          shopt -s nullglob
+          records=(evidence/runs/hosted-*.json)
+          node scripts/hosted-record-check.mjs "$RUNNER_TEMP/hosted.log" "${records[@]}"
+      - name: The run's log
+        run: cat "$RUNNER_TEMP/hosted.log"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: hosted-evidence
+          path: evidence/runs/hosted-*.json
+      - name: The run's result
+        run: test "${{ steps.run.outputs.code }}" = "0"

AGENTS.md

@@ -16,6 +16,7 @@ The Convex transactional domain platform. `docs/` holds the inputs. `design/` ho
 - Before you write or edit a Spec, read `design/PLAN.md` section 6 and `node_modules/@libar-dev/software-delivery-protocol/.agents/skills/sdp-authoring/SKILL.md`.
 - `python3 design/tools/check.py` prints `OK` when the Specs, the README and the ledger agree. Run it before you say they do.
 - Name the tier behind a claim about behavior: compiled, pure test, `convex-test`, or native backend.
+- Tests and CI are the proof. No agent writes a record file, a proof log or a per-number command list; a job answers in fifteen lines and the run log takes one line. The owner, 2026-10-03: "Tests should be all the proofs we need."
 - The earlier platform, in the `convex-event-sourcing` repository, is evidence about Convex and about what failed. Take a fact from it with its date and versions. Take none of its designs or working habits.
 - `design/reviews/r3-*.jsonl` are records of a finished review round and keep their text.
 - Prose uses plain words, sentence-case headings and no em dashes.
@@ -25,7 +26,7 @@ The Convex transactional domain platform. `docs/` holds the inputs. `design/` ho
 - `design/ROADMAP.md` is the aggregated roadmap: the next units in rounds, what each needs first and shows, what is deferred and why. The owner rules on it; the main thread keeps it current at each close. The slices of `design/STATE.md` keep their names, and the roadmap orders the units inside and between them.
 - Four advisors, `advisor-convex`, `advisor-domain`, `advisor-operator` and `advisor-product`, are Fable agents defined under `.claude/agents/`. Each is launched with a task file under `design/advisors/`: `task-sort.md` sorts the open decisions of its lens, `task-fork.md` writes one owner decision as a fork, `task-roadmap.md` proposes the milestones of one subject. The four run at once, with disjoint subjects, and the main thread merges or cuts.
 - Every lean, fork or memo is checked by a `gpt-6.1-sol` job of the other family before the owner sees it, on a copy that carries one planted false citation. `design/advisors/README.md` says how each run goes and what the first runs showed; `design/advisors/protocol.md` binds every sentence an advisor writes.
-- The memos, briefs, plants and check reports of a run live outside the repository, in the unit folder the project notes name.
+- The memos, briefs and plants of a run live outside the repository, in the unit folder the project notes name. A check job's report stays in its job directory.
 
 ## The language
 

CONTEXT.md

@@ -1,6 +1,6 @@
 # Transactional domain platform
 
-The language of a platform on which a business operation is one transaction: a command is authorized, decided against current state, recorded as events and answered, all or nothing. These are the words for what the platform is. Words for how it is designed and proven, and words for the work of building it, are listed apart at the end, because they must not leak into the first group.
+The language of a platform on which a business operation is one transaction: a command is authorized, decided against current state, recorded as events and answered, all or nothing. These are the words for what the platform is. Words for how it is designed and proven, and words for the work of building it, are listed apart at the end, because they must not leak into the first group. This file leads: `spec:platform.vocabulary` follows it, and the doc keeps its authority over what the platform decides.
 
 ## Language
 
@@ -22,6 +22,10 @@ _Avoid_: operation (alone), endpoint, handler, context command
 The parent's carrying out of one command across one or more contexts, with one outcome.
 _Avoid_: workflow, saga, orchestration, executor (the code's name for the function)
 
+**Entry**:
+A function the parent registers for a caller: a public command, an internal command, a parent query or an operator entry.
+_Avoid_: endpoint, handler, function (alone)
+
 ### Commands and outcomes
 
 **Command**:
@@ -104,7 +108,7 @@ _Avoid_: apply, reduce, patch, state update
 
 **Rebuild**:
 Recomputing stored state from the history that should produce it: a stream's current state from its events, or a read model from its sources.
-_Avoid_: replay, resync, reprocess, backfill (one step of a read-model rebuild)
+_Avoid_: replay, resync, reprocess
 
 **Baseline event**:
 An event that holds migrated state, from which a rebuild starts when the meaning of earlier events has changed. Earlier events stay readable.
@@ -124,6 +128,10 @@ _Avoid_: scope (alone), tenancy
 The server-established identity that caused a command: a human, a service, an agent, a reviewer or an operator.
 _Avoid_: user, caller, principal, identity
 
+**Stated operator**:
+The name an administrator states when calling an operator entry. It records who said they acted and establishes no actor; an actor of kind operator is one the server establishes, which no entry does.
+_Avoid_: operator (alone, for this meaning), actor (for a stated name)
+
 **Grant**:
 An authoritative statement that an actor holds a permission in a tenant, read in the same transaction as the command it authorizes.
 _Avoid_: role, ACL, access rule
@@ -156,6 +164,18 @@ _Avoid_: replay, repeat, retry (what the caller does)
 
 ### Reads
 
+**Parent query**:
+A read the parent answers to a caller, authorized in the parent, relaying a context query or reading a read model.
+_Avoid_: query (alone), endpoint, read (alone)
+
+**Context query**:
+A read a context answers to the parent, returning a DTO and never a document.
+_Avoid_: query (alone), getter
+
+**Query refusal**:
+The refusal of a parent query, in the same wire shape as a rejection, naming the entry that refused. It is not an outcome, and nothing is recorded.
+_Avoid_: rejection (for a query), error, denial
+
 **Read model**:
 A stored shape made for reading, updated inside the command from the state that command committed.
 _Avoid_: view (alone), cache, table, projection (the logic, not the data)
@@ -168,10 +188,64 @@ _Avoid_: read model (the data), handler, subscriber
 One numbered build of a read model.
 _Avoid_: version, attempt
 
+**Installation**:
+Making a read model exist in a deployment: its declaration and its first rebuild.
+_Avoid_: activation, first activation, setup
+
+**Backfill**:
+The part of a rebuild that writes a generation's rows from its sources.
+_Avoid_: rebuild (for this part alone), replay, import
+
+**Verification**:
+The part of a rebuild that checks a generation's rows against its sources and corrects them.
+_Avoid_: validation, reconciliation, audit
+
+**Pass**:
+One traversal of a rebuild over its sources or its rows: a backfill, a verification, a purge or a fill. The verb passes and a pass condition belong to scenarios, and a test's outcome is a test result.
+_Avoid_: run, iteration, round
+
+**Switch**:
+Making a verified generation the one readers see, in one write.
+_Avoid_: cutover, promotion, activation
+
+**Rollback**:
+Making a retired generation the one readers see again.
+_Avoid_: revert, undo, downgrade
+
+**Retired generation**:
+A generation readers no longer see, kept until it is purged.
+_Avoid_: old generation, previous version, inactive
+
+**Purge**:
+Deleting a retired generation's rows.
+_Avoid_: cleanup, garbage collection, drop
+
+**Fence**:
+The number a generation's batches carry so that a batch from before an interruption writes no read-model row and schedules nothing.
+_Avoid_: epoch, token, lease
+
+**Progress row**:
+The row that holds where a rebuild stands, read by its batches and by no command.
+_Avoid_: checkpoint, cursor row, status row
+
+**Tenant list**:
+The parent's list of its tenants, which a rebuild and a sweep walk one tenant at a time.
+_Avoid_: tenant table, registry, directory
+
 **Write pause**:
 A stretch during which commands that write the sources of a read model are refused, so that the read model can be rebuilt from a consistent cut.
 _Avoid_: lock, maintenance mode, freeze
 
+### Backups
+
+**Backup archive**:
+The exported file of a deployment's table data at one moment, which a restore imports.
+_Avoid_: snapshot (a transaction's view of the database), export, dump, backup (alone, for the file)
+
+**Restore**:
+The procedure that imports a backup archive under matching code and proves the invariants hold before any writer runs.
+_Avoid_: import (one step of it), recovery, rollback
+
 ### Deferred work
 
 **Obligation**:
@@ -206,9 +280,27 @@ Words for how the platform is specified and proven. They are lasting and may app
 - **Do-nothing option**: the design that adds no mechanism and relies on Convex as it is.
 - **Fact**: something the design relies on Convex to do, marked documented, probed or assumed.
 - **Probe**: one small test on a real backend that turns an assumed fact into a probed one.
-- **Scenario**: a situation with a pass condition that the platform must meet.
-- **Tier**: the kind of test that can prove a scenario: domain, simulator, native or end to end.
+- **Scenario**: a row of the doc's acceptance table, a situation with a pass condition that the platform must meet; a case is one example of a row.
+- **Tier**: the kind of test that can prove a scenario: compiled, pure test, convex-test or native backend.
+- **Target**: where a native backend test runs, the local backend or a hosted deployment, recorded apart from the tier and the composition.
 - **Composition**: an application assembled from the platform for a purpose: the production composition, or the fixture composition that exists only to prove scenarios.
+- **Verifier**: a test bound to an example, which proves it when it passes at the example's tier on its composition.
+- **Acceptance check**: the check that reads from the graph every scenario the first experiment requires and from one run's record whether each passed.
+- **Test result**: what one run of a verifier leaves in the run record: passed, failed or skipped.
+- **Run record**: the harness's record of one run of the test projects, with the commit, the pins, the target and every test result; a restore's own record is a restore run.
+- **Measurement record**: a run record's entry that holds a measured cost or time with its pins and its target.
+- **Local backend**: the pinned backend process the harness starts and disposes of for a test.
+- **Hosted deployment**: a Convex Cloud deployment the harness targets with a deploy key.
+- **Deploy key**: a hosted deployment's credential, scoped to the actions a run needs.
+- **Admin key**: the local backend's credential.
+- **Usage reading**: what a hosted deployment's usage report says for a window; a difference of two readings is one run's own only when no other run overlapped it.
+- **Stated plan**: the Convex plan a hosted run records as the owner stated it, never read from billing.
+- **Kept dataset**: the data a hosted deployment carries from one run to the next on purpose.
+- **Planting record**: the row a run writes beside a schedule it planted, so that a later run can tell a retained schedule from a lost one.
+- **Execution**: one run of a function by the backend, the unit the function log counts.
+- **OCC rerun**: an execution the engine repeats after a write conflict; neither an attempt nor a retry by the caller.
+- **Contention**: several commands at once on one stream.
+- **Controlled change**: one difference against a reference run, so that a cost is attributed to a line.
 
 ## Words that are not part of the language
 
@@ -223,7 +315,7 @@ Words about the work of building the platform: when something was done, in what
 Three words exist on both sides and mean different things:
 
 - **Agent**: in the language, a kind of actor whose proposals the parent checks. In the work, a model that writes or reviews code. Only the first is a domain term.
-- **Reviewer** and **operator**: in the language, kinds of actor. In the work, whoever reviews a change or runs a deployment by hand.
+- **Reviewer** and **operator**: in the language, kinds of actor, and apart from them the stated operator. In the work, whoever reviews a change or runs a deployment by hand.
 - **Operation**: in the language, one accepted execution of a command. In the work, nothing: "an operation of the session" is a step.
 
 Fixture names such as depot, document and stock are the fixture composition's own small domain. They are not platform language either.