Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Address review findings on the accessibility-mode instrumentation (PRD-8179) (#3767)

Andrew Mikofalvy87fddb4fd4af
diff --git a/packages/desktop/src/main/accessibility-posture.test.ts b/packages/desktop/src/main/accessibility-posture.test.ts
new file mode 100644
index 000000000..7dbc8a816
--- /dev/null
+++ b/packages/desktop/src/main/accessibility-posture.test.ts
@@ -0,0 +1,121 @@
+/**
+ * The one property this module exists for: a reading that did not happen must
+ * not be indistinguishable from a reading that came back empty.
+ *
+ * Both are otherwise "nothing to see" — an empty flag array and a failed read
+ * look identical the moment either is flattened to `[]`, and a responder
+ * reading the bundle then cannot tell "no accessibility modes were active"
+ * from "we could not ask". The crash-side sites draw the same distinction for
+ * the mode read off a dump; these tests keep this side honest about it.
+ */
+
+import { describe, expect, test, vi } from 'vitest';
+import {
+ accessibilityPostureFacts,
+ resolveAccessibilityFeatures,
+} from './accessibility-posture.ts';
+
+describe('resolveAccessibilityFeatures', () => {
+ test('a real reading comes back as itself', () => {
+ const onError = vi.fn();
+ expect(resolveAccessibilityFeatures(() => ['nativeAPIs', 'webContents'], onError)).toEqual([
+ 'nativeAPIs',
+ 'webContents',
+ ]);
+ expect(onError).not.toHaveBeenCalled();
+ });
+
+ test('an EMPTY reading is a real answer, not a failure', () => {
+ // The distinction the whole module turns on: Chromium answered, and the
+ // answer was "no modes active". That must not become null.
+ const onError = vi.fn();
+ expect(resolveAccessibilityFeatures(() => [], onError)).toEqual([]);
+ expect(onError).not.toHaveBeenCalled();
+ });
+
+ test('an absent method reads as null, never as an empty array', () => {
+ // An Electron older than the one that added the method. Flattening this to
+ // `[]` would assert "no modes active" about a process we never asked.
+ const onError = vi.fn();
+ expect(resolveAccessibilityFeatures(undefined, onError)).toBeNull();
+ expect(onError).not.toHaveBeenCalled();
+ });
+
+ test('a throwing method reads as null AND reports the error', () => {
+ // A guard that swallows its error removes the only signal it ever fired,
+ // which matters most here because this sits where a throw would otherwise
+ // take a boot down.
+ const onError = vi.fn();
+ const boom = new Error('accessibility state unavailable');
+ expect(
+ resolveAccessibilityFeatures(() => {
+ throw boom;
+ }, onError),
+ ).toBeNull();
+ expect(onError).toHaveBeenCalledWith(boom);
+ });
+
+ test('a throw does not escape to the caller', () => {
+ // The invariant the guard exists for: this reading never propagates.
+ expect(() =>
+ resolveAccessibilityFeatures(
+ () => {
+ throw new Error('boom');
+ },
+ () => {},
+ ),
+ ).not.toThrow();
+ });
+});
+
+describe('accessibilityPostureFacts', () => {
+ const base = { phase: 'boot', supportEnabled: true, forcedByEnv: false } as const;
+
+ test('a read flag set is carried verbatim', () => {
+ expect(accessibilityPostureFacts({ ...base, features: ['screenReader'] })).toEqual({
+ event: 'desktop.accessibility',
+ phase: 'boot',
+ supportEnabled: true,
+ features: ['screenReader'],
+ forcedByEnv: false,
+ });
+ });
+
+ test('an empty flag set is PRESENT as an empty array', () => {
+ // "We looked and nothing was active" is a finding, and it has to survive
+ // onto the line as an empty array rather than vanishing.
+ const facts = accessibilityPostureFacts({ ...base, features: [] });
+ expect(facts).toHaveProperty('features');
+ expect(facts.features).toEqual([]);
+ });
+
+ test('an unread flag set is ABSENT, not an empty array', () => {
+ // The pair to the case above, and the reason the field is spread
+ // conditionally. If this emitted `features: []` the two would be one line.
+ expect(accessibilityPostureFacts({ ...base, features: null })).not.toHaveProperty('features');
+ });
+
+ test('the empty and unread cases do not produce the same line', () => {
+ // Stated directly, so a future refactor that flattens null to `[]` fails
+ // here rather than quietly in a bundle nobody can interpret.
+ expect(accessibilityPostureFacts({ ...base, features: [] })).not.toEqual(
+ accessibilityPostureFacts({ ...base, features: null }),
+ );
+ });
+
+ test('the changed phase and the forced flag ride through', () => {
+ expect(
+ accessibilityPostureFacts({
+ phase: 'changed',
+ supportEnabled: false,
+ features: null,
+ forcedByEnv: true,
+ }),
+ ).toEqual({
+ event: 'desktop.accessibility',
+ phase: 'changed',
+ supportEnabled: false,
+ forcedByEnv: true,
+ });
+ });
+});
diff --git a/packages/desktop/src/main/accessibility-posture.ts b/packages/desktop/src/main/accessibility-posture.ts
new file mode 100644
index 000000000..e3449a183
--- /dev/null
+++ b/packages/desktop/src/main/accessibility-posture.ts
@@ -0,0 +1,94 @@
+/**
+ * The facts a `desktop.accessibility` line carries, and the one rule that makes
+ * them readable: a reading that did not happen must not look like a reading
+ * that came back empty.
+ *
+ * A family of renderer crashes reaches a Blink `CHECK` that is only reachable
+ * with a live accessibility tree. Chromium builds that tree lazily, once it
+ * detects an attached assistive-technology client, so on a report where the
+ * app's own force switch was not set, the precondition of the whole diagnosis
+ * has to be read off the log or guessed at. This line is what makes it
+ * readable on every session, crash or not — and it timestamps WHEN a client
+ * attached, which a crash dump cannot say.
+ *
+ * Lives here rather than inline in the main entry point because that module
+ * cannot be unit-tested: importing it boots Electron. The Electron calls stay
+ * at the call site and their RESULTS arrive here as plain values, so the
+ * decision this module owns — what an absent reading means — is checkable
+ * without an app.
+ */
+
+/** How a caller reads the browser process's live accessibility flag set. */
+export type AccessibilityFeatureReader = (() => string[]) | undefined;
+
+export interface AccessibilityPostureInput {
+ phase: 'boot' | 'changed';
+ /**
+ * Chromium's own "is this an accessible browser" predicate over the current
+ * mode. Kept alongside `features` because it is NOT derivable from that
+ * array: it is a predicate over the whole mode rather than a test for any one
+ * flag, and recomputing it here would be this module guessing at it.
+ */
+ supportEnabled: boolean;
+ /**
+ * The flag set, or null when it could not be read. Null is the whole point of
+ * this type — see `resolveAccessibilityFeatures`.
+ */
+ features: string[] | null;
+ /** Whether the app forced the tree on, which moots both readings above. */
+ forcedByEnv: boolean;
+}
+
+/**
+ * Read the flag set, distinguishing "came back empty" from "could not read".
+ *
+ * `[]` and null are DIFFERENT ANSWERS, and collapsing them is the failure this
+ * module exists to prevent. An empty array is a real reading: no accessibility
+ * modes are active. Null means the reading did not happen — the method is
+ * missing on an Electron older than the one that added it, or it threw — and an
+ * incident responder has to be able to tell those apart, exactly as the
+ * crash-side sites distinguish a dump that named no mode from no dump having
+ * been read at all.
+ *
+ * `onError` is not optional in spirit: a guard that swallows its error removes
+ * the only signal that it ever fired, and this one sits where a throw would
+ * otherwise take a boot down. Where that warning goes is the caller's business.
+ *
+ * What this module's contract turns on is only that the reader MAY be absent,
+ * and that its one real absence case is an Electron older than the method —
+ * not a platform. Which platforms the underlying Electron method actually
+ * works on, and the version-pinned citation backing that, live once with the
+ * call site rather than being restated here: a claim in two places is a claim
+ * that can go stale in one of them, and this particular claim has already been
+ * shipped wrong and retracted once.
+ */
+export function resolveAccessibilityFeatures(
+ read: AccessibilityFeatureReader,
+ onError: (error: unknown) => void,
+): string[] | null {
+ if (read === undefined) return null;
+ try {
+ return read();
+ } catch (error) {
+ onError(error);
+ return null;
+ }
+}
+
+/**
+ * The log payload. `features` is present only when it was actually read, so its
+ * absence says "we could not look" while `[]` says "we looked and nothing was
+ * active" — the same present-vs-absent convention the crash-detection and
+ * bug-report sites use for the accessibility mode read off a dump.
+ */
+export function accessibilityPostureFacts(
+ input: AccessibilityPostureInput,
+): Record<string, unknown> {
+ return {
+ event: 'desktop.accessibility',
+ phase: input.phase,
+ supportEnabled: input.supportEnabled,
+ ...(input.features !== null ? { features: input.features } : {}),
+ forcedByEnv: input.forcedByEnv,
+ };
+}
diff --git a/packages/desktop/src/main/crash-detection.test.ts b/packages/desktop/src/main/crash-detection.test.ts
index f42854364..1276bb4c2 100644
--- a/packages/desktop/src/main/crash-detection.test.ts
+++ b/packages/desktop/src/main/crash-detection.test.ts
@@ -1552,6 +1552,30 @@ describe('the version a boot invitation attributes the crash to', () => {
expect(breadcrumb?.crashedAppVersion).toBe(CRASHED_VERSION);
});
+ test('a sentinel-driven boot with no dump omits the accessibility fields entirely', () => {
+ // The other half of the distinction the sibling test pins. A dirty shutdown
+ // that left no dump means nothing was ever read, and an explicit null here
+ // would claim we read a dump and it stayed silent. Absent and null are two
+ // different findings; a `?? null` on this line would merge them.
+ const rig = makeRig();
+ createCrashDetection(rig.deps).detectBootCrash();
+ // Session ends without markCleanQuit and without seeding any dump.
+
+ const infoLines: Array<Record<string, unknown>> = [];
+ rig.deps.logger = {
+ info: (payload: Record<string, unknown>) => {
+ infoLines.push(payload);
+ },
+ warn: () => {},
+ };
+ createCrashDetection(rig.deps).detectBootCrash();
+
+ const breadcrumb = infoLines.find((line) => line.event === 'crash-detection.boot');
+ expect(breadcrumb?.dirtyShutdown).toBe(true);
+ expect(breadcrumb).not.toHaveProperty('crashedAccessibilityMode');
+ expect(breadcrumb).not.toHaveProperty('crashedAccessibilityModeParseFailed');
+ });
+
test('a dump carrying no accessibility mode logs null, not a missing field', () => {
// "We looked and the dump does not say" is itself the finding, and it is
// NOT "accessibility was off" — a dump for a process with no renderer in it
diff --git a/packages/desktop/src/main/crash-detection.ts b/packages/desktop/src/main/crash-detection.ts
index ff1f93c77..4f99ab256 100644
--- a/packages/desktop/src/main/crash-detection.ts
+++ b/packages/desktop/src/main/crash-detection.ts
@@ -868,12 +868,27 @@ export function createCrashDetection(deps: CrashDetectionDeps): CrashDetection {
// accessibility `CHECK` crashes are reachable only with a live
// accessibility tree, and `OK_FORCE_A11Y` is opt-in, so before
// this the precondition could only be guessed at from
- // circumstance. Logged even when null for the same reason the
- // version is — but null here is NOT "accessibility was off",
- // only "this dump does not say"; see
- // `MinidumpAccessibilityModeRead`.
- crashedAccessibilityMode: dumpAccessibilityMode?.mode ?? null,
- crashedAccessibilityModeParseFailed: dumpAccessibilityMode?.parseFailed ?? false,
+ // circumstance.
+ //
+ // Present as an explicit null when a dump WAS read and did not
+ // name a mode; absent entirely when no dump was read at all
+ // (the sentinel-driven path, where `eventDump` is undefined).
+ // Those are different findings and a single `?? null` would
+ // merge them — which is the whole distinction
+ // `MinidumpAccessibilityModeRead` exists to preserve, and the
+ // convention the sibling site in `ipc/bug-report.ts` follows.
+ //
+ // The app version beside this one CAN collapse to `?? null`,
+ // because it has a second witness in the sentinel; the
+ // accessibility mode has exactly one source, so absence here
+ // would otherwise be unreadable. Null is never "accessibility
+ // was off".
+ ...(dumpAccessibilityMode !== null
+ ? {
+ crashedAccessibilityMode: dumpAccessibilityMode.mode,
+ crashedAccessibilityModeParseFailed: dumpAccessibilityMode.parseFailed,
+ }
+ : {}),
detectingAppVersion: deps.appVersion,
},
'previous session ended uncleanly — arming report invitation',
diff --git a/packages/desktop/src/main/index.ts b/packages/desktop/src/main/index.ts
index 9ced880d3..0f093b669 100644
--- a/packages/desktop/src/main/index.ts
+++ b/packages/desktop/src/main/index.ts
@@ -170,6 +170,10 @@ import { isTerminalPlatform } from '../shared/terminal-platform.ts';
import { UNINSTALL_PRELOAD_ARG } from '../shared/uninstall-preload-arg.ts';
import { resolveShell } from '../utility/pty-host.ts';
import { buildAboutPanelOptions } from './about-panel.ts';
+import {
+ accessibilityPostureFacts,
+ resolveAccessibilityFeatures,
+} from './accessibility-posture.ts';
import { docNameFromActiveTarget, EditorActiveTargetRegistry } from './active-target-registry.ts';
import { appendOkIgnoreSync } from './append-okignore.ts';
import { registerAppImageDeepLinks } from './appimage-integration.ts';
@@ -7489,38 +7493,103 @@ if (A11Y_FORCED_BY_ENV) {
* from.
*
* The companion signal is `ax_mode`, read off a minidump's Crashpad
- * annotations (see `readMinidumpAccessibilityMode`). That one is exact — the
- * full mode bitmask — but exists ONLY where there is a readable dump. This one
- * is coarse and always present, and it carries the thing a dump cannot: WHEN
- * the client attached, relative to everything else in the log.
+ * annotations (see `readMinidumpAccessibilityMode`). This line and that one
+ * differ by SCOPE, not by granularity: `features` below is the BROWSER
+ * process's live flag set, while `ax_mode` is the flag set of ONE renderer at
+ * the instant it died. Chromium can run renderers at different modes from each
+ * other and from the browser-process summary, so neither substitutes for the
+ * other — but this one is present on every session, and it carries the thing a
+ * dump cannot: WHEN the client attached, relative to everything else in the log.
+ *
+ * `features` is Electron's `getAccessibilitySupportFeatures()`, whose own docs
+ * direct diagnostics and telemetry to it in preference to the legacy boolean.
+ * `supportEnabled` is kept beside it because it is not derivable from the array:
+ * the boolean is Chromium's own "is this an accessible browser" predicate over
+ * the mode, not a test for a particular flag, and reconstructing it here would
+ * be this file guessing at that predicate.
+ *
+ * AS OF THE ELECTRON PINNED IN THIS PACKAGE — re-verify on any upgrade —
+ * `features` is real on EVERY platform, the `@platform darwin,win32` tag in
+ * Electron's typings notwithstanding. That tag is a docs annotation rather than
+ * a runtime gate: the method is registered outside every `#if BUILDFLAG` and
+ * implemented straight over `BrowserAccessibilityState::GetAccessibilityMode()`
+ * with no platform branch, so Linux returns the live flag set like anywhere
+ * else. Checkable at
+ * https://github.com/electron/electron/blob/v41.10.3/shell/browser/api/electron_api_app.cc
+ * (`GetAccessibilitySupportFeatures`, and its `SetMethod` registration in
+ * `GetObjectTemplateBuilder`).
*
- * Read `supportEnabled` narrowly. It is Electron's `isAccessibilitySupportEnabled`,
- * the browser process's own summary of whether an AT client is attached — not
- * the renderer's `ui::AXMode`, and not a claim about which accessibility flags
- * any particular renderer had set. A false here does NOT establish that no
- * accessibility tree existed; only `ax_mode` answers that, and only for a
- * process that died.
+ * The version scoping is the load-bearing part, not decoration: the same tag
+ * sits on `isAccessibilitySupportEnabled`, which this very line already reports
+ * unqualified on all platforms, and nobody re-reads a JSDoc during a routine
+ * Electron bump. An incident responder must NOT discard a Linux `features`
+ * value as meaningless — it is evidence.
*
- * Each phase reports the value from its own authoritative source rather than
- * re-reading: the event hands the new value to the listener directly, and
- * whether the getter has already settled by then is Chromium's business, not a
- * thing this log should quietly depend on.
+ * An empty array therefore means "no accessibility modes active", not
+ * "unavailable" — and the two stay apart because the field is ABSENT when the
+ * reading did not happen (see `accessibilityPostureFacts`). What an empty array
+ * never means is that no renderer had a tree; only `ax_mode` answers that, and
+ * only for a process that died. A false `supportEnabled` does not establish it
+ * either.
+ *
+ * Each phase reports `supportEnabled` from its own authoritative source rather
+ * than re-reading: the event hands the new value to the listener directly, and
+ * whether the getter has settled by then is Chromium's business, not a thing
+ * this log should quietly depend on. `features` has no such event-supplied
+ * counterpart and is read live at each call.
*/
function logAccessibilityPosture(phase: 'boot' | 'changed', supportEnabled: boolean): void {
+ const features = resolveAccessibilityFeatures(
+ app.getAccessibilitySupportFeatures?.bind(app),
+ (error) =>
+ getRootDesktopLogger().warn(
+ // `phase` rides along because both phases share this one call site: a
+ // failure on every boot and one that only happens when an AT client
+ // attaches mid-session are different problems, and without it the two
+ // produce a byte-identical line. Reading it off the neighbouring info
+ // line instead would be an implicit dependency on log adjacency.
+ { event: 'desktop.accessibility.features-unreadable', phase, err: error },
+ 'could not read accessibility support features',
+ ),
+ );
getRootDesktopLogger().info(
- {
- event: 'desktop.accessibility',
+ accessibilityPostureFacts({
phase,
supportEnabled,
- // Whether the app itself forced the tree on, which makes `supportEnabled`
+ features,
+ // Whether the app itself forced the tree on, which makes both readings
// beside the point for reachability: with the switch set, every renderer
// has a full tree whatever any AT client is doing.
forcedByEnv: A11Y_FORCED_BY_ENV,
- },
+ }),
'renderer accessibility posture',
);
}
+/**
+ * Emit the boot posture without letting it become the thing that breaks a boot.
+ *
+ * The guard is around the WHOLE statement rather than inside the helper because
+ * `app.isAccessibilitySupportEnabled()` is evaluated as an argument, before
+ * anything inside is entered — a guard that reached only the flag-set read
+ * would leave the boolean unprotected at the same position in the same
+ * `whenReady` chain, and the invariant would be half-held.
+ *
+ * The risk is small: that boolean has been called unguarded per window creation
+ * for a long time. Small is not the same as absent, and this call site is the
+ * one place where being wrong costs the launch rather than a log field.
+ */
+function logBootAccessibilityPosture(): void {
+ try {
+ logAccessibilityPosture('boot', app.isAccessibilitySupportEnabled());
+ } catch (error) {
+ getRootDesktopLogger().warn(
+ { event: 'desktop.accessibility.boot-posture-failed', err: error },
+ 'could not record boot accessibility posture',
+ );
+ }
+}
+
if (isDriverBootSmokeMode(process.env)) {
app.whenReady().then(() => {
runDriverBootSmokeInProduction();
@@ -8041,7 +8110,7 @@ function bootPrimaryInstance(): void {
// does not exist until then, and a pre-ready read would report a default
// rather than an answer. `accessibility-support-changed` covers every
// later flip, so between them the whole session is described.
- logAccessibilityPosture('boot', app.isAccessibilitySupportEnabled());
+ logBootAccessibilityPosture();
// Login-shell SSH_AUTH_SOCK harvest — started here so its (2s-bounded)
// shell spawn overlaps the bootstrap I/O below; awaited + applied just
// before the window-open branch, ahead of the git preflight and both
diff --git a/packages/desktop/src/main/minidump-ownership.test.ts b/packages/desktop/src/main/minidump-ownership.test.ts
index 44520c3fd..4e6dbb610 100644
--- a/packages/desktop/src/main/minidump-ownership.test.ts
+++ b/packages/desktop/src/main/minidump-ownership.test.ts
@@ -739,6 +739,150 @@ describe('readMinidumpAccessibilityMode', () => {
).toBeNull();
});
+ /**
+ * The ceilings, pinned by dumps whose records are ALL PRESENT.
+ *
+ * The three lying-count cases above do not pin them. A declared 4096 makes
+ * `readExactly` run off the end of the fixture, so the EOF bound refuses
+ * first and the ceiling is never consulted — delete `MAX_ANNOTATIONS` or
+ * `MAX_MODULE_LINKS` and every one of those cases still passes. A ceiling
+ * that no test can redden is a comment, not a bound.
+ *
+ * So each case below builds every record it claims, and straddles the limit:
+ * one dump just over it must be refused, one just under it must still answer.
+ */
+ describe('the declared ceilings, pinned by fully-present records', () => {
+ /** `n` real annotation objects, with `ax_mode` last so the whole list is walked. */
+ function objectsWithAxModeLast(n: number): Record<string, string> {
+ const objects: Record<string, string> = {};
+ for (let i = 0; i < n - 1; i += 1) objects[`filler_${i}`] = String(i);
+ objects.ax_mode = REAL_AX_MODE;
+ return objects;
+ }
+
+ // Straddles sit on the EXACT boundary rather than near it. A 300/250 pair
+ // would pin only gross removal of the ceiling; 257/256 additionally catches
+ // the `>` becoming `>=` — the off-by-one that silently narrows every bound
+ // by one and is the likeliest way one of these ever breaks.
+ test('MAX_ANNOTATIONS refuses a module holding one object over the ceiling', () => {
+ // 257 real objects, all present, ceiling is 256.
+ expect(modeOf({ annotationObjects: [objectsWithAxModeLast(257)] })).toBeNull();
+ });
+
+ test('a module exactly AT MAX_ANNOTATIONS still answers', () => {
+ // The other half of the straddle. Without it, a parser that refused every
+ // large module — or one whose comparison slipped to `>=` — would pass the
+ // case above.
+ expect(modeOf({ annotationObjects: [objectsWithAxModeLast(256)] })).toBe(REAL_AX_MODE);
+ });
+
+ /**
+ * `n` real annotation objects and no `ax_mode`, for padding out a walk.
+ * Held at 256 by callers below so the per-module ceiling never fires and
+ * the budget is the only thing that can refuse.
+ */
+ function fillerObjects(n: number): Record<string, string> {
+ const objects: Record<string, string> = {};
+ for (let i = 0; i < n; i += 1) objects[`filler_${i}`] = String(i);
+ return objects;
+ }
+
+ /** `n` objects with `ax_mode` FIRST, so it is found on the walk's next slot. */
+ function objectsWithAxModeFirst(n: number): Record<string, string> {
+ const objects: Record<string, string> = { ax_mode: REAL_AX_MODE };
+ for (let i = 0; i < n - 1; i += 1) objects[`filler_${i}`] = String(i);
+ return objects;
+ }
+
+ // The budget spends exactly one unit per object INSPECTED, so `ax_mode` is
+ // found if and only if its position across the whole walk is <= 1024. That
+ // makes 1024 and 1025 the boundary, and the pair below sits on it rather
+ // than near it — the same standard the two ceilings above are held to.
+ test('the scan budget answers at exactly its last slot', () => {
+ // 3 x 256 fillers = 768 spent, then `ax_mode` last in a 256-object
+ // module — inspection 1024, the final slot the budget can pay for.
+ const modules = [
+ fillerObjects(256),
+ fillerObjects(256),
+ fillerObjects(256),
+ objectsWithAxModeLast(256),
+ ];
+ expect(modeOf({ annotationObjects: modules })).toBe(REAL_AX_MODE);
+ });
+
+ test('the scan budget refuses one object past its last slot', () => {
+ // 4 x 256 fillers spend the budget exactly, and `ax_mode` sits FIRST in
+ // the fifth module — inspection 1025, one past the last payable slot.
+ // Placing it first is what makes this ±1: at a budget of 1025 the walk
+ // reaches it and this test reddens, where a copy with `ax_mode` LAST
+ // would keep passing for any budget up to 1279.
+ //
+ // Every module is under MAX_ANNOTATIONS, so no per-module ceiling fires —
+ // and a budget that RESET per module would answer this with the mode,
+ // which is the distinction the whole-walk budget exists to make.
+ const modules = [
+ fillerObjects(256),
+ fillerObjects(256),
+ fillerObjects(256),
+ fillerObjects(256),
+ objectsWithAxModeFirst(256),
+ ];
+ expect(modeOf({ annotationObjects: modules })).toBeNull();
+ });
+
+ test('the scan budget stops PARTWAY through a module, not only between them', () => {
+ // Both cases above spend the budget on a module boundary, so each is
+ // caught by the between-module check and the per-object cutoff inside the
+ // walk never fires. This one lands the exhaustion mid-module: 200 + 256 +
+ // 256 + 256 = 968 spent, 56 left, and a fifth module of 256 whose
+ // `ax_mode` sits at index 255. Only the per-object cutoff can refuse it.
+ //
+ // Worth a test of its own because deleting that cutoff as redundant does
+ // not merely widen the budget — `remaining` would run NEGATIVE, and the
+ // between-module check compares `=== 0` rather than `<= 0`, so a negative
+ // slips past it and the budget is silently defeated for every module that
+ // follows.
+ const modules = [
+ fillerObjects(200),
+ fillerObjects(256),
+ fillerObjects(256),
+ fillerObjects(256),
+ objectsWithAxModeLast(256),
+ ];
+ expect(modeOf({ annotationObjects: modules })).toBeNull();
+ });
+
+ test('MAX_MODULE_LINKS refuses a link list longer than the ceiling', () => {
+ // 4097 modules that all genuinely exist, ceiling is 4096. Every module
+ // but the last is empty, so the object budget cannot be what refuses
+ // this — the link ceiling is the only thing standing in the way.
+ const modules = Array.from({ length: 4097 }, () => ({}) as Record<string, string>);
+ modules[4096] = { ax_mode: REAL_AX_MODE };
+ expect(modeOf({ annotationObjects: modules })).toBeNull();
+ });
+
+ test('a link list exactly AT MAX_MODULE_LINKS still answers', () => {
+ // Boundary-exact for the same reason as the pair above: 4096 must pass
+ // where 4097 is refused, so a `>` slipping to `>=` reddens this.
+ const modules = Array.from({ length: 4096 }, () => ({}) as Record<string, string>);
+ modules[4095] = { ax_mode: REAL_AX_MODE };
+ expect(modeOf({ annotationObjects: modules })).toBe(REAL_AX_MODE);
+ });
+
+ test('a walk that stays inside the budget still answers from the last module', () => {
+ // Three modules of 250 = 750 objects, under the 1024 budget. Pairs with
+ // the case above so the budget is pinned from both sides rather than by
+ // a parser that simply gives up on multi-module dumps.
+ const modules = [250, 250, 250].map((n, i) =>
+ i === 2 ? objectsWithAxModeLast(n) : objectsWithAxModeLast(n + 1),
+ );
+ modules.slice(0, 2).forEach((m) => {
+ delete m.ax_mode;
+ });
+ expect(modeOf({ annotationObjects: modules })).toBe(REAL_AX_MODE);
+ });
+ });
+
test('a declared object-list size too small for its own entries is refused', () => {
expect(modeOf({ annotationObjects: [REAL_NEIGHBOURS], annotationObjectsSize: 8 })).toBeNull();
});