mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/observability/runtime-friction.js

@@ -1,43 +1,8 @@
 /**
- * runtime-friction.js — derive friction signals from observables the
- * runtime already has (Story #4578).
- *
- * ## Why this exists
- *
- * Friction telemetry was **opt-in**: a `friction` record existed only when
- * an agent volunteered a `diagnose-friction.js --story <id> --cmd <...>`
- * call. `plan-run-epilogue.js`'s `follow-up-rollup` then read an empty
- * `signals.ndjson` and truthfully reported "No friction signals — nothing
- * to follow up". A 7-Story run containing a mid-run git outage, a parked
- * worker needing an operator resume, and a four-round acceptance critic
- * produced a **zero-signal retro** — because the stream is least likely to
- * fill exactly when a run is going badly and the agent is busy.
- *
- * This module closes that gap from the other side: the runtime emits
- * friction from what it *already knows*, at the point it already knows it.
- * No agent cooperation required.
- *
- * ## Not a second channel
- *
- * These records go through the **existing** `appendSignal` path, carry the
- * **existing** `kind: 'friction'` shape, and land in the **same**
- * `signals.ndjson` stream `diagnose-friction.js` writes and the roll-up
- * reads. The only thing that is new is *who* decides to write.
- *
- * Deliberately distinct from {@link ../gates/friction.js}'s
- * `emitFrictionSignal`, which early-returns unless **both** `storyId` and
- * `epicId` are truthy. Every v2 Story is standalone (`epicId: null` — see
- * `temp-paths.storyTempDir`'s standalone branch), and the roll-up reads the
- * standalone stream via `forEachLine(null, sid, ...)`. Routing runtime
- * friction through the gate helper would drop **every** record on the floor,
- * silently, which is the bug this Story exists to fix.
- *
- * ## Robustness contract
- *
- * Observability MUST NOT halt the runner (`signals-writer.js`; the
- * `docs/patterns.md` friction pattern). Every export here is best-effort:
- * it swallows its own failures after a `Logger.warn` and resolves `false`.
- * A missing signal is strictly preferable to a broken close.
+ * runtime-friction.js — emit friction signals from what the runtime already
+ * knows. Not via `gates/friction.js`, which drops records without an
+ * `epicId` (every v2 Story has none). Best-effort: failures log and resolve
+ * `false`.
  *
  * @module lib/observability/runtime-friction
  */
