vouchington-tooling 0.31.0 → 0.33.0

package/README.md

@@ -366,6 +366,31 @@ summaries and quoted attributes; it is not a general HTML validator or sanitizer
 the input or infers semantic relevance, cost, schema conformance, or failure causes. The existing
 `markdownSectionBetweenHeadings` API retains its original boundary behavior.
 
+`hasUncheckedMarkdownTask` reports parsed unchecked GFM task items, ignoring code and non-task text.
+`markdownLiteralSpans` returns source-backed `{ kind, position, value }` facts for fenced or indented
+code, inline code, and raw HTML. `markdownHtmlFacts` distinguishes inline HTML from block HTML and
+labels CommonMark block types 1–7; `markdownHtmlBlocks` selects block types 1, 6, and 7, retaining
+the parser's source bounds, including type 1 blocks through their matching closer or end of input.
+Positions use 1-indexed line/column coordinates and JavaScript string offsets, including CRLF and
+Unicode source text. These APIs return facts rather than mdast nodes so callers can apply their own
+content policy without binding it to parser internals.
+
+```ts
+import {
+  hasUncheckedMarkdownTask,
+  markdownHtmlBlocks,
+  markdownLiteralSpans,
+} from 'vouchington-tooling/markdown'
+
+const hasOpenTask = hasUncheckedMarkdownTask(body)
+const literalSpans = markdownLiteralSpans(body)
+const blockHtml = markdownHtmlBlocks(body)
+```
+
+`markdownHtmlBlocks` reports CommonMark types 1, 6, and 7; inline tags do not appear in that result.
+Use `markdownHtmlFacts` when inline/block classification and other CommonMark HTML block types are
+also needed.
+
 Machine-wide agent configuration now belongs to [vouchington-machines](https://github.com/vouchington/vouchington-machines/blob/main/docs/agent-config.md).
 Use its `configure-agents.sh` and `diagnose-agents.sh`; project hooks and MCP configuration remain in their checkouts.
 
@@ -455,6 +480,8 @@ Version one recognizes literal-key `apiResponse`, `apiNoContent`, `apiOpenApiRaw
 `ctx.pipeline`, `ctx.response.empty/buffer/xml`, `ctx.request.json/buffer`, `parseJsonBody`,
 `ctx.setStatus`, and static `Content-Type` setters. The input source files and TypeScript checker
 are the source representation; the adapter does not parse or discover a repository on its own.
+Reading the handler context in another object's computed assignment key preserves its binding;
+assignments or updates to the context itself, including side effects inside that key, still reject it.
 
 Error-only 405 routes require a terminal throw on the handler's own context. Named handlers and
 imported wrappers are followed through compiler declarations; conditional, caught, recursive,
@@ -502,11 +529,19 @@ Caller-owned `apiOpenApiHttpResponse(key, response)` markers bind a constant opa
 carrying optional readonly `apiHttpResponseVariants` metadata. Each concrete union variant has
 `status` and `bodyKind`; content variants also have `mediaType` and `body`. Discovery associates
 the marked variable's status and body emissions without reading or replacing response bytes.
+Feasible assignments, deletions, or updates to its body or status, including cast and constant
+aliases, invalidate the selected contracts because their metadata no longer proves the dispatch.
 A status setter must dominate each body emission, including separate branches; constant context
 aliases are followed, assigned mutable context aliases and object-literal context wrappers fail closed,
 and helper parameters must resolve to the registered caller's unchanged response context.
 Helper-owned contracts also account for response emissions in their proven caller scopes.
+Opaque callees receiving the canonical HTTP context or its response object invalidate its contract;
+implemented helpers and consumed callbacks retain their proven dispatch behavior.
+Feasible assignments or deletions of response methods through canonical context aliases invalidate
+that dispatch evidence; dead, ignored, or unrelated method mutations preserve the contract.
 Indirect response `call`, `apply`, and `bind` forms fail closed, including borrowed context receivers.
+Compiler-resolved standard `Reflect.apply` uses its target and actual receiver to reject unrepresented
+HTTP emissions; project implementations, unrelated contexts, and non-executed calls are preserved.
 SSE frames and branded content variants reject body-forbidden 1xx, 204, 205, and 304 statuses.
 Literal bracket response methods have the same emission checks as property methods. Unrelated raw emissions
 remain unavailable. Separate branded response branches are checked together, and the nearest
@@ -675,3 +710,10 @@ block, escaped and length-bounded like CI failures, and other entries are ignore
 `Status: none observed` or `Status: events observed`, each followed by
 `(journal entries only; no friction log observed)`; a truncated scan reports
 `unavailable (journal scan incomplete)` with the entries read so far.
+
+## Basic Auth exemption facts
+
+`vouchington-tooling/basic-auth-doc-sync` extracts literal exemption collections from
+TypeScript and route rows from Markdown. Callers configure declaration names and
+runbook headings, then compare the returned data using their own route policy.
+See the [API contract](docs/basic-auth-doc-sync.md).

package/dist/api-contract-discovery/protocol-http-association.mjs

@@ -8,7 +8,10 @@ import { unsupportedContextAlias } from './protocol-context-alias.mjs';
 import { expressionReceiver } from './protocol-write-receiver.mjs';
 import { visit } from './response-contract-route-analysis.mjs';
 import { isSupportedProtocolCallback } from './protocol-callback-invocation.mjs';
+import { mutatesHttpResponseMethod } from './protocol-http-method-mutations.mjs';
 import { opaqueProtocolCallbackPath } from './protocol-opaque-callback.mjs';
+import { opaqueHttpContextArgument } from './protocol-http-context-escapes.mjs';
+import { mutatedHttpResponse } from './protocol-http-response-mutations.mjs';
 const responseMethods = new Set([
     'setStatus',
     'pipeline',
@@ -26,6 +29,12 @@ export function associateHttpResponse(call, response, checker, siblings) {
     const emissions = new Map();
     for (const [scope, context] of httpContextScopes(handler, checker))
         visit(scope, (node) => {
+            if (mutatedHttpResponse(node, response, checker))
+                throw new Error('HTTP branded response body or status is mutated');
+            if (ts.isCallExpression(node) && opaqueHttpContextArgument(node, checker, context))
+                throw new Error('HTTP response context escapes through an opaque argument');
+            if (mutatesHttpResponseMethod(node, context, checker))
+                throw new Error('HTTP response context method is mutated');
             if (ts.isCallExpression(node) &&
                 executableProtocolPath(node, checker) &&
                 responseMethods.has(indirectHttpResponseMethod(node, context, checker) ?? ''))
@@ -65,6 +74,8 @@ export function associateHttpResponse(call, response, checker, siblings) {
 }
 /** Opaque callbacks may emit through an independently proven handler's context. */
 export function opaqueHttpResponse(call, checker, context) {
+    if (opaqueHttpContextArgument(call, checker, context))
+        return true;
     if (context)
         return (responseMethods.has(contextResponseMethod(call.expression, context, checker, true) ??
             indirectHttpResponseMethod(call, context, checker) ??

package/dist/api-contract-discovery/protocol-http-context-escapes.d.mts

@@ -0,0 +1,3 @@
+import ts from '../contract-schema/typescript-api.mts';
+/** Opaque consumers of the canonical context may emit undocumented status or bodies. */
+export declare function opaqueHttpContextArgument(call: ts.CallExpression, checker: ts.TypeChecker, context?: ts.Symbol, active?: Set<ts.FunctionLikeDeclaration>): boolean;

package/dist/api-contract-discovery/protocol-http-context-escapes.mjs

@@ -0,0 +1,95 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { expressionReceiver } from './protocol-write-receiver.mjs';
+import { httpHandlerContext, contextResponseMethod } from './protocol-http-context.mjs';
+import { httpContextInvocations } from './protocol-http-context-callers.mjs';
+import { callbackArgumentBindings } from './protocol-callback-argument-bindings.mjs';
+import { runtimeParameters } from './registered-route-runtime-parameters.mjs';
+import { enclosingFunction, unwrapExpression } from './protocol-marker-analysis.mjs';
+import { executableProtocolPath } from './protocol-execution-path.mjs';
+import { opaqueProtocolCallbackPath } from './protocol-opaque-callback.mjs';
+import { visit } from './response-contract-route-analysis.mjs';
+import { standardReflectApply } from './protocol-http-reflect.mjs';
+import { createProtocolCallbackValueResolver, isProtocolCallbackFunction, } from './protocol-callback-values.mjs';
+/** Opaque consumers of the canonical context may emit undocumented status or bodies. */
+export function opaqueHttpContextArgument(call, checker, context, active = new Set()) {
+    const matches = (symbol) => call.arguments.some((argument) => contextArgument(argument, symbol, checker));
+    if (context && !matches(context))
+        return false;
+    if (!(executableProtocolPath(call, checker) || opaqueProtocolCallbackPath(call, checker)))
+        return false;
+    if (context)
+        return !implementedCallee(call, context, checker, active);
+    for (let owner = enclosingFunction(call); owner; owner = enclosingFunction(owner)) {
+        const name = runtimeParameters(owner)[0]?.name;
+        const symbol = name && ts.isIdentifier(name) ? checker.getSymbolAtLocation(name) : undefined;
+        if (symbol && matches(symbol) && httpHandlerContext(owner, checker) === symbol)
+            return !implementedCallee(call, symbol, checker, active);
+    }
+    return false;
+}
+function contextArgument(expression, context, checker) {
+    const receiver = expressionReceiver(expression, checker);
+    return ((receiver?.root === context &&
+        (receiver.path.length === 0 ||
+            (receiver.path.length === 1 && receiver.path[0] === 'response'))) ||
+        contextResponseMethod(unwrapExpression(expression), context, checker, true) === 'response');
+}
+/** Actual caller bindings retain the concrete implementations of consumed callback parameters. */
+function implementedCallee(call, context, checker, active) {
+    const resolver = createProtocolCallbackValueResolver(checker);
+    if (standardReflectApply(call, checker)) {
+        const target = call.arguments[0] && resolver.resolve(call.arguments[0], new Map());
+        return !!(target &&
+            isProtocolCallbackFunction(target.node) &&
+            target.node.body &&
+            ts.isBlock(target.node.body) &&
+            target.node.body.statements.length === 0);
+    }
+    const implemented = (env) => {
+        const target = resolver.resolve(call.expression, env);
+        return !!(target &&
+            isProtocolCallbackFunction(target.node) &&
+            target.node.body &&
+            !calleeEscapes(target.node, call, context, checker, active));
+    };
+    if (implemented(new Map()))
+        return true;
+    const expression = unwrapExpression(call.expression);
+    const declaration = ts.isIdentifier(expression)
+        ? checker.getSymbolAtLocation(expression)?.valueDeclaration
+        : undefined;
+    const owner = declaration && ts.isParameter(declaration) ? enclosingFunction(declaration) : undefined;
+    if (!owner || !runtimeParameters(owner).includes(declaration))
+        return false;
+    const callers = httpContextInvocations(owner, checker).callers;
+    return (callers.length > 0 &&
+        callers.every((invocation) => {
+            const target = resolver.resolve(invocation.expression, new Map());
+            if (target?.node !== owner)
+                return false;
+            const env = callbackArgumentBindings(owner, invocation, new Map(), target.env, checker, resolver);
+            return !!env && implemented(env);
+        }));
+}
+/** The current proven call binds canonical arguments; other foreign callers do not hide escapes. */
+function calleeEscapes(fn, call, context, checker, active) {
+    if (active.has(fn))
+        return true;
+    const next = new Set(active).add(fn);
+    const contexts = [context];
+    for (const [index, parameter] of runtimeParameters(fn).entries()) {
+        const argument = call.arguments[index];
+        if (!argument || !contextArgument(argument, context, checker))
+            continue;
+        if (!ts.isIdentifier(parameter.name))
+            return true;
+        contexts.push(checker.getSymbolAtLocation(parameter.name));
+    }
+    let escaped = false;
+    visit(fn.body, (node) => {
+        if (ts.isCallExpression(node) &&
+            contexts.some((symbol) => opaqueHttpContextArgument(node, checker, symbol, next)))
+            escaped = true;
+    });
+    return escaped;
+}

package/dist/api-contract-discovery/protocol-http-context.d.mts

@@ -1,8 +1,7 @@
 import ts from '../contract-schema/typescript-api.mts';
+export { contextResponseMethod } from './protocol-http-method-access.mts';
 /** A helper parameter is a response context only when every executable caller passes one. */
 export declare function httpHandlerContext(fn: ts.FunctionLikeDeclaration, checker: ts.TypeChecker, active?: Set<ts.FunctionLikeDeclaration>): ts.Symbol | undefined;
-/** Literal bracket access is equivalent to property access for response methods. */
-export declare function contextResponseMethod(expression: ts.Expression, context: ts.Symbol, checker: ts.TypeChecker, allowMutable?: boolean): string | undefined;
 /** Follow only caller contexts already admitted by the actual-argument proof. */
 export declare function httpContextScopes(fn: ts.FunctionLikeDeclaration, checker: ts.TypeChecker): Map<ts.FunctionLikeDeclaration, ts.Symbol>;
 /** Indirect methods cannot prove the declared status or body, including borrowed this receivers. */

package/dist/api-contract-discovery/protocol-http-context.mjs

@@ -4,6 +4,9 @@ import { enclosingFunction } from './protocol-marker-analysis.mjs';
 import { expressionReceiver } from './protocol-write-receiver.mjs';
 import { hasBindingWrite } from './registered-route-binding-writes.mjs';
 import { runtimeParameters } from './registered-route-runtime-parameters.mjs';
+import { contextResponseMethod, methodAccess } from './protocol-http-method-access.mjs';
+import { reflectHttpResponseMethod } from './protocol-http-reflect.mjs';
+export { contextResponseMethod } from './protocol-http-method-access.mjs';
 /** A helper parameter is a response context only when every executable caller passes one. */
 export function httpHandlerContext(fn, checker, active = new Set()) {
     if (active.has(fn))
@@ -31,35 +34,6 @@ export function httpHandlerContext(fn, checker, active = new Set()) {
     const result = valid ? context : undefined;
     return result;
 }
-/** Literal bracket access is equivalent to property access for response methods. */
-export function contextResponseMethod(expression, context, checker, allowMutable = false) {
-    const access = methodAccess(expression);
-    if (!access)
-        return undefined;
-    const receiver = expressionReceiver(access.receiver, checker) ??
-        bracketResponseReceiver(access.receiver, checker);
-    if (receiver?.root !== context || (receiver.mutableAlias && !allowMutable))
-        return undefined;
-    if (receiver.path.length === 0)
-        return access.name;
-    if (receiver.path.length === 1 && receiver.path[0] === 'response')
-        return `response.${access.name}`;
-    return undefined;
-}
-function methodAccess(expression) {
-    if (ts.isPropertyAccessExpression(expression))
-        return { receiver: expression.expression, name: expression.name.text };
-    if (ts.isElementAccessExpression(expression) && ts.isStringLiteral(expression.argumentExpression))
-        return { receiver: expression.expression, name: expression.argumentExpression.text };
-    return undefined;
-}
-function bracketResponseReceiver(expression, checker) {
-    const access = methodAccess(expression);
-    if (!access || access.name !== 'response')
-        return undefined;
-    const receiver = expressionReceiver(access.receiver, checker);
-    return receiver && { ...receiver, path: [...receiver.path, 'response'] };
-}
 /** Follow only caller contexts already admitted by the actual-argument proof. */
 export function httpContextScopes(fn, checker) {
     const scopes = new Map();
@@ -84,6 +58,9 @@ export function httpContextScopes(fn, checker) {
 }
 /** Indirect methods cannot prove the declared status or body, including borrowed this receivers. */
 export function indirectHttpResponseMethod(call, context, checker) {
+    const reflected = reflectHttpResponseMethod(call, context, checker);
+    if (reflected)
+        return reflected;
     const outer = methodAccess(call.expression);
     if (!outer || !['call', 'apply', 'bind'].includes(outer.name))
         return undefined;

package/dist/api-contract-discovery/protocol-http-method-access.d.mts

@@ -0,0 +1,9 @@
+import ts from '../contract-schema/typescript-api.mts';
+/** Literal bracket access is equivalent to property access for response methods. */
+export declare function contextResponseMethod(expression: ts.Expression, context: ts.Symbol, checker: ts.TypeChecker, allowMutable?: boolean): string | undefined;
+export declare function methodAccess(expression: ts.Expression): {
+    receiver: ts.LeftHandSideExpression;
+    name: string;
+} | undefined;
+/** Uses the existing canonical receiver plus literal response-property access. */
+export declare function httpContextReceiver(expression: ts.Expression, checker: ts.TypeChecker): import("./protocol-write-receiver.mts").WriteReceiver | undefined;

package/dist/api-contract-discovery/protocol-http-method-access.mjs

@@ -0,0 +1,34 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { expressionReceiver } from './protocol-write-receiver.mjs';
+/** Literal bracket access is equivalent to property access for response methods. */
+export function contextResponseMethod(expression, context, checker, allowMutable = false) {
+    const access = methodAccess(expression);
+    if (!access)
+        return undefined;
+    const receiver = httpContextReceiver(access.receiver, checker);
+    if (receiver?.root !== context || (receiver.mutableAlias && !allowMutable))
+        return undefined;
+    if (receiver.path.length === 0)
+        return access.name;
+    if (receiver.path.length === 1 && receiver.path[0] === 'response')
+        return `response.${access.name}`;
+    return undefined;
+}
+export function methodAccess(expression) {
+    if (ts.isPropertyAccessExpression(expression))
+        return { receiver: expression.expression, name: expression.name.text };
+    if (ts.isElementAccessExpression(expression) && ts.isStringLiteral(expression.argumentExpression))
+        return { receiver: expression.expression, name: expression.argumentExpression.text };
+    return undefined;
+}
+/** Uses the existing canonical receiver plus literal response-property access. */
+export function httpContextReceiver(expression, checker) {
+    const receiver = expressionReceiver(expression, checker);
+    if (receiver)
+        return receiver;
+    const access = methodAccess(expression);
+    if (!access || access.name !== 'response')
+        return undefined;
+    const parent = expressionReceiver(access.receiver, checker);
+    return parent && { ...parent, path: [...parent.path, 'response'] };
+}

package/dist/api-contract-discovery/protocol-http-method-mutations.d.mts

@@ -0,0 +1,3 @@
+import ts from '../contract-schema/typescript-api.mts';
+/** A feasible write through a canonical context alias invalidates response dispatch evidence. */
+export declare function mutatesHttpResponseMethod(node: ts.Node, context: ts.Symbol, checker: ts.TypeChecker): boolean;

package/dist/api-contract-discovery/protocol-http-method-mutations.mjs

@@ -0,0 +1,31 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { contextResponseMethod } from './protocol-http-context.mjs';
+import { unwrapExpression } from './protocol-marker-analysis.mjs';
+import { executableProtocolPath } from './protocol-execution-path.mjs';
+import { opaqueProtocolCallbackPath } from './protocol-opaque-callback.mjs';
+const responseMethods = new Set([
+    'setStatus',
+    'pipeline',
+    'json',
+    'response',
+    'response.buffer',
+    'response.empty',
+]);
+/** A feasible write through a canonical context alias invalidates response dispatch evidence. */
+export function mutatesHttpResponseMethod(node, context, checker) {
+    let target;
+    if (ts.isBinaryExpression(node) &&
+        node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+        node.operatorToken.kind <= ts.SyntaxKind.LastAssignment)
+        target = node.left;
+    if (ts.isDeleteExpression(node))
+        target = node.expression;
+    if ((ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) &&
+        (node.operator === ts.SyntaxKind.PlusPlusToken ||
+            node.operator === ts.SyntaxKind.MinusMinusToken))
+        target = node.operand;
+    if (!target ||
+        !responseMethods.has(contextResponseMethod(unwrapExpression(target), context, checker, true) ?? ''))
+        return false;
+    return executableProtocolPath(node, checker) || opaqueProtocolCallbackPath(node, checker);
+}

package/dist/api-contract-discovery/protocol-http-reflect.d.mts

@@ -0,0 +1,5 @@
+import ts from '../contract-schema/typescript-api.mts';
+/** Both the actual invoked value and signature must belong to the compiler library. */
+export declare function standardReflectApply(call: ts.CallExpression, checker: ts.TypeChecker): boolean;
+/** Reflected context emissions cannot prove the marked status or response body. */
+export declare function reflectHttpResponseMethod(call: ts.CallExpression, context: ts.Symbol, checker: ts.TypeChecker): string | undefined;

package/dist/api-contract-discovery/protocol-http-reflect.mjs

@@ -0,0 +1,45 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { standardCompilerDeclaration } from './protocol-platform-callbacks.mjs';
+import { expressionReceiver } from './protocol-write-receiver.mjs';
+import { unwrapExpression } from './protocol-marker-analysis.mjs';
+import { contextResponseMethod, httpContextReceiver, methodAccess, } from './protocol-http-method-access.mjs';
+/** Both the actual invoked value and signature must belong to the compiler library. */
+export function standardReflectApply(call, checker) {
+    const access = methodAccess(unwrapExpression(call.expression));
+    const receiver = expressionReceiver(access?.receiver ?? call.expression, checker);
+    if (!receiver)
+        return false;
+    const path = [...receiver.path, ...(access ? [access.name] : [])];
+    if (path.join('.') !== 'apply')
+        return false;
+    if (!receiver.root.declarations?.every((value) => standardCompilerDeclaration(value, checker)))
+        return false;
+    const declaration = checker.getResolvedSignature(call)?.declaration;
+    if (!declaration || !ts.isFunctionDeclaration(declaration) || declaration.name?.text !== 'apply')
+        return false;
+    const namespace = declaration.parent.parent;
+    return (ts.isModuleDeclaration(namespace) &&
+        namespace.name.text === 'Reflect' &&
+        standardCompilerDeclaration(declaration, checker));
+}
+/** Reflected context emissions cannot prove the marked status or response body. */
+export function reflectHttpResponseMethod(call, context, checker) {
+    if (!standardReflectApply(call, checker))
+        return undefined;
+    const target = call.arguments[0];
+    const direct = target && contextResponseMethod(target, context, checker, true);
+    if (direct)
+        return direct;
+    const method = target && expressionReceiver(target, checker);
+    if (method?.root === context)
+        return method.path[0] === 'response' ? method.path.slice(0, 2).join('.') : method.path[0];
+    const receiver = call.arguments[1] && httpContextReceiver(call.arguments[1], checker);
+    const name = (target && methodAccess(target)?.name) ?? method?.path.at(-1);
+    if (receiver?.root !== context || !name)
+        return undefined;
+    return receiver.path.length === 0
+        ? name
+        : receiver.path.length === 1 && receiver.path[0] === 'response'
+            ? `response.${name}`
+            : undefined;
+}

package/dist/api-contract-discovery/protocol-http-response-mutations.d.mts

@@ -0,0 +1,3 @@
+import ts from '../contract-schema/typescript-api.mts';
+/** Branded metadata requires the dispatched response's body and status to remain intact. */
+export declare function mutatedHttpResponse(node: ts.Node, response: ts.Symbol, checker: ts.TypeChecker): boolean;

package/dist/api-contract-discovery/protocol-http-response-mutations.mjs

@@ -0,0 +1,31 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { contextResponseMethod } from './protocol-http-context.mjs';
+import { unwrapExpression } from './protocol-marker-analysis.mjs';
+import { expressionReceiver } from './protocol-write-receiver.mjs';
+import { executableProtocolPath } from './protocol-execution-path.mjs';
+import { opaqueProtocolCallbackPath } from './protocol-opaque-callback.mjs';
+/** Branded metadata requires the dispatched response's body and status to remain intact. */
+export function mutatedHttpResponse(node, response, checker) {
+    const target = mutationTarget(node);
+    if (!target)
+        return false;
+    const receiver = expressionReceiver(target, checker);
+    const field = receiver?.root === response
+        ? receiver.path[0]
+        : contextResponseMethod(unwrapExpression(target), response, checker, true);
+    return ((field === 'body' || field === 'status') &&
+        (executableProtocolPath(node, checker) || opaqueProtocolCallbackPath(node, checker)));
+}
+function mutationTarget(node) {
+    if (ts.isBinaryExpression(node) &&
+        node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+        node.operatorToken.kind <= ts.SyntaxKind.LastAssignment)
+        return node.left;
+    if (ts.isDeleteExpression(node))
+        return node.expression;
+    if ((ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) &&
+        (node.operator === ts.SyntaxKind.PlusPlusToken ||
+            node.operator === ts.SyntaxKind.MinusMinusToken))
+        return node.operand;
+    return undefined;
+}

package/dist/api-contract-discovery/protocol-platform-callbacks.d.mts

@@ -1,5 +1,7 @@
 import ts from '../contract-schema/typescript-api.mts';
 /** Records the actual caller compiler's library identities, including another installation. */
 export declare function registerPlatformCompilerLibraries(program: ts.Program): void;
+/** Shares actual compiler-library identity with other standard API guards. */
+export declare function standardCompilerDeclaration(declaration: ts.Declaration, checker: ts.TypeChecker): boolean;
 /** Recognizes only callback APIs supplied by the compiler's standard libraries or Node typings. */
 export declare function platformCallbackArgument(node: ts.CallExpression | ts.NewExpression, checker: ts.TypeChecker): ts.Expression | undefined;

package/dist/api-contract-discovery/protocol-platform-callbacks.mjs

@@ -27,6 +27,10 @@ function standardDeclaration(declaration, timer, checker) {
     return (timer &&
         /\/node_modules\/@types\/node\/(?:web-globals\/)?timers\.d\.ts$/.test(file.replaceAll('\\', '/')));
 }
+/** Shares actual compiler-library identity with other standard API guards. */
+export function standardCompilerDeclaration(declaration, checker) {
+    return standardDeclaration(declaration, false, checker);
+}
 function platformSymbol(expression, checker, seen = new Set()) {
     const value = unwrapExpression(expression);
     if (!ts.isIdentifier(value))

package/dist/api-contract-discovery/protocol-sse-raw-writes.mjs

@@ -6,7 +6,8 @@ import { enclosingRouteBinding, visit, } from './response-contract-route-analysi
 import { expressionReceiver, sameWriteReceiver, } from './protocol-write-receiver.mjs';
 import { sseWriteInvocation } from './protocol-sse-write-access.mjs';
 import { isSourceLevelMutation, mutationAffectsSelectedStream, sseWriteMutation, } from './protocol-sse-write-mutations.mjs';
-import { actualReceivers, helperBindings, routeKey } from './protocol-sse-write-helpers.mjs';
+import { actualReceivers, helperBindings, opaqueCallReceivesSelectedStream, routeKey, } from './protocol-sse-write-helpers.mjs';
+import { writeAccess } from './protocol-sse-write-resolution.mjs';
 /** Reports unmarked writes on executable or opaque escaping paths to a selected frame's stream. */
 export function rejectRawSseWrites(files, checker, bindings, framedWrites, routes, reject) {
     const calls = [];
@@ -30,8 +31,14 @@ export function rejectRawSseWrites(files, checker, bindings, framedWrites, route
                     if (mutationNode.getSourceFile() === source && isSourceLevelMutation(mutationNode))
                         return true;
                     const candidate = enclosingRouteBinding(mutationNode, checker, bindings, false);
-                    return !!candidate && routeKey(candidate) === routeKey(binding);
-                }, (expression) => {
+                    if (candidate && routeKey(candidate) === routeKey(binding))
+                        return true;
+                    if (!candidate &&
+                        mutationNode.getSourceFile() === source &&
+                        opaqueProtocolCallbackPath(mutationNode, checker))
+                        return true;
+                    return helperBindings(mutationNode, calls, checker, bindings).some((helper) => routeKey(helper) === routeKey(binding));
+                }, (mutationNode) => helperBindings(mutationNode, calls, checker, bindings).length > 0, (expression) => {
                     const receiver = expressionReceiver(expression, checker);
                     return receiver && actualReceivers(receiver, binding, calls, checker, bindings);
                 }, (receiver) => actualReceivers(receiver, binding, calls, checker, bindings)))
@@ -39,7 +46,7 @@ export function rejectRawSseWrites(files, checker, bindings, framedWrites, route
             continue;
         }
         const access = sseWriteInvocation(node, checker);
-        if (!access || !access.rawBytes || !potentiallyExecuted(node))
+        if (!potentiallyExecuted(node))
             continue;
         const proven = executableProtocolPath(node, checker) || opaqueProtocolCallbackPath(node, checker);
         const helpers = helperBindings(node, calls, checker, bindings);
@@ -51,17 +58,39 @@ export function rejectRawSseWrites(files, checker, bindings, framedWrites, route
             const route = routes.get(routeKey(candidate));
             if (!route)
                 continue;
+            const receiver = access?.receiver && expressionReceiver(access.receiver, checker);
+            const actual = receiver ? actualReceivers(receiver, candidate, calls, checker, bindings) : [];
+            const framed = route.receivers.flatMap((value) => actualReceivers(value, candidate, calls, checker, bindings));
+            const bound = writeAccess(node.expression);
+            const boundReceiver = bound?.method === 'bind' && expressionReceiver(bound.receiver, checker);
+            const boundActual = boundReceiver
+                ? actualReceivers(boundReceiver, candidate, calls, checker, bindings)
+                : [];
+            const accessTargetsSelected = (access?.method === 'write' || access?.method === 'end') &&
+                actual.some((value) => value !== undefined &&
+                    framed.some((frame) => frame !== undefined && sameWriteReceiver(frame, value)));
+            const bindsSelectedMember = bound?.method === 'bind' &&
+                boundActual.some((value) => value !== undefined &&
+                    framed.some((frame) => frame !== undefined &&
+                        frame.root === value.root &&
+                        value.path.length > frame.path.length &&
+                        value.path.slice(0, frame.path.length).join('.') === frame.path.join('.')));
+            if (!accessTargetsSelected &&
+                !bindsSelectedMember &&
+                opaqueCallReceivesSelectedStream(node, route.receivers, candidate, calls, checker, bindings)) {
+                reject(node, candidate, route.keys);
+                continue;
+            }
+            if (!access || !access.rawBytes)
+                continue;
             if (!access.receiver) {
                 reject(node, candidate, route.keys);
                 continue;
             }
-            const receiver = expressionReceiver(access.receiver, checker);
             if (!receiver) {
                 reject(node, candidate, route.keys);
                 continue;
             }
-            const actual = actualReceivers(receiver, candidate, calls, checker, bindings);
-            const framed = route.receivers.flatMap((value) => actualReceivers(value, candidate, calls, checker, bindings));
             if (actual.some((value) => value === undefined ||
                 framed.some((frame) => frame === undefined || sameWriteReceiver(frame, value))))
                 reject(node, candidate, route.keys);

package/dist/api-contract-discovery/protocol-sse-write-helpers.d.mts

@@ -2,5 +2,6 @@ import ts from '../contract-schema/typescript-api.mts';
 import { type HandlerBindings, type RouteBinding } from './response-contract-route-analysis.mts';
 import { type WriteReceiver } from './protocol-write-receiver.mts';
 export declare function routeKey(binding: RouteBinding): string;
+export declare function opaqueCallReceivesSelectedStream(call: ts.CallExpression, selectedReceivers: readonly WriteReceiver[], binding: RouteBinding, calls: readonly ts.CallExpression[], checker: ts.TypeChecker, bindings: HandlerBindings): boolean;
 export declare function helperBindings(node: ts.Node, calls: readonly ts.CallExpression[], checker: ts.TypeChecker, bindings: HandlerBindings): RouteBinding[];
 export declare function actualReceivers(receiver: WriteReceiver, binding: RouteBinding, calls: readonly ts.CallExpression[], checker: ts.TypeChecker, bindings: HandlerBindings, active?: Set<ts.Symbol>): (WriteReceiver | undefined)[];

package/dist/api-contract-discovery/protocol-sse-write-helpers.mjs

@@ -1,10 +1,11 @@
 import ts from '../contract-schema/typescript-api.mjs';
 import { hasBindingWrite } from './registered-route-binding-writes.mjs';
+import { createProtocolCallbackValueResolver } from './protocol-callback-values.mjs';
 import { runtimeParameters } from './registered-route-runtime-parameters.mjs';
 import { enclosingFunction } from './protocol-marker-analysis.mjs';
 import { executableProtocolPath } from './protocol-execution-path.mjs';
 import { enclosingRouteBinding, } from './response-contract-route-analysis.mjs';
-import { expressionReceiver } from './protocol-write-receiver.mjs';
+import { expressionReceiver, sameWriteReceiver, } from './protocol-write-receiver.mjs';
 export function routeKey(binding) {
     return `${binding.method}:${binding.routeTemplate}`;
 }
@@ -22,13 +23,29 @@ function implementationDeclaration(declaration, checker) {
     }
     return undefined;
 }
+function implementationCall(call, checker) {
+    return (implementationDeclaration(checker.getResolvedSignature(call)?.declaration, checker) ??
+        createProtocolCallbackValueResolver(checker).resolve(call.expression, new Map())?.node);
+}
+export function opaqueCallReceivesSelectedStream(call, selectedReceivers, binding, calls, checker, bindings) {
+    const implementation = implementationCall(call, checker);
+    if (implementation && ts.isFunctionLike(implementation) && 'body' in implementation)
+        return false;
+    const framed = selectedReceivers.flatMap((receiver) => actualReceivers(receiver, binding, calls, checker, bindings));
+    return call.arguments.some((argument) => {
+        const receiver = expressionReceiver(argument, checker);
+        if (!receiver)
+            return false;
+        return actualReceivers(receiver, binding, calls, checker, bindings).some((value) => value === undefined ||
+            framed.some((frame) => frame === undefined || sameWriteReceiver(frame, value)));
+    });
+}
 export function helperBindings(node, calls, checker, bindings) {
     const fn = enclosingFunction(node);
     if (!fn || fn.asteriskToken)
         return [];
     return calls.flatMap((call) => {
-        if (implementationDeclaration(checker.getResolvedSignature(call)?.declaration, checker) !== fn ||
-            !executableProtocolPath(call, checker))
+        if (implementationCall(call, checker) !== fn || !executableProtocolPath(call, checker))
             return [];
         const binding = enclosingRouteBinding(call, checker, bindings, false);
         return binding ? [binding] : [];
@@ -50,8 +67,7 @@ export function actualReceivers(receiver, binding, calls, checker, bindings, act
         return [undefined];
     const index = runtimeParameters(fn).indexOf(declaration);
     const actuals = calls.flatMap((call) => {
-        if (implementationDeclaration(checker.getResolvedSignature(call)?.declaration, checker) !== fn ||
-            !executableProtocolPath(call, checker))
+        if (implementationCall(call, checker) !== fn || !executableProtocolPath(call, checker))
             return [];
         const callBinding = enclosingRouteBinding(call, checker, bindings, false);
         if (!callBinding || routeKey(callBinding) !== routeKey(binding))

package/dist/api-contract-discovery/protocol-sse-write-mutations.d.mts

@@ -5,5 +5,5 @@ export type SseWriteMutation = {
     receiver: ts.Expression;
 };
 export declare function sseWriteMutation(node: ts.Node): SseWriteMutation | undefined;
-export declare function mutationAffectsSelectedStream(mutations: readonly SseWriteMutation[], frameReceivers: readonly WriteReceiver[], checker: ts.TypeChecker, isSameRoute: (node: ts.Node) => boolean, resolveActual: (expression: ts.Expression) => readonly (WriteReceiver | undefined)[] | undefined, resolveFrame: (receiver: WriteReceiver) => readonly (WriteReceiver | undefined)[]): boolean;
+export declare function mutationAffectsSelectedStream(mutations: readonly SseWriteMutation[], frameReceivers: readonly WriteReceiver[], checker: ts.TypeChecker, isSameRoute: (node: ts.Node) => boolean, isInvokedHelper: (node: ts.Node) => boolean, resolveActual: (expression: ts.Expression) => readonly (WriteReceiver | undefined)[] | undefined, resolveFrame: (receiver: WriteReceiver) => readonly (WriteReceiver | undefined)[]): boolean;
 export declare function isSourceLevelMutation(node: ts.Node): boolean;

package/dist/api-contract-discovery/protocol-sse-write-mutations.mjs

@@ -1,5 +1,7 @@
 import ts from '../contract-schema/typescript-api.mjs';
+import { potentiallyExecuted } from './protocol-executable-path.mjs';
 import { executableProtocolPath } from './protocol-execution-path.mjs';
+import { opaqueProtocolCallbackPath } from './protocol-opaque-callback.mjs';
 import { sameWriteReceiver } from './protocol-write-receiver.mjs';
 import { writeAccess } from './protocol-sse-write-resolution.mjs';
 export function sseWriteMutation(node) {
@@ -18,10 +20,14 @@ export function sseWriteMutation(node) {
 function isAssignment(kind) {
     return kind >= ts.SyntaxKind.FirstAssignment && kind <= ts.SyntaxKind.LastAssignment;
 }
-export function mutationAffectsSelectedStream(mutations, frameReceivers, checker, isSameRoute, resolveActual, resolveFrame) {
+export function mutationAffectsSelectedStream(mutations, frameReceivers, checker, isSameRoute, isInvokedHelper, resolveActual, resolveFrame) {
     const framed = frameReceivers.flatMap(resolveFrame);
     return mutations.some(({ node, receiver }) => {
-        if ((!isSourceLevelMutation(node) && !executableProtocolPath(node, checker)) ||
+        if (!potentiallyExecuted(node) ||
+            (!isSourceLevelMutation(node) &&
+                !executableProtocolPath(node, checker) &&
+                !opaqueProtocolCallbackPath(node, checker) &&
+                !isInvokedHelper(node)) ||
             !isSameRoute(node))
             return false;
         const actual = resolveActual(receiver);

package/dist/api-contract-discovery/registered-route-binding-writes.mjs

@@ -8,6 +8,14 @@ export function hasBindingWrite(declaration, checker) {
     const binding = checker.getSymbolAtLocation(declaration.name);
     let written = false;
     const referencesBinding = (node) => {
+        // Index expressions and computed property names read their keys, not write them.
+        // inspect still visits these expressions separately to detect nested side-effect writes.
+        if (ts.isComputedPropertyName(node))
+            return;
+        if (ts.isElementAccessExpression(node)) {
+            referencesBinding(node.expression);
+            return;
+        }
         if (ts.isIdentifier(node) && checker.getSymbolAtLocation(node) === binding)
             written = true;
         node.forEachChild(referencesBinding);

package/dist/basic-auth-doc-sync/index.d.mts

@@ -0,0 +1,3 @@
+export { findBasicAuthExemptPaths, findBasicAuthExemptMethodsByPath } from './source.mts';
+export { findRunbookExemptRoutes } from './runbook.mts';
+export type { ExemptRoute } from './runbook.mts';

package/dist/basic-auth-doc-sync/index.mjs

@@ -0,0 +1,2 @@
+export { findBasicAuthExemptPaths, findBasicAuthExemptMethodsByPath } from './source.mjs';
+export { findRunbookExemptRoutes } from './runbook.mjs';

package/dist/basic-auth-doc-sync/methods.d.mts

@@ -0,0 +1 @@
+export declare function isCanonicalHttpMethod(method: string): boolean;

package/dist/basic-auth-doc-sync/methods.mjs

@@ -0,0 +1,4 @@
+const HTTP_METHOD_TOKEN_RE = /^[!#$%&'*+\-.^_`|~0-9A-Z]+$/;
+export function isCanonicalHttpMethod(method) {
+    return method === method.toUpperCase() && HTTP_METHOD_TOKEN_RE.test(method);
+}

