λgitsite

docs: consolidate security documentation map

Jaime Fournier <jaimef@linbsd.org>

408eb7524eef20fdfd6255cc623af49ad61b2cac

diff --git a/docs/ai-threat.md b/docs/ai-threat.md
index a821afb..686879e 100644
--- a/docs/ai-threat.md
+++ b/docs/ai-threat.md
@@ -27,15 +27,18 @@ offset errors in.
 has zero FFI surface. The risk is concentrated in Jerboa's own implementation,
 not in user code.
 
-### Contract Validators Are String-Based Heuristics
+### SQL Validators Are Defense-In-Depth
 
 The SQL injection detection in `(std safe)` uses pattern matching —
 multi-statement detection, comment injection heuristics. An AI adversary will
 generate bypass payloads faster than a human. Heuristic-based injection
 detection has a long history of being beaten by sufficiently creative encoding.
 
-**Mitigation**: Parameterized queries remain the real defense. The heuristic
-is a speed bump, not a wall. Document this honestly to users.
+**Mitigation**: `(jerboa prelude safe)` exposes SQLite query/execute names as
+literal-SQL, parameterized syntax. String-built SQL does not compile on the
+safe-prelude surface, and the `sql-interpolation` lint rule reports string
+construction as an error. The runtime heuristic remains as defense-in-depth for
+lower-level wrappers.
 
 ### The Type System Won't Help Much
 
@@ -213,7 +216,7 @@ patterns. If the pattern doesn't exist, there's nothing to find.
 | Unsafe Scheme execution after raw fork | High | Fixed: `run-safe` fails closed; use an exec worker |
 | No memory limit in `run-safe-eval` | Medium | By design: use OS limits on an exec worker |
 | Import conflict in safe prelude | Low | Fixed: deterministic safe-symbol resolution is regression-tested |
-| SQL injection heuristic bypasses | Medium | By design (use parameterized queries) |
+| SQL injection heuristic bypasses | Medium | Mitigated on `(jerboa prelude safe)`: SQL calls require literal strings plus parameters; heuristic remains defense-in-depth below that surface |
 | Seccomp/Landlock x86_64-only | Low | By design (arch-specific syscalls) |
 | Silent degradation of requested process controls | Medium | Fixed: reject unless `allow-degraded? #t` is explicit |
 | Raw `read` / native FASL call sites need provenance triage | Medium | Open; tracked in the K3 security handoff |
@@ -229,8 +232,9 @@ patterns. If the pattern doesn't exist, there's nothing to find.
    provides an allowlist and an interruptible Scheme timeout in the current
    process. Send adversarial work to a bounded, separately exec'd worker.
 
-3. **Use parameterized queries.** Don't rely on the SQL injection heuristic.
-   It's a safety net, not a wall.
+3. **Use the safe-prelude SQLite surface.** It requires literal SQL plus
+   parameters. Don't rely on the lower-level SQL injection heuristic; it's a
+   safety net, not a wall.
 
 4. **Set `*type-errors-fatal*` to `#t` in strict environments.** Catch type
    mismatches early instead of at runtime.
diff --git a/docs/index.md b/docs/index.md
index 5f7934f..6345afe 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -10,6 +10,19 @@ use the `jerboa` CLI: run programs with `jerboa run file.ss`, open the REPL with
 Start with [quickstart.md](quickstart.md), then use
 [JERBOA-LANG.md](JERBOA-LANG.md) as the language reference.
 
+## How To Use This Map
+
+This page is the canonical documentation table of contents for the language
+repository. Stable user-facing language and library docs live at the top level
+of `docs/`. Security implementation claims live in
+[security-reference.md](security-reference.md), while dated audits, threat
+reviews, and handoff notes live under `docs/reviews/` or in the explicit
+backlog [kimi3-security-recommmendations.md](kimi3-security-recommmendations.md).
+
+When a topic has both a reference and a review note, prefer the reference for
+current behavior and use the review note only for historical context or open
+work.
+
 ## Getting Started
 
 - [quickstart.md](quickstart.md) - install, run a file, use the REPL, run tests
diff --git a/docs/kimi3-security-recommmendations.md b/docs/kimi3-security-recommmendations.md
index a82abc6..7c32aff 100644
--- a/docs/kimi3-security-recommmendations.md
+++ b/docs/kimi3-security-recommmendations.md
@@ -882,15 +882,17 @@ fix must add its scanner rule in the same commit (write it into
 ### K3-P2-06 — Documentation consistency pass
 **Serves:** G5. **Effort:** 2 days.
 
-- **Status:** partially complete. `docs/security-reference.md` is the canonical
-  implemented-security reference; this file is only the roadmap/handoff; review
-  snapshots live under `docs/reviews/`; `docs/index.md` and `SECURITY.md` point
-  readers to that hierarchy.
-- Refresh `ai-threat.md`'s comparative table (supply chain now:
-  TUF + signatures + transparency + OSV; update the "Behind" cells and the
-  "Known Vulnerabilities" table statuses).
-- Document `(std security cage)`, `(std security secret)`,
-  `(std security env)` in `security-reference.md`.
+- **Status:** complete for the current language-repo documentation hierarchy.
+  `docs/index.md` now states that stable language/library references live at
+  top-level `docs/`, implemented security claims live in
+  `docs/security-reference.md`, dated audits/reviews live under
+  `docs/reviews/`, and this file is only the roadmap/handoff. `SECURITY.md`
+  points to the same hierarchy.
+- `ai-threat.md`'s comparative table already reflects TUF, signatures,
+  transparency, SBOM, OSV, and content-addressed artifacts; its SQL status now
+  reflects the literal-SQL, parameterized safe-prelude surface.
+- `(std security cage)`, `(std security secret)`, and `(std security env)` are
+  documented in `security-reference.md`'s security module inventory.
 - Add this file to `docs/index.md` (done at creation) and cross-link from
   `SECURITY.md`.
 - Move the appended "Security Patterns & Threat-Model Checklist" findings