@anchrd/intel-api 0.12.5 → 0.14.0

package/dist/adapters/cloudflare/cloudflare.js

@@ -259,6 +259,7 @@ export default {
             content: createContentStore(env.CONTENT),
             semantic: env.AI && env.SEARCH ? createSemanticIndex({ ai: env.AI, index: env.SEARCH }) : undefined,
             converter: env.AI ? createDocumentConverter(env.AI) : undefined,
+            hash: async (content) => await sha256Hex(crypto, content),
             now: () => new Date(),
         });
         for (const message of batch.messages) {

package/dist/adapters/cloudflare-api/cloudflare-api.js

@@ -19,6 +19,33 @@ const ApiOrigin = "https://api.cloudflare.com/client/v4";
  */
 const MaxPages = 20;
 const PerPage = 50;
+/**
+ * ⚠️ Cloudflare's ceiling on `/ai/models/search`, and a DIFFERENT number from `PerPage` above —
+ * the limit belongs to the endpoint, not to the account. Neither may be copied onto the other's
+ * call: 50 on the model catalog halves it, 100 on the log is refused outright.
+ *
+ * And the two fail in opposite ways, of which this is the worse one. The log endpoint REFUSES with
+ * `HTTP 400 Number must be less than or equal to 50` — loud, and found in a day (#294). This one
+ * IGNORES: measured against the live account (#297), `per_page=200` and `per_page=1000` both answer
+ * `HTTP 200` with no error and `result_info.per_page: 100`.
+ *
+ * ⚠️ `result_info.total_count` cannot be used to notice a short answer either. The same account
+ * reports `total_count: 286` and returns 61 entries on page 1, with page 2 empty — a reader that
+ * paginated on that figure would loop over empty pages and call the result partial. The truthful
+ * signal is a page that came back FULL, which the log reader already uses and this one does not
+ * yet (anchrd/intel#330).
+ */
+const ModelPerPage = 100;
+/**
+ * How many pages of the model catalog are read before the reader gives up.
+ *
+ * ⚠️ It is a runaway brake and not a window, which is the opposite of `MaxPages` above. The log has
+ * more calls than anybody wants to read; the catalog is finite and small — 61 entries on this
+ * account — so the loop normally ends on the first short page and this number is never reached.
+ * What it guards against is an endpoint that answers a full page forever, and a loop inside a
+ * request nobody is watching.
+ */
+const ModelMaxPages = 10;
 /**
  * The gateway's log entry, read tolerantly.
  *
@@ -142,56 +169,138 @@ export function createCloudflareApi(deps) {
     }
     return {
         async gatewayCalls(query) {
-            const calls = [];
-            let partial = false;
-            for (let page = 1; page <= MaxPages; page += 1) {
-                const body = await get(`/accounts/${encodeURIComponent(deps.accountId)}/ai-gateway/gateways/${encodeURIComponent(deps.gatewayId)}/logs`, {
-                    page: String(page),
-                    per_page: String(PerPage),
-                    start_date: query.since.toISOString(),
-                    end_date: query.until.toISOString(),
-                    order_by: "created_at",
-                    order_by_direction: "desc",
-                    // ⚠️ Only documented scalar parameters travel. The endpoint also takes a `filters` array
-                    // whose query encoding Cloudflare documents nowhere — neither the reference nor the
-                    // curl example shows it — so a guess at it would either be ignored (a slow read) or
-                    // rejected (no read at all), and there is no way to tell those apart from the status.
-                    // The agent is therefore picked out below, from the metadata the runtime stamped.
-                });
-                const parsed = LogResponse.safeParse(body);
-                // A shape this reader cannot make sense of is a failure, not an empty window: an empty
-                // window reads as "this agent cost nothing".
-                if (!parsed.success) {
-                    throw new IntelError(502, "cloudflare_api_unreadable", "The Cloudflare API answered in a shape this version does not understand");
-                }
-                const entries = parsed.data.result ?? [];
-                for (const entry of entries) {
-                    const metadata = readMetadata(entry.metadata);
-                    if (metadata.agentId !== query.agentId)
-                        continue;
-                    calls.push({
-                        runId: typeof metadata.runId === "string" ? metadata.runId : null,
-                        model: entry.model ?? "",
-                        cost: entry.cost ?? 0,
-                        at: entry.created_at ?? query.until.toISOString(),
+            const logPath = `/accounts/${encodeURIComponent(deps.accountId)}/ai-gateway/gateways/${encodeURIComponent(deps.gatewayId)}/logs`;
+            /**
+             * One window of the log, optionally cut to this agent by the gateway itself.
+             *
+             * The encoding Cloudflare documents nowhere, measured against the live gateway (#274):
+             * `filters` is a URL-encoded JSON array, and `value` is an ARRAY even for a single value.
+             *
+             *   filters=[{"key":"metadata.value","operator":"eq","value":["<id>"]}]  → 200, filtered
+             *   value as a scalar string  → 400 `Expected array, received string`
+             *   filters as a JSON object  → 400 `Expected array, received object`
+             *   filters[0][key]=… (brackets) and filters.0.key=… (dots) → 200, SILENTLY IGNORED
+             *
+             * ⚠️ The last line is why this was never guessed at: two of the five spellings answer 200
+             * with the whole unfiltered window, which reads exactly like a filter that matched
+             * everything. Two filters combine with AND (measured with `metadata.key` plus `runId`).
+             */
+            async function read(pages, filtered) {
+                const calls = [];
+                let partial = false;
+                for (let index = 1; index <= pages; index += 1) {
+                    const body = await get(logPath, {
+                        page: String(index),
+                        per_page: String(PerPage),
+                        start_date: query.since.toISOString(),
+                        end_date: query.until.toISOString(),
+                        order_by: "created_at",
+                        order_by_direction: "desc",
+                        ...(filtered
+                            ? {
+                                filters: JSON.stringify([
+                                    { key: "metadata.value", operator: "eq", value: [query.agentId] },
+                                ]),
+                            }
+                            : {}),
                     });
+                    const parsed = LogResponse.safeParse(body);
+                    // A shape this reader cannot make sense of is a failure, not an empty window: an empty
+                    // window reads as "this agent cost nothing".
+                    if (!parsed.success) {
+                        throw new IntelError(502, "cloudflare_api_unreadable", "The Cloudflare API answered in a shape this version does not understand");
+                    }
+                    const entries = parsed.data.result ?? [];
+                    // ⚠️ The local check stays even under the server-side filter, and it is no longer belt
+                    // and braces: it is the only thing that could notice the filter matching the wrong rows.
+                    for (const entry of entries) {
+                        const metadata = readMetadata(entry.metadata);
+                        if (metadata.agentId !== query.agentId)
+                            continue;
+                        calls.push({
+                            runId: typeof metadata.runId === "string" ? metadata.runId : null,
+                            model: entry.model ?? "",
+                            cost: entry.cost ?? 0,
+                            at: entry.created_at ?? query.until.toISOString(),
+                        });
+                    }
+                    if (entries.length < PerPage)
+                        return { calls, partial: false };
+                    partial = index === pages;
                 }
-                if (entries.length < PerPage)
-                    return { calls, partial: false };
-                partial = page === MaxPages;
+                return { calls, partial };
             }
-            return { calls, partial };
+            const answer = await read(MaxPages, true);
+            /**
+             * ⚠️ Anything at all is taken at face value, and that is a decision with a hole in it. A
+             * filter that degraded PARTLY — matching some of this agent's rows and not others — returns
+             * here, and the under-count is then handed out as `partial: false`, which claims to be a
+             * total. The probe below cannot see that case, because the probe is only reached when the
+             * filtered read found nothing. It is the price of not reading the whole log twice on every
+             * request, and it is worth knowing before somebody reads `partial: false` as "complete".
+             */
+            if (answer.calls.length > 0)
+                return answer;
+            /**
+             * ⚠️ Zero is the ONE answer this reader may not take at face value, and the reason is the
+             * way `filters` fails. Measured: `cached` filtered to `["false"]` answers 200 with zero rows
+             * although every row in that window carries `cached: false` — a value the index does not
+             * match empties the page instead of being refused. So the day metadata stops being indexed
+             * the way it is today, this would report "cost nothing" for an agent that spent money, under
+             * `status: "read"`. That is precisely the sentence #251 exists for.
+             *
+             * One unfiltered page is the probe: if the newest calls contain any of this agent's, the
+             * filter is lying and the honest answer is that the log could not be read. It costs one
+             * request and only in the empty case, which is a fresh agent or a quiet window — and in the
+             * case it replaces, a quiet agent on a busy gateway, it costs 2 requests where reading the
+             * whole log unfiltered used to cost 20.
+             *
+             * ⚠️ It is a probe and not a proof: an agent whose only calls are older than the newest
+             * `PerPage` of the whole gateway is invisible to it, and that case still reports zero. What
+             * it buys is that a filter which stopped working ENTIRELY cannot pass as silence.
+             *
+             * ⚠️ A probe that cannot run leaves the answer standing, deliberately. The read this is
+             * checking SUCCEEDED and said "no calls"; letting a second opinion that never arrived turn
+             * that into `unreadable` would report an outage for the most ordinary state there is — a
+             * fresh agent — because one extra request met a 429. The guard is a second opinion, not the
+             * answer.
+             */
+            const probe = await read(1, false).catch(() => null);
+            if (probe === null || probe.calls.length === 0)
+                return answer;
+            throw new IntelError(502, "cloudflare_api_unreadable", "The Cloudflare API answered no calls for this agent while its own log holds some");
         },
         async workersAiModels() {
-            const body = await get(`/accounts/${encodeURIComponent(deps.accountId)}/ai/models/search`, {
-                per_page: "200",
-                hide_experimental: "true",
-            });
-            const parsed = ModelResponse.safeParse(body);
-            if (!parsed.success) {
-                throw new IntelError(502, "cloudflare_api_unreadable", "The Cloudflare API answered in a shape this version does not understand");
+            const models = [];
+            for (let index = 1; index <= ModelMaxPages; index += 1) {
+                const body = await get(`/accounts/${encodeURIComponent(deps.accountId)}/ai/models/search`, {
+                    page: String(index),
+                    per_page: String(ModelPerPage),
+                    hide_experimental: "true",
+                });
+                const parsed = ModelResponse.safeParse(body);
+                if (!parsed.success) {
+                    throw new IntelError(502, "cloudflare_api_unreadable", "The Cloudflare API answered in a shape this version does not understand");
+                }
+                const entries = parsed.data.result ?? [];
+                models.push(...entries.map(readModel));
+                // ⚠️ A SHORT page is the end, and a full one is not a reason to believe the answer was
+                // complete (#330). Before this the reader took page one and stopped: a model past position
+                // 100 was simply absent from the select, `liveStatus` still said `read`, and nothing said
+                // the list was shorter than the account. A missing entry has no `source` to mark stale
+                // with, so the per-entry labelling that covers a fallback cannot cover this at all.
+                //
+                // ⚠️ `result_info.total_count` is NOT the test, which is why it is not parsed. Measured on
+                // the live account (#297): it reports 286 while page one returns 61 and page two is empty.
+                // A reader that paginated on that figure would loop over empty pages and call the result
+                // partial. The full page is the only honest signal.
+                if (entries.length < ModelPerPage)
+                    return models;
             }
-            return (parsed.data.result ?? []).map(readModel);
+            // Ten full pages is not a big account, it is an endpoint that stopped ending. Refusing is the
+            // honest answer: the catalog service falls back to its built-in table and the screen says the
+            // figures may be old — better than a list that is silently missing whatever came after.
+            throw new IntelError(502, "cloudflare_api_unreadable", "The Cloudflare API kept answering full pages of models past the read limit");
         },
     };
 }