package/dist/basic-auth-doc-sync/runbook.d.mts

@@ -0,0 +1,5 @@
+export type ExemptRoute = {
+    methods: string[];
+    path: string;
+};
+export declare function findRunbookExemptRoutes(markdown: string, heading: string): ExemptRoute[] | null;

package/dist/basic-auth-doc-sync/runbook.mjs

@@ -0,0 +1,59 @@
+import { parseGfmMarkdown } from '../markdown/ast.mjs';
+import { markdownNodeText } from '../markdown/text.mjs';
+import { parseMarkdownTables } from '../markdown/tables.mjs';
+import { isCanonicalHttpMethod } from './methods.mjs';
+const METHODS_CELL_RE = /^`[^`]+`(?:\s*,\s*`[^`]+`)*$/;
+function codeText(cell) {
+    const match = /^`([^`]+)`$/.exec(cell);
+    return match?.[1] ?? null;
+}
+function methodTexts(cell) {
+    if (!METHODS_CELL_RE.test(cell))
+        return null;
+    const methods = Array.from(cell.matchAll(/`([^`]+)`/g), (match) => match[1]).filter((value) => value !== undefined);
+    return methods.every(isCanonicalHttpMethod) ? methods : null;
+}
+function tableHeaderColumns(cells) {
+    const columns = new Map();
+    for (const [index, cell] of cells.entries()) {
+        const name = cell.toLowerCase();
+        if ((name === 'path' || name === 'methods') && columns.has(name))
+            return null;
+        columns.set(name, index);
+    }
+    return columns;
+}
+export function findRunbookExemptRoutes(markdown, heading) {
+    const children = parseGfmMarkdown(markdown).children;
+    const headingIndex = children.findIndex((node) => node.type === 'heading' &&
+        node.depth === 3 &&
+        markdownNodeText(node, { whitespace: 'collapse' }).toLowerCase() === heading.toLowerCase());
+    if (headingIndex === -1)
+        return null;
+    const endIndex = children.findIndex((node, index) => index > headingIndex && node.type === 'heading' && node.depth <= 3);
+    const startOffset = children[headingIndex].position.end.offset;
+    const endOffset = endIndex === -1 ? markdown.length : children[endIndex].position.start.offset;
+    const table = parseMarkdownTables(markdown.slice(startOffset, endOffset), {
+        preserveInlineCodeMarkers: true,
+    })[0];
+    if (!table || table.length < 2)
+        return null;
+    const routes = [];
+    const columns = tableHeaderColumns(table[0].cells);
+    if (!columns)
+        return null;
+    const pathColumn = columns.get('path') ?? -1;
+    const methodsColumn = columns.get('methods') ?? -1;
+    if (pathColumn === -1 || methodsColumn === -1)
+        return null;
+    for (const row of table.slice(1)) {
+        const path = codeText(row.cells[pathColumn] ?? '');
+        const methods = methodTexts(row.cells[methodsColumn] ?? '');
+        if (!path)
+            return null;
+        if (!methods || methods.length === 0)
+            return null;
+        routes.push({ methods, path });
+    }
+    return routes;
+}

