@formicoidea/labre-core 0.31.0 → 0.32.0

package/dist/_pkgs/affine-shared/adapters/utils/color.js

@@ -0,0 +1,280 @@
+import { cssVarV2, darkThemeV2, lightThemeV2 } from '@toeverything/theme/v2';
+/**
+ * A colour is treated as a shade of grey below this chroma, and is then only
+ * ever mapped onto the grey highlight — never onto a hue.
+ */
+const ACHROMATIC_CHROMA_THRESHOLD = 0.02;
+/**
+ * Greys this dark or this light are the reader's own text and background
+ * colours: leaving them unmapped is what keeps a pasted document legible in
+ * both themes.
+ */
+const DEFAULT_TEXT_LIGHTNESS_MIN = 0.4;
+const DEFAULT_TEXT_LIGHTNESS_MAX = 0.9;
+const MAX_COLOR_DISTANCE = 0.18;
+const MAX_CHROMA_DISTANCE = 0.12;
+const MAX_HUE_DISTANCE = 45;
+const supportedTextColorNames = [
+    'red',
+    'orange',
+    'yellow',
+    'green',
+    'teal',
+    'blue',
+    'purple',
+    'grey',
+];
+/**
+ * The basic CSS colour keywords. Anything outside this set parses as `null`,
+ * which means "leave the text alone" — the conservative outcome.
+ */
+const NAMED_COLORS = {
+    aqua: '#00ffff',
+    black: '#000000',
+    blue: '#0000ff',
+    cyan: '#00ffff',
+    fuchsia: '#ff00ff',
+    gray: '#808080',
+    green: '#008000',
+    grey: '#808080',
+    lime: '#00ff00',
+    magenta: '#ff00ff',
+    maroon: '#800000',
+    navy: '#000080',
+    olive: '#808000',
+    orange: '#ffa500',
+    purple: '#800080',
+    red: '#ff0000',
+    silver: '#c0c0c0',
+    teal: '#008080',
+    transparent: '#00000000',
+    white: '#ffffff',
+    yellow: '#ffff00',
+};
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+const parseHex = (value) => {
+    const hex = value.slice(1);
+    if (!/^[0-9a-f]+$/i.test(hex))
+        return null;
+    const expand = (part) => part.length === 1 ? Number.parseInt(part + part, 16) : Number.parseInt(part, 16);
+    const size = hex.length === 3 || hex.length === 4 ? 1 : 2;
+    if (hex.length !== size * 3 && hex.length !== size * 4)
+        return null;
+    return {
+        r: expand(hex.slice(0, size)),
+        g: expand(hex.slice(size, size * 2)),
+        b: expand(hex.slice(size * 2, size * 3)),
+        alpha: hex.length === size * 4 ? expand(hex.slice(size * 3, size * 4)) / 255 : 1,
+    };
+};
+/** A colour channel: `0-255`, or a percentage of 255. */
+const parseChannel = (token) => {
+    const trimmed = token.trim();
+    if (!trimmed)
+        return null;
+    const isPercentage = trimmed.endsWith('%');
+    const value = Number.parseFloat(isPercentage ? trimmed.slice(0, -1) : trimmed);
+    if (Number.isNaN(value))
+        return null;
+    return clamp(Math.round(isPercentage ? (value / 100) * 255 : value), 0, 255);
+};
+/** An alpha value: `0-1`, or a percentage. */
+const parseAlpha = (token) => {
+    if (token === null)
+        return 1;
+    const trimmed = token.trim();
+    if (!trimmed)
+        return null;
+    const isPercentage = trimmed.endsWith('%');
+    const value = Number.parseFloat(isPercentage ? trimmed.slice(0, -1) : trimmed);
+    if (Number.isNaN(value))
+        return null;
+    return clamp(isPercentage ? value / 100 : value, 0, 1);
+};
+/**
+ * Split the body of a colour function into its arguments and its alpha,
+ * accepting both the legacy comma syntax (`rgb(1, 2, 3, 0.5)`) and the modern
+ * space syntax (`rgb(1 2 3 / 50%)`).
+ */
+const splitFunctionArgs = (body) => {
+    const [main, alphaPart] = body.split('/');
+    const args = main.split(/[\s,]+/).filter(Boolean);
+    let alpha = alphaPart?.trim() ? alphaPart.trim() : null;
+    if (alpha === null && args.length === 4) {
+        alpha = args.pop() ?? null;
+    }
+    return { args, alpha };
+};
+const parseHue = (token) => {
+    const trimmed = token.trim().toLowerCase();
+    const value = Number.parseFloat(trimmed);
+    if (Number.isNaN(value))
+        return null;
+    if (trimmed.endsWith('turn'))
+        return value * 360;
+    if (trimmed.endsWith('rad'))
+        return (value * 180) / Math.PI;
+    if (trimmed.endsWith('grad'))
+        return value * 0.9;
+    return value;
+};
+const hslToRgb = (h, s, l) => {
+    const hue = ((h % 360) + 360) % 360;
+    const c = (1 - Math.abs(2 * l - 1)) * s;
+    const x = c * (1 - Math.abs(((hue / 60) % 2) - 1));
+    const m = l - c / 2;
+    const [r, g, b] = [
+        [c, x, 0],
+        [x, c, 0],
+        [0, c, x],
+        [0, x, c],
+        [x, 0, c],
+        [c, 0, x],
+    ][Math.floor(hue / 60) % 6];
+    return {
+        r: Math.round((r + m) * 255),
+        g: Math.round((g + m) * 255),
+        b: Math.round((b + m) * 255),
+    };
+};
+/**
+ * Parse the subset of CSS colour syntax that turns up in pasted HTML: hex,
+ * `rgb()`/`rgba()`, `hsl()`/`hsla()` and the basic colour keywords. Anything
+ * else — `color-mix()`, a custom property, an unknown keyword — is `null`.
+ */
+export const parseCssColor = (value) => {
+    const trimmed = value.trim().toLowerCase();
+    if (!trimmed)
+        return null;
+    const named = NAMED_COLORS[trimmed];
+    if (named)
+        return parseHex(named);
+    if (trimmed.startsWith('#'))
+        return parseHex(trimmed);
+    const fn = trimmed.match(/^(rgba?|hsla?)\(([^)]*)\)$/);
+    if (!fn)
+        return null;
+    const { args, alpha: rawAlpha } = splitFunctionArgs(fn[2]);
+    if (args.length !== 3)
+        return null;
+    const alpha = parseAlpha(rawAlpha);
+    if (alpha === null)
+        return null;
+    if (fn[1].startsWith('rgb')) {
+        const [r, g, b] = args.map(parseChannel);
+        if (r === null || g === null || b === null)
+            return null;
+        return { r, g, b, alpha };
+    }
+    const hue = parseHue(args[0]);
+    const saturation = parseAlpha(args[1]);
+    const lightness = parseAlpha(args[2]);
+    if (hue === null || saturation === null || lightness === null)
+        return null;
+    return { ...hslToRgb(hue, saturation, lightness), alpha };
+};
+const srgbToLinear = (channel) => {
+    const value = channel / 255;
+    return value <= 0.04045
+        ? value / 12.92
+        : Math.pow((value + 0.055) / 1.055, 2.4);
+};
+/**
+ * Oklab is perceptually uniform, so "near enough to count as the same colour"
+ * is a plain distance here, which it is not in sRGB.
+ */
+const rgbToOklab = ({ r, g, b }) => {
+    const red = srgbToLinear(r);
+    const green = srgbToLinear(g);
+    const blue = srgbToLinear(b);
+    const l = Math.cbrt(0.4122214708 * red + 0.5363325363 * green + 0.0514459929 * blue);
+    const m = Math.cbrt(0.2119034982 * red + 0.6806995451 * green + 0.1073969566 * blue);
+    const s = Math.cbrt(0.0883024619 * red + 0.2817188376 * green + 0.6299787005 * blue);
+    const result = {
+        l: 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+        a: 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+        b: 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+    };
+    return {
+        ...result,
+        chroma: Math.hypot(result.a, result.b),
+        hue: (Math.atan2(result.b, result.a) * 180) / Math.PI,
+    };
+};
+const supportedTextColors = supportedTextColorNames.map(name => ({
+    name,
+    cssVar: cssVarV2(`text/highlight/fg/${name}`),
+    // Both themes are candidates: a document is pasted in one theme and read in
+    // the other, so whichever reference is nearer decides the highlight.
+    references: [
+        lightThemeV2[`text/highlight/fg/${name}`],
+        darkThemeV2[`text/highlight/fg/${name}`],
+    ].flatMap(color => {
+        const parsed = parseCssColor(color);
+        return parsed ? [rgbToOklab(parsed)] : [];
+    }),
+}));
+const colorDistance = (a, b) => Math.hypot(a.l - b.l, a.a - b.a, a.b - b.b);
+const hueDistance = (a, b) => {
+    const distance = Math.abs(a - b) % 360;
+    return Math.min(distance, 360 - distance);
+};
+/**
+ * Map a CSS colour onto the nearest supported text highlight, or `null` when
+ * nothing is near enough. `null` is the good outcome for the reader: text with
+ * no colour follows the theme, whereas a wrong colour can leave it unreadable
+ * in one of the two themes.
+ */
+export const resolveNearestSupportedColor = (color) => {
+    const parsed = parseCssColor(color);
+    // A translucent colour was picked to sit on the source background, not ours.
+    if (!parsed || parsed.alpha < 1) {
+        return null;
+    }
+    const target = rgbToOklab(parsed);
+    const achromatic = target.chroma < ACHROMATIC_CHROMA_THRESHOLD;
+    if (achromatic &&
+        (target.l < DEFAULT_TEXT_LIGHTNESS_MIN || target.l > DEFAULT_TEXT_LIGHTNESS_MAX)) {
+        return null;
+    }
+    let nearest;
+    for (const supported of supportedTextColors) {
+        // A grey never becomes a hue, and a hue never becomes the grey.
+        if (achromatic !== (supported.name === 'grey')) {
+            continue;
+        }
+        for (const reference of supported.references) {
+            const distance = colorDistance(target, reference);
+            if (distance > MAX_COLOR_DISTANCE ||
+                (!achromatic &&
+                    (Math.abs(target.chroma - reference.chroma) > MAX_CHROMA_DISTANCE ||
+                        hueDistance(target.hue, reference.hue) > MAX_HUE_DISTANCE))) {
+                continue;
+            }
+            if (!nearest || distance < nearest.distance) {
+                nearest = { cssVar: supported.cssVar, distance };
+            }
+        }
+    }
+    return nearest?.cssVar ?? null;
+};
+/**
+ * Read the `color` declaration out of an inline `style` attribute, leaving
+ * `background-color` and friends alone.
+ */
+export const extractColorFromStyle = (style) => {
+    if (typeof style !== 'string') {
+        return null;
+    }
+    for (const declaration of style.split(';')) {
+        const colon = declaration.indexOf(':');
+        if (colon === -1)
+            continue;
+        // Split on the first colon only: `rgb(0 0 0 / 50%)` has none, but a
+        // `url()` or a future colour syntax may.
+        if (declaration.slice(0, colon).trim().toLowerCase() === 'color') {
+            return declaration.slice(colon + 1).trim();
+        }
+    }
+    return null;
+};

