From eb4f6019f0631b9eaf82cf98641365d1a9509819 Mon Sep 17 00:00:00 2001 From: zzstoatzz Date: Thu, 30 Jul 2026 05:49:33 -0500 Subject: [PATCH] docs: config audit predates comptime-derived names, and is behind the artifact configuration-parity.md is in good shape -- no dead paths, it correctly marks its upstream Go sources as upstream, its eb95c14 basis resolves, and it does not repeat the false "flags declared in src/main.zig" claim that configuration.md carried. Two additions rather than corrections. The audit predates ac09654, which made flag and environment names comptime-derived from the options struct. That changes what the 47 rows are for: a --flag / JETSTREAM_* mismatch is now a comptime impossibility, not something an audit can find. Says so, and names what still does need auditing -- defaults, parse and validation rules, precedence, and whether the parsed value reaches the mechanism the row names. Also notes the basis is behind the deployed artifact (eb95c14 vs the 29705cb that ran experiment 6), consistent with the note added to semantic-parity.md. Co-Authored-By: Claude Opus 5 (1M context) --- docs/configuration-parity.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/configuration-parity.md b/docs/configuration-parity.md index b61f8bb..ce4a6f5 100644 --- a/docs/configuration-parity.md +++ b/docs/configuration-parity.md @@ -5,7 +5,20 @@ Authority: - upstream `cmd/jetstream/main.go` and `internal/jetstreamd/options.go` at `f29815c391fc2644f8a3dd36b899fb3697dd1ea6` - Stream `eb95c14310ef18c7ab9edbcff991a04a560a7d86` - (admitted artifact `sha256:43001041...`, `receipts/eb95c14.json`) + (admitted artifact `sha256:43001041...`, `receipts/eb95c14.json`) — this hash + resolves, but note experiment 6 deployed `29705cb` + (`receipts/29705cb.json`), so the basis is behind the artifact that ran. Same + gap recorded in `semantic-parity.md`. + +**Flag and environment names are derived, so they are not what needs auditing.** +Since `ac09654`, a field on the options struct in `runtime/cli.zig` generates +both spellings at comptime — `backfill_workers` becomes `--backfill-workers` and +`JETSTREAM_BACKFILL_WORKERS` via `flagName` / `envName`. A canonical name +therefore cannot silently drift from its environment variable, and a +`--flag`/`JETSTREAM_*` mismatch is a comptime impossibility rather than an audit +finding. What still needs a row is the part derivation cannot supply: the +default value, the parse and validation rules, precedence, and whether the +parsed value actually reaches the runtime mechanism named in the row. This document audits public configuration and command wiring. A **verified** configuration row proves only that the input is parsed/defaulted and reaches -- 2.51.2