package/dist/adapters/db/db-indexing.js

@@ -1,3 +1,7 @@
+// How much of a chunk is kept as the passage a searcher is shown. The same 480 characters
+// `hydrateVisibleCitations` cuts out of the full-text row, so a citation reads the same length
+// whether it came from a card's own vector or from the fallback beside it.
+const maxPassageCharacters = 480;
 function mapTarget(row, contentKeys) {
     return {
         nodeId: row.node_id,
@@ -68,6 +72,81 @@ export function createNodeIndexRepository(db) {
                     .bind(target.versionId, target.nodeId, chunk.title, chunk.text, target.nodeId, target.versionId)),
             ]);
         },
+        /**
+         * ⚠️ `archived_at IS NOT NULL` carries this on its own, and it is the whole guard
+         * (anchrd/intel#348). `getTarget` above answers null for two reasons and only one of them means
+         * "purge": the other is a queue message for a version a later save superseded, and Cloudflare
+         * Queues deliver at least once, so those arrive as a matter of course. Acting on one would empty
+         * the vector index of a live board behind the back of the save that had just filled it — and
+         * nothing would report it, because a search that finds less is not an error.
+         *
+         * ⚠️ Deliberately NOT `current_version_id = v.id` as well, although that is what would make this
+         * the mirror image of `getTarget`. Symmetry is not a reason to write a condition: once the node
+         * IS archived, every version of it says the same thing about that node's vectors, so the extra
+         * clause could only ever refuse a purge that was right. A condition no test can turn red is a
+         * condition the next reader has to guess the purpose of.
+         */
+        async archivedNodeId(versionId) {
+            const row = await db
+                .prepare(`SELECT n.id AS node_id
+          FROM node_versions v
+          JOIN nodes n ON n.id = v.node_id
+          WHERE v.id = ? AND n.archived_at IS NOT NULL`)
+                .bind(versionId)
+                .first();
+            return row?.node_id ?? null;
+        },
+        async listVectors(nodeId) {
+            const result = await db
+                .prepare(`SELECT chunk_key, fingerprint, passage FROM node_vectors WHERE node_id = ?`)
+                .bind(nodeId)
+                .all();
+            return (result.results ?? []).map((row) => ({
+                chunkKey: row.chunk_key,
+                fingerprint: row.fingerprint,
+                passage: row.passage,
+            }));
+        },
+        /**
+         * The record of every vector this node has, replacing the record it had.
+         *
+         * ⚠️ The same delete-then-insert in ONE batch as `replace` above, and the same guard in front of
+         * every statement: a pass for a version that is no longer current, or for a node that has been
+         * archived meanwhile, writes nothing at all rather than half a record. What must not happen is
+         * the delete landing without the inserts — the next pass would then re-embed the whole board,
+         * which is exactly the cost anchrd/intel#301 exists to avoid.
+         */
+        async replaceVectors(target, records) {
+            await db.batch([
+                db
+                    .prepare(`DELETE FROM node_vectors WHERE node_id = ? AND EXISTS (
+            SELECT 1 FROM nodes
+            WHERE id = ? AND current_version_id = ? AND archived_at IS NULL
+          )`)
+                    .bind(target.nodeId, target.nodeId, target.versionId),
+                ...records.map((record) => db
+                    .prepare(`INSERT INTO node_vectors (node_id, chunk_key, version_id, fingerprint, passage)
+              SELECT ?, ?, ?, ?, ? WHERE EXISTS (
+                SELECT 1 FROM nodes
+                WHERE id = ? AND current_version_id = ? AND archived_at IS NULL
+              )`)
+                    .bind(target.nodeId, record.chunkKey, target.versionId, record.fingerprint, record.passage.slice(0, maxPassageCharacters), target.nodeId, target.versionId)),
+            ]);
+        },
+        /**
+         * The record of one node, gone — because its vectors are (anchrd/intel#348).
+         *
+         * ⚠️ No guard at all, and the absence is deliberate in both directions. There is no
+         * `archived_at IS NOT NULL`: the state this write exists to prevent is a row that outlives the
+         * vector it names, and a node restored between the deletion and this statement would keep
+         * exactly that — a record claiming vectors that are gone, which the next pass reads as "already
+         * embedded" and skips, leaving those cards silently unfindable. And there is no version
+         * condition: `archivedNodeId` has already established which node this is, from that same
+         * version, and a second reading of a moving row is a second answer rather than a safer one.
+         */
+        async deleteVectors(nodeId) {
+            await db.prepare("DELETE FROM node_vectors WHERE node_id = ?").bind(nodeId).run();
+        },
         async markIndexed(versionId, occurredAt) {
             await db
                 .prepare(`UPDATE node_index_state

package/dist/adapters/db/db.js

@@ -289,20 +289,17 @@ export function createNodeRepository(deps) {
          * ⚠️ `nodes` arrive parents before children: `parent_id REFERENCES nodes(id)` is checked as
          * each row lands, and a child before its parent would abort the batch that is otherwise valid.
          * The service owns that order; this only writes what it is handed.
-         *
-         * `context_policy` is the dead column migration 0009 explains; 'relevant' is the fixed value
-         * `insertNode` writes for the same reason.
          */
         async importTree(input) {
             const statements = [
                 deps.db
                     .prepare(`INSERT INTO nodes (
-            id, parent_id, kind, title, description, context_policy, owner_id,
+            id, parent_id, kind, title, description, owner_id,
             current_version_id, created_at, updated_at, archived_at
           ) SELECT
             json_extract(value, '$.id'), json_extract(value, '$.parentId'),
             json_extract(value, '$.kind'), json_extract(value, '$.title'),
-            json_extract(value, '$.description'), 'relevant',
+            json_extract(value, '$.description'),
             json_extract(value, '$.ownerId'), json_extract(value, '$.currentVersionId'),
             json_extract(value, '$.createdAt'), json_extract(value, '$.updatedAt'), NULL
           FROM json_each(?)`)
@@ -458,14 +455,10 @@ export function createNodeRepository(deps) {
             try {
                 await deps.db.batch([
                     deps.db
-                        // ⚠️ `context_policy` is dead and is written anyway (#76). The column is NOT NULL
-                        // without a DEFAULT and D1 will not let it be dropped — migration 0009 carries the
-                        // reason. The fixed value is the price; nothing reads it, and the contract no longer
-                        // knows the field. When the column goes (anchrd/intel#86), this line goes with it.
                         .prepare(`INSERT INTO nodes (
-            id, parent_id, kind, title, description, context_policy, owner_id,
+            id, parent_id, kind, title, description, owner_id,
             current_version_id, created_at, updated_at, archived_at
-          ) VALUES (?, ?, ?, ?, ?, 'relevant', ?, ?, ?, ?, ?)`)
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
                         .bind(node.id, node.parentId, node.kind, node.title, node.description, node.ownerId, node.currentVersionId, node.createdAt, node.updatedAt, node.archivedAt),
                     deps.db
                         .prepare(`INSERT INTO idempotency_keys (
@@ -1144,32 +1137,46 @@ export function createNodeRepository(deps) {
                 match: "lexical",
             }));
         },
