@sleepy_panda_srl/portulan 0.1.3 → 0.2.0

package/cli/telemetry.mjs

@@ -1,120 +1,10 @@
 #!/usr/bin/env node
-// The OTel emitter — milestone 8's *OTel opt-in config*, and the first thing in this repository that
-// can send anything anywhere on purpose.
+// The OTel emitter: the review-loop figures as OTLP/HTTP JSON, sent only when a committed config opts in.
 //
-// The argument for the clause is in `../docs/milestones/m08.md`; what belongs here is what the
-// opt-in IS, why it is not the standard environment surface, and — at more length than is
-// comfortable — what a silent run means, because for an emitter whose correct default state is
-// silence, *did nothing* and *is broken* look identical from outside.
+//   node cli/telemetry.mjs --config <file> [--repo-root <dir>] [--render | --check <file> | --write <file> | --export]
+//   node cli/telemetry.mjs --audit-recipes [--workspace <dir>] [--repo-root <dir>] [--pack-root <dir>]...
 //
-// ## The reading was ruled, not derived
-//
-// *"OTel opt-in config"* reads at least three ways, and `../.portulan/gate-map.md`'s
-// *"Session-open runs `clarify` against the milestone row itself"* exists because milestone 4 guessed
-// at exactly this shape of ambiguity and cost a session-blocking question. Put to the maintainer on
-// 2026-08-28 as three readings: **(i)** a validated config surface emitting nothing; **(ii)** that
-// surface plus a real emitter — hand-written OTLP-over-HTTP JSON, no OpenTelemetry SDK — off by
-// default and never callable from a verify recipe; **(iii)** an OTLP-shaped local file sink with no
-// network path at all. **He ruled (ii).**
-//
-// Reading (i) is what this file would be if the emitter were deferred, and it fails
-// `../.portulan/dod.md` condition 4 in a way the *names the milestone where it arrives* escape does
-// not cover: under the row's `1 per clause` budget the clause would be spent with the emitter owned
-// by no session — the *rule with no owner* shape the 2026-08-24 amendment exists to end, one
-// altitude up from a rule with no checker.
-//
-// ## Why the opt-in is a committed file and NOT `OTEL_SDK_DISABLED`
-//
-// This is the one place this tool deliberately departs from the OpenTelemetry environment contract,
-// and it is stated out loud rather than left for a reader to discover from the code.
-//
-// **`OTEL_SDK_DISABLED` defaults to `false`.** Honouring the standard env surface as the gate would
-// mean an adopter who already exports `OTEL_EXPORTER_OTLP_ENDPOINT` in CI — for some other
-// service — starts emitting from Portulan without having decided to. That is an opt-**out**, and the
-// criterion's word is *opt-in*. It would also put a team decision in ambient per-machine state,
-// which is the inverse of the cascade's `core < pack < workspace`: the workspace is where a team's
-// policy lives.
-//
-// So: **the committed config file is the only gate**, and the environment supplies transport only —
-// the OTLP endpoint and header variables, in both their general and their metrics-specific forms, so
-// an adopter's existing collector configuration works unchanged. A secret never enters the committed
-// file; that is `../.portulan/dod.md` condition 5 holding by construction rather than by a reviewer
-// noticing.
-//
-// **What of that contract is implemented, stated at its real width rather than as *"exactly as the
-// specification defines them"*, which is what this paragraph used to say and was false.** Read:
-// `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` (used as given) falling back to `OTEL_EXPORTER_OTLP_ENDPOINT`
-// (a base, with `/v1/metrics` appended), and `OTEL_EXPORTER_OTLP_METRICS_HEADERS` **replacing**
-// `OTEL_EXPORTER_OTLP_HEADERS` rather than merging with it. **Not** read, and each would be a silent
-// no-op for an adopter who set it: `OTEL_EXPORTER_OTLP_PROTOCOL` — this emitter speaks
-// `http/json` and nothing else — `_TIMEOUT`, `_COMPRESSION`, `_CERTIFICATE` and the client-auth pair.
-// Naming them is the point: a partial implementation of a standard contract is fine, and a partial
-// implementation described as a complete one is the overclaim `../.portulan/principles.md` opens with.
-//
-// _An earlier draft of this clause put the config in the Workspace Definition as a `telemetry` slot
-// at spec 2.9. The session-open checkpoint cut it: every slot in that train arrived through a **ruled
-// proposal** (`../spec/README.md`'s 2.8 argument cites proposal `0025`; `governed_by` cites `0017`;
-// `provenance` cites `0002`), and `../.portulan/gate-map.md` makes an idea that adds a surface a
-// proposal rather than an implementation pull request. `../spec/slots.md`'s own `evals` deferral says
-// a schema change plus a spec bump plus a migration **"is not a thing to do in passing"** and defers
-// to *when milestone 8 closes* — and the slot would have shipped with zero filled instances, since
-// this workspace declares telemetry off and `../examples/` stays at 2.4. The slot is filed to ride
-// with `evals` at the close, which makes it one bump instead of two. **Milestone 8 closed 2026-09-09,
-// so that deferral is now DUE and undrafted** — proposal `0034` commissions it and settles none of the
-// shape; the close named it rather than drafting a schema inside itself._
-//
-// ## Consent — ruled 2026-08-28, and it is a reading of a tier rather than a new one
-//
-// `../.portulan/gates.json` makes *sending anything outward on the team's behalf* Gated, and
-// `../core/operating/autonomy.md` says Gated is **per action**. Proposal `0014` reserves telemetry as
-// *"a separate mechanism with separate consent"* — named there, never ruled, until now.
-//
-// **The maintainer's ruling: the opt-in config IS the standing consent.** A committed config with
-// `enabled: true` is the team's decision, and each subsequent export rides on it without a fresh
-// per-send approval — the way a compiled gate carries a tier without asking again. What stays his
-// alone is **enabling it in this workspace**, which is why the committed config here says `false` and
-// why no endpoint is committed anywhere in this tree.
-//
-// What makes that safe rather than merely decided is the payload, and the payload is closed by
-// construction: it is assembled from an explicit allow-list of aggregate figures, and there is no
-// path from a snapshot's free-text or path-shaped fields into a request body. See `PRODUCERS` below,
-// where the allow-list is the code rather than a promise about it.
-//
-// ## What a silent run means — the trap this file is most likely to ship
-//
-// `./review-meter.mjs` shipped a broken entry guard and `--fetch` **printed nothing, exited 0, and
-// wrote no snapshot** — the fourth time this repository has met that shape. For every other tool
-// here that is a bad day. For an emitter it is worse: **the correct behaviour of an opted-out
-// emitter is also to send nothing**, so a tool that never started and a tool working exactly as
-// designed produce the same observable. There is no way to tell them apart from outside.
-//
-// Two consequences, both load-bearing:
-//
-//   * The entry guard is the ONE form `./rule-carriers.mjs` designates, copied rather than
-//     re-derived, and the suite pins it under a path containing a space.
-//   * **Every refusal prints a sentence and returns non-zero.** Silence is never this tool's answer
-//     to anything. A caller may read exit 0 as *the payload went where it was asked to go* and
-//     nothing else.
-//
-// And the two non-export states are kept apart, because collapsing them is its own seam defect: a
-// config file with a typo that its author meant to be `true` must not report *opted out*.
-//
-//   0  the thing asked for happened
-//   1  a verdict: the golden has drifted, or `--export` was asked of a workspace that is opted out
-//   2  could not run: the config or the snapshot is missing, unreadable, or malformed
-//
-// _`../.portulan/memory/verify-preconditions-fail-closed.md` is deliberately NOT cited for the
-// opted-out arm. That record is scoped to verify recipes and its subject is an enumeration that came
-// back empty; `--export` against a workspace legitimately off is not a failed precondition — the tool
-// looked, and the answer was no. The checkpoint caught this file citing it and it is a
-// misapplication, so it is named here as one._
-//
-// ## Deliberately not a ninth `portulan` subcommand
-//
-// `../docs/vision.md` names eight and is human-owned; `../.portulan/identity.md` says a ninth is the
-// maintainer's call. The precedent is `./eval-bundle.mjs`, `./drills.mjs`, `./review-meter.mjs` and
-// `./skill-goldens.mjs`, each of which carries this same sentence. Run it as
-// `node cli/telemetry.mjs …`.
+// Exit 0 done · 1 a verdict (golden drift, export while opted out, a recipe reaching the network) · 2 could not run.
 
 import fs from "node:fs";
 import path from "node:path";