package/dist/basic-auth-doc-sync/source.d.mts

@@ -0,0 +1,2 @@
+export declare function findBasicAuthExemptPaths(code: string, variableName: string): string[] | null;
+export declare function findBasicAuthExemptMethodsByPath(code: string, variableName: string): Map<string, string[]> | null;

package/dist/basic-auth-doc-sync/source.mjs

@@ -0,0 +1,71 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { isCanonicalHttpMethod } from './methods.mjs';
+export function findBasicAuthExemptPaths(code, variableName) {
+    const declaration = findTopLevelConstInitializer(code, variableName);
+    if (!declaration)
+        return null;
+    return stringSetValues(declaration);
+}
+export function findBasicAuthExemptMethodsByPath(code, variableName) {
+    const declaration = findTopLevelConstInitializer(code, variableName);
+    if (!declaration || !isNewCollectionExpression(declaration, 'Map'))
+        return null;
+    const [entriesArg] = declaration.arguments ?? [];
+    if (!entriesArg || !ts.isArrayLiteralExpression(entriesArg))
+        return null;
+    const entries = new Map();
+    for (const entry of entriesArg.elements) {
+        if (!ts.isArrayLiteralExpression(entry) || entry.elements.length !== 2)
+            return null;
+        const path = stringLiteralValue(entry.elements[0]);
+        const methods = stringSetValues(entry.elements[1]);
+        if (!path || !methods || methods.length === 0)
+            return null;
+        if (!methods.every(isCanonicalHttpMethod))
+            return null;
+        entries.set(path, methods);
+    }
+    return entries.size > 0 ? entries : null;
+}
+function findTopLevelConstInitializer(code, name) {
+    const source = ts.createSourceFile('basic-auth.mts', code, ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
+    for (const statement of source.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0)
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (!ts.isIdentifier(declaration.name) || declaration.name.text !== name)
+                continue;
+            return declaration.initializer ?? null;
+        }
+    }
+    return null;
+}
+function stringSetValues(expression) {
+    if (!expression || !isNewCollectionExpression(expression, 'Set'))
+        return null;
+    const [valuesArg] = expression.arguments ?? [];
+    if (!valuesArg || !ts.isArrayLiteralExpression(valuesArg))
+        return null;
+    const values = [];
+    for (const element of valuesArg.elements) {
+        const value = stringLiteralValue(element);
+        if (!value)
+            return null;
+        values.push(value);
+    }
+    return values.length > 0 ? values : null;
+}
+function stringLiteralValue(expression) {
+    if (expression &&
+        (ts.isStringLiteral(expression) || ts.isNoSubstitutionTemplateLiteral(expression))) {
+        return expression.text;
+    }
+    return null;
+}
+function isNewCollectionExpression(expression, collectionName) {
+    return (ts.isNewExpression(expression) &&
+        ts.isIdentifier(expression.expression) &&
+        expression.expression.text === collectionName);
+}