-        async hydrateVisibleCitations(actor, nodeIds, scopeId) {
-            const uniqueIds = [...new Set(nodeIds)].slice(0, 100);
-            if (uniqueIds.length === 0)
+        async hydrateVisibleCitations(actor, hits, scopeId) {
+            // One entry per node: the caller has already picked the best-scoring chunk of each, so a
+            // board that answered with four cards arrives as the one card that answered best.
+            const unique = [...new Map(hits.map((hit) => [hit.nodeId, hit])).values()].slice(0, 100);
+            if (unique.length === 0)
                 return [];
             const rows = [];
-            for (let offset = 0; offset < uniqueIds.length; offset += 96) {
-                const ids = uniqueIds.slice(offset, offset + 96);
-                const placeholders = ids.map(() => "?").join(", ");
+            // Two bindings per hit now instead of one, so the batch is halved and then some: the actor's
+            // predicate and the optional scope are bound in front of them, and D1 counts every one of
+            // them against the same per-statement ceiling.
+            for (let offset = 0; offset < unique.length; offset += 40) {
+                const batch = unique.slice(offset, offset + 40);
+                const pairs = batch.map(() => "(?, ?)").join(", ");
                 const result = await deps.db
-                    .prepare(`${visibleCte}${scopeCte(scopeId)}
+                    .prepare(`${visibleCte}${scopeCte(scopeId)},
+            hits(node_id, chunk_key) AS (VALUES ${pairs})
             SELECT n.id AS node_id, v.id AS version_id, n.title,
-              substr(node_fts.content, 1, 480) AS passage,
+              -- ⚠️ The card that answered, and only otherwise the first passage of the node
+              -- (anchrd/intel#301). Every vector written before #301 is named by the bare node id
+              -- and has no row here, so the fallback is not defensive coding but the exact
+              -- behaviour those vectors had — a board found through one of them still answers,
+              -- with the passage it always answered with, until the next indexing pass.
+              COALESCE(vector.passage, substr(node_fts.content, 1, 480)) AS passage,
               n.updated_at AS freshness
-            FROM nodes n
+            FROM hits
+            JOIN nodes n ON n.id = hits.node_id
             JOIN node_versions v ON v.id = n.current_version_id
             JOIN node_fts ON node_fts.version_id = v.id
+            LEFT JOIN node_vectors vector
+              ON vector.node_id = hits.node_id AND vector.chunk_key = hits.chunk_key
             JOIN allowed ON allowed.id = n.id${scopeJoin(scopeId)}
-            WHERE n.id IN (${placeholders}) AND n.archived_at IS NULL`)
-                    .bind(...readBindings(actor), ...scopeBindings(scopeId), ...ids)
+            WHERE n.archived_at IS NULL`)
+                    .bind(...readBindings(actor), ...scopeBindings(scopeId), ...batch.flatMap((hit) => [hit.nodeId, hit.chunkKey]))
                     .all();
                 rows.push(...(result.results ?? []));
             }
-            const order = new Map(uniqueIds.map((id, index) => [id, index]));
-            // The same one-per-node rule as the lexical half above, for the same reason: a semantic hit
-            // is a hit on a NODE (the vector index is keyed by node id), so hydrating it must not turn one
-            // hit into one row per task.
+            const order = new Map(unique.map((hit, index) => [hit.nodeId, index]));
+            // The same one-per-node rule as the lexical half above, for the same reason: a citation names
+            // a NODE, and a board holds one full-text row per task (#285), so the join above still
+            // produces one row per card even though only one of them was asked about.
             const deduped = dedupedByNode(rows);
             deduped.sort((left, right) => (order.get(left.node_id) ?? 0) - (order.get(right.node_id) ?? 0));
             return deduped.map((row) => ({
@@ -1183,10 +1190,42 @@ export function createNodeRepository(deps) {
                 match: "semantic",
             }));
         },
+        async invalidateVectors() {
+            /**
+             * ⚠️ The fingerprints are cleared and the ROWS are kept, which is not a detail. A record row
+             * says two things at once: "this chunk was embedded from this text" and "this vector exists".
+             * Only the first is stale after a rebuild is asked for; deleting the row would throw the
+             * second away, and then a card removed between this call and that board's pass would leave a
+             * vector nothing could ever name again — matching questions and answering with a card that is
+             * not on the board.
+             *
+             * The empty string is a value no digest produces, so every chunk compares as changed and the
+             * next pass embeds all of them. `node_fts` is deliberately not touched: its rows are
+             * overwritten by the pass that rewrites them, and emptying it would take the lexical half of
+             * the installation offline for as long as the queue needs to work through the tree.
+             */
+            await deps.db.prepare("UPDATE node_vectors SET fingerprint = ''").run();
+        },
+        /**
+         * ⚠️ Archived nodes are IN this walk since anchrd/intel#348, and the omission of
+         * `archived_at IS NULL` is the point. The pass an archived node gets is a purge, not an index —
+         * `getTarget` refuses it and `archivedNodeId` says why — so including them is what makes
+         * `reindex` the way back for a vector that is in the index with nothing left to name it.
+         *
+         * Three of those exist and none of them has another repair: everything archived before #348,
+         * which nothing ever swept; a node whose `archive` wrote its row and then failed to reach the
+         * queue; and a pass that upserted vectors in the moment somebody archived the node underneath
+         * it. Without this line an administrator's rebuild walked straight past all three, and the only
+         * remaining answer would have been to delete the whole Vectorize index by hand.
+         *
+         * It does mean `queued` counts them. That is still what the number says — versions handed to the
+         * queue — and a rebuild that silently skipped part of the tree is the failure `reindex` exists
+         * to prevent.
+         */
         async listCurrentVersionIds(input) {
             const result = await deps.db
                 .prepare(`SELECT current_version_id AS id FROM nodes
-          WHERE current_version_id IS NOT NULL AND archived_at IS NULL
+          WHERE current_version_id IS NOT NULL
             AND (? IS NULL OR current_version_id > ?)
           ORDER BY id LIMIT ?`)
                 .bind(input.after, input.after, input.limit)

package/dist/adapters/openid/openid.js

@@ -24,9 +24,56 @@ function metadataCandidates(resourceUrl, challenge) {
 function resourceMetadataChallenge(header) {
     return header?.match(/resource_metadata="([^"]+)"/i)?.[1] ?? null;
 }
+/**
+ * ⚠️ `issuer` is REQUIRED by RFC 8414 §2 and by OpenID Connect Discovery, and it is read here for one
+ * reason: it is the only thing that says WHO a metadata document describes. Two of the URLs below are
+ * bare-root guesses, and a bare root under a multi-tenant authorization server answers for a
+ * different tenant — a perfectly valid document about somebody else.
+ */
 const AuthorizationServerMetadata = z.looseObject({
+    issuer: z.string().nullish(),
     scopes_supported: z.array(z.string()).nullish(),
 });
+/**
+ * Where an authorization server may publish its metadata, in the order worth asking.
+ *
+ * ⚠️ One candidate was never a decision, it was an omission — `metadataCandidates` above tries three
+ * and `withAlgorithmFallback` tries two. A server that publishes only OIDC discovery read as "names
+ * no scopes", which is #97 at a different server class and with the same silent symptom (#303).
+ *
+ * ⚠️ The three spellings are not interchangeable, and the third is the one that is easy to miss.
+ * RFC 8414 §3.1 INSERTS the issuer's path between the well-known prefix and nothing else; OpenID
+ * Connect Discovery 1.0 APPENDS its suffix to the issuer instead. A realm-style issuer
+ * (`https://as.example/realms/x`) publishes at `…/realms/x/.well-known/openid-configuration` and at
+ * neither of the other two — which is exactly the form `client.discovery` asks for further down this
+ * file, so the same server was reachable for registration and invisible here.
+ */
+function authorizationServerCandidates(issuer) {
+    const url = new URL(issuer);
+    const path = url.pathname === "/" ? "" : url.pathname.replace(/\/+$/, "");
+    return [
+        // RFC 8414 with the path inserted. First, because it is the shape the MCP portals publish.
+        `${url.origin}/.well-known/oauth-authorization-server${path}`,
+        // The same document at the bare root, for an issuer WITH a path that publishes it there anyway.
+        `${url.origin}/.well-known/oauth-authorization-server`,
+        // OpenID Connect Discovery 1.0, appended to the issuer — the realm-style form.
+        `${url.origin}${path}/.well-known/openid-configuration`,
+        // The same document read the RFC 8414 way, and at the bare root.
+        `${url.origin}/.well-known/openid-configuration${path}`,
+        `${url.origin}/.well-known/openid-configuration`,
+    ].filter((value, index, values) => values.indexOf(value) === index);
+}
+/** Two issuer identifiers are the same server, compared the way a URL says so and not as strings. */
+function sameIssuer(published, wanted) {
+    if (!published)
+        return false;
+    try {
+        return new URL(published).href.replace(/\/$/, "") === new URL(wanted).href.replace(/\/$/, "");
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * The scopes this authorization server says it understands, or `null` when it names none.
  *
@@ -41,16 +88,29 @@ const AuthorizationServerMetadata = z.looseObject({
  * Intel then asked it for `offline_access`, a scope it never published (#97).
  */
 async function publishedScopes(fetcher, issuer) {
-    const url = new URL(issuer);
-    const path = url.pathname === "/" ? "" : url.pathname.replace(/\/+$/, "");
-    const response = await fetcher(`${url.origin}/.well-known/oauth-authorization-server${path}`, {
-        signal: AbortSignal.timeout(RequestTimeoutMs),
-        headers: { accept: "application/json" },
-    }).catch(() => null);
-    if (!response?.ok)
-        return null;
-    const metadata = AuthorizationServerMetadata.safeParse(await response.json().catch(() => null));
-    return metadata.success ? (metadata.data.scopes_supported ?? null) : null;
+    for (const candidate of authorizationServerCandidates(issuer)) {
+        const response = await fetcher(candidate, {
+            signal: AbortSignal.timeout(RequestTimeoutMs),
+            headers: { accept: "application/json" },
+        }).catch(() => null);
+        if (!response?.ok)
+            continue;
+        const metadata = AuthorizationServerMetadata.safeParse(await response.json().catch(() => null));
+        if (!metadata.success)
+            continue;
+        // ⚠️ The document has to be ABOUT this issuer, and that check is what makes the bare-root
+        // candidates safe to ask at all. Under a multi-tenant server the root answers for a different
+        // tenant, and taking its `scopes_supported` would ask THIS server for a scope it never published
+        // — the very rule this function exists to keep, broken by the fallback added to protect it.
+        // The resource loop further down does the same thing for the same reason.
+        if (!sameIssuer(metadata.data.issuer, issuer))
+            continue;
+        // ⚠️ A document that answered ABOUT THIS SERVER and named no scopes ends the search. Reading on
+        // would let the next candidate answer a question this server has already answered — "I publish
+        // none" — and the documents of one issuer may disagree about a field RFC 8414 makes optional.
+        return metadata.data.scopes_supported ?? null;
+    }
+    return null;
 }
 /**
  * Of the scopes Intel would like, the ones this server published — joined, or absent.