@honua/app-platform 0.1.2-beta.0 → 0.1.7-beta.0

package/web-components/feature-table-engine.js

@@ -0,0 +1,1360 @@
+/**
+ * Bounded feature-table engine — the headless kernel behind
+ * `<honua-feature-table>` (issue #681).
+ *
+ * The engine is deliberately DOM-free so the whole production contract
+ * (paging, sort, typed filters, column semantics, budgets, virtualization,
+ * linked exploration state, realtime reconciliation, bounded export, and the
+ * keyboard focus model) is testable without a browser and reusable by any
+ * renderer.
+ *
+ * Design rules this module holds itself to:
+ *
+ * - **Public seams only.** Data arrives through the canonical `Source`-shaped
+ *   query surface ({@link HonuaFeatureTableQuerySource}), typed filters are
+ *   compiled by `@honua/sdk-js/filter-registry`, linked state flows through an
+ *   `@honua/sdk-js/exploration` view controller, and realtime deltas arrive as
+ *   the `@honua/sdk-js/realtime` reconciliation diff. No protocol adapter,
+ *   renderer, or SDK-private path is imported.
+ * - **Never manufacture a count.** {@link HonuaFeatureTableCount} always names
+ *   the evidence a number came from, and reports `"unknown"` rather than
+ *   guessing (REQ-004).
+ * - **Never materialize a layer.** Every fetch is bounded by
+ *   {@link HonuaFeatureTableBudgets}; the page cache evicts to stay under the
+ *   row/byte ceilings and stops issuing work once the request ceiling is
+ *   reached (REQ-002).
+ * - **Identity before linkage.** A table with no resolvable stable row identity
+ *   enters the `"unsupported"` state instead of keying rows by their position
+ *   in a page, which would corrupt selection across paging.
+ *
+ * @module
+ */
+import { isSourceQualifiedSelectionTarget, sourceFeatureSelectionTarget } from "../exploration/selection.js";
+import { projectFilterRegistryToQuery } from "../filter-registry/index.js";
+import { reconcileRealtimeKeyedState, reconcileRealtimeViewport } from "../realtime/reconciliation.js";
+/** Build the engine's row key. Shares the realtime key space (`sourceId:id`). */
+export function featureTableRowKey(sourceId, id) {
+    return `${sourceId}:${String(id)}`;
+}
+/** Conservative defaults sized for an operational browser panel. */
+export const DEFAULT_FEATURE_TABLE_BUDGETS = Object.freeze({
+    pageSize: 200,
+    maxCachedRows: 2_000,
+    maxCachedBytes: 4 * 1024 * 1024,
+    maxRequests: 64,
+    maxExportRows: 10_000,
+    windowOverscan: 20,
+});
+/** Select the work items attributed to one execution tier. */
+export function featureTableWorkByTier(evidence, tier) {
+    return Object.freeze(evidence.work.filter((item) => item.tier === tier));
+}
+/**
+ * Pure window computation: which absolute row indices a renderer must paint
+ * for the given scroll geometry, widened by `overscan` and clamped to
+ * `totalRows` when a total is known.
+ */
+export function featureTableWindow(metrics, options = {}) {
+    const rowHeight = metrics.rowHeight > 0 ? metrics.rowHeight : 1;
+    const overscan = Math.max(0, options.overscan ?? 0);
+    const first = Math.max(0, Math.floor(Math.max(0, metrics.scrollTop) / rowHeight) - overscan);
+    const visible = Math.max(1, Math.ceil(Math.max(0, metrics.viewportHeight) / rowHeight));
+    const last = first + visible + overscan * 2;
+    const end = options.totalRows === undefined ? last : Math.min(last, Math.max(0, options.totalRows));
+    return Object.freeze({ startIndex: Math.min(first, end), endIndex: end });
+}
+/** Deterministic page-cache key. Stable across property insertion order. */
+export function featureTablePageCacheKey(identity, page = {}) {
+    return [
+        `source=${identity.sourceId}`,
+        `sourceVersion=${identity.sourceVersion ?? ""}`,
+        `schemaVersion=${identity.schemaVersion ?? ""}`,
+        `plan=${identity.planFingerprint ?? ""}`,
+        `filter=${identity.filterKey}`,
+        `sort=${identity.sortKey}`,
+        `projection=${identity.projectionKey}`,
+        `scope=${[...identity.authorizationScope].sort().join("|")}`,
+        `freshness=${identity.freshness}`,
+        `offset=${page.offset ?? ""}`,
+        `limit=${page.limit ?? ""}`,
+        `cursor=${page.cursor ?? ""}`,
+    ].join(" ");
+}
+const EMPTY_EVIDENCE = Object.freeze({
+    work: Object.freeze([]),
+    degraded: Object.freeze([]),
+    cacheKey: "",
+});
+const CANCELLED_MESSAGE = "The table refresh was cancelled.";
+const NO_IDENTITY_FIELD_MESSAGE = "A stable row identity is required. Set `identityField` (or the source descriptor's `schema.primaryKey`) so selection, focus, and realtime reconciliation survive paging.";
+const QUERY_CAPABILITY_MESSAGE = "The source does not advertise the canonical `query` capability, so a feature table cannot claim that bounded paging is supported.";
+const IDENTITY_REQUIRED_HINT = "Every row must carry a string or number identity value, or selection and realtime reconciliation cannot survive paging.";
+const PAGE_SIZE_HINT = "no page could ever be held within the memory budget. Lower `pageSize` or raise `maxCachedRows`.";
+const CACHE_BUDGET_HINT = "Lower `pageSize` or raise the cache budget.";
+/**
+ * Create a bounded feature table.
+ *
+ * The engine starts `"idle"` and performs no I/O until {@link
+ * HonuaFeatureTable.refresh} or {@link HonuaFeatureTable.setScroll} is called,
+ * so mounting a grid never triggers an unbounded drain.
+ */
+export function createHonuaFeatureTable(options) {
+    const budgets = Object.freeze({ ...DEFAULT_FEATURE_TABLE_BUDGETS, ...options.budgets });
+    const pagingMode = options.pagingMode ?? "offset";
+    const residualTier = options.residualExecution === "worker" ? "worker" : "client";
+    const authorizationScope = Object.freeze([...(options.authorizationScope ?? [])]);
+    const returnGeometry = options.returnGeometry ?? false;
+    const identityField = options.identityField ?? options.source.descriptor?.schema?.primaryKey;
+    const queryCapabilityAdvertised = options.source.descriptor?.capabilities?.has("query");
+    const listeners = new Set();
+    const pages = new Map();
+    /**
+     * Exploration selection targets for the keys currently selected. Selection
+     * outlives cache residency, so a row scrolled out of the bounded window must
+     * still round-trip to a target. Pruned to the live selection on every change,
+     * so this never becomes a second unbounded row cache.
+     */
+    const selectionTargetIndex = new Map();
+    const misconfiguredPageSize = budgets.pageSize > budgets.maxCachedRows;
+    let columns = resolveColumns(options.columns ?? []);
+    let sort = Object.freeze([...(options.sort ?? [])]);
+    let filters = normalizeFilters(options.filters);
+    let selection = Object.freeze([]);
+    let focus;
+    let window = Object.freeze({ startIndex: 0, endIndex: 0 });
+    let state = identityField && !misconfiguredPageSize && queryCapabilityAdvertised !== false ? "idle" : "unsupported";
+    let stale = false;
+    let message = !identityField
+        ? NO_IDENTITY_FIELD_MESSAGE
+        : queryCapabilityAdvertised === false
+            ? QUERY_CAPABILITY_MESSAGE
+            : misconfiguredPageSize
+                ? `\`budgets.pageSize\` (${budgets.pageSize}) exceeds \`budgets.maxCachedRows\` (${budgets.maxCachedRows}), so ${PAGE_SIZE_HINT}`
+                : undefined;
+    /** Set when a bounded operation had to give something up; survives a successful run. */
+    let budgetNotice;
+    let error;
+    let conflicts = Object.freeze([]);
+    let evidence = EMPTY_EVIDENCE;
+    let count = Object.freeze({ kind: "unknown", loaded: 0, evidence: "none" });
+    let ledger = Object.freeze({
+        requests: 0,
+        lifetimeRequests: 0,
+        rows: 0,
+        bytes: 0,
+        evictedRows: 0,
+        exhausted: Object.freeze([]),
+    });
+    let totalKnown;
+    /** Which evidence produced `totalKnown`. Never inferred after the fact. */
+    let totalEvidence = "result-total-count";
+    let totalEstimated;
+    let exhausted = false;
+    let sequence = 0;
+    let revision = 0;
+    let disposed = false;
+    let generation = 0;
+    let cursorPages = 0;
+    let cursorIterator;
+    let inFlight;
+    // ── Snapshot assembly ───────────────────────────────────────
+    function buildSnapshot() {
+        return Object.freeze({
+            sourceId: options.sourceId,
+            state,
+            columns,
+            visibleColumns: Object.freeze(columns.filter((column) => column.visible)),
+            rows: Object.freeze(rowsInWindow()),
+            window,
+            count,
+            sort,
+            filters,
+            selection,
+            ...(focus ? { focus } : {}),
+            paging: Object.freeze({ mode: pagingMode, pageSize: budgets.pageSize, loadedPages: pages.size, exhausted }),
+            budgets,
+            ledger,
+            evidence,
+            conflicts,
+            stale,
+            ...(message !== undefined ? { message } : {}),
+            ...(error !== undefined ? { error } : {}),
+            revision,
+        });
+    }
+    let snapshot = buildSnapshot();
+    function publish() {
+        revision += 1;
+        snapshot = buildSnapshot();
+        for (const listener of [...listeners])
+            listener(snapshot);
+        return snapshot;
+    }
+    /**
+     * Read `state` opaquely. `loadWindow`/`nextCursorPage` can move the table to
+     * `"unsupported"` mid-flight, which a direct comparison would have narrowed
+     * away at the call site.
+     */
+    function currentState() {
+        return state;
+    }
+    function rowsInWindow() {
+        const out = [];
+        for (let index = window.startIndex; index < window.endIndex; index += 1)
+            out.push(rowAt(index));
+        return out;
+    }
+    function rowAt(index) {
+        const page = pages.get(pageOffsetFor(index));
+        if (!page)
+            return undefined;
+        return page.rows.find((row) => row.index === index);
+    }
+    function pageOffsetFor(index) {
+        return Math.floor(index / budgets.pageSize) * budgets.pageSize;
+    }
+    function loadedRows() {
+        const out = [];
+        for (const page of [...pages.values()].sort((left, right) => left.offset - right.offset))
+            out.push(...page.rows);
+        return out;
+    }
+    function findRow(key) {
+        for (const page of pages.values()) {
+            const hit = page.rows.find((row) => row.key === key);
+            if (hit)
+                return hit;
+        }
+        return undefined;
+    }
+    // ── Query composition ───────────────────────────────────────
+    function projection() {
+        const fields = columns.filter((column) => column.visible).map((column) => column.field);
+        if (fields.length === 0)
+            return undefined;
+        return identityField && !fields.includes(identityField) ? [...fields, identityField] : fields;
+    }
+    function orderedFields() {
+        const visible = columns.filter((column) => column.visible).map((column) => column.field);
+        return visible.length > 0 ? visible : columns.map((column) => column.field);
+    }
+    function composeQuery(page) {
+        const descriptor = options.source.descriptor;
+        const projected = projectFilterRegistryToQuery({ version: 1, clauses: filters }, {
+            sourceId: options.sourceId,
+            ...(descriptor
+                ? { source: { id: descriptor.id, protocol: descriptor.protocol, capabilities: descriptor.capabilities } }
+                : {}),
+        });
+        const outFields = projection();
+        const query = {
+            ...(projected.where !== undefined ? { where: projected.where } : {}),
+            ...(projected.query.spatialFilter ? { spatialFilter: projected.query.spatialFilter } : {}),
+            ...(outFields ? { outFields } : {}),
+            ...(sort.length > 0 ? { orderBy: [...sort] } : {}),
+            pagination: { ...(page.offset === undefined ? {} : { offset: page.offset }), limit: page.limit },
+            returnGeometry,
+        };
+        return { query, degraded: projected.degraded ?? [], filterKey: projected.cacheKey };
+    }
+    function identity(filterKey, planFingerprint) {
+        const descriptor = options.source.descriptor;
+        const freshness = descriptor?.analytics?.freshness;
+        return {
+            sourceId: options.sourceId,
+            ...(options.sourceVersion ? { sourceVersion: options.sourceVersion } : {}),
+            ...(descriptor?.schemaV2?.fingerprint ? { schemaVersion: descriptor.schemaV2.fingerprint } : {}),
+            ...(planFingerprint ? { planFingerprint } : {}),
+            filterKey,
+            sortKey: sort.map((entry) => `${entry.field}:${entry.direction ?? "asc"}`).join(","),
+            projectionKey: (projection() ?? ["*"]).join(","),
+            authorizationScope,
+            freshness: freshness ? `${freshness.mode}:${freshness.ttlMs ?? ""}:${generation}` : `generation:${generation}`,
+        };
+    }
+    function buildEvidence(plan, degraded, cacheKey) {
+        const work = [];
+        for (const step of plan?.steps ?? []) {
+            if (step.engine === "remote") {
+                work.push({
+                    tier: "server",
+                    concern: step.pushdown === "full" ? "filter" : "paging",
+                    detail: `${step.operation} pushdown=${step.pushdown} fidelity=${step.fidelity}: ${step.reason}`,
+                    planStepId: step.id,
+                });
+            }
+            else {
+                work.push({
+                    tier: residualTier,
+                    concern: "filter",
+                    detail: `residual ${step.operation} bounded to ${step.maxRows} rows: ${step.reason}`,
+                    planStepId: step.id,
+                });
+            }
+        }
+        for (const reason of degraded) {
+            work.push({
+                tier: residualTier,
+                concern: "filter",
+                detail: `residual for ${reason.capability}: ${reason.reason}`,
+            });
+        }
+        if (sort.length > 0) {
+            work.push({
+                tier: plan === undefined || plan.pushdown === "full" ? "server" : residualTier,
+                concern: "sort",
+                detail: `orderBy ${sort.map((entry) => `${entry.field} ${entry.direction ?? "asc"}`).join(", ")}`,
+            });
+        }
+        work.push({
+            tier: "client",
+            concern: "virtualization",
+            detail: `window ${window.startIndex}-${window.endIndex} over ${pages.size} resident page(s)`,
+        });
+        const formatted = columns.filter((column) => column.format).length;
+        if (formatted > 0) {
+            work.push({
+                tier: "client",
+                concern: "format",
+                detail: `${formatted} column formatter(s) applied at render`,
+            });
+        }
+        return Object.freeze({
+            ...(plan ? { planId: plan.id, planFingerprint: plan.fingerprint, pushdown: plan.pushdown } : {}),
+            ...(plan ? { fidelity: plan.fidelity } : {}),
+            work: Object.freeze(work.map((item) => Object.freeze(item))),
+            degraded: Object.freeze([...degraded]),
+            cacheKey,
+        });
+    }
+    // ── Budget accounting ───────────────────────────────────────
+    function noteBudget(patch) {
+        ledger = Object.freeze({
+            requests: ledger.requests + (patch.requests ?? 0),
+            lifetimeRequests: ledger.lifetimeRequests + (patch.requests ?? 0),
+            rows: ledger.rows + (patch.rows ?? 0),
+            bytes: ledger.bytes + (patch.bytes ?? 0),
+            evictedRows: ledger.evictedRows + (patch.evictedRows ?? 0),
+            exhausted: ledger.exhausted,
+        });
+    }
+    function markExhausted(kind) {
+        if (ledger.exhausted.includes(kind))
+            return;
+        ledger = Object.freeze({ ...ledger, exhausted: Object.freeze([...ledger.exhausted, kind]) });
+    }
+    function residentRows() {
+        let total = 0;
+        for (const page of pages.values())
+            total += page.rows.length;
+        return total;
+    }
+    function residentBytes() {
+        let total = 0;
+        for (const page of pages.values())
+            total += page.bytes;
+        return total;
+    }
+    function withinMemoryBudgets() {
+        return residentRows() <= budgets.maxCachedRows && residentBytes() <= budgets.maxCachedBytes;
+    }
+    function evictPage(victim) {
+        markExhausted(residentBytes() > budgets.maxCachedBytes ? "bytes" : "rows");
+        pages.delete(victim.offset);
+        noteBudget({ evictedRows: victim.rows.length });
+    }
+    /**
+     * Evict least-recently-used pages until both memory ceilings hold.
+     *
+     * `protectedOffsets` names the pages the current window just fetched, which
+     * are evicted last — but they are *not* exempt. A single page heavier than
+     * `maxCachedBytes` would otherwise sit above a ceiling documented as hard,
+     * so once every other page is gone the oversized page is dropped too and the
+     * caller is told why. Its window rows then render as placeholders, which is
+     * the honest outcome: the budget forbids holding that page.
+     */
+    function enforceMemoryBudgets(protectedOffsets) {
+        const byAge = (left, right) => left.sequence - right.sequence;
+        const notice = `A page exceeded the table's memory budget (${budgets.maxCachedRows} rows / ${budgets.maxCachedBytes} bytes) and was dropped. ${CACHE_BUDGET_HINT}`;
+        const evictable = [...pages.values()].filter((page) => !protectedOffsets.has(page.offset)).sort(byAge);
+        for (const victim of evictable) {
+            if (withinMemoryBudgets())
+                return;
+            evictPage(victim);
+            budgetNotice = notice;
+        }
+        if (withinMemoryBudgets())
+            return;
+        for (const victim of [...pages.values()].sort(byAge)) {
+            if (withinMemoryBudgets())
+                break;
+            evictPage(victim);
+            budgetNotice = notice;
+        }
+    }
+    // ── Fetching ────────────────────────────────────────────────
+    async function fetchPage(offset, signal) {
+        const composed = composeQuery({ offset: pagingMode === "cursor" ? undefined : offset, limit: budgets.pageSize });
+        const plan = options.planner?.(composed.query);
+        const cacheKey = featureTablePageCacheKey(identity(composed.filterKey, plan?.fingerprint), {
+            offset,
+            limit: budgets.pageSize,
+            ...(pagingMode === "cursor" ? { cursor: offset / budgets.pageSize } : {}),
+        });
+        const cached = pages.get(offset);
+        if (cached && cached.cacheKey === cacheKey) {
+            sequence += 1;
+            cached.sequence = sequence;
+            evidence = buildEvidence(plan, composed.degraded, cacheKey);
+            return cached;
+        }
+        if (ledger.requests >= budgets.maxRequests) {
+            markExhausted("requests");
+            return undefined;
+        }
+        noteBudget({ requests: 1 });
+        const request = { ...composed.query, ...(signal ? { signal } : {}) };
+        // `Source.query` is not required to reject when its signal aborts, so a
+        // superseded generation's response can still resolve normally and land here
+        // long after the filter/sort/projection moved on. Cancellation alone cannot
+        // prevent that; only refusing to write results whose generation no longer
+        // matches can.
+        const requestGeneration = generation;
+        const result = pagingMode === "cursor" ? await nextCursorPage(offset, request) : await options.source.query(request);
+        if (generation !== requestGeneration || disposed)
+            return undefined;
+        if (!result)
+            return undefined;
+        const rows = [];
+        for (const [index, feature] of result.features.entries()) {
+            const row = toRow(feature, offset + index);
+            if (!row)
+                return undefined; // `toRow` already moved the table to `"unsupported"`.
+            rows.push(row);
+        }
+        const bytes = estimateBytes(result.features);
+        sequence += 1;
+        const page = { offset, rows: Object.freeze([...rows]), bytes, cacheKey, sequence };
+        pages.set(offset, page);
+        noteBudget({ rows: rows.length, bytes });
+        if (rows.length < budgets.pageSize && !result.exceededTransferLimit) {
+            exhausted = true;
+            if (totalKnown === undefined) {
+                totalKnown = offset + rows.length;
+                totalEvidence = "exhausted-pages";
+            }
+        }
+        if (typeof result.totalCount === "number") {
+            totalKnown = result.totalCount;
+            totalEvidence = "result-total-count";
+        }
+        else if (typeof plan?.estimates?.rows === "number")
+            totalEstimated = plan.estimates.rows;
+        evidence = buildEvidence(plan, [...composed.degraded, ...(result.degraded ?? [])], cacheKey);
+        enforceMemoryBudgets(new Set([offset]));
+        return page;
+    }
+    /**
+     * Forward-only cursor paging over `Source.stream()` — the protocol-neutral
+     * cursor seam. Random access is impossible by construction, so a jump past
+     * the drained frontier is reported as `"unsupported"` rather than silently
+     * served from the wrong page.
+     */
+    async function nextCursorPage(offset, request) {
+        const stream = options.source.stream;
+        if (!stream) {
+            state = "unsupported";
+            message = 'Cursor paging requires the source\'s `stream` capability. Use `pagingMode: "offset"` instead.';
+            return undefined;
+        }
+        const wantedPage = offset / budgets.pageSize;
+        if (wantedPage > cursorPages) {
+            state = "unsupported";
+            message = `Cursor paging is forward-only: page ${wantedPage} is past the drained frontier (${cursorPages}).`;
+            return undefined;
+        }
+        cursorIterator ??= stream.call(options.source, request);
+        const next = await cursorIterator.next();
+        if (next.done) {
+            exhausted = true;
+            return { features: [], exceededTransferLimit: false };
+        }
+        cursorPages += 1;
+        return next.value;
+    }
+    /**
+     * Build one row, or move the table to `"unsupported"` and return `undefined`.
+     *
+     * A row whose identity attribute is missing, `null`, or not a string/number
+     * has no stable identity. Substituting its position in the page would key the
+     * row by an offset that changes with every sort, filter, and page boundary —
+     * exactly the selection corruption the unsupported-identity state exists to
+     * prevent — so this refuses instead of inventing one.
+     */
+    function toRow(feature, index) {
+        const attributes = feature.attributes ?? {};
+        const raw = identityField ? attributes[identityField] : undefined;
+        if (typeof raw !== "string" && typeof raw !== "number") {
+            state = "unsupported";
+            message = `Row ${index} has no stable identity: \`${identityField}\` is ${describeIdentityValue(raw)}. ${IDENTITY_REQUIRED_HINT}`;
+            return undefined;
+        }
+        const id = raw;
+        return Object.freeze({
+            key: featureTableRowKey(options.sourceId, id),
+            id,
+            sourceId: options.sourceId,
+            index,
+            attributes,
+            ...(feature.geometry !== undefined ? { geometry: feature.geometry } : {}),
+            target: sourceFeatureSelectionTarget(options.sourceId, id),
+        });
+    }
+    function recomputeCount() {
+        const loaded = residentRows();
+        if (typeof totalKnown === "number") {
+            count = Object.freeze({ kind: "known", value: totalKnown, loaded, evidence: totalEvidence });
+            return;
+        }
+        if (exhausted) {
+            count = Object.freeze({ kind: "known", value: loaded, loaded, evidence: "exhausted-pages" });
+            return;
+        }
+        if (typeof totalEstimated === "number") {
+            count = Object.freeze({ kind: "estimated", value: totalEstimated, loaded, evidence: "plan-estimate" });
+            return;
+        }
+        count =
+            loaded > 0
+                ? Object.freeze({ kind: "partial", loaded, evidence: "loaded-rows" })
+                : Object.freeze({ kind: "unknown", loaded, evidence: "none" });
+    }
+    async function loadWindow(signal) {
+        const wanted = new Set();
+        const end = Math.max(window.endIndex, window.startIndex + 1);
+        for (let index = window.startIndex; index < end; index += 1)
+            wanted.add(pageOffsetFor(index));
+        for (const offset of [...wanted].sort((left, right) => left - right)) {
+            if (currentState() === "unsupported")
+                return;
+            if (exhausted && typeof totalKnown === "number" && offset >= totalKnown)
+                continue;
+            await fetchPage(offset, signal);
+            if (signal?.aborted)
+                return;
+        }
+        enforceMemoryBudgets(wanted);
+    }
+    async function run(signal) {
+        if (disposed || state === "unsupported")
+            return snapshot;
+        inFlight?.abort();
+        const controller = new AbortController();
+        inFlight = controller;
+        if (signal) {
+            if (signal.aborted)
+                controller.abort();
+            else
+                signal.addEventListener("abort", () => controller.abort(), { once: true });
+        }
+        // A superseded run must not write state either: its `cancelled` verdict
+        // would otherwise land after the newer run already published `ready`.
+        const runGeneration = generation;
+        state = "loading";
+        error = undefined;
+        publish();
+        try {
+            await loadWindow(controller.signal);
+            if (generation !== runGeneration || disposed)
+                return snapshot;
+            if (controller.signal.aborted) {
+                state = "cancelled";
+                message = CANCELLED_MESSAGE;
+            }
+            else if (currentState() !== "unsupported") {
+                const complete = exhausted || (typeof totalKnown === "number" && residentRows() >= totalKnown);
+                state = complete ? "ready" : "partial";
+                // A budget the run had to give something up for is not an error, but it
+                // must not be silently cleared either.
+                message = budgetNotice;
+                stale = false;
+            }
+        }
+        catch (caught) {
+            if (generation !== runGeneration || disposed)
+                return snapshot;
+            if (isAbort(caught)) {
+                state = "cancelled";
+                message = CANCELLED_MESSAGE;
+            }
+            else {
+                state = "error";
+                error = caught;
+                message = caught instanceof Error ? caught.message : "The table query failed.";
+            }
+        }
+        finally {
+            if (inFlight === controller)
+                inFlight = undefined;
+        }
+        recomputeCount();
+        return publish();
+    }
+    function invalidate() {
+        generation += 1;
+        pages.clear();
+        exhausted = false;
+        totalKnown = undefined;
+        totalEvidence = "result-total-count";
+        totalEstimated = undefined;
+        cursorPages = 0;
+        void cursorIterator?.return(undefined);
+        cursorIterator = undefined;
+        // `budgets.maxRequests` bounds one filter/sort/projection identity. Carrying
+        // the previous identity's consumption forward would let an exhausted table
+        // refuse to load a brand-new question forever, so the per-identity counter
+        // and its exhaustion flags reset while the lifetime totals stay intact.
+        ledger = Object.freeze({ ...ledger, requests: 0, exhausted: Object.freeze([]) });
+        budgetNotice = undefined;
+        conflicts = Object.freeze([]);
+        if (state !== "unsupported")
+            state = "idle";
+    }
+    function ensureWindow() {
+        if (window.endIndex > window.startIndex)
+            return;
+        window = Object.freeze({ startIndex: 0, endIndex: budgets.pageSize });
+    }
+    // ── Selection + focus ───────────────────────────────────────
+    function setSelection(next) {
+        const deduped = [...new Set(next)];
+        if (deduped.length === selection.length && deduped.every((key, index) => selection[index] === key))
+            return;
+        selection = Object.freeze(deduped);
+        rememberSelectionTargets();
+        publish();
+    }
+    /**
+     * Keep an exploration target for every selected key, and only for those keys.
+     *
+     * Resident rows supply their own target; keys learned from
+     * {@link HonuaFeatureTable.keysForTargets} keep the target they were resolved
+     * from. Pruning to the live selection bounds the index by selection size.
+     */
+    function rememberSelectionTargets() {
+        for (const key of selection) {
+            const row = findRow(key);
+            if (row)
+                selectionTargetIndex.set(key, row.target);
+        }
+        for (const key of [...selectionTargetIndex.keys()]) {
+            if (!selection.includes(key))
+                selectionTargetIndex.delete(key);
+        }
+    }
+    /**
+     * The row key a selection target maps to, or `undefined` when the target
+     * belongs to another source.
+     *
+     * Resolution is arithmetic on identity, not a cache lookup: a target for this
+     * source resolves whether or not its page is resident. A bare `FeatureId`
+     * target (the single-source exploration form) is treated as this source's.
+     */
+    function keyForTarget(target) {
+        if (!isSourceQualifiedSelectionTarget(target))
+            return featureTableRowKey(options.sourceId, target);
+        if (target.sourceId !== options.sourceId)
+            return undefined;
+        return featureTableRowKey(options.sourceId, target.id);
+    }
+    async function applyFocusMove(move) {
+        const fields = orderedFields();
+        if (fields.length === 0)
+            return snapshot;
+        const current = focus ? findRow(focus.rowKey) : undefined;
+        const pageStep = Math.max(1, window.endIndex - window.startIndex);
+        const lastIndex = typeof totalKnown === "number" ? Math.max(0, totalKnown - 1) : maxLoadedIndex();
+        let absolute = current?.index ?? window.startIndex;
+        let field = focus ? Math.max(0, fields.indexOf(focus.field)) : 0;
+        switch (move) {
+            case "up":
+                absolute -= 1;
+                break;
+            case "down":
+                absolute += 1;
+                break;
+            case "left":
+                field -= 1;
+                break;
+            case "right":
+                field += 1;
+                break;
+            case "row-start":
+                field = 0;
+                break;
+            case "row-end":
+                field = fields.length - 1;
+                break;
+            case "page-up":
+                absolute -= pageStep;
+                break;
+            case "page-down":
+                absolute += pageStep;
+                break;
+            case "grid-start":
+                absolute = 0;
+                field = 0;
+                break;
+            case "grid-end":
+                absolute = lastIndex;
+                field = fields.length - 1;
+                break;
+        }
+        absolute = Math.max(0, Math.min(absolute, lastIndex));
+        field = Math.max(0, Math.min(field, fields.length - 1));
+        if (absolute < window.startIndex || absolute >= window.endIndex) {
+            const span = Math.max(1, window.endIndex - window.startIndex);
+            const start = Math.max(0, absolute - Math.floor(span / 2));
+            window = Object.freeze({ startIndex: start, endIndex: start + span });
+            await run(undefined);
+        }
+        const row = rowAt(absolute);
+        const nextField = fields[field];
+        if (!row || nextField === undefined)
+            return publish();
+        focus = Object.freeze({ rowKey: row.key, field: nextField });
+        return publish();
+    }
+    function maxLoadedIndex() {
+        let max = 0;
+        for (const page of pages.values()) {
+            for (const row of page.rows)
+                max = Math.max(max, row.index);
+        }
+        return max;
+    }
+    // ── Realtime reconciliation (REQ-005) ───────────────────────
+    function reconcile(diff) {
+        const keyed = {
+            changes: diff.changes.map((change) => ({ kind: change.kind, key: change.key, id: change.id })),
+            reset: diff.reset,
+            ...(diff.resetReason ? { resetReason: diff.resetReason } : {}),
+        };
+        const nextConflicts = [];
+        const patched = [];
+        const sortFields = new Set(sort.map((entry) => entry.field));
+        const selectionResult = reconcileRealtimeKeyedState(new Set(selection), keyed);
+        const focusResult = reconcileRealtimeKeyedState(new Set(focus ? [focus.rowKey] : []), keyed);
+        const viewportResult = reconcileRealtimeViewport(window, keyed);
+        if (diff.reset) {
+            // A replacement snapshot / schema change replaces identity wholesale: the
+            // cache is dropped and the conflict announced. Sort, filters, and column
+            // state are user intent, so they are deliberately preserved.
+            const preservedWindow = window;
+            invalidate();
+            window = preservedWindow;
+            selection = Object.freeze([]);
+            focus = undefined;
+            stale = true;
+            if (state !== "unsupported")
+                state = "stale";
+            const code = diff.resetReason === "schema-changed" ? "schema-changed" : "snapshot-reset";
+            message =
+                code === "schema-changed"
+                    ? "The source schema changed; refresh the table to rebuild rows."
+                    : "A replacement snapshot arrived; refresh the table to rebuild rows.";
+            nextConflicts.push({ code, message, rowKeys: Object.freeze([]) });
+        }
+        else {
+            for (const change of diff.changes) {
+                if (change.kind === "delete") {
+                    removeRow(change.key);
+                    continue;
+                }
+                const existing = findRow(change.key);
+                // A create landing outside the resident window is picked up by the next
+                // fetch; patching it in would fabricate an ordering position.
+                if (!existing)
+                    continue;
+                const attributes = change.record?.feature.attributes;
+                if (!attributes)
+                    continue;
+                if (changesSortKey(existing.attributes, attributes, sortFields)) {
+                    nextConflicts.push({
+                        code: "sort-key-changed",
+                        message: "A live update changed a sorted column. The row was patched in place; refresh to re-order the table.",
+                        rowKeys: Object.freeze([change.key]),
+                    });
+                }
+                patchRow(existing, attributes, change.record?.feature.geometry);
+                patched.push(change.key);
+            }
+            if (selectionResult.invalidations.length > 0) {
+                selection = Object.freeze([...selectionResult.next]);
+                nextConflicts.push({
+                    code: "selection-invalidated",
+                    message: "Selected rows were deleted upstream and were dropped from the selection.",
+                    rowKeys: Object.freeze(selectionResult.invalidations.map((entry) => entry.key)),
+                });
+            }
+            if (focus && focusResult.invalidations.length > 0) {
+                const deleted = focus.rowKey;
+                focus = nextFocusAfterDeletion(focus);
+                nextConflicts.push({
+                    code: "focused-row-deleted",
+                    message: "The focused row was deleted upstream. Focus moved to the next available row.",
+                    rowKeys: Object.freeze([deleted]),
+                });
+            }
+        }
+        // Realtime updates can change the serialized size of a resident page.
+        // Re-apply the hard cache ceilings after reconciliation so a large delta
+        // cannot bypass the same bounded-memory contract as a fetched page.
+        enforceMemoryBudgets(new Set());
+        if (budgetNotice !== undefined)
+            message = budgetNotice;
+        recomputeCount();
+        conflicts = Object.freeze(nextConflicts.map((conflict) => Object.freeze(conflict)));
+        return Object.freeze({
+            preserved: nextConflicts.length === 0,
+            conflicts,
+            ...(focus ? { focus } : {}),
+            selection,
+            sort,
+            window: viewportResult.viewport,
+            invalidations: Object.freeze([...selectionResult.invalidations, ...focusResult.invalidations]),
+            patchedRowKeys: Object.freeze(patched),
+        });
+    }
+    function removeRow(key) {
+        for (const page of [...pages.values()]) {
+            if (!page.rows.some((row) => row.key === key))
+                continue;
+            const rows = Object.freeze(page.rows.filter((row) => row.key !== key));
+            pages.set(page.offset, {
+                ...page,
+                rows,
+                bytes: estimateBytes(rows.map((row) => ({ attributes: row.attributes }))),
+            });
+            if (typeof totalKnown === "number")
+                totalKnown = Math.max(0, totalKnown - 1);
+            return;
+        }
+    }
+    function patchRow(row, attributes, geometry) {
+        const page = pages.get(pageOffsetFor(row.index));
+        if (!page)
+            return;
+        const next = Object.freeze({
+            ...row,
+            attributes: { ...row.attributes, ...attributes },
+            ...(geometry !== undefined ? { geometry } : {}),
+        });
+        const rows = Object.freeze(page.rows.map((candidate) => (candidate.key === row.key ? next : candidate)));
+        pages.set(page.offset, {
+            ...page,
+            rows,
+            bytes: estimateBytes(rows.map((candidate) => ({ attributes: candidate.attributes }))),
+        });
+    }
+    function nextFocusAfterDeletion(current) {
+        const fallback = loadedRows().find((row) => row.key !== current.rowKey);
+        return fallback ? Object.freeze({ rowKey: fallback.key, field: current.field }) : undefined;
+    }
+    // ── Mutators ────────────────────────────────────────────────
+    async function refresh(refreshOptions = {}) {
+        invalidate();
+        ensureWindow();
+        return run(refreshOptions.signal);
+    }
+    async function setSort(nextSort) {
+        sort = Object.freeze([...nextSort]);
+        invalidate();
+        ensureWindow();
+        return run(undefined);
+    }
+    async function setColumns(nextColumns) {
+        const before = (projection() ?? []).join(",");
+        columns = resolveColumns(nextColumns);
+        if ((projection() ?? []).join(",") === before)
+            return publish();
+        invalidate();
+        ensureWindow();
+        return run(undefined);
+    }
+    async function runExport(request) {
+        const fields = orderedFields();
+        if (currentState() === "unsupported") {
+            return Object.freeze({
+                format: request.format,
+                content: request.format === "csv" ? toCsv([], fields, columns) : toJson([], fields, columns),
+                rowCount: 0,
+                truncated: false,
+                columns: Object.freeze([...fields]),
+                evidence,
+            });
+        }
+        const ceiling = Math.max(0, Math.min(request.maxRows ?? budgets.maxExportRows, budgets.maxExportRows));
+        const rows = [];
+        let limit = (request.maxRows ?? 0) > budgets.maxExportRows ? "export-rows" : undefined;
+        if (request.selectionOnly) {
+            const keys = new Set(selection);
+            for (const row of loadedRows()) {
+                if (keys.has(row.key) && rows.length < ceiling)
+                    rows.push(row);
+            }
+        }
+        else {
+            let offset = 0;
+            while (rows.length < ceiling) {
+                if (ledger.requests >= budgets.maxRequests) {
+                    markExhausted("requests");
+                    limit = "requests";
+                    break;
+                }
+                const page = await fetchPage(offset, request.signal);
+                if (!page || page.rows.length === 0)
+                    break;
+                for (const row of page.rows) {
+                    if (rows.length < ceiling)
+                        rows.push(row);
+                }
+                if (page.rows.length < budgets.pageSize)
+                    break;
+                offset += budgets.pageSize;
+            }
+            if (rows.length >= ceiling && !exhausted)
+                limit ??= "export-rows";
+        }
+        recomputeCount();
+        publish();
+        return Object.freeze({
+            format: request.format,
+            content: request.format === "csv" ? toCsv(rows, fields, columns) : toJson(rows, fields, columns),
+            rowCount: rows.length,
+            truncated: limit !== undefined,
+            ...(limit ? { limit } : {}),
+            columns: Object.freeze([...fields]),
+            evidence,
+        });
+    }
+    return {
+        get snapshot() {
+            return snapshot;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        refresh,
+        async setScroll(metrics) {
+            const next = featureTableWindow(metrics, {
+                overscan: budgets.windowOverscan,
+                ...(typeof totalKnown === "number" ? { totalRows: totalKnown } : {}),
+            });
+            if (next.startIndex === window.startIndex && next.endIndex === window.endIndex && state !== "idle") {
+                return snapshot;
+            }
+            window = next;
+            return run(undefined);
+        },
+        setSort,
+        async toggleSort(field, toggleOptions = {}) {
+            const existing = sort.find((entry) => entry.field === field);
+            const others = toggleOptions.additive ? sort.filter((entry) => entry.field !== field) : [];
+            if (existing === undefined)
+                return setSort([...others, { field, direction: "asc" }]);
+            if ((existing.direction ?? "asc") === "asc")
+                return setSort([...others, { field, direction: "desc" }]);
+            return setSort(others);
+        },
+        async setFilters(nextFilters) {
+            filters = normalizeFilters(nextFilters);
+            invalidate();
+            ensureWindow();
+            return run(undefined);
+        },
+        setColumns,
+        async setColumnVisibility(field, visible) {
+            return setColumns(columns.map((column) => (column.field === field ? { ...column, visible } : { ...column })));
+        },
+        select(keys, selectOptions = {}) {
+            setSelection(selectOptions.replace === false ? [...selection, ...keys] : keys);
+        },
+        deselect(keys) {
+            if (!keys) {
+                setSelection([]);
+                return;
+            }
+            const drop = new Set(keys);
+            setSelection(selection.filter((key) => !drop.has(key)));
+        },
+        keysForTargets(targets) {
+            const out = [];
+            for (const target of targets) {
+                const key = keyForTarget(target);
+                if (key === undefined || out.includes(key))
+                    continue;
+                // Remember the target so a selection made from an off-window key can
+                // still be published back as a target.
+                selectionTargetIndex.set(key, target);
+                out.push(key);
+            }
+            return Object.freeze(out);
+        },
+        selectionTargets() {
+            const out = [];
+            for (const key of selection) {
+                const target = findRow(key)?.target ?? selectionTargetIndex.get(key);
+                if (target !== undefined)
+                    out.push(target);
+            }
+            return Object.freeze(out);
+        },
+        setFocus(nextFocus) {
+            focus = nextFocus ? Object.freeze({ ...nextFocus }) : undefined;
+            publish();
+        },
+        moveFocus: applyFocusMove,
+        applyRealtimeDiff(diff) {
+            const outcome = reconcile(diff);
+            publish();
+            return outcome;
+        },
+        markStale(nextMessage) {
+            stale = true;
+            if (state === "ready" || state === "partial")
+                state = "stale";
+            message = nextMessage;
+            publish();
+        },
+        export: runExport,
+        cancel() {
+            const controller = inFlight;
+            inFlight = undefined;
+            controller?.abort();
+            if (state === "loading") {
+                state = "cancelled";
+                message = CANCELLED_MESSAGE;
+                publish();
+            }
+        },
+        dispose() {
+            disposed = true;
+            inFlight?.abort();
+            inFlight = undefined;
+            void cursorIterator?.return(undefined);
+            cursorIterator = undefined;
+            pages.clear();
+            listeners.clear();
+        },
+    };
+}
+/**
+ * Wire a bounded table to a shared exploration view controller in **both**
+ * directions (REQ-003).
+ *
+ * Table → context: selection, sort, filters, and the virtualization window
+ * (as the shared `page` slice) are published as intents from the bound view,
+ * so the linked-view preset decides whether peers accept them.
+ *
+ * Context → table: peer changes to selection, sort, visible fields, and filters
+ * are applied to the table. The view controller suppresses self-origin
+ * notifications, and this binding additionally guards re-entry, so no feedback
+ * loop is possible.
+ *
+ * Returns an unsubscribe function; call it on component teardown.
+ */
+export function linkFeatureTableToExploration(table, view, options = {}) {
+    const syncSort = options.sort ?? true;
+    const syncFields = options.visibleFields ?? true;
+    const syncFilters = options.filters ?? true;
+    const syncSelection = options.selection ?? true;
+    const syncPage = options.page ?? true;
+    let applying = false;
+    let suppressFilterPublish = 0;
+    /** Filter snapshots requested by inbound assignments; these are suppressed. */
+    const inboundFilterSnapshots = new Set();
+    let queuedFilterPublish = false;
+    const publishedFilterIds = new Set();
+    function publishFilters(snapshot) {
+        const currentFilterIds = new Set();
+        for (const clause of snapshot.filters) {
+            const explorationClause = filterClauseToExplorationClause(clause);
+            if (explorationClause === undefined || clause.enabled === false)
+                continue;
+            currentFilterIds.add(clause.id);
+            publishedFilterIds.add(clause.id);
+            view.setFilter(clause.id, explorationClause);
+        }
+        for (const id of publishedFilterIds) {
+            if (!currentFilterIds.has(id)) {
+                view.clearFilter(id);
+                publishedFilterIds.delete(id);
+            }
+        }
+    }
+    const unsubscribeContext = view.subscribe(["selection", "sort", "visibleFields", "filters"], (event) => {
+        if (applying)
+            return;
+        applying = true;
+        try {
+            if (syncSelection && event.changedSlices.has("selection")) {
+                table.select(table.keysForTargets(event.state.selection), { replace: true });
+            }
+            if (syncSort && event.changedSlices.has("sort"))
+                void table.setSort(event.state.sort);
+            if (syncFields && event.changedSlices.has("visibleFields")) {
+                const fields = new Set(event.state.visibleFields);
+                if (fields.size > 0) {
+                    void table.setColumns(table.snapshot.columns.map((column) => ({ ...column, visible: fields.has(column.field) })));
+                }
+            }
+            if (syncFilters && event.changedSlices.has("filters")) {
+                suppressFilterPublish += 1;
+                const inboundRefresh = table.setFilters(Object.entries(event.state.filters).map(([id, clause]) => explorationClauseToFilterClause(id, clause)));
+                // setFilters publishes its loading snapshot synchronously before it
+                // returns. Remember that exact snapshot so completion of this inbound
+                // assignment is not mistaken for a local table edit.
+                const inboundSnapshot = table.snapshot.filters;
+                inboundFilterSnapshots.add(inboundSnapshot);
+                void inboundRefresh.finally(() => {
+                    inboundFilterSnapshots.delete(inboundSnapshot);
+                    suppressFilterPublish -= 1;
+                    if (suppressFilterPublish === 0 && queuedFilterPublish) {
+                        queuedFilterPublish = false;
+                        if (!inboundFilterSnapshots.has(table.snapshot.filters))
+                            publishFilters(table.snapshot);
+                    }
+                });
+            }
+        }
+        finally {
+            applying = false;
+        }
+    });
+    let lastSelection = table.snapshot.selection;
+    let lastSort = table.snapshot.sort;
+    let lastWindow = table.snapshot.window;
+    let lastFilters = table.snapshot.filters;
+    const unsubscribeTable = table.subscribe((snapshot) => {
+        const filtersChanged = snapshot.filters !== lastFilters;
+        lastFilters = snapshot.filters;
+        if (applying)
+            return;
+        applying = true;
+        try {
+            if (syncSelection && snapshot.selection !== lastSelection) {
+                lastSelection = snapshot.selection;
+                // Replace only this table's own source. A multi-source workspace's
+                // selections for peer sources are not the table's to drop.
+                const sourceId = snapshot.sourceId;
+                const peers = view.state.selection.filter((target) => isSourceQualifiedSelectionTarget(target) && target.sourceId !== sourceId);
+                view.select([...peers, ...table.selectionTargets()], { replace: true });
+            }
+            if (syncSort && snapshot.sort !== lastSort) {
+                lastSort = snapshot.sort;
+                view.setSort(snapshot.sort);
+            }
+            if (syncPage && snapshot.window !== lastWindow) {
+                lastWindow = snapshot.window;
+                view.setPage({
+                    offset: snapshot.window.startIndex,
+                    limit: Math.max(0, snapshot.window.endIndex - snapshot.window.startIndex),
+                });
+            }
+            if (syncFilters && filtersChanged && suppressFilterPublish === 0) {
+                publishFilters(snapshot);
+            }
+            else if (syncFilters && filtersChanged && suppressFilterPublish > 0) {
+                // A local setFilters can start while an inbound refresh is awaiting
+                // I/O. Do not lose that edit when the inbound suppression settles.
+                queuedFilterPublish = true;
+            }
+        }
+        finally {
+            applying = false;
+        }
+    });
+    return () => {
+        unsubscribeContext();
+        unsubscribeTable();
+    };
+}
+/**
+ * Project one exploration filter clause onto a filter-registry clause so the
+ * shared `filters` slice compiles through the same typed pushdown path as
+ * table-owned filters.
+ */
+export function explorationClauseToFilterClause(id, clause) {
+    return {
+        id,
+        owner: { kind: "table", id: "honua-feature-table" },
+        field: clause.field,
+        operator: clause.operator,
+        ...(clause.value === undefined ? {} : { value: clause.value }),
+        ...(clause.appliesTo && clause.appliesTo.length > 0 ? { sourceScope: [...clause.appliesTo] } : {}),
+        effect: "filter",
+    };
+}
+/**
+ * Project a table-owned filter back onto the shared exploration filter shape.
+ * Registry-only metadata is intentionally omitted; unsupported clauses (for
+ * example spatial masks without a field/operator pair) remain table-local.
+ */
+export function filterClauseToExplorationClause(clause) {
+    if (clause.field === undefined || clause.operator === undefined)
+        return undefined;
+    const policy = clause.valuePolicy;
+    if (policy?.secret === true)
+        return undefined;
+    if (policy?.maxSerializedBytes !== undefined && clause.value !== undefined) {
+        let serialized;
+        try {
+            serialized = JSON.stringify(clause.value);
+        }
+        catch {
+            return undefined;
+        }
+        if (serialized.length > policy.maxSerializedBytes)
+            return undefined;
+    }
+    return {
+        field: clause.field,
+        operator: clause.operator,
+        ...(clause.value === undefined ? {} : { value: clause.value }),
+        ...(Array.isArray(clause.sourceScope) && clause.sourceScope.length > 0
+            ? { appliesTo: [...clause.sourceScope] }
+            : {}),
+    };
+}
+// ── Presentation helpers ──────────────────────────────────────
+/**
+ * Default cell formatting. Pure presentation (always client work): `null` and
+ * `undefined` render as an empty string rather than the words
+ * `"null"`/`"undefined"`.
+ */
+export function formatFeatureTableCell(value, column) {
+    if (column?.format)
+        return column.format(value);
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "number")
+        return Number.isFinite(value) ? String(value) : "";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "string")
+        return value;
+    return JSON.stringify(value) ?? "";
+}
+/** `aria-sort` token for one column, per the WAI-ARIA grid pattern. */
+export function featureTableAriaSort(field, sort) {
+    const entry = sort.find((candidate) => candidate.field === field);
+    if (!entry)
+        return "none";
+    if (sort.length > 1 && sort[0]?.field !== field)
+        return "other";
+    return (entry.direction ?? "asc") === "asc" ? "ascending" : "descending";
+}
+/**
+ * Screen-reader announcement for the current result truth. Deliberately says
+ * "at least" for partial results instead of presenting a loaded-row count as a
+ * total (REQ-004).
+ */
+export function describeFeatureTableCount(count) {
+    switch (count.kind) {
+        case "known":
+            return `${count.value ?? 0} rows`;
+        case "estimated":
+            return `about ${count.value ?? 0} rows (estimated)`;
+        case "partial":
+            return `at least ${count.loaded} rows loaded; total unknown`;
+        default:
+            return "row count unknown";
+    }
+}
+/**
+ * `aria-rowcount` for the grid. Returns `-1` — the ARIA value for "total
+ * unknown" — instead of substituting the loaded-row count (REQ-004).
+ */
+export function featureTableAriaRowCount(count) {
+    return count.kind === "known" || count.kind === "estimated" ? (count.value ?? -1) + 1 : -1;
+}
+// ── Internals ─────────────────────────────────────────────────
+function resolveColumns(columns) {
+    return Object.freeze(columns.map((column) => Object.freeze({
+        field: column.field,
+        label: column.label ?? column.field,
+        type: column.type ?? "unknown",
+        visible: column.visible ?? true,
+        sortable: column.sortable ?? true,
+        ...(column.format ? { format: column.format } : {}),
+    })));
+}
+/** Name an unusable identity value without leaking the attribute payload. */
+function describeIdentityValue(value) {
+    if (value === undefined)
+        return "absent";
+    if (value === null)
+        return "null";
+    return `a ${Array.isArray(value) ? "array" : typeof value}`;
+}
+function normalizeFilters(filters) {
+    if (!filters)
+        return Object.freeze([]);
+    if (Array.isArray(filters))
+        return Object.freeze([...filters]);
+    return Object.freeze([...filters.clauses]);
+}
+function estimateBytes(features) {
+    let total = 0;
+    for (const feature of features) {
+        try {
+            total += JSON.stringify(feature.attributes ?? {})?.length ?? 0;
+        }
+        catch {
+            // A non-serializable attribute bag contributes no measurable ceiling cost.
+        }
+    }
+    return total * 2; // UTF-16 code units
+}
+function changesSortKey(previous, next, sortFields) {
+    if (sortFields.size === 0)
+        return false;
+    const before = previous;
+    const after = next;
+    for (const field of sortFields) {
+        if (field in after && before[field] !== after[field])
+            return true;
+    }
+    return false;
+}
+function isAbort(error) {
+    return error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError");
+}
+function toCsv(rows, fields, columns) {
+    const byField = new Map(columns.map((column) => [column.field, column]));
+    const lines = [fields.map(csvCell).join(",")];
+    for (const row of rows) {
+        const attributes = row.attributes;
+        lines.push(fields.map((field) => csvCell(formatFeatureTableCell(attributes[field], byField.get(field)))).join(","));
+    }
+    return lines.join("\n");
+}
+function csvCell(value) {
+    if (!value.includes(",") && !value.includes('"') && !value.includes("\n"))
+        return value;
+    return `"${value.split('"').join('""')}"`;
+}
+function toJson(rows, fields, columns) {
+    const byField = new Map(columns.map((column) => [column.field, column]));
+    return JSON.stringify(rows.map((row) => {
+        const attributes = row.attributes;
+        const out = {};
+        for (const field of fields)
+            out[field] = formatFeatureTableCell(attributes[field], byField.get(field));
+        return { id: row.id, attributes: out };
+    }));
+}