docs-drift-check.yml

name: Docs Drift Check

# When a PR changes packages/** code, flag the hand-written docs that NAME something the
# change touched — a symbol, a wire route, or the SDK method a route ledger binds to it —
# so they can be re-verified for implementation accuracy before the drift lands on main.
# Advisory only: posts a PR comment, and its VERDICT never fails the build. Since #9373 a
# transient GitHub API failure while DELIVERING that comment does not fail it either — but
# it is never swallowed: the run then states, in its own job summary and a warning
# annotation, that the advisory could not be delivered, so "could not tell" can never
# render as "no drift". Scan and derivation errors DO still fail the job. The actual LLM
# audit is run on-demand / on a schedule via the `docs-accuracy-audit` workflow, scoped to
# exactly the docs this check lists.
#
# It used to list pages by PACKAGE DEPENDENCY ("which docs mention @objectstack/x"), and
# #9192 measured that wrong in both directions on a real PR: 2 of 3 listed pages were
# irrelevant, and the 2 pages that actually documented the changed surface were missing
# because they document it through the SDK, which does not depend on the implementing
# package. The comment now also states what the run could NOT see — the derivation being
# read past its precision, with its silence taken for absence, is what #9192 records.
#
# Since #11357 the same posture reaches the HEADLINE. A README exports no symbol, mounts
# no route and declares no SDK method, so a README-only diff derives no anchor at all and
# the comment answered it with "this run has no opinion" — while the file it could not
# anchor was named only inside the collapsed fold. Two real README defects landed that way
# on one day (#11180, #11262). The fold was right and stays; what changed is that a run
# with an unanchored file now says so where a reviewer reads it, and withholds its ✅.
#
# Since #11356 the ✅ is withheld from the last arm that carried it: "N anchor(s) derived,
# no hand-written page names any of them". That sentence reports the NAMING RELATION, and
# a page is listed only when it already names a changed token — so a PR that widens an
# enumerable vocabulary (a function table, an allowed-value set) is structurally invisible
# to it, because the new members' absence from the page is precisely the defect. ⚠️ The
# narrowing does NOT catch that class; it stops the run from claiming it did.
#
# And since #9519 it states WHICH TREE it read. On `pull_request`, actions/checkout gives
# the MERGE of base and head, so the row set is a fact about a commit that exists on no
# branch a reader can name — while the comment's own re-derivation command sent them to
# run the tool on their own worktree. A reader who did that got a different list and
# reported a correct row as a false positive, and the investigation of the non-existent
# defect cost a full round. Same posture, one more thing the run knows and used not to say.
#
# THE RECALL DENOMINATOR (#13306, maintainer ruling 2026-08-31) — the OTHER half of the
# structural-invisibility paragraphs above. #11356/#11357 are about a page that IS already
# in this tool's scope and still goes unlisted (it restates a rule without naming what this
# tool anchors on). Separately, and wider: scripts/docs-audit/affected-docs.mjs's own header
# declares the CORPUS this whole check claims to cover — hand-written docs, excluding
# `content/docs/references/**` (generated, never hand-edited; excluding it is this check's
# constructive design, not an omission). Any recall figure for this check must use THAT
# corpus as its denominator; one computed against all edits under content/docs measures how
# often the docs generator ran in the sampling window, not this check — measured 2026-08-30,
# 31 of 46 ground-truth entries in the one figure ever computed that way were generated
# pages this check can never list (method and correction in #13306). This check stays
# advisory-only (see the top of this file) and the ceiling does not license widening the
# corpus to improve the number. Full statement in affected-docs.mjs's header — this
# paragraph only points at it so the two files compose instead of each stating their own
# half.

on:
  pull_request:
    types: [opened, synchronize, reopened]
    paths:
      - 'packages/**'
      # The mapper and this workflow, so a change to the guard runs the guard. Without
      # these, editing `affected-docs.mjs` was the one change its own self-test could
      # never see — a `packages/**`-only trigger means the tool is unguarded exactly
      # when it is being modified. A PR that touches only these gets the benign
      # "0 changed package(s) ✅" comment, which is the correct answer.
      - 'scripts/docs-audit/**'
      - '.github/workflows/docs-drift-check.yml'

permissions:
  contents: read
  pull-requests: write