package/dist/_pkgs/affine-shared/adapters/utils/index.d.ts

@@ -1,3 +1,4 @@
+export * from './color.js';
 export * from './fetch.js';
 export * from './file-path.js';
 export * from './hast.js';

package/dist/_pkgs/affine-shared/adapters/utils/index.js

@@ -1,3 +1,4 @@
+export * from './color.js';
 export * from './fetch.js';
 export * from './file-path.js';
 export * from './hast.js';

package/dist/_pkgs/affine-shared/commands/block-crud/get-selected-blocks.js

@@ -86,9 +86,17 @@ export const getSelectedBlocksCommand = (ctx, next) => {
     if (ctx.filter) {
         dirtyResult = dirtyResult.filter(ctx.filter);
     }
-    // remove duplicate elements
+    // Remove duplicate elements. A `Set` and not `indexOf`: selecting a whole
+    // document hands this command every block at once, and a scan per block is
+    // quadratic in the size of the document.
+    const seen = new Set();
     const result = dirtyResult
-        .filter((el, index) => dirtyResult.indexOf(el) === index)
+        .filter(el => {
+        if (seen.has(el))
+            return false;
+        seen.add(el);
+        return true;
+    })
         // sort by document position
         .sort((a, b) => {
         if (a === b) {

package/dist/_pkgs/affine-shared/services/audit-service.d.ts

@@ -0,0 +1,300 @@
+import type { BlockStdScope } from '../../std/index.js';
+import type { ExtensionType } from '../../store/index.js';
+/**
+ * One audit criterion, as DATA owned by its framework and versioned like a
+ * validation rule.
+ *
+ * The criterion carries its own PROSE, in {@link prompt} — and that is a
+ * deliberate exception to the library's "no sentences" rule, not an oversight.
+ * A rule's message is addressed to a USER and therefore belongs to a host
+ * catalogue (hence `messageKey` + `messageFallback`); a criterion's prompt is
+ * addressed to an ASSISTANT, is not displayed anywhere, and is exactly the kind
+ * of thing that must be reviewable, diffable and versioned in the repository
+ * rather than retyped in an app. The user-facing half still goes through
+ * {@link labelKey} + {@link fallback}, unchanged.
+ */
+export interface AuditCriterion {
+    /** Stable id, namespaced by framework: `wardley.A1`. */
+    id: string;
+    /** Owning framework, e.g. `wardley`. A criterion never crosses frameworks. */
+    framework: string;
+    /** i18n key of the human name; resolved by the host. */
+    labelKey: string;
+    /** The framework's own wording when the host ships no catalogue for the key. */
+    fallback: string;
+    /**
+     * The criterion itself, in words, for the assistant. Never rendered.
+     *
+     * Written as an instruction to a reviewer, not as a message to a user: it
+     * states what to look for and what would make the map fail it.
+     */
+    prompt: string;
+    /** Bumped when the criterion's meaning changes, so a host can pin behaviour. */
+    version: number;
+}
+/** A role, as the assistant sees it. Vocabulary only, no geometry. */
+export interface AuditRoleFact {
+    id: string;
+    /**
+     * Mirrors `RoleKind` structurally rather than importing it: this package sits
+     * below `@labre/std/gfx` in the seam, and the DTO must stay a plain shape a
+     * host can implement. Kept in sync by the collector, which fails to compile
+     * if `RoleKind` gains a member this union does not have — which is exactly
+     * how `'text'` arrived here (MF3).
+     */
+    kind: 'node' | 'edge' | 'text';
+    /** Data hierarchy: `wardley:market` specialises `wardley:component`. */
+    parent?: string;
+    /** Optional, mirroring `RoleDef.labelKey`: a role may ship without one. */
+    labelKey?: string;
+}
+/** An axis of a framework frame. Same facts the rule families read. */
+export interface AuditAxisFact {
+    id: string;
+    orientation: 'horizontal' | 'vertical';
+    /** Unit vector of increasing value, model space (`y` grows downwards). */
+    forward: readonly [number, number];
+}
+/**
+ * A named zone of a framework frame, as PLOT RATIOS.
+ *
+ * Ratios, never model coordinates: a zone is a statement about the frame, and
+ * expressing it in model units would make it a statement about how big the user
+ * happened to draw the map. `{ x: 0.4, w: 0.3 }` is "Product" on every Wardley
+ * map ever drawn.
+ */
+export interface AuditZoneFact {
+    id: string;
+    rect: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+}
+/** One framework frame on the board — a Wardley map, a Cynefin grid. */
+export interface AuditFrameFact {
+    elementId: string;
+    framework: string;
+    /** Background declaration type, e.g. `'wardley'`. */
+    type: string;
+    /** The level of requirement in force, when the frame names one. */
+    profileId?: string;
+    axes: readonly AuditAxisFact[];
+    zones: readonly AuditZoneFact[];
+}
+/** One element measured against a frame. */
+export interface AuditElementFact {
+    id: string;
+    /** Role id, e.g. `wardley:component`. Neutral elements are never collected. */
+    role: string;
+    /** The frame it was attributed to, when it sits on one. */
+    frameId?: string;
+    /**
+     * Where it sits INSIDE that frame's plot, as ratios — `[0.62, 0.31]` reads as
+     * "in Product, fairly high up the value chain" on any Wardley map, at any
+     * size. Absent when the element is on no frame.
+     */
+    at?: readonly [number, number];
+    /** The zone its centre falls in, when the frame declares zones. */
+    zone?: string;
+}
+/**
+ * A level 1 / level 2 finding, handed to the assistant as a FACT about the map.
+ *
+ * The deterministic engine's output is an input to the audit and never the
+ * other way round. Structurally a subset of the engine's `Violation`, so the
+ * collector copies rather than converts — and so this package needs no
+ * dependency on `@labre/affine-block-surface`, which depends on it.
+ */
+export interface AuditViolationFact {
+    ruleId: string;
+    /** Never `'audit'`: an audit finding is not a fact about the map. */
+    severity: 'blocking-overridable' | 'warning';
+    elementIds: string[];
+    messageKey: string;
+    backgroundId?: string;
+    /** Set when a user already arbitrated this finding away (PF8). */
+    exemption?: 'element' | 'map';
+}
+/**
+ * Everything the assistant is told about the board. **Render-free** (ADR 0006
+ * § 5): no `TemplateResult`, no element model, no function, no DOM — a plain
+ * object that survives `structuredClone` and a `postMessage`.
+ */
+export interface AuditFacts {
+    /** The role vocabulary in play, so an id is never an opaque string. */
+    roles: readonly AuditRoleFact[];
+    frames: readonly AuditFrameFact[];
+    elements: readonly AuditElementFact[];
+    /** Levels 1 and 2, as computed by the deterministic engine. */
+    violations: readonly AuditViolationFact[];
+}
+/** What the assistant is asked to do. */
+export interface AuditRequest {
+    criteria: readonly AuditCriterion[];
+    facts: AuditFacts;
+}
+/** How far along a run is. Reported, never awaited. */
+export interface AuditProgress {
+    /** Criteria settled so far. */
+    done: number;
+    /** Criteria in the request — `request.criteria.length`. */
+    total: number;
+    /** The criterion currently being evaluated, when the provider says. */
+    criterionId?: string;
+}
+/**
+ * One audit result, in the shape of a violation object at `audit` severity.
+ *
+ * Structurally assignable to the engine's `Violation` (a test pins that), which
+ * is what lets a host panel render an audit finding with the very same code it
+ * renders a rule finding with — while `userFacingViolations` keeps it off the
+ * canvas, because that is what `audit` severity means.
+ */
+export interface AuditFinding {
+    /**
+     * Namespaced as `audit:<criterionId>` so it can never collide with a
+     * registered rule id, and so `ValidationManager.ruleOf` returns nothing for it
+     * — an audit finding is not arbitrable with a user exception. It is an
+     * opinion, and an opinion is not a rule to be waived.
+     */
+    ruleId: string;
+    /**
+     * The elements the finding is about — **not validated against the surface**.
+     *
+     * The library checks that these are strings and nothing more. An id naming an
+     * element that no longer exists, or one from another document, is published
+     * as-is: validating would cost a lookup per id, and a missing id is not
+     * *wrong* so much as *stale* — the board moves on while an audit is in
+     * flight, which is the normal case for a call that takes seconds.
+     *
+     * **A host panel must therefore tolerate absent ids**: resolve them
+     * defensively and render what it can, rather than assuming every id is a live
+     * element. This is the one place the "render it with the code you already
+     * have" claim needs a caveat.
+     */
+    elementIds: string[];
+    /** Always `'audit'`. Forced by {@link normalizeFinding}, never trusted. */
+    severity: 'audit';
+    messageKey: string;
+    messageFallback?: string;
+    suggestion?: string;
+    suggestionFallback?: string;
+    backgroundId?: string;
+    /** The criterion this came from. */
+    criterionId: string;
+    /** The criterion's `version` at the time of the run. */
+    criterionVersion: number;
+    /** When the run that produced it finished, `Date.now()`. */
+    at: number;
+}
+/**
+ * How a run ended.
+ *
+ * - `complete` — the provider settled every criterion.
+ * - `aborted` — the caller's `AbortSignal` fired. Findings produced before the
+ *   abort are KEPT: an audit interrupted halfway has still said something true.
+ * - `error` — the provider threw or rejected. A host's broken build must not
+ *   become a crash on a keystroke.
+ * - `unavailable` — nothing could answer. Either no provider is registered in
+ *   this assembly (the standalone playground, where the whole of levels 1 and 2
+ *   still works), or a registered one **declared itself unavailable** — an
+ *   assistant behind an app-side feature flag, an exhausted quota, no model
+ *   configured. The second case is passed through rather than folded into
+ *   `complete`: `unavailable` is the count of users reaching for an audit this
+ *   build cannot deliver, and it is worthless if a provider can opt out of it
+ *   by answering politely.
+ * - `superseded` — a NEWER run for the same editor started while this one was
+ *   in flight. Its `findings` are **always empty**: the answer described a
+ *   board the user has already moved past, so it is dropped from the return
+ *   value as well as from the signal, and a host that awaits without checking
+ *   the status cannot render it. Never returned by {@link requestAudit}:
+ *   superseding is the library's arbitration between two of its own calls, not
+ *   something a provider can declare (one that returns it is read as
+ *   `complete`).
+ */
+export type AuditStatus = 'complete' | 'aborted' | 'error' | 'unavailable' | 'superseded';
+export interface AuditResult {
+    status: AuditStatus;
+    findings: readonly AuditFinding[];
+    /** Free-form diagnostic for `error`. Never rendered. */
+    reason?: string;
+}
+export interface AuditRunOptions {
+    onProgress?: (progress: AuditProgress) => void;
+    signal?: AbortSignal;
+}
+export interface AuditService {
+    /**
+     * Run the audit. The ONE method of this seam.
+     *
+     * Contract for hosts:
+     * - MUST honour `signal`: stop work and either resolve with what it has or
+     *   reject with an `AbortError`. Both are accepted — {@link requestAudit}
+     *   normalises them into `status: 'aborted'`.
+     * - MUST NOT mutate anything it is handed. `request` is the library's data.
+     * - SHOULD call `onProgress` as criteria settle. Purely advisory: a provider
+     *   that never calls it is correct, just silent.
+     * - MAY reject. The library guards it anyway — see {@link requestAudit}.
+     */
+    runAudit(request: AuditRequest, options: AuditRunOptions): Promise<AuditResult>;
+}
+export declare const AuditProvider: import("../../global/di/types.js").ServiceIdentifier<AuditService> & (<U extends AuditService = AuditService>(variant: import("../../global/di/types.js").ServiceVariant) => import("../../global/di/types.js").ServiceIdentifier<U>);
+/**
+ * The ONLY way in. **No noop default is registered**, exactly as for
+ * `PivotPropertiesProvider`: absence is a *meaningful* state (standalone
+ * playground, unit tests, a labreapp build that has not wired its assistant),
+ * and making it the tested default is what keeps the degraded path honest.
+ */
+export declare function AuditExtension(service: AuditService): ExtensionType;
+/** Multi-instance: one registered {@link AuditCriterion} per impl. */
+export declare const AuditCriterionIdentifier: import("../../global/di/types.js").ServiceIdentifier<AuditCriterion> & (<U extends AuditCriterion = AuditCriterion>(variant: import("../../global/di/types.js").ServiceVariant) => import("../../global/di/types.js").ServiceIdentifier<U>);
+/**
+ * Register a framework's audit criteria. Call it from the FLAG-GATED view
+ * extension, beside `ValidationRuleExtension`: criteria are tooling, so a
+ * disabled framework contributes none and an audit of its maps has nothing to
+ * ask about.
+ *
+ * ```ts
+ * context.register(AuditCriterionExtension(WARDLEY_AUDIT_CRITERIA));
+ * ```
+ */
+export declare function AuditCriterionExtension(criteria: readonly AuditCriterion[]): ExtensionType;
+/** Every criterion registered in this editor assembly. */
+export declare function getAuditCriteria(std: BlockStdScope): AuditCriterion[];
+/**
+ * The guarded call every in-library consumer uses — the one place the provider
+ * contract is enforced rather than trusted.
+ *
+ * - **No provider registered** → `{ status: 'unavailable', findings: [] }`. A
+ *   clean refusal, not a throw and not a crash: levels 1 and 2 are untouched
+ *   and the caller reports nothing.
+ * - **The provider throws or rejects** → `{ status: 'error' }`, with the reason
+ *   kept for logs and never rendered.
+ * - **The caller aborted** → `{ status: 'aborted' }`, keeping whatever findings
+ *   the provider had already returned.
+ * - **`onProgress` throws** → swallowed. A broken progress bar must not kill
+ *   the run that feeds it.
+ *
+ * ## The request is ISOLATED before it crosses (the outbound half)
+ *
+ * `normalizeFinding` exists because a provider is not believed on the way back.
+ * This is the same statement on the way out, and it was missing: the facts a
+ * collector assembles are not all fresh objects. `backgroundAxisFacts` returns
+ * `forward` straight from a module constant (`FORWARD` in
+ * `framework-background/facts.ts`) — `as const` is compile-time only and
+ * nothing is frozen — so every `frames[].axes[].forward` handed over WAS the
+ * very array the engine multiplies against in `evaluateOrientationAgainstAxis`.
+ * A provider writing into the facts it is given (normalising a vector in place,
+ * say) flipped the axis convention for the whole process, and correct arrows
+ * started reporting as violations on the canvas. That is precisely what this
+ * file's header declares impossible.
+ *
+ * `structuredClone` at the boundary fixes the whole class rather than that one
+ * field: no future fact can leak identity either, and the cost is a constraint
+ * the seam already claims (ADR 0006 § 5 — the request must be serializable, and
+ * a test round-trips it). Value-comparing tests were structurally blind to it;
+ * an identity assertion (`.toBe`) now guards it.
+ */
+export declare function requestAudit(std: BlockStdScope, request: AuditRequest, options?: AuditRunOptions): Promise<AuditResult>;