package/dist/markdown/content-facts.d.mts

@@ -0,0 +1,6 @@
+import type { MarkdownSourceSpan } from './types.mts';
+/**
+ * Returns source spans for fenced/indented code, inline code, and raw HTML. Offsets are JavaScript
+ * string offsets; positions retain the parser's 1-indexed line and column coordinates.
+ */
+export declare function markdownLiteralSpans(markdown: string): MarkdownSourceSpan[];

package/dist/markdown/content-facts.mjs

@@ -0,0 +1,18 @@
+import { parseGfmMarkdown, walkMarkdown } from './ast.mjs';
+/**
+ * Returns source spans for fenced/indented code, inline code, and raw HTML. Offsets are JavaScript
+ * string offsets; positions retain the parser's 1-indexed line and column coordinates.
+ */
+export function markdownLiteralSpans(markdown) {
+    const spans = [];
+    walkMarkdown(parseGfmMarkdown(markdown), (node) => {
+        if (node.type !== 'code' && node.type !== 'inlineCode' && node.type !== 'html')
+            return;
+        spans.push({
+            kind: node.type === 'inlineCode' ? 'inline-code' : node.type,
+            position: node.position,
+            value: node.value,
+        });
+    });
+    return spans;
+}

package/dist/markdown/html-blocks.d.mts