@@ -127,86 +17,27 @@ import { recipeSet, resolverFor } from "./recipe-set.mjs";
 import { isInside } from "./inside.mjs";
 
 // ---------------------------------------------------------------------------------------------
-// The offline audit — no verify recipe may reach the network, and now something checks
+// The offline audit: no verify recipe may reach the network
 // ---------------------------------------------------------------------------------------------
 
-/**
- * The network-capable modes in `cli/`, and the flag that turns each one on.
- *
- * **The subject is the MODE, not the module.** `../.portulan/verify/review-loop.sh` legitimately runs
- * `./review-meter.mjs` — in its snapshot-reading mode, which touches nothing. What a recipe may never
- * do is reach the mode that opens a socket. A rail that banned the module would forbid an existing
- * green recipe; a rail that bans the flag forbids the thing actually prohibited.
- *
- * **It rails the CLASS rather than this session's own module**, which is the whole reason it is a
- * table. Adding `./telemetry.mjs` and railing only it would have left `--fetch` unrailed — one rule
- * enforced at the newer of its two sites, which is the defect
- * `../.portulan/proposals/0020-a-fix-is-not-done-at-the-site-it-was-found.md` names and the one this
- * repository repeats most. A new network mode adds a row here or it is uncovered, and nothing can
- * audit that a row was added — the arrears are named rather than pretended away, as
- * `../.portulan/rule-carriers.json` does for its own registry.
- */
+/** Every mode in cli/ that can reach the network; a new one is unrailed until it has a row here. */
 export const NETWORK_MODES = Object.freeze([
     { module: "cli/review-meter.mjs", flag: "--fetch", what: "fetches review data from GitHub" },
     { module: "cli/telemetry.mjs", flag: "--export", what: "posts an OTLP payload to a collector" },
-    // **Added at round 10, and its absence is the defect this table's own docblock warns about,
-    // committed at the table's birth.** `./feedback.mjs` files a GitHub issue through
-    // `gh issue create`, gated on `--approve` exactly as this module's export is gated on a committed
-    // config. It was network-capable before either of the rows above existed, and enumerating two of
-    // three while claiming to rail *the class* is the census-over-its-own-set shape milestone 8's own
-    // session 4 named: a set drawn by its author, reported as complete.
     { module: "cli/feedback.mjs", flag: "--approve", what: "files a GitHub issue with `gh issue create`" },
 ]);
 
