chore(close-out): session 4 documentation + 6a2 sweep

- ECOSYSTEM.a2ml: CF Workers as production, Fly.io as test-only, V-lang
  ref (rgtv_client.v) removed, vault-worker integration points added
- META.a2ml: 5 ADRs recorded (CF over Fly, DO over KV, axum/tokio,
  rgtv CLI rewrite, Bearer auth)
- PLAYBOOK.a2ml: full operational runbook (CF deploy, Fly spot-test,
  local dev, CLI, incident response, release process)
- NEUROSYM.a2ml: report-format logtalk→json (Logtalk removed 2026-04-12)
- STATE.a2ml: vault-worker completion 85→100%, DO migration blocker
  resolved, session 3+4 history entries added
- EXPLAINME.adoc: replaced template stub with real architecture doc
  (grant lifecycle diagram, technology rationale, one-use guarantee)
- .gitignore: add per-crate target/ dirs, vault-worker/build/, .wrangler/
- Justfile: GRANTS comment corrected (DO not KV)
- contractiles: SPDX typo PLMP→PMPL, rewritten to RGTV-specific checks

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: hyperpolymath

.gitignore

@@ -10,10 +10,19 @@ Thumbs.db
 .idea/
 .vscode/
 
-# Build
+# Rust — per-crate target directories (root /target/ is root-anchored, won't match subdirs)
 /target/
+vault-broker/target/
+vault-core/target/
+svalinn-cli/target/
+vault-worker/target/
+
+# Cloudflare Workers build artefacts
+vault-worker/build/
+.wrangler/
+
+# Build
 /_build/
-/build/
 /dist/
 /out/
 
@@ -22,9 +31,6 @@ Thumbs.db
 /vendor/
 /deps/
 
-# Rust
-# Cargo.lock  # Keep for binaries
-
 # Secrets
 .env
 .env.*

.machine_readable/6a2/ECOSYSTEM.a2ml

@@ -4,8 +4,8 @@
 # ECOSYSTEM.a2ml — Reasonably Good Token Vault ecosystem position
 
 [metadata]
-version = "0.2.0"
-last-updated = "2026-04-11"
+version = "0.3.0"
+last-updated = "2026-04-12"
 
 [project]
 name = "Reasonably Good Token Vault (RGTV)"
