@bridge_gpt/mcp-server 0.2.41 → 0.2.43

package/build/executor/worker-finalization.js

@@ -34,8 +34,29 @@
  * the terminal-disposition classifier (`terminal_disposition.py`) can route it as
  * a resumable, deterministic cause instead of laundering it into a generic crash
  * that gets retried as a transient upstream failure.
+ *
+ * BAPI-862: a matching pushed head is NECESSARY but not SUFFICIENT. The BAPI-837
+ * run's finding F4 had BAPI-850's implement job push three commits, report plain
+ * success, and never open a pull request — every check above passed, so the gap
+ * only surfaced hours later as an implement gate polling `pr_not_attached`
+ * forever. Finalization therefore also requires an authoritative pull request for
+ * the branch: visible, carrying a usable URL, carrying a NON-BLANK description
+ * (BAPI-824 folded in — the VCS API never applies `.github/PULL_REQUEST_TEMPLATE.md`,
+ * so an omitted body opens a PR with no description at all), and — when the
+ * provider reports it — sitting at the same pushed head. Anything short of that
+ * is `WorkerFinalizationPrNotAttached`, whose guidance names attachment and never
+ * suggests removing or re-writing the branch: the commits ARE the completed
+ * implementation, and both of the stale-worktree guard's historical remedies
+ * would have destroyed them.
+ *
+ * This check is deliberately fail-CLOSED, unlike the BAPI-586 base check it now
+ * shares a lookup with. "The PR could not be verified" and "there is no PR" are
+ * the same thing from the contract's point of view: neither is evidence that the
+ * work was published, and laundering either into success is precisely the defect
+ * this ticket removes. The reconciler stays the decision-maker — the executor
+ * only reports the observation (R14 rule 3).
  */
-import { secretFreeErrorMessage, WorkerFinalizationMissingRemoteBranchAndPr, WorkerFinalizationPrBaseMismatch, WorkerFinalizationSavedButUnfinalized, } from "./job-errors.js";
+import { secretFreeErrorMessage, WorkerFinalizationMissingRemoteBranchAndPr, WorkerFinalizationPrBaseMismatch, WorkerFinalizationPrNotAttached, WorkerFinalizationSavedButUnfinalized, } from "./job-errors.js";
 import { isImplementationStyleJobType } from "./job-types.js";
 /** Bounded settling re-check defaults for the authoritative origin-tip lookup. */
 const DEFAULT_ORIGIN_FINALIZATION_ATTEMPTS = 3;
@@ -115,51 +136,73 @@ async function resolveOriginBranchShaForFinalization(runCommand, worktreePath, b
         remoteSha = await resolveOriginBranchSha(runCommand, worktreePath, branch);
         if (remoteSha !== null) {
             // Existence-only success when HEAD is unknown; exact-match success otherwise.
-            if (!trimmedHeadSha || remoteSha === trimmedHeadSha)
-                return remoteSha;
+            if (!trimmedHeadSha || remoteSha === trimmedHeadSha) {
+                return { sha: remoteSha, attemptsUsed: attempt + 1 };
+            }
         }
         if (attempt < total - 1)
             await sleep(retryDelayMs);
     }
-    return remoteSha;
+    // `attemptsUsed` is reported even on failure so the caller can tell a
+    // first-try answer from one that needed the settling window (BAPI-862).
+    return { sha: remoteSha, attemptsUsed: total };
+}
+/** The bounded, public projection finalization asks the provider for. */
+const PR_VIEW_JSON_FIELDS = "number,url,baseRefName,body,headRefOid";
+/** Trim a string field to a non-empty value, or null. Never throws on odd JSON. */
+function nonBlankString(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
 }
+/** The "no PR observed" reading, used for every unavailability. */
+const PR_LOOKUP_ABSENT = {
+    found: false,
+    baseRef: null,
+    url: null,
+    body: null,
+    headRefOid: null,
+};
 /**
- * BAPI-586: resolve the base branch of the PR for `branch` via `gh pr view`.
- * Fail-open on any unavailability (gh missing, non-zero exit, unparseable JSON)
- * → `{ found: false }`, so a wrong-base guard never blocks a job on transport
- * failure; the reconciliation observation (epic-runtime) is the second layer.
- * When a PR IS visible, `baseRef` is the trimmed `baseRefName`, or null if that
- * field is absent/non-string (which the caller treats as a fail-closed mismatch —
- * missing base evidence is never a match). Never copies raw stderr.
+ * Resolve the pull request for `branch` via a single `gh pr view`. Parses ONLY
+ * the bounded public fields in {@link PR_VIEW_JSON_FIELDS}; every failure mode
+ * collapses to {@link PR_LOOKUP_ABSENT} without copying raw stderr, an
+ * authenticated remote, or the command line into anything the caller can render.
  */