-/**
- * Strip shell comments so a recipe may **explain** a network mode without being accused of running
- * one. `../.portulan/verify/review-loop.sh` says *"Refreshing is `node cli/review-meter.mjs --fetch`,
- * run by a person"* in a comment, and a matcher that could not tell prose from a command would red on
- * the sentence documenting the very rule it enforces — the failure shape
- * `./version-carriers.mjs` records for its own record-layer exclusion.
- *
- * Whole-line comments only. A trailing `#` cannot be stripped without knowing whether it is inside a
- * quote, and a half-right stripper fails OPEN — it would delete a real command that happened to carry
- * a `#`. Named as a limit rather than approximated.
- */
+/** Whole-line comments only: a trailing `#` may sit inside a quote. */
 export const stripShellComments = (source) =>
     source
         .split("\n")
         .filter((line) => !/^\s*#/.test(line))
         .join("\n");
 
-/**
- * Does this recipe's script reach a network mode?
- *
- * Deliberately whole-body rather than same-line: a recipe invokes a tool across several continued
- * lines (`review-loop.sh` spreads one command over four), so a same-line rule would miss exactly the
- * spelling a real invocation uses.
- */
-/**
- * Split a shell body into the tokens a command is actually made of, stripping the quoting and
- * bracketing a path picks up in a script.
- */
 const shellTokens = (body) => body.split(/\s+/).map((t) => t.replace(/^[("'`]+/, "").replace(/[)"'`;]+$/, "")).filter(Boolean);
 
-/**
- * Does this token name that module, however it is spelled?
- *
- * **A matcher that knew one spelling was a bypass, not a rail.** The first version compared the body
- * against the literal `cli/telemetry.mjs`, so `node ./cli/telemetry.mjs --export` — the same file, the
- * same effect, one prefix different — walked straight past an enforcement check. That is precisely the
- * class milestone 8's clauses (a) and (b) exist for: a matcher's coverage is measured, never described,
- * and seven of the eight bypasses that produced those clauses were path and grammar spellings.
- * Copilot round 3 on #362, and https://github.com/sleepy-panda-srl/portulan/issues/337 already names
- * `./` as a spelling that matches nothing at runtime.
- *
- * So the test is a **suffix** on a path-separator boundary: `cli/telemetry.mjs`, `./cli/telemetry.mjs`
- * and `/abs/where/ever/cli/telemetry.mjs` all name it. The cost is stated rather than hidden — some
- * *other* tree's `vendor/cli/telemetry.mjs` would match too, which is a **false red**, the safe
- * direction, and a recipe reaching into another tree is worth a human looking either way.
- */
 const tokenNamesModule = (token, module) => token === module || token.endsWith(`/${module}`);
 
-/** A flag token, in the two spellings a shell writes it: bare, or `--flag=value`. */
 const tokenIsFlag = (token, flag) => token === flag || token.startsWith(`${flag}=`);
 
 export function auditRecipeSource(source) {
@@ -214,44 +45,11 @@ export function auditRecipeSource(source) {
     return NETWORK_MODES.filter((m) => tokens.some((t) => tokenNamesModule(t, m.module)) && tokens.some((t) => tokenIsFlag(t, m.flag)));
 }
 
-/**
- * Sweep the recipe set the workspace **yields**, at a pinned root.
- *
- * Three properties, each from a defect this repository has already paid for:
- *
- *   * **It reads the yielded set, not the directory.** `../.portulan/dod.md` condition 1 is about what
- *     the manifest yields, which since milestone 7's composition amendment includes a composed pack's
- *     recipes — `tools/github:actions-pinned` lives under `packs/`. A directory sweep of
- *     `.portulan/verify/` would exempt precisely the recipes hardest to see.
- *   * **An empty or unobtainable set is could-not-run, never green.** *No recipe reaches the network*
- *     is satisfied vacuously by no recipes, and a rail whose green can be produced by an enumeration
- *     coming back empty is the fail-open
- *     `../.portulan/memory/verify-preconditions-fail-closed.md` was written about — and the vacuity
- *     `./skill-goldens.mjs` refuses one clause over.
- *   * **The root is pinned**, so the answer is about this tree rather than about the machine.
- */
 export function auditRecipes({ workspaceDir, repoRoot, packRoots = [] }) {
-    // **The workspace directory is pinned by `--repo-root` like every other path here.** It was
-    // resolved against the CURRENT WORKING DIRECTORY, so a run from outside the tree that named
-    // `--repo-root` correctly would still look for the manifest beside wherever the caller happened to
-    // stand — the same root/cwd split https://github.com/sleepy-panda-srl/portulan/issues/347 names for
-    // `--pack-root`, arriving in a new tool. `path.resolve` leaves an absolute `--workspace` alone, so
-    // naming one explicitly still wins. Copilot round 1 on #362.
     const workspace = path.resolve(repoRoot, workspaceDir);
-    // **And it must be INSIDE the pinned root.** Resolving against `repoRoot` does not keep it there:
-    // `--workspace ../../elsewhere`, or an absolute path anywhere, would have this audit grade a
-    // manifest that is not part of the tree it claims to be answering about. Round 3 closed exactly
-    // this for a recipe's *script* and left the *manifest* open — the same fix owed at two sites and
-    // taken at one, which is now the fourth instance of that shape in this file. Copilot round 10.
     if (!isInside(path.resolve(repoRoot), workspace)) {
         return { ok: false, why: `the workspace at ${workspace} resolves outside the repository at ${repoRoot}; this audit grades the pinned tree and will not read past it` };
     }
-    // **And the pack roots, which the first repair of this defect left behind.** Round 1 pinned
-    // `workspaceDir` against `repoRoot` and passed `packRoots` through untouched, so a run from outside
-    // the tree still resolved them against the caller's cwd — and the yielded recipe SET, hence this
-    // audit's whole answer, moved with where the tool was invoked from. That is `0020`'s class exactly:
-    // a fix applied at the site it was found and not at its sibling, inside the change that made it.
-    // Copilot round 6 on #362.
     const roots = packRoots.map((r) => path.resolve(repoRoot, r));
     let manifest;
     try {
@@ -274,8 +72,6 @@ export function auditRecipes({ workspaceDir, repoRoot, packRoots = [] }) {
     const findings = [];
     const read = [];
     for (const r of recipes) {
-        // The script is the `.sh` token in the run line — `./.portulan/verify/docs.sh` for a
-        // workspace recipe, `bash packs/.../actions-pinned.sh` for a composed one.
         const script = String(r.run ?? "")
             .split(/\s+/)
             .find((t) => t.endsWith(".sh"));
@@ -283,12 +79,6 @@ export function auditRecipes({ workspaceDir, repoRoot, packRoots = [] }) {
             return { ok: false, why: `recipe ${JSON.stringify(r.id)} has no readable script in its run line (${JSON.stringify(r.run ?? null)}); this audit cannot grade what it cannot read` };
         }
         const file = path.resolve(repoRoot, script);
-        // **A script outside the tree is could-not-run, never a pass.** `path.resolve` happily follows
-        // `bash ../../somewhere/outside.sh` or an absolute path out of the repository, and this audit
-        // would then read and grade a file the pinned root does not cover — ending the property the
-        // pinned root exists to buy, and offering a bypass to anyone who wanted one. `isInside` was
-        // already imported into this module for the consent check and this call site did not use it.
-        // Copilot round 3 on #362.
         if (!isInside(path.resolve(repoRoot), file)) {
             return { ok: false, why: `recipe ${JSON.stringify(r.id)} names ${script}, which resolves outside the repository at ${repoRoot}; this audit grades the tree and will not read past it` };
         }
@@ -311,13 +101,7 @@ export function auditRecipes({ workspaceDir, repoRoot, packRoots = [] }) {
 /** The config document's own version, so a future shape change is a refusal rather than a misread. */
 export const CONFIG_SPEC = "1";
 
-/**
- * Validate an opt-in config. Returns an array of problems; empty means usable.
- *
- * **Every problem is a refusal, never a default.** A config that half-parses is the state in which
- * an author believes they opted in and did not — so there is no "assume off and carry on" arm here.
- * Off is a value this file requires somebody to have written down.
- */
+/** The config's problems; empty means usable. */
 export function validateConfig(config) {
     const problems = [];
     if (config === null || typeof config !== "object" || Array.isArray(config)) {
@@ -327,8 +111,6 @@ export function validateConfig(config) {
     if (spec !== CONFIG_SPEC) {
         problems.push(`portulan.telemetry must be ${JSON.stringify(CONFIG_SPEC)}, not ${JSON.stringify(spec ?? null)}`);
     }
-    // Absent is refused rather than read as false. An opt-in whose off state can be produced by
-    // FORGETTING a key is an opt-in that can be turned on by forgetting a different one.
     if (typeof config.enabled !== "boolean") {
         problems.push(`enabled must be a boolean — absent is not false, because a gate you can reach by omission is not a gate (got ${JSON.stringify(config.enabled ?? null)})`);
     }
@@ -347,8 +129,6 @@ export function validateConfig(config) {
             }
         }
     }
-    // The seam, as a refusal rather than as a review note. A committed file may name where a secret
-    // is read from; it may never carry one. `../.portulan/dod.md` condition 5.
     for (const banned of ["headers", "endpoint", "token", "apiKey", "api_key"]) {
         if (config[banned] !== undefined || config.exporter?.[banned] !== undefined) {
             problems.push(
@@ -364,49 +144,13 @@ export function validateConfig(config) {
 // The producer registry — the closed payload, as code
 // ---------------------------------------------------------------------------------------------
 
-/**
- * What each signal contributes, and nothing else reaches a request body.
- *
- * **This registry IS the allow-list.** A producer returns metric rows built from named scalars; no
- * producer is handed a whole snapshot to spread into a payload, so there is no path from a
- * free-text or path-shaped field to the network. That is the seam holding by construction rather
- * than by a reviewer noticing — `../.portulan/dod.md` condition 5.
- *
- * **Ruled 2026-08-28: the review-loop figures only.** `../.portulan/verify/review-loop.sh` says the
- * OTel clause *"owes an emission path for these figures"*, and that debt is this one signal. The
- * shape below is the seam a second rail joins through — a producer is one entry returning rows —
- * rather than a promise that one day it might be.
- *
- * Each row: `{name, unit, description, value}`. `value` is a finite number or `null`; a null row is
- * DROPPED rather than emitted as zero, because an unmeasured window is not a window measuring zero
- * and `./review-meter.mjs` is careful about exactly that distinction.
- */
+/** The payload's allow-list: a producer builds its rows from named figures and never spreads a snapshot into them. */
 export const PRODUCERS = {
     "review-loop": {
-        /** Where this producer's input is read from, relative to the repository root. */
         input: "evals/review-loop/snapshot.json",
         scope: "portulan/review-loop",
-        /**
-         * The instant these figures are ABOUT, which is not the instant they are sent.
-         *
-         * OTLP defines `timeUnixNano` as the time the measurement is associated with, so a snapshot's
-         * own `captured` stamp is the correct value and not a workaround for determinism — though it
-         * is also what makes the committed golden byte-stable, since a clock read would make every
-         * render differ from the last.
-         */
+        /** OTLP's timeUnixNano is when a figure applies, so the capture stamp, which also keeps the golden byte-stable. */
         capturedAt: (snapshot) => snapshot.captured ?? null,
-        /**
-         * **The input is validated before it is metered, and this was missing.**
-         *
-         * `meter()` treats a non-array `pullRequests` as `[]` and this producer defaults `repository`
-         * and `window.merged`, so a malformed snapshot rendered a payload carrying *wrong* window and
-         * repository metadata rather than refusing — a fail-open in the one direction that matters,
-         * since the payload is the thing that leaves the machine. `./review-meter.mjs` already exports
-         * the validator its own recipe uses; reusing it keeps one carrier of what a snapshot must be,
-         * rather than a second opinion here that could drift from the producer's. Copilot round 1 on
-         * #362, through the suppressed channel and promoted to a gating thread by this repository's own
-         * step.
-         */
         validate: (snapshot) => validateSnapshot(snapshot),
         rows(snapshot) {
             const m = meter(snapshot);
@@ -420,58 +164,17 @@ export const PRODUCERS = {
                 { name: "portulan.review.pushes_per_submission", unit: "1", description: "The criterion's literal pushes-per-round figure, in submission units.", value: m.pushesPerSubmission },
             ];
         },
-        /**
-         * Attributes every row of this signal carries.
-         *
-         * `window.captured` is here because of a defect one rail over: the review-loop snapshot **does
-         * not refresh itself** (https://github.com/sleepy-panda-srl/portulan/issues/356), so a stale
-         * capture and a current one are the same green. Stamping the capture date onto the exported
-         * data means a stale export is LABELLED stale at the far end rather than arriving as though it
-         * were fresh — which is the most this emitter can do about a silence it does not own.
-         */
         attributes: (snapshot) => ({
             "portulan.window.merged": snapshot.window?.merged ?? 0,
             "portulan.window.captured": snapshot.captured ?? "",
             "portulan.units": "submission",
         }),
-        /**
-         * The one identifier the payload carries, and it is the maintainer's widening rather than an
-         * implementer's.
-         *
-         * The ruled payload vocabulary was *figures, rule ids, recipe ids* — no identity at all. The
-         * supervisor's objection was that an export with no resource identity is indistinguishable at
-         * any real collector, so somebody adds one later, and a closed list widened by an implementer
-         * is the failure the list exists to prevent. Put to him 2026-08-28; **he widened it to one
-         * named resource attribute**, which is this.
-         *
-         * A **resource** attribute rather than a data-point one, because it identifies the source and
-         * not the measurement — and it rides once per payload instead of once per point.
-         *
-         * `login` stays excluded and is the field this deliberately is not. This snapshot's only login
-         * is a bot's, but an adopter's would carry human reviewer names, and an identifier about a
-         * PERSON is outside anything ruled here.
-         */
+        /** The payload's one identifier, the repository's; nothing naming a person, such as a login, may join it. */
         resource: (snapshot) => ({ "portulan.repository": snapshot.repository ?? "" }),
     },
 };
 
-/**
- * Every attribute key an emission **may** carry, pinned so the closed payload is a rail and not a
- * reminder.
- *
- * **An unfamiliar key in a rendered payload is a red.** Without this the "closed list" is a promise
- * about the code rather than a property of it — and a producer added later could widen the vocabulary
- * silently, which is precisely the widening the maintainer reserved to himself.
- *
- * **This is an ALLOW-LIST, and `REQUIRED_ATTRIBUTE_KEYS` below is the floor — one list was doing both
- * jobs and they are not the same job.** `service.namespace` is optional in the config *and* optional
- * in OpenTelemetry's own semantic conventions, so a workspace that declares none emits a payload
- * without it — legitimately. A single list checked "in both directions" made that legal config look
- * like a broken invariant, and the only reason nothing failed is that THIS workspace happens to
- * declare a namespace: the pin was green by coincidence of one instance. Requiring the key instead
- * would have been this repository inventing a constraint the specification does not have. Copilot
- * round 2 on #362.
- */
+/** Every attribute key a payload may carry; the suite fails a rendered key outside it. */
 export const EMITTED_ATTRIBUTE_KEYS = Object.freeze([
     "service.name",
     "service.namespace",
@@ -484,38 +187,16 @@ export const EMITTED_ATTRIBUTE_KEYS = Object.freeze([
     "portulan.units",
 ]);
 
-/**
- * The keys every emission **must** carry, whatever the config says.
- *
- * The floor rather than the ceiling: a payload missing one of these is not identifiable at a
- * collector, which is the thing the maintainer's one widening of the vocabulary was for. Everything in
- * `EMITTED_ATTRIBUTE_KEYS` and not here is legitimately conditional — today that is `service.namespace`
- * alone, and it is conditional on the config declaring one.
- */
 export const REQUIRED_ATTRIBUTE_KEYS = Object.freeze(EMITTED_ATTRIBUTE_KEYS.filter((k) => k !== "service.namespace"));
 
 // ---------------------------------------------------------------------------------------------
 // OTLP/HTTP JSON — the wire shape, written by hand
 // ---------------------------------------------------------------------------------------------
 
-/**
- * One OTLP `AnyValue`. Exported so the suite asserts against THIS map rather than re-spelling it —
- * a second copy of a wire encoding is a second thing to get wrong, and `./inside.mjs`'s docblock is
- * this repository's standing argument about that.
- */
 export function anyValue(v) {
     if (typeof v === "string") return { stringValue: v };
     if (typeof v === "boolean") return { boolValue: v };
-    // **`isSafeInteger`, not `isInteger`.** OTLP's `intValue` is an int64 and a JS number stops being an
-    // exact integer past 2^53 — `Number.isInteger(2**53 + 1)` is `true` and the value is already the
-    // wrong one, so stringifying it emits a precise-looking integer that is not the number anybody
-    // meant. Beyond that range `asDouble` is the honest encoding: approximate, and *labelled*
-    // approximate, which is the same distinction between could-not-run and a verdict that this module
-    // spends a docblock on. Copilot round 11 on #362, through the suppressed channel.
-    //
-    // **Not reachable with today's producer** — the review-loop figures are pull-request and submission
-    // counts — and it is fixed anyway because `anyValue` is exported, and the producer seam exists to
-    // invite rows this module did not write.
+    // Past 2^53 a number may not be the integer meant, so it goes out as a double rather than as a wrong int64.
     if (Number.isSafeInteger(v)) return { intValue: String(v) };
     if (typeof v === "number" && Number.isFinite(v)) return { doubleValue: v };
     throw new Error(`no OTLP encoding for ${JSON.stringify(v)}`);
@@ -523,21 +204,10 @@ export function anyValue(v) {
 
 const kv = (attrs) => Object.entries(attrs).map(([key, value]) => ({ key, value: anyValue(value) }));
 
-/**
- * Render the OTLP/HTTP JSON metrics payload.
- *
- * **Gauge, and the point type is a decision rather than a default.** These are snapshot statistics
- * over a window of merged pull requests — not monotonic counters. A `Sum` would owe an
- * `aggregationTemporality` and a `startTimeUnixNano`, and the snapshot records no window START (only
- * its size and the per-pull-request merge stamps), so any start instant would be derived — which is
- * where double counting comes from. A Gauge needs neither and says what these figures are.
- */
+/** Gauges, not Sums: a Sum owes a start time, and the snapshot records no window start. */
 export function renderPayload({ config, signals, version = VERSION }) {
     const resource = { "service.name": config.service.name, "telemetry.sdk.name": "portulan", "telemetry.sdk.language": "nodejs", "telemetry.sdk.version": version };
     if (config.service.namespace !== undefined) resource["service.namespace"] = config.service.namespace;
-    // The maintainer's one widening of the closed vocabulary, contributed by the signal rather than
-    // invented here. Signals agreeing on a key is fine; a signal inventing one the pin does not know
-    // is what `EMITTED_ATTRIBUTE_KEYS` and the suite exist to catch.
     for (const s of signals) Object.assign(resource, s.resource ?? {});
 
     const scopeMetrics = [];
@@ -545,9 +215,6 @@ export function renderPayload({ config, signals, version = VERSION }) {
         const timeUnixNano = String(BigInt(Date.parse(s.capturedAt)) * 1000000n);
         const attributes = kv(s.attributes);
         const metrics = s.rows
-            // A null figure is DROPPED, never sent as zero. `./review-meter.mjs` returns null for an
-            // unmeasured ratio precisely so nobody reads an empty corpus as a measured zero, and
-            // encoding it as 0 here would undo that one layer down.
             .filter((r) => r.value !== null && Number.isFinite(r.value))
             .map((r) => ({
                 name: r.name,
@@ -567,26 +234,7 @@ export const serialize = (payload) => `${JSON.stringify(payload, null, 2)}\n`;
 // Transport — the ONE mode that reaches the network
 // ---------------------------------------------------------------------------------------------
 
-/**
- * Read transport from the OpenTelemetry standard environment. Nothing here is committed anywhere.
- *
- * `OTEL_EXPORTER_OTLP_HEADERS` is the specification's `key=value,key=value` list; it is parsed but
- * **never printed**, because a header list is where a bearer token lives. Neither is the endpoint,
- * beyond its origin and path — see `safeEndpoint`, and round 14 of this file's own review for why
- * withholding one while printing the other was not enough.
- */
-/**
- * A URL safe to print: no userinfo, no query, no fragment.
- *
- * **The headers were withheld and the URL was not, which is the same reasoning applied at one site and
- * not its sibling.** A collector endpoint legally carries credentials — `https://user:pass@host/…` —
- * and tokens are routinely passed as query parameters, so printing the endpoint on success leaked
- * exactly what withholding the header list was protecting. Into CI logs, which are long-lived and, in
- * this repository, world-readable.
- *
- * Origin and path only. Enough for a human to tell *where it went*, which is the whole reason the
- * endpoint is printed at all. Copilot round 14 on #362.
- */
+/** A URL safe to print: origin and path, since userinfo and a query may carry credentials. */
 export function safeEndpoint(href) {
     try {
         const u = new URL(href);
@@ -596,21 +244,12 @@ export function safeEndpoint(href) {
         u.hash = "";
         return u.href;
     } catch {
-        // Unparsable, so nothing can be redacted from it with any confidence — and an unparsable value
-        // is exactly the one most likely to be a mistyped secret. Never echoed.
         return "<withheld: not a parsable URL>";
     }
 }
 
+/** Endpoint and headers only: the OTLP protocol, timeout, compression, certificate and client-key variables go unread. */
 export function transportFromEnv(env) {
-    // **The signal-specific variables win, and they are used AS GIVEN.** The OpenTelemetry protocol
-    // specification draws a distinction this function ignored: `OTEL_EXPORTER_OTLP_ENDPOINT` is a BASE
-    // to which the signal's path is appended, while `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` is the full
-    // URL and must be used untouched. Appending to both produced `…/v1/metrics/v1/metrics` for anyone
-    // configured the signal-specific way, and left them no escape hatch — while this file's own
-    // docblock claimed the variables are read "exactly as the OpenTelemetry specification defines
-    // them". A conformance claim is a claim like any other, and this one was false. Copilot round 5 on
-    // #362, through the suppressed channel.
     const specific = env.OTEL_EXPORTER_OTLP_METRICS_ENDPOINT;
     const base = env.OTEL_EXPORTER_OTLP_ENDPOINT;
     const named = typeof specific === "string" && specific.length > 0 ? "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT" : "OTEL_EXPORTER_OTLP_ENDPOINT";
@@ -622,14 +261,8 @@ export function transportFromEnv(env) {
     try {
         url = new URL(named === "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT" ? raw : raw.endsWith("/") ? `${raw}v1/metrics` : `${raw}/v1/metrics`);
     } catch {
-        // The raw value is NOT echoed. It comes from the environment, it may carry credentials or a
-        // query token, and a value that failed to parse is the likeliest of all to be a mistyped
-        // secret. The variable name is what a reader needs; the value is what they must not be given.
         return { ok: false, why: `${named} is not a parsable URL — its value is withheld, since an endpoint may carry credentials` };
     }
-    // Headers follow the same rule: the signal-specific list REPLACES the general one rather than
-    // merging with it, which is what the specification says and is the behaviour a reader configuring
-    // one tenant's credentials for metrics alone is relying on.
     const headerSource = env.OTEL_EXPORTER_OTLP_METRICS_HEADERS ?? env.OTEL_EXPORTER_OTLP_HEADERS ?? "";
     const headers = { "content-type": "application/json" };
     for (const pair of headerSource.split(",")) {
@@ -639,76 +272,24 @@ export function transportFromEnv(env) {
     return { ok: true, url: url.href, headers, from: named };
 }
 
-/**
- * The real send. **Injected everywhere it is exercised**, and that is a rule rather than a
- * convenience: `../.portulan/verify/tests.sh` runs the suite, so a test opening a real socket would
- * be a network call inside a verify recipe — which `../spec/slots.md` and
- * `../.portulan/verify/README.md` both prohibit outright. The suite tests this module against an
- * injected transport; the real socket is exercised in the session's recorded demonstration, outside
- * the recipe set.
- */
+/** The real send; the suite injects its own, since it runs inside a verify recipe, which may not reach the network. */
 export async function postJson(url, headers, body) {
     const res = await fetch(url, { method: "POST", headers, body });
     return { status: res.status, ok: res.ok, text: await res.text().catch(() => "") };
 }
 
-/**
- * Is the consent COMMITTED, or merely present in somebody's working copy?
- *
- * **The ruling is that the committed config is the standing consent — so an uncommitted config is not
- * consent at all.** Without this check an agent could write `enabled: true` into a working copy and
- * export on nobody's decision, and the maintainer's Gated act would have been performed by the thing
- * it gates. That is a mandate nothing checks, which this repository holds to be another way of
- * spelling broken (`../.portulan/memory/a-mandate-nothing-checks-is-already-broken.md`), arriving
- * inside the change that states the mandate.
- *
- * The discipline is `./drills.mjs`'s, one file wide: it **reports on a commit and says which one**.
- * Tracked, and byte-identical to `HEAD`, or `--export` refuses.
- *
- * **This is the ONLY path in this module that spawns anything**, and it is on the `--export` arm
- * alone — `--render` and `--check` are what a verify recipe may run, and they touch neither a
- * subprocess nor a socket.
- */
+/** Refuses a config that is untracked, staged and never committed, or changed since HEAD. */
 export function consentIsCommitted(configPath, repoRoot, spawn = spawnSync) {
     const parent = path.resolve(repoRoot);
-    // **Pinned by `repoRoot`, like every other path this tool takes.** `path.resolve(configPath)` alone
-    // reads a relative `--config` against the CALLER'S cwd, so an in-repo config was classed *outside
-    // the repository* whenever the tool ran from anywhere else. Third instance of the root/cwd split in
-    // this one file — `workspaceDir` in round 1, `packRoots` in round 6, this in round 7 — which is why
-    // it is fixed here as a rule rather than a site: every path this function touches derives from
-    // `child`, and nothing below calls `path.resolve` on the raw argument again.
     const child = path.resolve(parent, configPath);
     if (!isInside(parent, child)) {
         return { ok: false, why: `${configPath} is outside the repository at ${repoRoot}, so nothing can establish that it is committed` };
     }
-    // **Git wants POSIX separators, whatever the platform gives `path.relative`.** On Windows this
-    // returns `evals\\telemetry\\config.json`, and git's pathspecs and `HEAD:<path>` syntax both want
-    // `/` — so a config that IS committed would be refused as untracked, or as missing at HEAD. The
-    // consent gate would fail closed rather than open, but it would fail for every Windows adopter and
-    // the message would name the wrong cause.
-    //
-    // Seven sites in `cli/` already normalise this way, `./librarian.mjs` on exactly this
-    // git-relative case; this was the eighth that needed it and did not have it. Unlike `isInside`,
-    // which was extracted to one carrier, this convention is still copied — filed rather than reduced
-    // here, since collapsing seven call sites is a change of its own shape.
-    // Copilot round 9 on #362.
+    // Git pathspecs and HEAD:<path> want forward slashes, whatever separator path.relative gives.
     const rel = path.relative(parent, child).split(path.sep).join("/");
     const git = (args) => spawn("git", ["-C", parent, ...args], { encoding: "utf8" });
 
-    // **Is this a repository at all? Asked ONCE, up front, and that is the whole design of what
-    // follows.**
-    //
-    // The first repair of this function distinguished *git failed* from *the file is untracked* by
-    // treating exit **128** as "not a repository". That is true of `ls-files` and **false of `show`**:
-    // `git show HEAD:<path>` also exits 128 for a path that is tracked in the index and not in `HEAD` —
-    // *"fatal: path 'x' exists on disk, but not in 'HEAD'"*, measured. So the repair made the
-    // *does not exist at HEAD* branch unreachable and reported *not a repository* for a file somebody
-    // had **staged and never committed** — which is precisely the case this gate exists to catch, since
-    // staging is how an agent would try to manufacture consent one step short of a commit.
-    //
-    // Establishing repository-ness once removes the ambiguity structurally instead of by matching on
-    // git's prose, which is localised and version-dependent. After this line, a non-zero status is that
-    // command's own domain answer and nothing else. Copilot round 7 on #362.
+    // Asked first, since `git show HEAD:<path>` also exits 128 for a path staged but never committed.
     const repo = git(["rev-parse", "--git-dir"]);
     if (repo.error) return { ok: false, why: `git could not be run to establish whether the consent is committed — ${repo.error.message}` };
     if (repo.status !== 0) {
@@ -724,18 +305,10 @@ export function consentIsCommitted(configPath, repoRoot, spawn = spawnSync) {
     const head = git(["show", `HEAD:${rel}`]);
     if (head.error) return { ok: false, why: `git could not read ${rel} at HEAD — ${head.error.message}` };
     if (head.status !== 0) {
-        // Tracked but not in `HEAD` — staged, or committed on no branch yet. Either way the consent has
-        // never been committed, which is the answer, not a malfunction.
         return { ok: false, why: `${rel} is tracked but does not exist at HEAD, so the consent it states has been staged and never committed` };
     }
 
-    // **Git's own notion of "differs", not a byte compare.** Reading the working copy and comparing it
-    // to `git show HEAD:<path>` looks equivalent and is not: with `core.autocrlf=true` — the Windows
-    // default, and this repository ships no `.gitattributes` — a committed file is checked out with
-    // CRLF while the blob at HEAD stays LF. The bytes differ, `git diff` is clean, and the gate would
-    // refuse a consent that IS committed. Fail-closed, and wrong for every Windows adopter: the same
-    // platform class as the separator defect one round earlier, and equally invisible to CI here,
-    // which runs `ubuntu-latest` only. Copilot round 16 on #362.
+    // `git diff`, not a byte compare: under core.autocrlf a committed file checks out as CRLF over an LF blob.
     const diff = git(["diff", "--quiet", "HEAD", "--", rel]);
     if (diff.error) return { ok: false, why: `git could not compare ${rel} against HEAD — ${diff.error.message}` };
     if (diff.status === 1) {
@@ -770,28 +343,9 @@ const USAGE = [
     "       · 2 could not run (config or snapshot missing, unreadable, or malformed)",
 ].join("\n");
 
-/**
- * Every option whose value is a path, and therefore must be pinned by `--repo-root`.
- *
- * **This exists because the same defect was fixed five times, one site at a time.** Across this pull
- * request's review: `--workspace` resolved against the caller's cwd (round 1), `--pack-root` left
- * behind by that very fix (round 6), `--config` and its re-read (round 7), `--workspace` resolved but
- * not contained (round 10), and `--check`/`--write` (round 12). Each repair was correct and each left
- * a sibling, which is
- * `../.portulan/proposals/0020-a-fix-is-not-done-at-the-site-it-was-found.md`'s class five times over.
- *
- * So the pinning is **one operation over a declared list** rather than a call at each use. A new path
- * option is pinned by adding it here, and the suite asserts this list against the parser's own keys —
- * so an option that takes a path and is not named here reddens instead of becoming the sixth instance.
- */
 export const PATH_OPTIONS = Object.freeze(["config", "check", "write", "workspace"]);
 
-/**
- * Resolve every path option against the pinned root, once, before anything reads one.
- *
- * `path.resolve` leaves an absolute value alone, so naming an absolute path explicitly still wins —
- * which is the property `--pack-root` needed and the reason this is `resolve` rather than `join`.
- */
+/** Resolves each path option against the repository root; an absolute one stays as given. */
 export function pinPaths(opts) {
     const root = path.resolve(opts.repoRoot);
     const pinned = { ...opts, repoRoot: root, packRoots: opts.packRoots.map((r) => path.resolve(root, r)) };
@@ -841,11 +395,7 @@ export async function run(argv = process.argv.slice(2), io = console, { env = pr
         io.log(USAGE);
         return 0;
     }
-    // Pinned ONCE, here, before anything reads a path. See `PATH_OPTIONS`.
     opts = pinPaths(opts);
-    // The audit is about the RECIPES, not about a payload, so it runs before the config is read and
-    // needs no --config. A workspace that has not opted in still owes the property that none of its
-    // recipes can reach the network.
     if (opts.audit) {
         const res = auditRecipes({ workspaceDir: opts.workspace, repoRoot: opts.repoRoot, packRoots: opts.packRoots });
         if (!res.ok) {
@@ -877,9 +427,7 @@ export async function run(argv = process.argv.slice(2), io = console, { env = pr
         return 2;
     }
 
-    // ---- the config. Unreadable and opted-out are DIFFERENT ANSWERS and get different codes.
-    // Pinned against `--repo-root`, the same rule `consentIsCommitted` and the signal inputs follow —
-    // a relative `--config` must mean the same file wherever the tool is invoked from.
+    // ---- the config
     const configPath = opts.config;
     let config;
     try {
@@ -965,8 +513,7 @@ export async function run(argv = process.argv.slice(2), io = console, { env = pr
 
     // ---- --export, the one mode that reaches the network
     if (opts.export) {
-        // The gate, spelled ONCE and here. Non-zero and a sentence: for this tool silence is never an
-        // answer, because an opted-out emitter and a broken one are both silent.
+        // Never silent: an opted-out emitter and one that never started would look alike.
         if (config.enabled !== true) {
             io.error(`telemetry: ${configPath} says enabled: false, so nothing was sent.`);
             io.error("This is a verdict, not a failure: the config was read and it opts out. Emission is");
@@ -974,7 +521,6 @@ export async function run(argv = process.argv.slice(2), io = console, { env = pr
             io.error("workspace has not given it. Use --render to see exactly what WOULD be sent.");
             return 1;
         }
-        // The consent must be COMMITTED, not merely written. See `consentIsCommitted`.
         const committed = consentIsCommitted(configPath, opts.repoRoot);
         if (!committed.ok) {
             io.error(`telemetry: --export cannot run — ${committed.why}.`);
@@ -1001,14 +547,11 @@ export async function run(argv = process.argv.slice(2), io = console, { env = pr
             io.error(`telemetry: the collector answered ${res.status}${res.text ? ` — ${res.text.slice(0, 200)}` : ""}`);
             return 1;
         }
-        // **Origin and path only, and the headers never.** A header list is where a bearer token lives —
-        // and so is a URL, which may carry `user:pass@` or a query token. Withholding one and printing
-        // the other was the same rule applied at one site and not its sibling.
         io.log(`telemetry: exported ${emitted} metric(s) to ${safeEndpoint(t.url)} — ${res.status}`);
         return 0;
     }
 
-    // ---- --render, the default. No socket is opened on this path.
+    // ---- --render, the default
     io.log(body);
     io.log(`telemetry: rendered ${emitted} metric(s) over ${signals.length} signal(s); nothing was sent.`);
     io.log(`  This workspace's config says enabled: ${config.enabled}. --export is the only mode that`);
@@ -1018,14 +561,7 @@ export async function run(argv = process.argv.slice(2), io = console, { env = pr
     return 0;
 }
 
-// The entry guard, in the ONE form `./rule-carriers.mjs` designates — copied rather than re-derived,
-// as `./drills.mjs` and `./fuzz-shell.mjs` both are. `file://${argv[1]}` is NOT that form:
-// `import.meta.url` percent-encodes and a working copy under a path with spaces then never matches,
-// so the tool exits 0 having never started. Four files here have shipped that defect.
-//
-// **It matters more in this file than in any of them.** An emitter that never starts sends nothing,
-// and an emitter that is correctly opted out also sends nothing. The two are indistinguishable from
-// outside, so the guard is the difference between a working gate and a tool that has silently stopped.
+// As file URLs, since `import.meta.url` percent-encodes a space; through realpath too, for an npm `bin` symlink.
 function isMain() {
     const invoked = process.argv[1];
     if (!invoked) return false;
@@ -1037,8 +573,7 @@ function isMain() {
     }
 }
 
-// `process.exitCode` rather than `process.exit`, which `./control-chars.mjs` settled here: exiting
-// outright can truncate a pipe that has not drained, and a truncated line IS exit 0 with no output.
+// `process.exitCode` rather than `process.exit`, so a pipe that has not drained is not cut short.
 if (isMain()) {
     run(process.argv.slice(2)).then((code) => {
         process.exitCode = code;