@@ -48,75 +13,24 @@ import { Logger } from '../Logger.js';
 import { appendSignal, forEachLine } from './signals-writer.js';
 
 /**
- * The friction categories this module emits.
- *
- * Values are plain strings by design: `signal-event.schema.json` types
- * `category` as a free-form `{ type: 'string', minLength: 1 }`, so no schema
- * change is required to add one. They are frozen here so the emitters and
- * their tests name the same literal instead of spreading it.
- *
- * Category choice is load-bearing for the retro: `retro-proposals.js`
- * aggregates **by exact category string**, so these are deliberately coarse
- * — one bucket per failure mode — rather than per-incident. Two Stories that
- * hit the same wall in one run aggregate to `occurrences: 2` and route as a
- * real proposal instead of being discarded as two unrelated singletons.
+ * The retro aggregates by exact category string, so each is one coarse
+ * bucket per failure mode.
  */
 export const RUNTIME_FRICTION_CATEGORIES = Object.freeze({
-  /** A Story was parked at `agent::blocked` — the HITL pause (§ 1.J). */
   STORY_BLOCKED: 'story-blocked',
-  /** A close run ended on a `failed` terminal (non-zero exit). */
   CLOSE_FAILED: 'close-failed',
-  /** A bounded merge wait expired with the PR still in flight. */
   MERGE_WAIT_EXHAUSTED: 'merge-wait-exhausted',
-  /**
-   * A review/lens tool failed to *execute* (binary missing, unparseable
-   * output, materialization crash) — an operational degradation, not a code
-   * finding. Story #4699 routes these here so findings severity tiers
-   * reflect code findings only.
-   */
+  /** A tool failed to execute — kept out of code-finding severity tiers. */
   TOOL_DEGRADED: 'tool-degraded',
-  /**
-   * The light delivery path refused a scope — a suitability-gate escalation
-   * or a blocked diff backstop. Story #4856 added it because neither rejection
-   * emitted anything, so an over-tight ceiling could only reach the framework
-   * as anecdote; the roll-up aggregating these by category is what makes the
-   * ceilings recalibratable from recorded evidence.
-   */
   LIGHT_SCOPE_REJECTED: 'light-scope-rejected',
-  /**
-   * An operator overrode a Story-scope code-review critical blocker with
-   * `--override-review-block <reason>`. Deliberately its own
-   * bucket: this is the one signal that says a gate's verdict was rejected by
-   * a human who then shipped anyway, so a rising `occurrences` count is direct
-   * evidence the gate is miscalibrated rather than the code being bad. It is
-   * *not* `TOOL_DEGRADED` — the tool ran fine and produced a verdict; what
-   * failed was the verdict's usefulness.
-   */
+  /** A human shipped over a review blocker; a rising count means miscalibration. */
   REVIEW_BLOCK_OVERRIDDEN: 'review-block-overridden',
 });
 
 /**
- * The friction category one light-path refusal files under.
- *
- * `LIGHT_SCOPE_REJECTED` alone used to be the category for every refusal, and
- * the retro composer aggregates, de-duplicates and labels on the category
- * string ALONE — so an empty-diff refusal and a `public-api` sensitive-path
- * refusal landed in one bucket and filed one "recurred 2 times across 2
- * Stories" follow-up whose two occurrences had nothing in common but the
- * category (issue #5237; consumer Beestera/swarm-os#2408). The roll-up's shape
- * fingerprint could not separate them either: it hashes detail KEYS, and every
- * refusal carries an identical key set.
- *
- * Encoding the refusal class in the category is what splits them, and it
- * splits them in every consumer at once — bucket aggregation, the graduator's
- * idempotency marker and the `friction::<category>` label all read this one
- * string. N refusals of the SAME class still coalesce, which is the recurrence
- * evidence the light ceilings are recalibrated from. New categories need no
- * seeding: the graduator mints missing `friction::*` labels before filing.
- *
- * A class-less refusal keeps the bare category unchanged — that is the
- * suitability gate, which refuses a prompt before any diff exists and so has
- * no diff-derived class to carry.
+ * The refusal class rides in the category because aggregation, graduator
+ * idempotency and the `friction::*` label all key on it; a class-less
+ * refusal keeps the bare category.
  *
  * @param {string|null} [refusalClass] A
  *   {@link module:lib/orchestration/light-suitability.LIGHT_REFUSAL_CLASSES}
@@ -150,19 +64,15 @@ function positiveIntOrNull(value) {
 }
 
 /**
- * Append one runtime-derived `friction` record to the Story's signals
- * stream. Best-effort: never throws, never rejects.
- *
- * `epicId` defaults to `null` (the standalone-Story stream) because that is
- * where v2 Stories live and where the roll-up reads.
+ * Append one `friction` record. Never throws.
  *
  * @param {object} args
  * @param {number} args.storyId
  * @param {number|null} [args.epicId]
- * @param {string} args.category  One of {@link RUNTIME_FRICTION_CATEGORIES}.
- * @param {string} args.tool      Emitting surface, for `emitter.tool`.
- * @param {object} [args.details] Kind-specific payload (always an object).
- * @param {object} [args.config]  Resolved config (for `tempRoot`).
+ * @param {string} args.category
+ * @param {string} args.tool
+ * @param {object} [args.details]
+ * @param {object} [args.config]
  * @returns {Promise<boolean>} true when a record was appended.
  */
 export async function emitRuntimeFriction({
@@ -175,8 +85,6 @@ export async function emitRuntimeFriction({
 } = {}) {
   const sid = positiveIntOrNull(storyId);
   if (sid === null) {
-    // No Story context → no stream to write to. Not an error: some close
-    // paths (a usage error before the id is parsed) genuinely have none.
     return false;
   }
   if (typeof category !== 'string' || category.trim() === '') {
@@ -190,8 +98,6 @@ export async function emitRuntimeFriction({
     ts: new Date().toISOString(),
     epicId: positiveIntOrNull(epicId),
     storyId: sid,
-    // 2-tier hierarchy (Epic #3163): no Task tier. Retained for schema
-    // compatibility and always null — mirrors diagnose-friction.js.
     taskId: null,
     category: category.trim(),
     emitter: { tool: tool || 'runtime-friction' },
@@ -206,9 +112,6 @@ export async function emitRuntimeFriction({
       config,
     });
   } catch (err) {
-    // `appendSignal` already swallows its own I/O failures; this catch is
-    // defense in depth so a surprise (a poisoned config, a throwing
-    // validator) still cannot take down the path being observed.
     Logger.warn(
       `[runtime-friction] append failed for Story #${sid} (${category}): ${
         err instanceof Error ? err.message : String(err)
@@ -219,25 +122,13 @@ export async function emitRuntimeFriction({
 }
 
 /**
- * Emit the recovery counterpart of a `story-blocked` record when a Story
- * leaves `agent::blocked` for an active state (Story #4622).
- *
- * A transient block that self-resolves — lease contention or a stale label
- * read under concurrent shared-checkout pressure (swarm-os friction #581) —
- * still fired a `story-blocked` record at the block flip, which the retro
- * composer counts toward the `story-blocked` recurrence total exactly like a
- * terminal block. This emits a companion `story-blocked` record carrying the
- * `details.recovered: true` discriminator, so the composer can net the whole
- * incident out (see `retro-proposals.js`). The category is deliberately kept
- * as `story-blocked` rather than a new bucket: a distinct category would
- * itself aggregate into a routable proposal, re-introducing the noise.
- *
- * Best-effort; never throws.
+ * A `recovered: true` `story-blocked` record on leaving `agent::blocked`, so
+ * the retro nets the block out (same category, or it would aggregate itself).
  *
  * @param {object} args
  * @param {number} args.storyId
- * @param {string} [args.fromState] The state parked at (`agent::blocked`).
- * @param {string} [args.toState]   The active state recovered into.
+ * @param {string} [args.fromState]
+ * @param {string} [args.toState]
  * @param {object} [args.config]
  * @returns {Promise<boolean>} true when a record was appended.
  */
@@ -261,56 +152,16 @@ export async function emitBlockRecoveredFriction({
 }
 
 /**
- * Emit the recovery counterpart of an earlier friction record in `category`
- * when a Story ultimately lands, netting a transient incident out of the
- * retro (generalized from the `close-failed`-only emitter of Story #4649 by
- * Story #4654).
- *
- * An incident that fires once — a transient block, a CI/lease/GitHub fault at
- * close, a merge wait that outran one window — but is provably resolved by the
- * time the Story lands still left an un-netted record on the stream, which the
- * composer counts exactly like an incident that never recovered. This appends
- * the companion record carrying the `recovered: true` discriminator in the
- * **same** `category` (a distinct bucket would itself aggregate into a routable
- * proposal, re-introducing the noise), so `netOutRecoveredIncidents` /
- * `deriveUnresolvedBlockedEvents` in `retro-proposals.js` can cancel the whole
- * `(category, storyId)` incident out.
- *
- * **Why this is not emitted from `frictionForTerminal`.** A `landed` terminal
- * envelope is emitted at the very END of close — *after* the post-land tail
- * has already gathered the signal stream and filed its follow-ups. A marker
- * written there would arrive too late to net anything out of the run that
- * produced it. So the emit hangs off `runPostLandTail`, which is the single
- * shared land point (reached from both the in-close land and the standalone
- * `single-story-confirm-merge.js` resume) and runs BEFORE follow-up capture.
- * The tail runs *because* the PR merged, so every incident on the stream is
- * provably resolved at that point.
- *
- * **Conditional on an actual incident.** The marker is appended only when the
- * Story's stream already carries an un-recovered record in `category`. Emitting
- * unconditionally on every land would write a category-mislabelled row for
- * Stories that never had the incident — and, because the netting is per
- * `(category, storyId)` over the cumulative stream, that spurious marker would
- * suppress the Story's whole bucket for `category`, making it un-routable at
- * story scope for a Story that never hit the incident at all.
- *
- * What this guard does NOT do is bound the netting once a *legitimate* marker
- * exists. The netting inherits the Story #4622 coarsening — per
- * `(category, storyId)` across the whole stream, not 1:1 pairing — so a
- * later, genuinely un-landed record in `category` for a Story that already
- * recovered once is still netted away, and does not even reach `discarded`.
- * Reaching that needs a re-close after a land (a confirm-merge resume, or a
- * close after a revert). Deliberate, inherited, and called out here rather
- * than papered over: an aggregate is a routing heuristic, not an incident
- * ledger.
- *
- * Best-effort; never throws. A read failure yields no marker (the incident
- * stays counted) rather than a speculative write.
+ * On land, emit a `recovered: true` marker in `category` so the retro nets
+ * the `(category, storyId)` incident out. Hung off `runPostLandTail` because
+ * the `landed` envelope arrives after follow-ups are already filed. Only
+ * emitted over an existing un-recovered record — otherwise it would suppress
+ * a bucket the Story never hit. A read failure emits nothing.
  *
  * @param {object} args
  * @param {number} args.storyId
- * @param {string} args.category One of {@link RUNTIME_FRICTION_CATEGORIES}.
- * @param {string} [args.tool]   Emitting surface (default `runPostLandTail`).
+ * @param {string} args.category
+ * @param {string} [args.tool]
  * @param {object} [args.config]
  * @returns {Promise<boolean>} true when a record was appended.
  */
@@ -352,7 +203,6 @@ export async function emitRecoveredFrictionMarker({
     );
     return false;
   }
-  // Nothing to cancel, or already cancelled — a second marker would be noise.
   if (!incident || recovered) return false;
 
   return emitRuntimeFriction({
@@ -365,12 +215,6 @@ export async function emitRecoveredFrictionMarker({
 }
 
 /**
- * Emit the recovery counterpart of a `close-failed` record when a Story's
- * close ultimately lands (Story #4649). Thin wrapper over
- * {@link emitRecoveredFrictionMarker} bound to the `close-failed` category —
- * retained as its own export so the post-land seam that injects it stays
- * stable.
- *
  * @param {object} args
  * @param {number} args.storyId
  * @param {object} [args.config]
@@ -385,39 +229,12 @@ export async function emitCloseRecoveredFriction({ storyId, config } = {}) {
 }
 
 /**
- * Normalize one raw signals-stream row into the shape the retro composer
- * consumes, or `null` when the row carries no usable category.
- *
- * Single-homed because BOTH production gathers need it identically —
- * `gatherStoryFrictionSignals` (story scope) and `executeFollowUpRollup`
- * (run scope) — and the bug this exists to prevent is precisely the two of
- * them drifting: they each independently flattened rows to
- * `{ category, source }`, dropping the `storyId` / `details` the composer's
- * recovery-netting keys on, which left that netting unreachable on real data
- * while its unit tests stayed green (Story #4649).
- *
- * The row's own `storyId` wins over `fallbackStoryId` so a stream carrying
- * foreign rows attributes each one correctly; the fallback covers records
- * written before the field existed.
+ * One raw row → the retro composer's shape (`null` without a category).
+ * Shared by both gathers so they cannot drift; dropping `storyId`/`details`
+ * silently breaks recovery netting. `tool` is descriptive, never a routing key.
  *
- * `tool` (from `emitter.tool`) joined the shape in Story #4824. `category`
- * remains the routing and de-duplication unit — it is what titles and
- * de-duplicates a filed issue — but a roll-up that discards a candidate has
- * to be able to *name* it, and a bare category cannot distinguish a
- * `tool-degraded` from the scoped-lint runner from one out of lens
- * materialization. It is descriptive, never a routing key.
- *
- * `ts` joined the shape in Story #4850, and it joined it **here** rather than
- * in a second read beside the run-scope gather. The composer had no notion of
- * *when* its corpus happened, so it borrowed the triggering run as the window
- * and titled every proposal with a claim the evidence block below it already
- * contradicted. Carrying the timestamp through the one shared normalizer is
- * what lets the recurrence window be both bounded and describable; re-reading
- * it beside one of the two gathers is precisely the drift that made the
- * recovery-netting unreachable in Story #4649.
- *
- * @param {unknown} parsed          One parsed NDJSON row.
- * @param {number}  fallbackStoryId Stream owner, used when the row has none.
+ * @param {unknown} parsed
+ * @param {number}  fallbackStoryId Used when the row has no `storyId`.
  * @returns {{ category: string, source: 'framework'|'consumer', storyId: number, tool: string, ts: string|null, details: object }|null}
  */
 export function normalizeGatheredSignal(parsed, fallbackStoryId) {
@@ -444,13 +261,8 @@ export function normalizeGatheredSignal(parsed, fallbackStoryId) {
 }
 
 /**
- * The row's `ts` when it is a string a `Date` can read, else `null`.
- *
- * `signal-event.schema.json` requires `ts`, and both producers stamp
- * `new Date().toISOString()` — but the gathers read whatever survives on disk,
- * including rows a truncated write left half-formed. Resolving to `null`
- * rather than guessing a time is what lets the recurrence window exclude an
- * undateable row explicitly instead of aging it in as "recent".
+ * `null` for an unreadable `ts`, so the row is excluded from the recurrence
+ * window rather than aged in as recent.
  *
  * @param {unknown} value
  * @returns {string|null}
@@ -462,16 +274,8 @@ function parsableTimestamp(value) {
 }
 
 /**
- * Pure predicate: is this signal a recovery marker for its own category?
- * Shared with the retro composer so the "recovered" discriminator is read
- * from one place.
- *
- * **Category-agnostic by design (Story #4649).** The predicate used to hard-
- * code `story-blocked`, which meant every new category needing recovery
- * semantics had to re-implement the netting. A record is a recovery marker
- * when it carries a usable `category` and `details.recovered === true`; the
- * composer nets per `(category, storyId)`, so a marker can only ever cancel
- * records in its OWN bucket.
+ * Category-agnostic recovery-marker test; a marker only cancels its own
+ * `(category, storyId)` bucket.
  *
  * @param {object} signal
  * @returns {boolean}
@@ -489,41 +293,11 @@ export function isRecoveredSignal(signal) {
 }
 
 /**
- * Decide whether a `story-deliver-terminal` envelope is worth a friction
- * record, and describe it. **Pure** — no I/O — so the (interesting) policy
- * is unit-testable without touching disk.
- *
- * The partition is deliberate; each observable is emitted from exactly ONE
- * place, so one incident never double-counts into `occurrences: 2` and
- * fabricates a filed proposal out of a single event:
- *
- *   - `blocked`  → **null here.** Every blocked terminal flips the Story to
- *     `agent::blocked` (`confirm-merge.js`, both the `merge.unlanded` and
- *     `merge.flip-failed` paths), and that transition is instrumented at the
- *     canonical mutator (`ticketing/transition.js`). Emitting here as well
- *     would count the same block twice.
- *   - `landed`   → null. Nothing happened worth a retro.
- *   - `failed`   → friction. A close that ended non-zero.
- *   - `pending`  → friction **only when the cumulative wait budget is provably
- *     exhausted** (`waitBudget.cumulativeSeconds >= waitBudget.maxBudgetSeconds`).
- *     A `pending` return is reached at the per-invocation `maxWaitSeconds`
- *     bound (`phases/confirm-merge.js`); genuine cumulative exhaustion returns
- *     earlier as a **blocked** terminal via `blockOnUnlanded` (Story #4654).
- *     So a routine long-CI window rollover under budget is NOT exhaustion and
- *     emits nothing — its category name would otherwise assert an exhaustion
- *     that did not occur. Only the residual case the merge-wait guard cannot
- *     suppress — a merge that genuinely spends its whole budget and lands on a
- *     later resume — reaches here. A missing or non-numeric `cumulativeSeconds`
- *     / `maxBudgetSeconds` means exhaustion cannot be proven → emit nothing. A
- *     `pending` with **no** `waitBudget` is the `--no-wait-merge` /
- *     operator-merge path, where the human deliberately owns the land and
- *     nothing is broken — flagging it would train operators to ignore the
- *     channel.
- *
- * Deliberately **not exported**: it is this module's internal policy, and
- * `emitTerminalFriction` is the contract callers (and tests) exercise. An
- * export solely for testability would be production-dead code — the
- * `--production` dead-exports ratchet exists to catch exactly that.
+ * The friction a terminal envelope implies; each incident is emitted from one
+ * place only. `blocked` → null (the transition mutator emits it); `failed` →
+ * `close-failed`; `pending` → `merge-wait-exhausted` only when the cumulative
+ * budget is provably spent — a routine window rollover or an operator-merge
+ * `pending` (no `waitBudget`) emits nothing.
  *
  * @param {object} envelope A `story-deliver-terminal` envelope.
  * @returns {{ category: string, details: object }|null}
@@ -543,12 +317,6 @@ function frictionForTerminal(envelope) {
   }
 
   if (status === 'pending' && waitBudget) {
-    // Only a PROVEN cumulative-budget exhaustion is friction. The `pending`
-    // return is reached at the per-invocation `maxWaitSeconds` bound, not at
-    // the cumulative `maxBudgetSeconds` (that returns a blocked terminal
-    // earlier), so a routine window rollover carries `cumulativeSeconds`
-    // still under budget — emit nothing. A missing/non-numeric field means
-    // exhaustion cannot be proven, which is likewise not a record.
     const cumulativeSeconds = Number(waitBudget.cumulativeSeconds);
     const maxBudgetSeconds = Number(waitBudget.maxBudgetSeconds);
     if (
@@ -575,22 +343,12 @@ function frictionForTerminal(envelope) {
 }
 
 /**
- * Emit the friction record (if any) implied by a terminal envelope.
- * Best-effort; never throws.
- *
- * `tool` is the CALLER's name, threaded in rather than assumed: TWO CLIs emit
- * terminal envelopes — `single-story-close.js` (plus its runner) and
- * `single-story-confirm-merge.js` — and `retro-proposals.js` reads
- * `emitter.tool` (via {@link normalizeGatheredSignal}) to name the surface a
- * candidate came from, so hard-coding the close name here attributed every
- * confirm-merge record to a CLI that never ran and misdirected the follow-up.
- * Both callers already declare their name once via `runAsCli({ source })`;
- * pass that same string. The default keeps the close paths — the original
- * callers, which pass none — emitting exactly what they always did.
+ * `tool` must be the calling CLI's name: two CLIs emit terminal envelopes and
+ * the retro attributes by `emitter.tool`.
  *
  * @param {object} args
  * @param {object} args.envelope
- * @param {string} [args.tool] Emitting surface (default `single-story-close`).
+ * @param {string} [args.tool]
  * @param {object} [args.config]
  * @returns {Promise<boolean>} true when a record was appended.
  */

package/.agents/scripts/lib/observability/signal-validator.js

@@ -1,27 +1,7 @@
 /**
- * signal-validator.js — write-time validation of NDJSON signal records
- * against the canonical `signal-event.schema.json` (Epic #4406 /
- * Story #4413).
- *
- * The signals writer calls {@link validateSignal} before appending a
- * record so a schema-invalid line is dropped with a `Logger.warn` naming
- * the violating field rather than polluting the stream (and defeating the
- * downstream consumers that assume the canonical shape). Validation is
- * best-effort: the writer contract (Tech Spec #1032) is preserved —
- * observability MUST NOT throw into the runner, so every helper here
- * swallows its own faults and degrades to "treat as valid" only when the
- * validator itself cannot be constructed.
- *
- * The AJV instance compiles the on-disk schema **once** at module load so
- * the writer and the contract test validate against the exact same
- * document (no hand-rolled drift). `strict: false` matches the repo's
- * other draft-07 validators (see `tests/schemas/signal-schemas.test.js`).
- *
- * Story #5003 deleted the persisted per-Epic reject tally
- * (`temp/run-<eid>/signal-rejects.json`) and its `readSignalRejectCount`
- * reader: the tally was keyed on a positive `epicId`, and v2 Stories are
- * standalone, so nothing ever wrote a row and nothing could ever read one.
- * Write-time validation itself is untouched.
+ * signal-validator.js — write-time validation of signal records against the
+ * on-disk `signal-event.schema.json`, compiled once so the writer and the
+ * contract test validate against the same document. Never throws.
  */
 
 import { readFileSync } from 'node:fs';
@@ -44,10 +24,8 @@ const SCHEMA_PATH = path.resolve(
 );
 
 /**
- * Compile the signal-event schema once. Returns `null` when the schema
- * cannot be read or compiled — the caller then treats every record as
- * valid (fail-open) so a packaging error never silently drops all
- * signals.
+ * `null` when the schema cannot be compiled: validation then fails open so a
+ * packaging error never drops every signal.
  *
  * @returns {import('ajv').ValidateFunction | null}
  */
@@ -70,10 +48,6 @@ function buildValidator() {
 const _validate = buildValidator();
 
 /**
- * Derive a human-readable "violating field" label from the first AJV
- * error. Prefers the missing property name (required errors) or the
- * instance path, falling back to the raw message.
- *
  * @param {import('ajv').ErrorObject[] | null | undefined} errors
  * @returns {string}
  */
@@ -96,12 +70,6 @@ function violatingFieldOf(errors) {
 }
 
 /**
- * Validate a signal record against the canonical schema.
- *
- * Fail-open: when the validator could not be compiled the record is
- * reported valid (the writer keeps working). A non-object record is
- * reported invalid without invoking AJV.
- *
  * @param {unknown} record
  * @returns {{ valid: boolean, violatingField: string|null, message: string|null }}
  */