-async function resolvePrBaseRef(runCommand, worktreePath, branch) {
+async function resolvePrForFinalization(runCommand, worktreePath, branch) {
     const args = ["pr", "view"];
     if (branch)
         args.push(branch);
-    args.push("--json", "number,baseRefName");
+    args.push("--json", PR_VIEW_JSON_FIELDS);
     let result;
     try {
         result = await runCommand("gh", args, { cwd: worktreePath });
     }
     catch {
-        return { found: false, baseRef: null };
+        return PR_LOOKUP_ABSENT;
     }
     if (result.exitCode !== 0)
-        return { found: false, baseRef: null };
+        return PR_LOOKUP_ABSENT;
     let parsed;
     try {
         parsed = JSON.parse(result.stdout);
     }
     catch {
-        return { found: false, baseRef: null };
+        return PR_LOOKUP_ABSENT;
     }
     if (!parsed || typeof parsed !== "object")
-        return { found: false, baseRef: null };
+        return PR_LOOKUP_ABSENT;
     const obj = parsed;
-    const prNumber = typeof obj.number === "number" ? obj.number : undefined;
-    const rawBase = obj.baseRefName;
-    const baseRef = typeof rawBase === "string" && rawBase.trim().length > 0 ? rawBase.trim() : null;
-    return { found: true, prNumber, baseRef };
+    const rawHead = nonBlankString(obj.headRefOid);
+    return {
+        found: true,
+        prNumber: typeof obj.number === "number" ? obj.number : undefined,
+        baseRef: nonBlankString(obj.baseRefName),
+        url: nonBlankString(obj.url),
+        body: nonBlankString(obj.body),
+        headRefOid: rawHead === null ? null : rawHead.toLowerCase(),
+    };
 }
 /**
  * BAPI-586: bounded, secret-free failure for a PR that targets a branch other
@@ -183,6 +226,102 @@ function prBaseMismatchFailure(job, prNumber, expectedBase, actualBase) {
         classification: "crashed",
     };
 }
+/**
+ * BAPI-586's base check over one PR observation, or `null` when it does not fire.
+ *
+ * Extracted (BAPI-862) so it can run against a REFRESHED observation as well as
+ * the first one. Semantics are unchanged: no expected base, or no PR visible,
+ * means no verdict at all (fail-open on unavailability), while a visible PR with
+ * absent or malformed base data is a fail-CLOSED mismatch.
+ */
+function evaluatePrBase(job, pr, expectedBase) {
+    if (!expectedBase || !pr.found)
+        return null;
+    if (pr.baseRef === null) {
+        return prBaseMismatchFailure(job, pr.prNumber, expectedBase, "(unresolved)");
+    }
+    if (pr.baseRef !== expectedBase) {
+        return prBaseMismatchFailure(job, pr.prNumber, expectedBase, pr.baseRef);
+    }
+    return null;
+}
+/**
+ * Evaluate one PR observation against the implement-completion contract.
+ *
+ * Reads STRUCTURED fields only — never a rendered message, never worker prose.
+ * `workerHeadSha` is the already-normalized worker HEAD that the authoritative
+ * origin tip has ALREADY been proven to match, so a `headRefOid` disagreement
+ * means the provider has not yet reflected the push, not that the push is in
+ * doubt.
+ */
+function evaluatePrContract(pr, workerHeadSha) {
+    if (!pr.found) {
+        return {
+            ok: false,
+            detail: "no pull request could be observed for that branch",
+            retryable: true,
+        };
+    }
+    if (pr.url === null) {
+        return {
+            ok: false,
+            detail: "its pull request reports no usable URL",
+            retryable: false,
+        };
+    }
+    if (pr.body === null) {
+        // BAPI-824, folded in here. The VCS API never applies the repository's
+        // PULL_REQUEST_TEMPLATE.md, so a pull request opened without a composed body
+        // has NO description at all. The server-side `create_pull_request` contract
+        // already rejects a blank body with a 422; this second layer catches a pull
+        // request opened some other way — by hand, by an older client, or by a future
+        // recovery path — before it can satisfy the success contract.
+        return {
+            ok: false,
+            detail: "its pull request has an empty description",
+            retryable: false,
+        };
+    }
+    if (workerHeadSha && pr.headRefOid !== null && pr.headRefOid !== workerHeadSha) {
+        return {
+            ok: false,
+            detail: `its pull request is still at ${pr.headRefOid.slice(0, 12)} and does not yet carry that commit`,
+            retryable: true,
+        };
+    }
+    return { ok: true };
+}
+/**
+ * BAPI-862: the pushed-but-unattached failure.
+ *
+ * The message is built ONLY from public identifiers — ticket key, job id, branch,
+ * truncated SHAs, the run base — plus a fixed detail phrase, so no provider
+ * output, URL, or credential can ride along. Two properties are load-bearing
+ * rather than stylistic:
+ *
+ * 1. It names `pr_not_attached`, the reason code the implement gate already uses,
+ *    so the executor failure and the reconciler's observation are searchable as
+ *    one state instead of two vocabularies for the same thing.
+ * 2. It recommends attachment and says plainly that removing or re-writing the
+ *    branch destroys completed work. In the F4 incident the pushed branch WAS the
+ *    finished implementation, and both remedies the stale-worktree guard offered
+ *    would have thrown it away.
+ */
+function prNotAttachedFailure(job, branch, workerHeadSha, expectedBase, detail) {
+    const label = job.ticket_key ? `${job.ticket_key} (job ${job.id})` : `job ${job.id}`;
+    const headLabel = workerHeadSha ? ` at ${workerHeadSha.slice(0, 12)}` : "";
+    const baseLabel = expectedBase ? ` targeting '${expectedBase}'` : "";
+    return {
+        error_kind: WorkerFinalizationPrNotAttached,
+        error_message: `${label} exited cleanly and its HEAD${headLabel} is durable on origin branch '${branch}', ` +
+            `but ${detail}. This is the pr_not_attached state: the implementation is COMPLETE and ` +
+            `published, only its pull request is missing. Recovery: open or attach a pull request for ` +
+            `'${branch}'${baseLabel} with a non-empty description. Removing or re-writing that branch ` +
+            `would destroy finished work — the commits on it are the implementation.`,
+        classification: "crashed",
+        last_commit_sha: workerHeadSha || undefined,
+    };
+}
 /**
  * `detail` describes a state with NO evidence any work reached origin (branch
  * unresolved, branch absent from origin, or the origin lookup itself failed).
@@ -224,47 +363,26 @@ function savedButUnfinalizedFailure(job, branch, originSha, workerHeadSha) {
 }
 /**
  * Validate that an implementation-style job's clean exit actually published its
- * work to origin. Non-implementation-style jobs (verdict jobs) bypass the git
- * check entirely. A `pr_url` on the completion result is NOT proof of a push
- * (BAPI-762) — the authoritative origin-tip-vs-HEAD comparison below always runs,
- * so an unpushed local commit is detected whether or not a pull request exists.
+ * work to origin AND left an attached pull request. Non-implementation-style jobs
+ * (verdict jobs) bypass both checks entirely. A `pr_url` on the completion result
+ * is NOT proof of a push (BAPI-762) — the authoritative origin-tip-vs-HEAD
+ * comparison below always runs, so an unpushed local commit is detected whether
+ * or not the worker claims a pull request; and symmetrically, a pushed head is
+ * not proof of a pull request (BAPI-862), so the attachment contract runs after
+ * it. Both halves read only durable provider/git facts the executor observed
+ * itself.
  */
 export async function validateWorkerFinalization(input) {
     const { job, branch, worktreePath, result, runCommand, headSha } = input;
     if (!isImplementationStyleJobType(job.job_type)) {
         return { ok: true };
     }
-    // BAPI-586: a wrong-base PR (opened against a dependency's feature branch or the
-    // repo default instead of the run base) never fires `claude-review.yml` and
-    // strands the ticket at `code_review`. When the run base is known, query the
-    // PR's `baseRefName` and fail loud on any mismatch BEFORE accepting the clean
-    // exit — even when a `pr_url` is present (a PR existing is not proof of a
-    // correct base). Fail-open when no PR is visible (gh unavailable / no PR):
-    // reconciliation is the backstop. A PR with absent/malformed base data is a
-    // fail-CLOSED mismatch — missing base evidence is never treated as a match.
-    const expectedBase = typeof input.expectedBaseBranch === "string" ? input.expectedBaseBranch.trim() : "";
-    if (expectedBase) {
-        const branchForPr = typeof branch === "string" ? branch.trim() : "";
-        const prBase = await resolvePrBaseRef(runCommand, worktreePath, branchForPr);
-        if (prBase.found) {
-            if (prBase.baseRef === null) {
-                return {
-                    ok: false,
-                    failure: prBaseMismatchFailure(job, prBase.prNumber, expectedBase, "(unresolved)"),
-                };
-            }
-            if (prBase.baseRef !== expectedBase) {
-                return {
-                    ok: false,
-                    failure: prBaseMismatchFailure(job, prBase.prNumber, expectedBase, prBase.baseRef),
-                };
-            }
-        }
-    }
     const hasPrUrl = Boolean(extractPrUrl(result));
     // BAPI-762: `branch`/`headSha` are normalized once here and reused through the
     // rest of the check — including by the diagnostics below — instead of being
-    // re-derived at each failure site.
+    // re-derived at each failure site. This purely local resolution runs FIRST
+    // (BAPI-862) so an unresolvable branch is reported without issuing a single
+    // provider or git query against the wrong subject.
     const trimmedBranch = typeof branch === "string" ? branch.trim() : "";
     if (!trimmedBranch) {
         return {
@@ -272,6 +390,27 @@ export async function validateWorkerFinalization(input) {
             failure: missingBranchAndPrFailure(job, "no expected branch to verify on origin", hasPrUrl),
         };
     }
+    // BAPI-862 folded the two PR-reading guards onto ONE `gh pr view`: the base
+    // check below and the attachment contract at the end of this function read the
+    // same observation. The lookup runs for every implementation-style job now —
+    // not only when a run base is known — because the attachment contract is
+    // unconditional. Their dispositions still differ on purpose (see `PrLookup`),
+    // and the ORDER is unchanged: a wrong-base PR is still reported before any
+    // origin lookup, exactly as BAPI-586 specified.
+    let pr = await resolvePrForFinalization(runCommand, worktreePath, trimmedBranch);
+    // BAPI-586: a wrong-base PR (opened against a dependency's feature branch or the
+    // repo default instead of the run base) never fires `claude-review.yml` and
+    // strands the ticket at `code_review`. When the run base is known, fail loud on
+    // any mismatch BEFORE the origin lookup below — even when a `pr_url` is present
+    // (a PR existing is not proof of a correct base). Still fail-OPEN when no PR is
+    // visible: reconciliation is the backstop for that, and BAPI-862's attachment
+    // contract at the end of this function is what now refuses to call it a success.
+    // A PR with absent/malformed base data stays a fail-CLOSED mismatch — missing
+    // base evidence is never treated as a match.
+    const expectedBase = typeof input.expectedBaseBranch === "string" ? input.expectedBaseBranch.trim() : "";
+    const baseVerdict = evaluatePrBase(job, pr, expectedBase);
+    if (baseVerdict)
+        return { ok: false, failure: baseVerdict };
     // Recovery/resume jobs fetch `origin/<branch>` before the worker even starts,
     // so the ref merely existing is not proof this session's commit landed. When
     // the worker's own HEAD is known, require the authoritative origin tip to match
@@ -286,9 +425,9 @@ export async function validateWorkerFinalization(input) {
     const attempts = normalizeAttempts(input.originResolveAttempts);
     const retryDelayMs = normalizeRetryDelay(input.originResolveRetryDelayMs);
     const sleep = input.sleep ?? sleepMs;
-    let remoteSha;
+    let origin;
     try {
-        remoteSha = await resolveOriginBranchShaForFinalization(runCommand, worktreePath, trimmedBranch, trimmedHeadSha, attempts, retryDelayMs, sleep);
+        origin = await resolveOriginBranchShaForFinalization(runCommand, worktreePath, trimmedBranch, trimmedHeadSha, attempts, retryDelayMs, sleep);
     }
     catch (err) {
         return {
@@ -296,6 +435,7 @@ export async function validateWorkerFinalization(input) {
             failure: missingBranchAndPrFailure(job, `branch '${trimmedBranch}' could not be verified on origin: ${secretFreeErrorMessage(err)}`, hasPrUrl),
         };
     }
+    const remoteSha = origin.sha;
     if (remoteSha === null) {
         return {
             ok: false,
@@ -314,5 +454,42 @@ export async function validateWorkerFinalization(input) {
             failure: savedButUnfinalizedFailure(job, trimmedBranch, remoteSha, trimmedHeadSha),
         };
     }
-    return { ok: true };
+    // BAPI-862: the work is provably ON ORIGIN. That was the whole of the success
+    // contract until finding F4 showed it was not enough — an implement job can
+    // satisfy everything above and still leave nothing for the reconciler to bind
+    // to. The last obligation is an authoritative, usable pull request.
+    //
+    // Placed LAST on purpose: an unpushed or mismatched head is a different and
+    // more urgent failure, and reporting "no pull request" for work that never
+    // reached origin would send an operator to the wrong remedy. So every
+    // pre-existing failure keeps precedence and this one only fires once the push
+    // is proven.
+    // The snapshot above was taken BEFORE the origin lookup, because BAPI-586
+    // requires a wrong-base PR to be reported ahead of any git call. When the
+    // origin lookup then needed the settling window, that snapshot predates the
+    // very push we just confirmed and is stale by construction — so refresh it
+    // once, for free, rather than making the contract's own retry budget spend its
+    // first cycle recovering from known staleness. The refreshed observation is
+    // re-checked against the base too: if the stale snapshot saw no PR at all, the
+    // base check fail-opened on it, and the PR that has since appeared must not
+    // reach success without that check.
+    if (origin.attemptsUsed > 1) {
+        pr = await resolvePrForFinalization(runCommand, worktreePath, trimmedBranch);
+        const refreshedBaseVerdict = evaluatePrBase(job, pr, expectedBase);
+        if (refreshedBaseVerdict)
+            return { ok: false, failure: refreshedBaseVerdict };
+    }
+    let contract = evaluatePrContract(pr, trimmedHeadSha);
+    for (let attempt = 1; attempt < attempts && !contract.ok && contract.retryable; attempt++) {
+        await sleep(retryDelayMs);
+        pr = await resolvePrForFinalization(runCommand, worktreePath, trimmedBranch);
+        contract = evaluatePrContract(pr, trimmedHeadSha);
+    }
+    if (!contract.ok) {
+        return {
+            ok: false,
+            failure: prNotAttachedFailure(job, trimmedBranch, trimmedHeadSha, expectedBase, contract.detail),
+        };
+    }
+    return { ok: true, prUrl: pr.url ?? undefined, prNumber: pr.prNumber };
 }

package/build/executor/worktree.js

@@ -183,7 +183,14 @@ export async function ensureExecutorWorktree(job, options, deps, policy = {}) {
         };
     }
     const baseSha = resolvedBase.base_sha;
-    const row = await createWorktreeForTicket(toWorktreeCoreDeps(deps), key, { [key]: branch }, options.worktrunkBinary, baseSha, guardStaleWorktree, { alignExistingBranchTo: baseSha, verifyHeadMatches: baseSha });
+    const row = await createWorktreeForTicket(toWorktreeCoreDeps(deps), key, { [key]: branch }, options.worktrunkBinary, baseSha, guardStaleWorktree, {
+        alignExistingBranchTo: baseSha,
+        verifyHeadMatches: baseSha,
+        // BAPI-862: the guard is ON for this fresh-dispatch path, and this is the
+        // path finding F4 hit — a re-dispatched implement whose branch already
+        // carried the previous, successful attempt's pushed commits.
+        staleBranchClassification: policy.staleBranchClassification,
+    });
     if (row.status === "created" && typeof row.path === "string") {
         // BAPI-731: `baseSha` is already the pinned immutable commit this fresh
         // worktree was cut from and verified against (`verifyHeadMatches`), so it is

package/build/index-scope-contract.js

@@ -0,0 +1,96 @@
+/**
+ * The opaque index-scope declaration carried across a process boundary (BAPI-844).
+ *
+ * An index scope is the per-epic shadow index research is routed to. A pilot
+ * ticket has no `epic_ticket_status` / `epic_runs` row, so server-side membership
+ * discovery proves "non-epic" and routes to the canonical index — which is why the
+ * scope has to be DECLARED by the worker rather than discovered for it.
+ *
+ * This module owns the three names that declaration travels under, and nothing
+ * else:
+ *
+ * - {@link INDEX_SCOPE_ENV_VAR} — the worker environment variable,
+ * - {@link INDEX_SCOPE_HEADER} — the out-of-band Bridge API request header,
+ * - {@link validateOptionalIndexScope} — the shared shape check.
+ *
+ * TOKEN-OPAQUE BY CONSTRUCTION. The validator checks type, length, and shape and
+ * derives NOTHING from the value: not a repository, not a branch, not an epic run,
+ * not a shadow repository name. Those derivations are server-side, because the
+ * scope id is a server-minted identity (R14) and a worker that could compute a
+ * shadow name from it would be authorizing itself.
+ *
+ * VALIDATION IS NOT AUTHORIZATION. A well-formed declaration only means the value
+ * is shaped like a scope id. Whether the declaring worker may USE that scope is
+ * decided server-side, against the authenticated repository — see
+ * `api/agent_flows/code_writer/library/research_repo_resolver.py`. Nothing here
+ * may ever be read as a permission check.
+ */
+/**
+ * The environment variable a scoped worker carries.
+ *
+ * Deliberately NOT in `executor/env.ts`'s `ALLOWED_ENV_KEYS`, and explicitly on
+ * its `EXPLICIT_DENY_KEYS`: the value must arrive from an explicit, validated
+ * spawn option, never inherited from the executor's (or an operator's) ambient
+ * environment. This mirrors `BAPI_BASE_BRANCH` exactly — an ambient value that
+ * could override a run-scoped decision is the failure mode both keys avoid.
+ */
+export const INDEX_SCOPE_ENV_VAR = "BAPI_INDEX_SCOPE";
+/**
+ * The Bridge API request header a scoped MCP worker attaches.
+ *
+ * Out-of-band on purpose. Every request body keeps the CANONICAL `repo_name`,
+ * because repository identity is what authorization, configuration, billing, and
+ * Jira side effects are keyed by; only research RETRIEVAL consumes this header.
+ */
+export const INDEX_SCOPE_HEADER = "X-Bapi-Index-Scope";
+/**
+ * The server-minted scope-id shape: exactly 32 lowercase hexadecimal characters.
+ *
+ * Mirrors the server's own `_SCOPE_ID_RE` (`api/library/db/epic_shadow_index.py`),
+ * which is what `mint_scope_id()` (a `uuid4().hex`) produces. Anchored at both
+ * ends, so a longer string containing a valid token is rejected rather than
+ * partially matched.
+ */
+const INDEX_SCOPE_PATTERN = /^[0-9a-f]{32}$/;
+/**
+ * The ONE configuration-error message every malformed declaration produces.
+ *
+ * Fixed and value-free by design: an error that echoed the submitted value would
+ * push an opaque routing token into terminal output, worker logs, conductor
+ * events, and error reports — all places this token must never appear. Every
+ * rejection is therefore indistinguishable in its text, which is deliberate.
+ */
+export const INDEX_SCOPE_CONFIGURATION_ERROR = `${INDEX_SCOPE_ENV_VAR} is not a valid index-scope declaration. ` +
+    "Expected a server-minted scope identity; the value was not logged.";
+/** Thrown for a malformed declaration. Its message is always the fixed text above. */
+export class IndexScopeConfigurationError extends Error {
+    constructor() {
+        super(INDEX_SCOPE_CONFIGURATION_ERROR);
+        this.name = "IndexScopeConfigurationError";
+    }
+}
+/**
+ * Validate an OPTIONAL scope declaration.
+ *
+ * Returns `undefined` for an absent declaration (`undefined`, `null`, or an
+ * empty/blank string) — absence is the ordinary unscoped case and must stay
+ * indistinguishable from today's behavior. Returns a well-formed value BYTE-FOR-BYTE
+ * unchanged: no trimming, no case folding, no normalization, because a value the
+ * server minted is the only value the server will recognize.
+ *
+ * Throws {@link IndexScopeConfigurationError} for anything else, including a
+ * non-string. Failing loudly is the point: silently dropping a malformed
+ * declaration would route a scoped worker's research at the canonical index while
+ * every observable signal still said "scoped".
+ */
+export function validateOptionalIndexScope(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string")
+        throw new IndexScopeConfigurationError();
+    if (value.trim().length === 0)
+        return undefined;
+    if (!INDEX_SCOPE_PATTERN.test(value))
+        throw new IndexScopeConfigurationError();
+    return value;
+}