jobs:
  docs-drift:
    name: Flag docs affected by code changes
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: '22'

      - name: Fetch base branch
        run: git fetch --no-tags origin "${{ github.base_ref }}"

      # The mapper excludes test files and package tooling scripts (neither can make
      # an implementation doc stale) and derives package roots from the filesystem.
      # Self-test first, so a regression that widened an exclusion into dropping real
      # implementation changes — or collapsed nested packages into their container
      # again (#4162) — fails loudly here instead of quietly skewing this comment.
      #
      # Run through check-affected-docs.mjs, not the raw `node affected-docs.mjs`
      # invocation: scripts/pm/dispatch-gates.mjs only discovers a check family from
      # a `check:NAME` / `check-NAME.mjs` shape, and this step's own `paths:` filter
      # above used to give that derivation nothing to attach to — this was the one
      # paths-filtered workflow contributing zero of the discovered families (#9187).
      # A `pnpm check:NAME` script is deliberately NOT the fix here: this job never
      # runs `pnpm install` (the mapper has zero dependencies, kept that way so this
      # job stays fast on every packages/** PR), so `pnpm` isn't even on PATH — the
      # wrapper stays a plain `node` call for exactly that reason.
      - name: Self-test the change → docs mapper
        run: node scripts/docs-audit/check-affected-docs.mjs

      # The advisory's own TEXT, pinned by rendering it (#11357). The step above answers
      # "what did this run find"; this one answers "what does the comment SAY about what
      # it did NOT find" — a question no other gate asks, because that wording lives in
      # the inline `github-script` block below, which nothing imports and nothing
      # type-checks. It runs THAT block against fixture diffs, so a blind-spot notice that
      # stopped rendering — or started rendering unconditionally, which is the same defect
      # wearing the opposite mask — fails here rather than on a reader.
      - name: Self-test the drift comment's wording
        run: node scripts/docs-audit/check-drift-comment.mjs

      - name: Compute affected docs
        id: affected
        run: |
          node scripts/docs-audit/affected-docs.mjs --json "origin/${{ github.base_ref }}" > affected.json
          cat affected.json

      - name: Comment on PR
        uses: actions/github-script@v9
        with:
          script: |
            const fs = require('fs');
            const data = JSON.parse(fs.readFileSync('affected.json', 'utf8'));
            const baseRef = context.payload.pull_request.base.ref;
            const docs = data.docs || [];
            const pkgs = (data.changedPackages || []).map(p => p.name || p.dir);
            const marker = '<!-- docs-drift-check -->';
            // #9192 — the derivation now matches pages that NAME something the change
            // touched (symbol / route / SDK-method anchors) instead of pages that merely
            // mention a changed package. Everything the derivation could NOT see is
            // stated in the comment, at the point of use: the failure this fixed was not
            // the tool lying, it was a reader taking its silence for absence.
            const anchorList = data.anchors || [];
            const anchorless = data.anchorlessChanges || [];
            const overbroad = data.overbroadAnchors || [];
            const crossCutting = data.crossCuttingSymbols || [];
            const weak = data.weakAnchorsDropped || [];
            const coarse = data.packageMentionDocs || [];
            // ── HOW MUCH OF THE SDK BRIDGE'S DECLARED SURFACE THIS RUN COULD REACH (#9572)
            // The `sdk` anchor kind is what puts `api/client-sdk.mdx` on the list, and it
            // rides one hop: a registrar's `path:` tail selecting a route-ledger row. A row
            // no tail can select is invisible to EVERY run — measured on `9ff11921a`, 45 of
            // 221 client-bound rows are reachable and 176 are not, and 88 of those 176 name
            // a client method at least one hand-written page carries. None of that printed
            // anywhere before this block: the run simply never mentioned the SDK page and
            // looked healthy. A structural blind spot is exactly what the "what this run
            // could not see" section is for, so it is rendered here beside the per-run
            // narrowings rather than left for a reader to infer from a gap.
            const bridge = data.bridgeCoverage || null;
            // ── WHICH TREE THIS WAS COMPUTED ON (#9519) ─────────────────────────────
            // The row set is a fact about two commits and this comment named neither.
            // Pages are read with `readFileSync` from the WORKING TREE, and on a
            // `pull_request` run `actions/checkout` gives us merge(base, head) — a tree
            // that exists on no branch a reader can name and that GitHub drops once the
            // PR closes. The change set is a diff whose base was published only as
            // `origin/<base>`, a moving NAME. The re-derivation command below then sent
            // the reader to run the tool against THEIR tree, so a page that gained or
            // lost an anchor token on the base branch after their worktree was cut
            // produced a row they could not reproduce, with nothing here to say why.
            //
            // Measured: a reader did exactly that, grepped, found nothing, and reported
            // a correct row as a false positive; the follow-up then investigated a
            // defect class that does not exist in this tool — the anchor set is derived
            // fresh per run, with no cache, index or snapshot anywhere — at the cost of
            // a full round. Naming the tree is this file's own #9192 posture (say what
            // the run could not see) applied to one more thing the run already knows.
            //
            // The mapper change behind this is strictly ADDITIVE: `computedOn` is read
            // off git at the emit boundary, after every derivation has finished, so no
            // row above depends on it. Verified byte-for-byte against the pre-change
            // mapper on three refs — the `computedOn` block is the entire diff.
            const computedOn = data.computedOn || {};
            const parents = Array.isArray(computedOn.headParents) ? computedOn.headParents : [];
            // Parent ORDER on `refs/pull/N/merge` (base first, head second) is GitHub's
            // convention, not git's, so it is CHECKED against the event payload rather
            // than assumed — the pair is labelled only when the payload says which is
            // which, and stays unlabelled otherwise. A confidently wrong label would
            // send a reader off to rebuild the mirror image of the tree.
            const prHeadSha = context.payload.pull_request.head.sha;
            const mergedHead = parents.find(p => p === prHeadSha) || null;
            const mergedBase = mergedHead ? (parents.find(p => p !== mergedHead) || null) : null;
            // The COMMIT the mapper measured its diff from — the three-dot merge-base it
            // had already resolved, not `origin/<base>` re-read later. Naming the commit
            // is what makes the command replayable from any clone; naming the branch is
            // what made it a trap.
            const diffBase = computedOn.diffBase || null;
            const rederive = `node scripts/docs-audit/affected-docs.mjs --json ${diffBase || `origin/${baseRef}`}`;
            const treeBlock = (() => {
              // ⛔ Never degrade to silence here. An unnamed tree is the exact state this
              // block exists to end, so a missing identity is SAID, not omitted.
              if (!computedOn.head) {
                return ['', '> ⚠️ This run could not identify the commit it read, so the list above cannot be'
                  + ' tied to a tree. Re-derive against your own checkout and compare by hand.'];
              }
              const lines = [
                '',
                '<details><summary>Which tree this was computed on</summary>',
                '',
                mergedHead && mergedBase
                  ? `This run read \`content/docs\` from \`${computedOn.head}\` — the merge of head`
                    + ` \`${mergedHead}\` into base \`${mergedBase}\`, which is what \`actions/checkout\``
                    + ` gives a \`pull_request\` run. **Not** the PR head.`
                  : `This run read \`content/docs\` from \`${computedOn.head}\`.`,
                '',
                `A worktree cut from an older \`${baseRef}\` holds a different \`content/docs\`, so re-deriving`
                  + ` there can legitimately return a different list — that is a **different tree, not a wrong`
                  + ` row**. To answer on the same tree:`,
                '',
                '```sh',
              ];
              if (mergedHead && mergedBase) {
                lines.push(
                  '# while this PR is open — GitHub drops the merge commit once it closes',
                  `git fetch origin ${computedOn.head} && git checkout ${computedOn.head}`,
                  '# afterwards, rebuild it from the two parents, which stay fetchable',
                  `git fetch origin ${mergedBase} ${mergedHead} && git checkout -B drift-repro ${mergedBase} && git merge --no-ff ${mergedHead}`,
                  '',
                );
              } else {
                lines.push(`git fetch origin ${computedOn.head} && git checkout ${computedOn.head}`);
              }
              lines.push(rederive, '```');
              // A sha that misidentifies the tree is worse than no sha, so the one
              // condition under which it does is stated right where the sha is.
              if (computedOn.dirty === true) {
                lines.push('', '⚠️ That checkout carried **uncommitted changes**, so the commit above does not fully identify what was read.');
              } else if (computedOn.dirty === null) {
                lines.push('', '⚠️ This run could not check whether its checkout was clean, so the commit above may not fully identify what was read.');
              }
              lines.push('</details>');
              return lines;
            })();
            // ── WHAT THIS RUN COULD NOT COVER BELONGS IN THE HEADLINE (#11357) ────
            //
            // A README carries no `@docs-rule` block, exports no symbol, mounts no route
            // and declares no SDK method, so a README-only diff derives NOTHING and lands
            // in the zero-anchor arm below. Two such defects landed on one day (#11180 —
            // `packages/cli/README.md` advertising `os studio`, a command the CLI does not
            // ship; #11262 — `packages/console/README.md` asserting a `@object-ui/console`
            // fallback the code no longer performs), and neither was detectable by this
            // check on any run. A README IS documentation — the published front page of a
            // package on npm — so this is a hole, not a tolerable exclusion.
            //
            // The run was already HONEST about it: the `limits` line below names the file
            // it could not anchor, and that half is correct. But `limits` renders inside a
            // <details> fold, which GitHub renders COLLAPSED, under a headline reading
            // "**this run has no opinion** about the docs" — so a reviewer who does not
            // expand the fold reads the whole comment as "nothing to check". That is #9192
            // one surface up: the tool's silence taken for absence, this time by a reader
            // of its own headline.
            //
            // So the blind spot is stated where it cannot be missed, and the fold keeps the
            // detail. ⛔ NOTHING about anchor derivation changes here — this run finds
            // exactly what it found before, and every verdict is byte-identical whenever
            // `anchorless` is empty. The rendering is pinned both directions by
            // `scripts/docs-audit/check-drift-comment.mjs`, which runs THIS script against
            // fixture diffs; unconditional text would pass a one-direction pin.
            const anchorlessNames = `\`${anchorless.slice(0, 3).join('`, `')}\`${anchorless.length > 3 ? ', …' : ''}`;
            const notCovered = anchorless.length
              ? `⚠️ **${anchorless.length}** changed file(s) yielded no anchor (${anchorlessNames}), so the pages documenting them are **NOT COVERED by this run** — this is not a clean bill of health for those files.`
              : '';
            const limits = [];
            // Same names, one derivation: the headline and this line must never be able to
            // disagree about which files went unseen.
            if (anchorless.length) limits.push(`**${anchorless.length}** changed file(s) yielded no anchor (${anchorlessNames}) — pages documenting those are invisible to this run`);
            if (crossCutting.length) limits.push(`**${crossCutting.length}** cross-cutting symbol(s) contributed no route anchor: \`${crossCutting.join('`, `')}\``);
            if (overbroad.length) limits.push(`**${overbroad.length}** anchor(s) matched too much of the corpus to be a work list: \`${overbroad.join('`, `')}\``);
            if (weak.length) limits.push(`**${weak.length}** name(s) were too generic to anchor anything (single lowercase words)`);
            // ── WHY THOSE ROWS ARE UNREACHABLE, NOT JUST HOW MANY (#11867) ────────
            //
            // The line above used to end at the count, and a count is one population.
            // The census says there are three, and the difference is the whole reason
            // the split exists: the auth ledger's `56 of 56` and the rest ledger's
            // `46 of 87` print identically and are NOT the same finding — the first has
            // no in-repo registration site at all, so the discovery widening the second
            // one wants moves it by zero rows. That conflation already aimed one card
            // (#11178) at widening a recognizer that was never the constraint, and this
            // comment is the surface where a human meets the number.
            //
            // ⛔ SAME NAMES, ONE DERIVATION — the rule stated three lines up for the
            // `anchorless` pair, and it binds here for the same reason. `bridge.causes`
            // is a PARTITION of `bridge.unreachable`, computed ONCE inside
            // `bridgeCoverageFrom` and published whole; the parts are READ off the same
            // object as the total and never recomputed here. Re-deriving them from
            // `bridge.ledgers` would be a second derivation that agrees today, drifts
            // silently tomorrow, and renders a breakdown that sums to something the
            // headline beside it denies.
            //
            // And on numbers that do NOT partition that total, the split is WITHHELD and
            // the run says the census is broken, rather than printing three figures
            // beside a fourth they contradict. That state cannot arise from
            // `bridgeCoverageFrom` — `affected-docs.mjs --self-test` pins the partition
            // — which is what makes it a verdict here and not a fallback.
            //
            // `measured: false` keeps its honest arm: a run that supplied no ceiling
            // reports that WHY was not measured. It says so in words rather than
            // rendering three nulls or, worse, three zeroes — "nobody looked" is not
            // "none found", the same distinction `computedOn.dirty`'s null arm draws.
            const causes = (bridge && bridge.causes) || null;
            let bridgeCauses = '';
            if (causes && causes.measured === true) {
              const parts = causes.remediable + causes.structural + causes.undecided;
              bridgeCauses = parts === bridge.unreachable
                ? ` Of those **${bridge.unreachable}**: **${causes.remediable}** are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); **${causes.structural}** are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; **${causes.undecided}** are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here).`
                : ` ⛔ Its cause census is BROKEN — **${causes.remediable}** + **${causes.structural}** + **${causes.undecided}** is not the **${bridge.unreachable}** it claims to break down, so the split is withheld.`;
            } else if (causes && causes.measured === false) {
              bridgeCauses = ` ⚠️ Cause NOT measured on this run: ${causes.reason}. No cause may be read into the count above — "nobody looked" is not "none found".`;
            }
            if (bridge && bridge.measured && bridge.unreachable > 0) limits.push(`the SDK route bridge reached **${bridge.reachable}** of **${bridge.clientRows}** client-bound route-ledger rows — the other **${bridge.unreachable}** have no registrar \`path:\` tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run.${bridgeCauses} The rows themselves: \`node scripts/docs-audit/affected-docs.mjs --bridge-coverage\``);
            // ── THE RULE-CARRYING PAGE AN EMITTER DIFF CANNOT REACH (#11434) ──────
            //
            // Every line above is a REPORT about this run: a count this run produced, a
            // set this run derived. This one is not — it is a BOUNDARY of the anchor
            // model, and it is why it is pushed unconditionally.
            //
            // The pair it describes: a page states a rule by the rule's INPUTS, and the
            // code that carries the rule is its EMITTER. They share no identifier, so
            // precision-first anchoring (#9192) has nothing to join them with, and no
            // per-run signal can be computed — the absence of a shared token is the whole
            // defect, and an absence anchors nothing. Reported here rather than detected
            // because there is nothing to detect on.
            //
            // Measured, twice, on the specimen from #11434. On the recorded diff (#11430,
            // `sql-driver.ts` `createColumn`, re-run through today's mapper): 9 anchors
            // derived, 7 pages listed, and `content/docs/protocol/objectql/types.mdx` —
            // the page that diff falsified in four places — listed by none of them. Not
            // by the coarse fallback either: the page never names the changed package. On
            // today's tree an emitter-only change to `MAX_KEYABLE_VARCHAR_CHARS` derives
            // 1 anchor, lists 0 pages, and leaves `anchorlessChanges`, `crossCuttingSymbols`,
            // `overbroadAnchors` and `weakAnchorsDropped` all EMPTY — so no line above
            // fires, and the run reads as narrow rather than blind. Positive control on
            // the same tree and the same page: a change to `FieldSchema`, which that page
            // does name, lists it via `FieldSchema (symbol)`. The page is reachable; this
            // pairing is not.
            //
            // ⛔ NOT a detector, and must not grow into one here. The routes that would
            // buy real coverage — a curated code↔page ledger, a per-type anchor
            // vocabulary, authored enumeration marks — are the open question escalated as
            // #11817, and deciding the cheap half of it by implementation would pre-empt
            // that ruling. This says the gap exists; it does not close it.
            //
            // ⛔ And it is deliberately NOT the `notCovered` headline's posture. That
            // sentence is conditional because it reports what THIS diff left unanchored,
            // and unconditional text there would report nothing (see
            // `scripts/docs-audit/check-drift-comment.mjs`). This one is true on every
            // run by construction, exactly like the SDK bridge line above, and stating it
            // only sometimes would be the lie.
            limits.push('a page that states a rule by its **inputs** shares no identifier with the **emitter** that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on #11430: `content/docs/protocol/objectql/types.mdx` documents the text-family column mapping by the ObjectQL type names it maps FROM (`text` / `textarea` / `html`) while the diff changed `createColumn`; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.');
            // ── A KEY NAME IS NOT A KEY — THE SECOND BOUNDARY OF THE HAND-GREP REMEDY (#19093)
            //
            // The line above ends by prescribing a remedy: re-read the rule by hand in the
            // pages that restate it. This one states that remedy's OWN failure mode, because
            // the remedy is a name-based search and a name does not identify a key.
            //
            // The same spelling can be authorable on one schema and a `[REMOVED]` tombstone
            // on another, and a search result carries nothing that tells the two apart. So a
            // hand-grep that lands on a page's LIVE example reads it as evidence about the
            // DEAD key — a false alarm that is indistinguishable from a real find until
            // someone parses the value. That is not hypothetical: on #19059 a reviewer
            // grepping `content/docs` for `tools` reported `content/docs/ai/agents.mdx` as
            // contradicting the `agent.tools` tombstone, citing an example at `:161` that is
            // inside a `defineSkill({` block opened at `:155`. The page was already correct;
            // the cost was one stop-the-line alarm and a round of the implementing dev's
            // attention. The grep was the RIGHT method — it is what found the genuinely
            // falsified page on #19080, in exactly the blind spot the line above names.
            //
            // The names are the payload, and they are a census rather than the one instance:
            // measured on #19093 by walking the liveness ledger's governed types and reading
            // each top-level key's `[REMOVED]` marker. ⛔ A COUNT IS NOT A READING HERE — the
            // whole defect is that a count cannot tell two identically-named keys apart, so
            // this line prints the names and any re-measure must do the same.
            //
            // ⛔ Its radius is stated because it is NOT the whole class. Top-level keys of
            // governed types only: a key retired through the `.strict()` guidance-map route
            // instead of `retiredKey()` leaves NO tombstone in the walked shape and so cannot
            // appear here at all — `tool.category` is retired that way while
            // `AIToolDefinition.category` stays live, the identical trap one radius out.
            //
            // ⛔ Sited here, not in the liveness ledger's `_note`, and that was a choice
            // between two candidates. The ledger records the verdict; this comment reaches
            // the reader AT THE MOMENT THE METHOD IS PRESCRIBED, on every run, in the same
            // fold as the prescription. A reader alarmed about `agent.tools` opens the AGENT
            // ledger — so a discriminator written on the SKILL ledger sits on the half they
            // have no reason to open, which is the failure this card exists to stop.
            //
            // Unconditional by construction, like the line above and for the same reason:
            // the collision is a property of the schemas, not of any diff. Pinned byte-exact
            // on every case in `scripts/docs-audit/check-drift-comment.mjs`
            // (`SAME_NAME_DIFFERENT_SHAPE`) — an unconditional line nothing pins is one that
            // can vanish silently, which is the defect that file was written for.
            limits.push('a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a `[REMOVED]` tombstone on another for each of `active`, `aria`, `joins`, `objects`, `template`, `tools` and `version` (censused on #19093 over the liveness ledger\'s governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on #19059: `content/docs/ai/agents.mdx` was reported as contradicting the `agent.tools` tombstone over its `tools:` example at `:161`, which is inside the `defineSkill({` block opened at `:155` — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES `SkillSchema`, and as an `AgentSchema` it FAILS at `tools` with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a `.strict()` guidance map leaves no tombstone in the walked shape and none of them here (`tool.category`, live as `AIToolDefinition.category`).');
            // A broken scan is not a coverage number and must not read like one — see
            // `bridgeCoverageFrom`. Rendered outside the collapsed section below, because
            // "the bridge could not read the ledgers" is not a limit of this run, it is a
            // defect in the tool that every subsequent run will keep reporting as clean.
            //
            // ⛔ NOT "structurally empty" any more, which is what this line used to say: the
            // verdict list also carries PARTIAL reads, where the scan produced a perfectly
            // ordinary-looking population that is simply smaller — or mis-bound — than what
            // the ledgers declare. Wording that promises emptiness would let a reader skip
            // exactly the case that renders like a clean one.
            const bridgeBroken = (bridge && bridge.measured && (bridge.brokenScan || []).length)
              ? ['', `> ⛔ The SDK route bridge's own scan is broken, not clean: ${bridge.brokenScan.join('; ')}. Treat every \`sdk\` row above as unavailable rather than absent.`]
              : [];
            // Rendered whenever there is anything to say, INCLUDING when the only thing to
            // say is "the wide net exists and holds N pages". A short list is the right
            // answer here, but a reader must be able to tell a short list from a blind one
            // without leaving the PR.
            //
            // Since #11434 `limits` is never empty — the rule-carrying line above holds on
            // every run — so this fold now renders on every run too. The guard stays: it is
            // what keeps the fold from rendering empty if that line is ever moved out, and
            // an empty "what this run could not see" is the reading it exists to refuse.
            const limitsBlock = (limits.length || coarse.length)
              ? ['', '<details><summary>What this run could not see</summary>', '', ...limits.map(l => `- ${l}`), ...(limits.length ? [''] : []), `Coarse fallback — **${coarse.length}** page(s) merely *mention* a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): \`${rederive}\` → \`packageMentionDocs\`.`, '</details>']
              : [];
            // The release-owned rows are PARTITIONED OUT of the editable list, never
            // dropped (#6893, following the #4920 ruling). They keep getting audited —
            // `docs` above is still the full set the audit workflow is scoped to — but
            // listing them beside editable pages steers a reader who treats this comment
            // as a worklist into the one edit AGENTS.md forbids outright. So they get
            // their own section, carrying the instruction that makes them safe.
            const readOnly = data.releaseOwnedDocs || [];
            const editable = docs.filter(d => !readOnly.includes(d));
            // Above this many editable rows, the list stops carrying per-PR information: a
            // hub package (referenced by nearly every hand-written doc) posts the same
            // near-invariant dump on every PR that touches it, relayed in full into every
            // subscribed agent session on every push (#9037). Measured against this repo's
            // actual per-package referencing-doc counts: @objectstack/spec sits at 106
            // editable rows, the next-largest non-hub packages (cli/core/runtime) at 18-19,
            // and the smallest packages that still warrant a real list (e.g.
            // @objectstack/client) at 11 — 15 sits in the gap between those two clusters,
            // so the suggested default is kept as-is.
            const EDITABLE_ROW_CAP = 15;
            const capped = editable.length > EDITABLE_ROW_CAP;
            let body;
            if (docs.length === 0) {
              // "Nothing found" and "I derived nothing to look for" are DIFFERENT results
              // and must never render alike — that conflation is #9192's own subject.
              // Since #11357 a THIRD result is separated from both: "part of this diff was
              // never looked at". `anchorless.length` is what tells it apart, and it is
              // already known here, at headline-composition time.
              //
              // ⛔ The ✅ is DROPPED whenever a file went unanchored, deliberately: a green
              // tick is the clean-bill glyph, and "no page names the anchors I derived" is
              // not a clean bill when some of the diff derived no anchor to name.
              //
              // ⛔ And since #11356 the ✅ is gone from this arm ENTIRELY — including the run
              // where nothing went unanchored, which is where it used to live. "No page names
              // the anchors I derived" is a fact about the NAMING RELATION, not about the
              // docs: a page is listed because it ALREADY names a changed token, so a change
              // that WIDENS an enumerable vocabulary can never be caught here — the new
              // members' absence from the page IS the defect, and an absence names nothing.
              // Measured on #11347 (six new flow-expression functions): 9 anchors derived, 0
              // pages named them, ✅ — while `content/docs/automation/flows.mdx` carried a
              // table enumerating the available bindings that the PR had just made
              // incomplete, and a reviewing seat almost passed the PR on that tick.
              //
              // ⚠️ This does NOT catch that class, and must not be read as doing so. Nothing
              // in the anchor model can (three in-model routes were measured to fail on the
              // one real instance; the authoring-mark route that would catch it is escalated
              // as #11817). What it stops is the run CLAIMING it did: the verdict now says
              // only what it measured — anchors were derived, no page named them — and leaves
              // the clean-bill glyph to a run that earned one.
              const headline = anchorList.length === 0
                ? (anchorless.length
                    ? `${notCovered} Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from **${pkgs.length}** changed package(s)).`
                    : `Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from **${pkgs.length}** changed package(s)), so **this run has no opinion** about the docs.`)
                : (anchorless.length
                    ? `**${anchorList.length}** anchor(s) derived from **${pkgs.length}** changed package(s); no hand-written page names any of them. ${notCovered}`
                    : `**${anchorList.length}** anchor(s) derived from **${pkgs.length}** changed package(s); no hand-written page names any of them, so this run has **nothing to list** — **not a clean bill of health**. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.`);
              // The tree identity is rendered here only when anchors WERE derived: that
              // is the run with an opinion ("no page names any of them"), and a reader
              // whose own tree does yield a row is owed the reason. With no anchors the
              // run has no opinion to disagree with, and the bytes would be pure noise on
              // every docs-tooling-only PR (#9037 — every byte here is relayed).
              body = [marker, '### 📓 Docs Drift Check', headline, ...bridgeBroken, ...limitsBlock,
                ...(anchorList.length ? treeBlock : [])].join('\n');
            } else {
              const detail = (data.detail || []).reduce((m, d) => (m[d.doc] = d.via, m), {});
              const row = d => `- \`${d}\`${detail[d] ? `  _(via ${detail[d].join(', ')})_` : ''}`;
              body = [
                marker,
                '### 📓 Docs Drift Check',
                // The row list below is a work list, and a work list that silently omits
                // part of the diff is read as the whole of it — so the same sentence rides
                // this headline too (#11357). It is the same conditional: with nothing
                // unanchored, this line is byte-identical to what it always was.
                `This PR changes **${pkgs.length}** package(s): ${pkgs.map(p => `\`${p}\``).join(', ')}, touching **${anchorList.length}** documentable anchor(s).${anchorless.length ? ` ${notCovered}` : ''}`,
              ];
              if (capped) {
                // NO row list above the cap — folding rows behind a details tag would
                // still ship every row's bytes to the event relay that pushes this
                // comment into subscribed agent sessions; only actually omitting them
                // caps the tokens. The re-derivation command is the escape hatch: full
                // fidelity is one command away, never lost.
                body.push(
                  '',
                  `**${editable.length}** hand-written doc(s) name something this change touched — list omitted above ${EDITABLE_ROW_CAP} rows. Re-derive on the tree named below: \`${rederive}\`.`,
                );
                if (readOnly.length) {
                  body.push(
                    '',
                    `⛔ **${readOnly.length}** release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.`,
                  );
                }
              } else {
                if (editable.length) {
                  body.push(
                    '',
                    `**${editable.length}** hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:`,
                    '',
                    editable.map(row).join('\n'),
                  );
                }
                if (readOnly.length) {
                  body.push(
                    '',
                    `⛔ **${readOnly.length}** release-owned page(s) ${editable.length ? 'also ' : ''}name something this change touched. These are **read-only**:`,
                    '',
                    readOnly.map(row).join('\n'),
                    '',
                    '> `content/docs/releases/` is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release',
                    '> notes are written centrally at release time, and a code PR that edits them is the exact PR',
                    '> that guardrail exists to stop. They are still audited — read-only. If one of them is actually',
                    '> wrong, **file an issue** or open a dedicated docs-only PR; do not edit it here.',
                  );
                }
              }
              body.push(...bridgeBroken);
              body.push(...limitsBlock);
              body.push(...treeBlock);
              body.push(
                '',
                '> Advisory only, and a **precision-first** one (#9192): a page is listed because it names a',
                '> symbol, wire route or SDK method this diff touched — not because it mentions a changed',
                '> package. Each row says which anchor put it there, so a wrong row is reportable rather than',
                '> merely annoying. To re-verify, run the `docs-accuracy-audit` workflow scoped to these files:',
                // Pinned to the commit the mapper measured from, and pointed at the tree
                // named above (#9519): run this against a different tree and a different
                // list is the CORRECT answer — which is exactly how a right row once got
                // reported as a wrong one.
                '> `node scripts/docs-audit/affected-docs.mjs ' + (diffBase || `origin/${baseRef}`) + '` → pass the list as',
                computedOn.head
                  ? '> `args.docs`, on the commit named under **Which tree this was computed on**.'
                  : '> `args.docs`.',
              );
              body = body.join('\n');
            }
            // ── Delivery, and ONLY delivery, tolerates platform weather (#9373) ────
            //
            // Everything above is the VERDICT. Everything below merely carries it to the
            // PR conversation. Those are two different failures and must not share one
            // outcome:
            //
            //   the scan ran wrong / the body could not be built  → red job (unchanged)
            //   the computed advisory could not be POSTED         → green job, said aloud
            //
            // Measured: this job died four consecutive times on PR #9370 (17:17Z-18:24Z,
            // 2026-08-17), every time with
            //   HttpError: No server is currently available to service your request.
            //   response: { url: '.../issues/9370/comments', status: 503 }
            // github-script hands any throw from this script to `main().catch(handleError)`
            // -> `core.setFailed('Unhandled error: ...')`, so an advisory-only check went
            // red on GitHub's weather and cost four re-runs that no local change could fix.
            // That URL is the endpoint of BOTH `listComments` (GET) and `createComment`
            // (POST), so the recorded log cannot say which call was rejected — both are
            // covered below.
            //
            // ⛔ Deliberately NOT `continue-on-error: true`, and NOT a bare catch:
            //   - this step also parses `affected.json` and builds `body`, so blanket
            //     tolerance would let a malformed scan result or an over-long (422) comment
            //     read as a clean run — real breakage wearing a green tick;
            //   - a swallowed failure leaves the run saying NOTHING, and then "could not
            //     tell" renders exactly like "no drift". That is the same defect in the
            //     opposite mask, and it is precisely what this file's #9192 posture — say
            //     what the run could not see — exists to prevent.
            // So: a narrow transient class, bounded retries, and, when they are spent, a
            // loud statement in the run's own output of exactly what was lost.

            // Transient = the request never received a considered answer.
            //   5xx  the server declined to serve it. octokit also normalises
            //        network-layer failures into a 500-shaped RequestError; the explicit
            //        code set covers any that arrive unnormalised.
            //   429  rate limited.
            //   403 + a rate-limit signature — GitHub answers a SECONDARY rate limit with
            //        403 as well as 429, so the signature, never the status alone, is what
            //        separates it from a genuine permission denial.
            // Everything else stays fatal on purpose: 401 / plain 403 (the `permissions:`
            // block above is wrong), 404 (wrong target), 422 (the body this workflow built
            // is not postable — e.g. past the COMMENT cap), and any non-HTTP error such as
            // a TypeError in the code above. Those are this repo's own bugs and must keep
            // failing the job.
            //
            // That cap is MEASURED, in UTF-8 BYTES, ⛔ not the 65,536 characters this
            // comment used to name: a comment stores 262,144 bytes and refuses 262,145
            // with a real 422, on BOTH `issues.createComment` and `issues.updateComment`
            // below — objectstack#18826, bisected to one byte on each endpoint. ⛔ Do not
            // re-derive 65,536 from the refusal itself: GitHub's own 422 text still reads
            // "maximum is 65536 characters" and #18826 falsified it in both unit and
            // value, storing a 262,144-CHARACTER comment.
            const TRANSIENT_NETWORK_CODES = new Set([
              'ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'EAI_AGAIN', 'ENOTFOUND', 'EPIPE',
              'EHOSTUNREACH', 'ENETUNREACH', 'UND_ERR_SOCKET', 'UND_ERR_CONNECT_TIMEOUT',
            ]);
            const isTransient = (error) => {
              if (error && TRANSIENT_NETWORK_CODES.has(error.code)) return true;
              const status = error && typeof error.status === 'number' ? error.status : null;
              if (status === null) return false;
              if (status >= 500 || status === 429) return true;
              if (status === 403) {
                const remaining = error.response?.headers?.['x-ratelimit-remaining'];
                return String(remaining) === '0'
                  || /secondary rate limit|abuse detection/i.test(String(error.message || ''));
              }
              return false;
            };

            // Bounded, and deliberately short. The measured incident ran over an hour — no
            // retry budget rides that out, and pretending otherwise only burns runner
            // minutes before degrading anyway. The retries are for a BLIP; the visible
            // degradation below is what handles an incident. The delays are a judgement,
            // not a measurement.
            const RETRY_DELAYS_MS = [3000, 9000];
            const ATTEMPTS = RETRY_DELAYS_MS.length + 1;
            const deliver = async (label, call) => {
              for (let attempt = 0; ; attempt++) {
                try {
                  return await call();
                } catch (error) {
                  if (!isTransient(error) || attempt >= RETRY_DELAYS_MS.length) throw error;
                  const wait = RETRY_DELAYS_MS[attempt];
                  core.info(`${label}: transient ${error.status ?? error.code} — retrying in ${wait}ms (attempt ${attempt + 2}/${ATTEMPTS})`);
                  await new Promise((resolve) => setTimeout(resolve, wait));
                }
              }
            };

            // Degrade VISIBLY — the house pattern (check-links.yml's "the link check did
            // not run", cross-repo-issue-closer.yml's missing-token notice). A reader looks
            // for this advisory's verdict on the PR; when it cannot be put there, the run
            // page must say so in full: what failed, what the reader must NOT infer from
            // whatever is on the PR, and the verdict itself — degraded but delivered,
            // never lost.
            const degrade = async (stage, error, staleNote) => {
              const detail = typeof error.status === 'number' ? `HTTP ${error.status}` : (error.code || 'error');
              // Octokit messages usually end in a full stop; ours supplies its own.
              const reason = `${detail}: ${String(error.message || '').replace(/\s*\.\s*$/, '')}`;
              const note = [
                '## ⚠️ Docs Drift Check — advisory computed, but NOT posted to this PR',
                '',
                `The scan completed; this is a **delivery** failure only. \`${stage}\` was rejected on all`,
                `${ATTEMPTS} attempts: \`${reason}\`.`,
                '',
                `- ${staleNote}`,
                '- The verdict this run computed is reproduced below. It is **not** on the pull request.',
                '- This job is **green on purpose**: its conclusion reflects the scan, not the',
                '  deliverability of its courtesy comment (#9373). The check is advisory either way.',
                '- Re-run this job to retry delivery once the API recovers.',
                '',
                '---',
                '',
                body,
                '',
              ].join('\n');
              try {
                await core.summary.addRaw(note).write();
              } catch (summaryError) {
                // The summary is the richer channel, the annotation the reliable one.
                // Losing the richer one must not restore the silence this exists to prevent.
                core.info(`Could not write the job summary: ${summaryError.message}`);
              }
              core.warning(
                `The docs-drift advisory was computed but could not be posted to this PR: `
                + `${stage} failed ${ATTEMPTS}x with ${reason}. ${staleNote} `
                + `The verdict is in this run's job summary. Transient GitHub API failure (#9373) — `
                + `the job stays green because the scan itself is unaffected.`,
                { title: 'Docs drift advisory not delivered' },
              );
            };

            let comments;
            try {
              ({ data: comments } = await deliver('issues.listComments', () => github.rest.issues.listComments({
                owner: context.repo.owner, repo: context.repo.repo, issue_number: context.issue.number,
              })));
            } catch (error) {
              if (!isTransient(error)) throw error;
              // Without the listing there is no way to tell an update from a create.
              // Posting blind would strand a SECOND advisory comment that the marker dedup
              // then updates forever alongside the first, and every comment here is relayed
              // into subscribed agent sessions (#9037). Saying so costs less than
              // duplicating.
              await degrade(
                'issues.listComments',
                error,
                'This run could not even determine whether an advisory comment exists on this PR; if one is shown there, it is from an earlier push.',
              );
              return;
            }

            const existing = comments.find(c => c.body && c.body.includes(marker));
            try {
              if (existing) {
                await deliver('issues.updateComment', () => github.rest.issues.updateComment({ owner: context.repo.owner, repo: context.repo.repo, comment_id: existing.id, body }));
              } else {
                await deliver('issues.createComment', () => github.rest.issues.createComment({ owner: context.repo.owner, repo: context.repo.repo, issue_number: context.issue.number, body }));
              }
            } catch (error) {
              if (!isTransient(error)) throw error;
              await degrade(
                existing ? 'issues.updateComment' : 'issues.createComment',
                error,
                existing
                  ? `The \`docs-drift-check\` comment on this PR still shows an EARLIER run's verdict — this run could not refresh it.`
                  : 'No advisory comment was posted on this PR for this run.',
              );
            }