@@ -0,0 +1,5 @@
+import type { MarkdownHtmlFact } from './types.mts';
+/** Returns source-backed HTML facts, classifying inline occurrences separately from block nodes. */
+export declare function markdownHtmlFacts(markdown: string): MarkdownHtmlFact[];
+/** Returns block HTML facts for CommonMark types 1, 6, and 7, preserving their parser bounds. */
+export declare function markdownHtmlBlocks(markdown: string): MarkdownHtmlFact[];

package/dist/markdown/html-blocks.mjs

@@ -0,0 +1,51 @@
+import { parseGfmMarkdown } from './ast.mjs';
+const BLOCK_CONTAINERS = new Set(['root', 'blockquote', 'list', 'listItem', 'footnoteDefinition']);
+const TYPE1 = /^ {0,3}<(script|style|pre|textarea)(?:[\s>]|$)/i;
+const TYPE6_NAMES = 'address|article|aside|base|basefont|blockquote|body|caption|center|col|colgroup|dd|details|' +
+    'dialog|dir|div|dl|dt|fieldset|figcaption|figure|footer|form|frame|frameset|h[1-6]|head|header|' +
+    'hr|html|iframe|legend|li|link|main|menu|menuitem|nav|noframes|ol|optgroup|option|p|param|' +
+    'search|section|summary|table|tbody|td|tfoot|th|thead|title|tr|track|ul';
+const TYPE6 = new RegExp(`^ {0,3}</?(?:${TYPE6_NAMES})(?:[\\s>]|/>|$)`, 'i');
+function htmlType(value) {
+    if (TYPE1.test(value))
+        return 1;
+    if (/^ {0,3}<!--/.test(value))
+        return 2;
+    if (/^ {0,3}<\?/.test(value))
+        return 3;
+    if (/^ {0,3}<![A-Za-z]/.test(value))
+        return 4;
+    if (/^ {0,3}<!\[CDATA\[/i.test(value))
+        return 5;
+    if (TYPE6.test(value))
+        return 6;
+    // Parsed block HTML outside types 1–6 is CommonMark type 7 by definition.
+    return 7;
+}
+/** Returns source-backed HTML facts, classifying inline occurrences separately from block nodes. */
+export function markdownHtmlFacts(markdown) {
+    const facts = [];
+    const visit = (node, inBlockContainer) => {
+        if (node.type === 'html') {
+            const kind = inBlockContainer ? 'block' : 'inline';
+            facts.push({
+                kind,
+                commonMarkType: kind === 'block' ? htmlType(node.value) : null,
+                position: node.position,
+                value: node.value,
+            });
+        }
+        if (!('children' in node))
+            return;
+        const childIsBlockContainer = BLOCK_CONTAINERS.has(node.type);
+        for (const child of node.children)
+            visit(child, childIsBlockContainer);
+    };
+    visit(parseGfmMarkdown(markdown), true);
+    return facts;
+}
+/** Returns block HTML facts for CommonMark types 1, 6, and 7, preserving their parser bounds. */
+export function markdownHtmlBlocks(markdown) {
+    return markdownHtmlFacts(markdown).filter((fact) => fact.kind === 'block' &&
+        (fact.commonMarkType === 1 || fact.commonMarkType === 6 || fact.commonMarkType === 7));
+}

package/dist/markdown/index.d.mts

@@ -1,4 +1,6 @@
 export { findMarkdownNode, findMarkdownNodes, parseGfmMarkdown, walkMarkdown } from './ast.mts';
+export { markdownHtmlBlocks, markdownHtmlFacts } from './html-blocks.mts';
+export { markdownLiteralSpans } from './content-facts.mts';
 export { extractLooseMarkdownTableRows } from './loose-pipe-rows.mts';
 export { parseMarkdownSections } from './document-sections.mts';
 export { validateMarkdownSections } from './validate-sections.mts';
@@ -6,4 +8,5 @@ export type { MarkdownVisibleSection, MarkdownSectionsDiagnostic, MarkdownSectio
 export { markdownSectionBetweenHeadings } from './sections.mts';
 export { extractMarkdownTables, parseMarkdownTables } from './tables.mts';
 export { markdownNodeText } from './text.mts';
-export type { LooseMarkdownTableRow, LooseMarkdownTableRowsOptions, MarkdownNode, MarkdownSection, MarkdownSectionOptions, MarkdownTableRow, MarkdownTextOptions, ParseMarkdownTablesOptions, PositionedMarkdownTable, } from './types.mts';
+export { hasUncheckedMarkdownTask } from './tasks.mts';
+export type { LooseMarkdownTableRow, LooseMarkdownTableRowsOptions, MarkdownNode, MarkdownHtmlBlockType, MarkdownHtmlFact, MarkdownSourcePosition, MarkdownSourceSpan, MarkdownSection, MarkdownSectionOptions, MarkdownTableRow, MarkdownTextOptions, ParseMarkdownTablesOptions, PositionedMarkdownTable, } from './types.mts';

package/dist/markdown/index.mjs

@@ -1,7 +1,10 @@
 export { findMarkdownNode, findMarkdownNodes, parseGfmMarkdown, walkMarkdown } from './ast.mjs';
+export { markdownHtmlBlocks, markdownHtmlFacts } from './html-blocks.mjs';
+export { markdownLiteralSpans } from './content-facts.mjs';
 export { extractLooseMarkdownTableRows } from './loose-pipe-rows.mjs';
 export { parseMarkdownSections } from './document-sections.mjs';
 export { validateMarkdownSections } from './validate-sections.mjs';
 export { markdownSectionBetweenHeadings } from './sections.mjs';
 export { extractMarkdownTables, parseMarkdownTables } from './tables.mjs';
 export { markdownNodeText } from './text.mjs';
+export { hasUncheckedMarkdownTask } from './tasks.mjs';

package/dist/markdown/tasks.d.mts

@@ -0,0 +1,2 @@
+/** True when the GFM parse contains at least one unchecked task-list item. */
+export declare function hasUncheckedMarkdownTask(markdown: string): boolean;

package/dist/markdown/tasks.mjs

@@ -0,0 +1,10 @@
+import { parseGfmMarkdown, walkMarkdown } from './ast.mjs';
+/** True when the GFM parse contains at least one unchecked task-list item. */
+export function hasUncheckedMarkdownTask(markdown) {
+    let unchecked = false;
+    walkMarkdown(parseGfmMarkdown(markdown), (node) => {
+        if (node.type === 'listItem' && node.checked === false)
+            unchecked = true;
+    });
+    return unchecked;
+}

package/dist/markdown/types.d.mts

@@ -1,6 +1,33 @@
 import type { Heading, Root, RootContent } from 'mdast';
 import type { Position } from 'unist';
 export type MarkdownNode = Root | RootContent;
+/** A source range measured in JavaScript string offsets and 1-indexed source coordinates. */
+export type MarkdownSourcePosition = {
+    start: {
+        line: number;
+        column: number;
+        offset: number;
+    };
+    end: {
+        line: number;
+        column: number;
+        offset: number;
+    };
+};
+/** A source-backed Markdown span with no dependency on mdast node types. */
+export type MarkdownSourceSpan = {
+    kind: 'code' | 'inline-code' | 'html';
+    position: MarkdownSourcePosition;
+    value: string;
+};
+export type MarkdownHtmlBlockType = 1 | 2 | 3 | 4 | 5 | 6 | 7;
+/** HTML parser facts distinguish block parsing from inline HTML in a phrasing container. */
+export type MarkdownHtmlFact = {
+    commonMarkType: MarkdownHtmlBlockType | null;
+    kind: 'block' | 'inline';
+    position: MarkdownSourcePosition;
+    value: string;
+};
 export type MarkdownTableRow = {
     cells: string[];
     line: number;

package/docs/basic-auth-doc-sync.md

@@ -0,0 +1,37 @@
+# Basic Auth exemption facts
+
+Import from `vouchington-tooling/basic-auth-doc-sync`. TypeScript source parsing uses
+the optional `@typescript/typescript6` dependency. Markdown-only callers can import
+`findRunbookExemptRoutes` from `vouchington-tooling/basic-auth-doc-sync/runbook`
+without installing that optional compiler.
+
+- `findBasicAuthExemptPaths(source, variableName)` returns the literal strings in a
+  top-level `const` initialized with `new Set([...])`.
+- `findBasicAuthExemptMethodsByPath(source, variableName)` returns a map of literal
+  paths to literal uppercase HTTP method tokens from `new Map([[path, new Set([...])]])`.
+- `findRunbookExemptRoutes(markdown, heading)` reads the first GFM table following
+  the configured real GFM level-three heading (case insensitive), stopping at the
+  next same-or-higher-level heading. Duplicate `Path` or `Methods` columns are rejected. Columns are named `Path`
+  and `Methods`; paths and comma-separated method tokens must be inline code.
+
+All functions return `null` for absent or unsupported declarations/tables. Source
+collections must be nonempty and contain only nonempty string literals or static
+templates; dynamic expressions are rejected. Literal order and duplicate methods
+or documentation rows are preserved for caller validation; repeated map keys follow
+Map replacement semantics. The runbook reader accepts short table separators and CRLF.
+
+Callers own symbol names, route inventory, document locations, comparisons, and
+diagnostics. These functions return data without exposing AST nodes.
+
+## Source provenance
+
+The fact readers were extracted from `vouchington/vouchington` at
+`99a0948e4e3cc0c5b9791062df6e9de37e4cf3f1`:
+
+- `static-code-analysis/targeted-guardrails/basic-auth-doc-sync-parsers.mts`
+- `static-code-analysis/targeted-guardrails/basic-auth-doc-sync.test.mts`
+- `static-code-analysis/targeted-guardrails/basic-auth-doc-sync-parser-edge.test.mts`
+
+The original parser and its characterization tests informed the extraction. The
+first extraction commit misspelled the edge-test basename in its provenance body;
+the paths above are the authoritative source list.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.31.0",
+  "version": "0.33.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -331,7 +331,17 @@
       "import": "./dist/gh-api-shell-quoting/index.mjs",
       "default": "./dist/gh-api-shell-quoting/index.mjs"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./basic-auth-doc-sync": {
+      "types": "./dist/basic-auth-doc-sync/index.d.mts",
+      "import": "./dist/basic-auth-doc-sync/index.mjs",
+      "default": "./dist/basic-auth-doc-sync/index.mjs"
+    },
+    "./basic-auth-doc-sync/runbook": {
+      "types": "./dist/basic-auth-doc-sync/runbook.d.mts",
+      "import": "./dist/basic-auth-doc-sync/runbook.mjs",
+      "default": "./dist/basic-auth-doc-sync/runbook.mjs"
+    }
   },
   "publishConfig": {
     "access": "public"