Frank
8af40c402b
Landing blocker for #61 and #63: the deployment checkout is 12 commits behind and `merge --ff-only` refuses while tracked paths are dirty. Discard is not available here (workspace policy: no `checkout`/`stash` on shared state), so the dirt is committed. - `agent/APPEND_SYSTEM.md`: the point-of-use / one-work-log / PR-link doctrine, already byte-identical to `origin/main` (`cmp` against the trunk blob: no difference). No new prose — the commit exists so the trunk merge can proceed. - `agent/config.yml` and `agent/managed-skills/**`: the machine-live tier the heartbeat owns (AGENTS.md § Live-sync tiers). `ALLOW_SECRETS=1` was used, deliberately and after auditing the staged diff by hand: the only credential-shaped strings in it are two copies of `AKIA0000000000000EXAMPLE` — the inert all-zero AWS example id — and they appear inside the two skill pages that teach that exact placeholder shape. This checkout is still running the pre-#61 hook; the merged gate (value-scoped placeholder filter, `71601f7`) exempts this value, so the refusal dies with this landing. No `--no-verify` was used: the gate ran and its verdict is recorded here. Refs #61
53 lines
3.7 KiB
Markdown
53 lines
3.7 KiB
Markdown
---
|
|
name: radiance-flag-truth-from-pinned-source
|
|
description: "Before writing a radiance flag, value, or metric name into a runbook, prove it against the pinned image's source and the engine's own boot ledger — catches invented option names and stale defaults."
|
|
---
|
|
|
|
# Radiance flag truth from the pinned source
|
|
|
|
Use when a radiance (`codeberg.org/StillDeadcode/radiance`) flag, its admitted values, a resolved
|
|
default, or a `/metrics` name is about to go into a vault page, env comment, or arm proposal — or when
|
|
a claim about one is being repeated from memory. Docs and old vault pages go stale; the pinned tree and
|
|
the boot ledger do not.
|
|
|
|
## Procedure
|
|
|
|
1. **Get the tree at the running version, not at master.** Read the pin:
|
|
`grep -E 'FRANK_ARCHON_IMAGE' scripts/frank-archon.env` (digest), then
|
|
`ssh dank@192.168.0.235 'podman images --no-trunc | grep radiance'`.
|
|
`git clone --branch <ver>` (or checkout the tag) into `/tmp/rad-<ver>`. A `--depth 1` clone makes
|
|
every `git log -S` report its own tip — never date a flag's introduction from a shallow clone.
|
|
2. **Flag table is the admitted set.** `core/config.cpp` holds the help strings (each option's legal
|
|
names/units live in the value column) and the validator branch refuses anything else at boot, e.g.
|
|
`--checkpoint-policy` → `geometric-backoff | tip-only | keep-all`. `core/rad_core.h` carries the
|
|
struct with the compiled-in defaults. `tests/config_test.cpp` asserts the admitted set — it is the
|
|
fastest oracle for "is `lru` a policy?".
|
|
3. **Live argv beats the repo env.** `sudo tr '\0' '\n' < /proc/$(pidof radiance)/cmdline` — proves the
|
|
knob actually reached the engine (an env var typo is invisible from the repo).
|
|
4. **Boot ledger is the referee for every resolved number.** The engine prints its own arithmetic:
|
|
`ssh dank@192.168.0.235 'podman logs frank-archon 2>&1 | grep -iE "checkpoint|chunk geometry|pools|arena|stager"'`
|
|
(root unit, but podman storage is dank's — **no sudo**, sudo reads empty root storage). Lines like
|
|
*"checkpoint slots: auto: 20 … geometric-backoff keeps 9 for a 200000-token session at a 2048-token
|
|
interval"* are exact; quote them.
|
|
5. **Reproduce the engine's arithmetic to check you understood it.** Reimplement the policy/geometry
|
|
function in a throwaway Python eval (`select()` / `held()` in `core/mem/prefix.cpp`, `plan_chunk` in
|
|
`core/sched/scheduler.cpp`) and confirm the numbers match the ledger line from step 4. Agreement
|
|
means the rule is understood; disagreement means the read is wrong. Delete the scratch after.
|
|
6. **Metric names: query the live target, not the guide.** Latency histograms and preemption live under
|
|
the **`vllm:`** compatibility prefix, cadence under **`radiance:`**; preemption is the counter
|
|
`vllm:num_preemptions_total` while `radiance:num_requests_preempted` is an instant gauge. Enumerate
|
|
with `curl -s localhost:7770/metrics | grep '^# HELP'` on Dankserver, or
|
|
Prometheus `/api/v1/label/__name__/values?match[]={job="frank-archon"}`.
|
|
|
|
## Traps that produced real errors here
|
|
|
|
- A policy name invented from prose (`--checkpoint-policy floor`) would be a boot refusal; a stale
|
|
resolved default (`auto` = 512) had been copied between pages. Both survived only in the vault.
|
|
- `--checkpoint-policy` governs **retention only**; snapshots are written at every interval regardless
|
|
(only `--prefill-span` skips writes). Read the call site (`retain()` in `core/mem/prefix.cpp`), not
|
|
the flag help.
|
|
- Guide/`GUIDE.md` inside an image can be newer or older than the binary; `/diagnostics`
|
|
`configuration` and the ledger print the running truth.
|
|
- Facts belong to the vault page that owns the endpoint (`serverAppConfigs-docs/LLM/frank-archon.md`) —
|
|
this skill owns the *procedure*, not the numbers.
|