@@ -22,10 +22,10 @@ category = "zero-trust"
 
 [related-projects]
 projects = [
-  { name = "nesy-solver-api (proven-servers)", relationship = "consumer", notes = "First wired consumer. Uses rgtv_client.v to fetch NESY_INGEST_TOKEN via grant→redeem. Deployed as rgtv-nesy on Fly.io." },
+  { name = "nesy-solver-api (proven-servers)", relationship = "consumer", notes = "First wired consumer. Fetches NESY_INGEST_TOKEN via grant→redeem protocol. Deployed as rgtv-nesy on Fly.io (spot-test only; production is CF Workers)." },
   { name = "svalinn", relationship = "sibling-security", notes = "Svalinn is a Deno container gateway; RGTV is a Rust credential broker. Different concerns, sometimes confused. Do NOT merge." },
   { name = "rokur", relationship = "sibling-security", notes = "Rokur is Svalinn's internal secrets store (Stapeln GUI). RGTV is a standalone broker. Different projects." },
-  { name = "vault-core", relationship = "internal-component", notes = "Existing crypto library crate in this monorepo. vault-broker builds on it." },
+  { name = "vault-core", relationship = "internal-component", notes = "Crypto library crate in this monorepo. vault-broker builds on it for Zeroizing<String> storage." },
   { name = "hypatia", relationship = "planned-consumer", notes = "CI scanning agent should use RGTV to fetch scan credentials rather than env vars." },
   { name = "gitbot-fleet", relationship = "planned-consumer", notes = "Bot agents should fetch GitHub tokens via RGTV grant→redeem." },
   { name = "007", relationship = "planned-consumer", notes = "Private language toolchain — agents must not see raw API tokens." },
@@ -35,12 +35,23 @@ projects = [
 [integration-points]
 points = [
   { system = "nesy-solver-api", direction = "inbound", protocol = "HTTP POST /v1/grants + /v1/grants/:id/redeem, Bearer auth" },
-  { system = "Fly.io private 6PN", direction = "inbound", protocol = "flycast DNS at rgtv-nesy.flycast:9100 (not .internal — auto-wake required)" },
-  { system = "vault-core", direction = "internal", protocol = "Rust crate dependency — Zeroizing<String> storage" },
+  { system = "Cloudflare Workers (production)", direction = "inbound", protocol = "HTTPS on rgtv-vault.workers.dev (or custom domain); same HTTP API as vault-broker" },
+  { system = "Fly.io private 6PN (spot-test only)", direction = "inbound", protocol = "flycast DNS at rgtv-nesy.flycast:9100 (not .internal — auto-wake required)" },
+  { system = "vault-core", direction = "internal", protocol = "Rust crate dependency — Zeroizing<String> storage (vault-broker only; vault-worker reimplements inline)" },
+  { system = "Cloudflare CREDENTIALS KV", direction = "internal", protocol = "hint → plaintext credential value; operator-managed; vault-worker only" },
+  { system = "Cloudflare GRANTS Durable Objects", direction = "internal", protocol = "one GrantObject DO instance per outstanding grant; atomic one-use enforcement; vault-worker only" },
 ]
 
 [deployment]
-platform = "Fly.io"
+# Production: Cloudflare Workers (vault-worker — Rust/WASM via workers-rs 0.8)
+platform-production = "Cloudflare Workers"
+worker-name = "rgtv-vault"
+worker-entry = "vault-worker/build/worker/shim.mjs"
+deploy-command = "just worker-deploy"
+grant-atomicity = "Durable Objects (single-threaded per instance; read+delete is atomic)"
+
+# Spot-test / internal: Fly.io (vault-broker — axum HTTP server)
+platform-spot-test = "Fly.io"
 app-name = "rgtv-nesy"
 region = "lhr"
 url-scheme = "http://rgtv-nesy.flycast:9100 (private 6PN only)"

.machine_readable/6a2/META.a2ml

@@ -3,22 +3,53 @@
 #
 # META.a2ml — Reasonably Good Token Vault meta-level information
 [metadata]
-version = "0.1.0"
-last-updated = "2026-02-08"
+version = "0.2.0"
+last-updated = "2026-04-12"
 
 [project-info]
 license = "PMPL-1.0-or-later"
 author = "Jonathan D.A. Jewell (hyperpolymath)"
 
 [architecture-decisions]
 decisions = [
-  # No ADRs recorded
+  { id = "ADR-001", title = "Cloudflare Workers as production target (not Fly.io)", status = "accepted", date = "2026-04-12",
+    context = "RGTV needs a production deployment reachable by external LLM agents without VPN or private network access.",
+    decision = "Cloudflare Workers (vault-worker, Rust/WASM via workers-rs 0.8) is the production deployment target.",
+    rationale = "CF Workers: globally distributed, no cold starts, native DO support, zero-infra ops. Fly.io (vault-broker, axum) retained for internal flycast spot-testing only.",
+    consequences = "vault-worker must remain API-compatible with vault-broker. Both implement identical HTTP routes." },
+
+  { id = "ADR-002", title = "Durable Objects for grant state (not KV)", status = "accepted", date = "2026-04-12",
+    context = "Cloudflare KV has no atomic read+delete operation. Two simultaneous redeem requests for the same grant could both succeed.",
+    decision = "Each outstanding grant is stored in its own GrantObject Durable Object instance, keyed by grant_id UUID.",
+    rationale = "DO instances are single-threaded: the Workers runtime serialises concurrent fetches to the same instance. The check-and-delete in the POST handler is therefore a true atomic operation.",
+    consequences = "GRANTS KV namespace removed from wrangler.toml. Durable Objects migrations block required. Each grant creates one DO instance." },
+
+  { id = "ADR-003", title = "axum + tokio for vault-broker (local/test server)", status = "accepted", date = "2026-04-11",
+    context = "vault-broker serves as the spot-test target on Fly.io and for local dev with `just broker-dev`.",
+    decision = "axum 0.7 on tokio, IPv6 dual-stack, Zeroizing<String> for all credential values.",
+    rationale = "Idiomatic async Rust for HTTP; Zeroizing scrubs heap on drop; axum router matches vault-worker's route surface identically so the rgtv CLI works against both.",
+    consequences = "vault-broker holds credentials in-process (Arc<Mutex<HashMap>>); not suitable for multi-node production — CF Workers is." },
+
+  { id = "ADR-004", title = "rgtv CLI (formerly svalinn-cli) wired to HTTP API", status = "accepted", date = "2026-04-12",
+    context = "The CLI binary was named svalinn_cli and was a skeleton not wired to vault-broker.",
+    decision = "Renamed to rgtv binary. Full rewrite using ureq 2 (sync HTTP) + Zeroizing<String>. Works against both vault-broker and vault-worker.",
+    rationale = "Single synchronous binary; no async runtime needed for CLI; ureq is minimal.",
+    consequences = "svalinn-cli crate name kept for Cargo workspace; only the binary name changed." },
+
+  { id = "ADR-005", title = "Bearer token auth (RGTV_AGENT_TOKEN) as sole auth mechanism", status = "accepted", date = "2026-04-11",
+    context = "LLM agents need a simple, stateless auth mechanism compatible with both vault-broker and vault-worker.",
+    decision = "Single shared secret (RGTV_AGENT_TOKEN) passed as Authorization: Bearer header. Worker Secret on CF side; env var on Fly.io side.",
+    rationale = "Simple, stateless, zero-dependency. Rate limiting per agent token is a future concern (see blockers in STATE.a2ml).",
+    consequences = "All tokens share the same privilege level. Per-agent tokens are a future enhancement." },
 ]
 
 [development-practices]
 versioning = "SemVer"
 documentation = "AsciiDoc"
 build-tool = "just"
+rust-edition = "2021"
+wasm-target = "wasm32-unknown-unknown"
+worker-build = "worker-build (cargo install worker-build)"
 
 [maintenance-axes]
 scoping-first = true

.machine_readable/6a2/NEUROSYM.a2ml

@@ -9,7 +9,7 @@ last-updated = "2026-04-11"
 [hypatia-config]
 scan-enabled = true
 scan-depth = "standard"  # quick | standard | deep
-report-format = "logtalk"
+report-format = "json"  # Logtalk removed from Hypatia 2026-04-12; JSON AssailReport consumed by Elixir rules
 
 [symbolic-rules]
 # Custom symbolic rules for this project

.machine_readable/6a2/PLAYBOOK.a2ml

@@ -1,26 +1,79 @@
 # SPDX-License-Identifier: PMPL-1.0-or-later
 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 #
-# PLAYBOOK.a2ml — Operational playbook
+# PLAYBOOK.a2ml — Operational runbook for RGTV
 [metadata]
-version = "0.1.0"
-last-updated = "2026-04-11"
+version = "0.2.0"
+last-updated = "2026-04-12"
 
-[deployment]
-# method = "gitops"  # gitops | manual | ci-triggered
-# target = "container"  # container | binary | library | wasm
+# ── Production: Cloudflare Workers ───────────────────────────────────────────
+
+[deployment.cloudflare-workers]
+worker-name = "rgtv-vault"
+crate = "vault-worker"
+one-time-setup = [
+  "wrangler kv:namespace create CREDENTIALS  → paste id + preview_id into vault-worker/wrangler.toml",
+  "wrangler secret put RGTV_AGENT_TOKEN",
+  "Populate credentials: wrangler kv:key put --namespace-id=<ID> HINT value",
+  "just worker-deploy  (DO migration runs automatically on first deploy)",
+]
+redeploy = "just worker-deploy"
+logs = "just worker-logs"
+creds-list = "just worker-creds-list"
+creds-put = "just worker-cred-put HINT value"
+
+[deployment.fly-io-spot-test]
+app-name = "rgtv-nesy"
+purpose = "Internal flycast spot-testing via nesy-solver-api only. NOT production."
+deploy = "NESY_INGEST_TOKEN=<tok> ./deploy-fly.sh rgtv"
+token-persistence = "~/.config/nesy-solver/rgtv-agent-token"
+url = "http://rgtv-nesy.flycast:9100 (private 6PN; not .internal)"
+
+[deployment.local-dev]
+start = "just broker-dev  (requires RGTV_AGENT_TOKEN + RGTV_CRED_<HINT>=<value>)"
+daemon-start = "just broker-start"
+daemon-stop = "just broker-stop"
+daemon-status = "just broker-status"
+logs = "just broker-logs"
+
+# ── CLI (rgtv) ────────────────────────────────────────────────────────────────
+
+[cli]
+binary = "rgtv"
+build = "just build-cli"
+commands = [
+  "rgtv get <hint> --env VAR --exec 'cmd'  — grant→redeem→exec with credential injected",
+  "rgtv list                               — list registered hint names",
+  "rgtv status                             — /health probe",
+  "rgtv verify                             — functional round-trip smoke test",
+  "rgtv daemon start|stop|status           — manage vault-broker daemon",
+]
+pid-file = "~/.local/state/rgtv/vault-broker.pid"
+log-file = "~/.local/state/rgtv/vault-broker.log"
+
+# ── Incident response ─────────────────────────────────────────────────────────
 
 [incident-response]
-# 1. Check .machine_readable/STATE.a2ml for current status
-# 2. Review recent commits and CI results
-# 3. Run `just validate` to check compliance
-# 4. Run `just security` to audit for vulnerabilities
+steps = [
+  "1. rgtv status  — check broker reachable",
+  "2. rgtv verify  — functional round-trip (grant→redeem)",
+  "3. Check STATE.a2ml for known blockers",
+  "4. Check recent commits and CI results",
+  "5. For CF Workers: just worker-logs",
+  "6. For Fly.io: fly logs -a rgtv-nesy",
+]
 
-[release-process]
-# 1. Update version in STATE.a2ml, META.a2ml
-# 2. Run `just release-preflight` (validate + quality + security + maint-hard-pass)
-# 3. Tag and push
+grant-expired = "Redeem returns 410 — grant was valid but expired (30s TTL default). Request a new grant."
+grant-not-found = "Redeem returns 404 — grant already redeemed or never existed. One-use guarantee enforced by DO."
+unauthorized = "401 — check RGTV_AGENT_TOKEN matches worker secret."
 
-[maintenance-operations]
-# Baseline audit: just maint-audit
-# Hard release gate: just maint-hard-pass
+# ── Release process ───────────────────────────────────────────────────────────
+
+[release-process]
+steps = [
+  "1. Update version in STATE.a2ml, META.a2ml, Cargo.toml files",
+  "2. Run: just check  (clippy + fmt for broker + cli)",
+  "3. Run: just build-worker  (WASM compile)",
+  "4. Run: just worker-deploy",
+  "5. Tag and push",
+]

.machine_readable/6a2/STATE.a2ml

@@ -6,7 +6,7 @@
 [metadata]
 project = "reasonably-good-token-vault"
 version = "0.2.0"
-last-updated = "2026-04-12 (session 2)"
+last-updated = "2026-04-12 (session 4)"
 status = "active"
 
 [project-context]
@@ -15,7 +15,7 @@ purpose = """Zero-trust LLM credential broker. Issues opaque one-use grants to
 authenticated agents; agents redeem grants for raw credential values. Raw values
 never appear in agent context, prompts, or logs. Monorepo containing vault-core
 (crypto library), vault-broker (axum HTTP server), ada-cli, and FFI bindings."""
-completion-percentage = 62
+completion-percentage = 68
 
 [position]
 phase = "implementation"
@@ -33,7 +33,7 @@ milestones = [
   { name = "vault-broker GET /v1/credentials endpoint (list hints, no values)", completion = 100 },
   { name = "rgtv CLI wired to vault-broker HTTP API (get/list/status/verify/daemon)", completion = 100 },
   { name = "rgtv daemon start/stop/status (PID-file-managed vault-broker process)", completion = 100 },
-  { name = "vault-worker: Cloudflare Workers production target (Rust/WASM, workers-rs 0.8)", completion = 85 },
+  { name = "vault-worker: Cloudflare Workers production target (Rust/WASM, workers-rs 0.8)", completion = 100 },
   { name = "Honeypot endpoint (canary for credential sniffing)", completion = 20 },
   { name = "RGTV Idris2 ABI formal proofs (grant lifecycle invariants)", completion = 0 },
   { name = "Zig FFI layer (C-compatible vault_grant / vault_redeem)", completion = 0 },
@@ -45,7 +45,7 @@ milestones = [
 
 [blockers-and-issues]
 issues = [
-  "vault-worker: KV grant store is not atomic (no read+delete CAS in CF KV) — production needs Durable Objects",
+  # RESOLVED 2026-04-12: vault-worker grant store migrated from KV to Durable Objects (atomic one-use enforced by DO single-thread runtime)
   "vault-worker: wrangler.toml has placeholder KV namespace IDs — must run wrangler kv:namespace create before deploy",
   "vault-worker: credential values stored plaintext in KV — TODO: encrypt with RGTV_MASTER_KEY Worker Secret",
   "vault-broker (Fly.io) not yet deployed to production — only spot-test role, CF Workers is production target",
@@ -58,7 +58,7 @@ issues = [
 [critical-next-actions]
 actions = [
   "vault-worker production deploy: wrangler kv:namespace create CREDENTIALS + GRANTS → update wrangler.toml IDs → wrangler secret put RGTV_AGENT_TOKEN → populate credentials → just worker-deploy",
-  "Migrate vault-worker grant store from KV to Durable Objects for atomic one-use guarantee",
+  # DONE 2026-04-12: vault-worker grant store migrated to Durable Objects
   "Add RGTV_MASTER_KEY Worker Secret + AES-256-GCM encryption of CREDENTIALS KV values",
   "Run: NESY_INGEST_TOKEN=<tok> ./deploy-fly.sh rgtv (Fly.io spot-test only)",
   "Migrate Containerfile from debian:bookworm-slim to cgr.dev/chainguard/rust:latest (builder) + cgr.dev/chainguard/static:latest (runtime)",
@@ -68,6 +68,8 @@ actions = [
 
 [completed-work]
 entries = [
+  { date = "2026-04-12 (s4)", description = "Close-out: ECOSYSTEM.a2ml updated (CF Workers as production, Fly.io as test-only, V-lang ref removed). META.a2ml updated (5 ADRs recorded). PLAYBOOK.a2ml updated (full CF+Fly+CLI+incident runbook). NEUROSYM.a2ml fixed (Logtalk→JSON). Contractiles rewritten (SPDX typo fixed, RGTV-specific checks). EXPLAINME.adoc replaced template stub with real architecture doc. .gitignore updated (per-crate target dirs, vault-worker/build/, .wrangler/). Justfile: GRANTS DO comment corrected. vault-worker completion 85→100." },
+  { date = "2026-04-12 (s3)", description = "vault-worker DO migration: replaced GRANTS KV namespace with Durable Objects. One GrantObject DO instance per outstanding grant. Atomic one-use enforced by DO single-threaded runtime. Removed GRANTS KV binding from wrangler.toml. Added migrations block for GrantObject. do_put_request/do_post_request helpers. handle_create_grant stores via DO PUT. handle_redeem_grant dispatches via DO POST (atomic read+delete)." },
   { date = "2026-04-12 (s2)", description = "vault-worker: Cloudflare Workers production target (Rust/WASM, workers-rs 0.8). Same HTTP API as vault-broker. CREDENTIALS KV (hint→value, operator-managed). GRANTS KV (grant_id→hint, 30s TTL). Justfile: worker-dev, worker-deploy, worker-logs, worker-creds-list, worker-cred-put. KV double-spend caveat documented; Durable Objects migration on roadmap." },
   { date = "2026-04-12", description = "vault-broker: added GET /v1/credentials endpoint returning sorted hint names with no credential values. Fixed two pre-existing bugs: Zeroizing<String> clone in redeem handler, .json() tracing_subscriber call removed (feature not enabled)." },
   { date = "2026-04-12", description = "rgtv CLI (svalinn-cli crate renamed): full rewrite wired to vault-broker HTTP API. Commands: get (grant→redeem→exec with Zeroizing value), list (/v1/credentials), status (/health), verify (functional round-trip), daemon start/stop/status (PID-file managed). Binary renamed from svalinn_cli to rgtv. Added ureq+zeroize deps." },