@happyvertical/smrt-ui 0.42.4 → 0.42.5

package/dist/components/data/data-surface.js

@@ -0,0 +1,1102 @@
+/**
+ * Transport-neutral contracts for mounted, addressable data surfaces.
+ *
+ * This module is intentionally a leaf: it owns no transport, DOM, query
+ * execution, authorization, persistence, or domain workflow. A browser host
+ * may register a mounted surface here; adapters above smrt-ui can expose the
+ * resulting serializable contracts to people or agents.
+ */
+/** Generic browser-transport ceiling for normalized command/action envelopes. */
+export const DATA_SURFACE_MAX_REQUEST_BYTES = 100_000;
+/** Per-surface LRU capacity for command acknowledgement replay. */
+export const DATA_SURFACE_MAX_REPLAY_ENTRIES = 100;
+const MAX_QUERY_LIMIT = 1_000;
+const MAX_REQUEST_ID_LENGTH = 256;
+const MAX_CURSOR_LENGTH = 2_048;
+const MAX_JSON_DEPTH = 16;
+const MAX_JSON_CONTAINER_ITEMS = 1_000;
+const PROTOTYPE_POLLUTION_KEYS = new Set([
+    '__proto__',
+    'constructor',
+    'prototype',
+]);
+const DATA_SURFACE_KINDS = new Set([
+    'table',
+    'list',
+    'report',
+    'custom',
+]);
+const SENSITIVITIES = new Set([
+    'public',
+    'personal',
+    'sensitive',
+    'secret',
+]);
+const COLUMN_CAPABILITIES = new Set([
+    'read',
+    'search',
+    'filter',
+    'sort',
+    'project',
+]);
+const QUERY_MODES = new Set(['rows', 'count', 'facets']);
+const SELECTION_SCOPES = new Set([
+    'current-page',
+    'explicit-ids',
+    'all-matching',
+]);
+const FORBIDDEN_BOUNDARY_KEYS = new Set([
+    'tenant',
+    'tenantid',
+    'principalid',
+    'principal',
+    'actorid',
+    'auth',
+    'authtoken',
+    'authorization',
+    'authorizationtoken',
+    'authorizationheader',
+    'authentication',
+    'authenticationtoken',
+    'accesstoken',
+    'token',
+    'bearer',
+    'bearertoken',
+    'apikey',
+    'sessiontoken',
+    'credential',
+    'credentials',
+    'sql',
+    'rawsql',
+    'rawquery',
+    'where',
+]);
+function plainObject(value, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new TypeError(`${label} must be a plain object`);
+    }
+    if (Object.getPrototypeOf(value) !== Object.prototype) {
+        throw new TypeError(`${label} must be a plain object`);
+    }
+    return value;
+}
+function exactKeys(value, allowed, label) {
+    const allowedKeys = new Set(allowed);
+    for (const key of Object.keys(value)) {
+        if (!allowedKeys.has(key)) {
+            throw new TypeError(`${label} contains unsupported field: ${key}`);
+        }
+    }
+}
+function stringValue(value, label) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new TypeError(`${label} must be a non-empty string`);
+    }
+    return value;
+}
+function optionalString(value, label) {
+    if (value === undefined)
+        return undefined;
+    return stringValue(value, label);
+}
+function positiveInteger(value, label) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
+        throw new TypeError(`${label} must be a positive safe integer`);
+    }
+    return value;
+}
+function revisionNumber(value) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        throw new TypeError('DataSurface revision must be a non-negative safe integer');
+    }
+    return value;
+}
+function consumeJsonBytes(budget, byteLength) {
+    if (!budget)
+        return;
+    assertJsonBytesAvailable(budget, byteLength);
+    budget.used += byteLength;
+}
+function assertJsonBytesAvailable(budget, byteLength, used = budget?.used ?? 0) {
+    if (!budget)
+        return;
+    if (byteLength > budget.limit - used) {
+        throw new TypeError(`${budget.label} cannot exceed ${budget.limit} UTF-8 bytes`);
+    }
+}
+/** UTF-8 byte length of JSON.stringify(value), limited to a string value. */
+function jsonStringByteLength(value, budget, used = budget?.used ?? 0) {
+    let byteLength = 2; // Opening and closing quotes.
+    for (let index = 0; index < value.length; index += 1) {
+        const codeUnit = value.charCodeAt(index);
+        if (codeUnit === 0x22 || codeUnit === 0x5c) {
+            byteLength += 2;
+        }
+        else if (codeUnit === 0x08 ||
+            codeUnit === 0x09 ||
+            codeUnit === 0x0a ||
+            codeUnit === 0x0c ||
+            codeUnit === 0x0d) {
+            byteLength += 2;
+        }
+        else if (codeUnit <= 0x1f) {
+            byteLength += 6;
+        }
+        else if (codeUnit >= 0xd800 && codeUnit <= 0xdbff) {
+            const next = value.charCodeAt(index + 1);
+            if (next >= 0xdc00 && next <= 0xdfff) {
+                byteLength += 4;
+                index += 1;
+            }
+            else {
+                byteLength += 6;
+            }
+        }
+        else if (codeUnit >= 0xdc00 && codeUnit <= 0xdfff) {
+            byteLength += 6;
+        }
+        else if (codeUnit <= 0x7f) {
+            byteLength += 1;
+        }
+        else if (codeUnit <= 0x7ff) {
+            byteLength += 2;
+        }
+        else {
+            byteLength += 3;
+        }
+        assertJsonBytesAvailable(budget, byteLength, used);
+    }
+    return byteLength;
+}
+/** Preflight only: actual object bytes are consumed in canonicalJson below. */
+function assertJsonObjectKeysWithinBudget(keys, budget) {
+    if (!budget)
+        return;
+    let used = budget.used;
+    const structuralBytes = keys.length === 0 ? 2 : keys.length * 2 + 1;
+    assertJsonBytesAvailable(budget, structuralBytes, used);
+    used += structuralBytes;
+    for (const key of keys) {
+        used += jsonStringByteLength(key, budget, used);
+    }
+}
+function canonicalJson(value, ancestors = new Set(), depth = 0, budget) {
+    if (depth > MAX_JSON_DEPTH) {
+        throw new TypeError(`DataSurface values cannot exceed ${MAX_JSON_DEPTH} nested levels`);
+    }
+    if (value === null ||
+        typeof value === 'string' ||
+        typeof value === 'boolean') {
+        consumeJsonBytes(budget, value === null
+            ? 4
+            : typeof value === 'boolean'
+                ? value
+                    ? 4
+                    : 5
+                : jsonStringByteLength(value, budget));
+        return value;
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            throw new TypeError('DataSurface values cannot contain non-finite numbers');
+        }
+        const normalized = value === 0 ? 0 : value;
+        consumeJsonBytes(budget, String(normalized).length);
+        return normalized;
+    }
+    if (Array.isArray(value)) {
+        if (value.length > MAX_JSON_CONTAINER_ITEMS) {
+            throw new TypeError(`DataSurface arrays cannot contain more than ${MAX_JSON_CONTAINER_ITEMS} items`);
+        }
+        if (ancestors.has(value)) {
+            throw new TypeError('DataSurface values cannot be circular');
+        }
+        ancestors.add(value);
+        consumeJsonBytes(budget, 1);
+        const clone = [];
+        for (const [index, entry] of value.entries()) {
+            if (index > 0)
+                consumeJsonBytes(budget, 1);
+            clone.push(canonicalJson(entry, ancestors, depth + 1, budget));
+        }
+        consumeJsonBytes(budget, 1);
+        ancestors.delete(value);
+        return clone;
+    }
+    if (value && typeof value === 'object') {
+        const object = plainObject(value, 'DataSurface value');
+        if (ancestors.has(object)) {
+            throw new TypeError('DataSurface values cannot be circular');
+        }
+        ancestors.add(object);
+        const clone = {};
+        const keys = Object.keys(object);
+        if (keys.length > MAX_JSON_CONTAINER_ITEMS) {
+            throw new TypeError(`DataSurface objects cannot contain more than ${MAX_JSON_CONTAINER_ITEMS} keys`);
+        }
+        assertJsonObjectKeysWithinBudget(keys, budget);
+        consumeJsonBytes(budget, 1);
+        for (const [index, key] of keys.sort().entries()) {
+            if (index > 0)
+                consumeJsonBytes(budget, 1);
+            if (PROTOTYPE_POLLUTION_KEYS.has(key)) {
+                throw new TypeError(`DataSurface values cannot contain prototype key: ${key}`);
+            }
+            consumeJsonBytes(budget, jsonStringByteLength(key, budget) + 1);
+            clone[key] = canonicalJson(object[key], ancestors, depth + 1, budget);
+        }
+        consumeJsonBytes(budget, 1);
+        ancestors.delete(object);
+        return clone;
+    }
+    throw new TypeError('DataSurface values must be JSON-safe plain data');
+}
+function jsonObject(value, label) {
+    const clone = canonicalJson(value);
+    if (Array.isArray(clone) || clone === null || typeof clone !== 'object') {
+        throw new TypeError(`${label} must be a JSON object`);
+    }
+    return clone;
+}
+function jsonSignature(value) {
+    return JSON.stringify(canonicalJson(value));
+}
+/** The UTF-8 size of the normalized, canonical query envelope. */
+function canonicalQueryByteLength(request) {
+    const budget = {
+        used: 0,
+        limit: Number.MAX_SAFE_INTEGER,
+        label: 'DataSurface query request',
+    };
+    canonicalJson(request, new Set(), 0, budget);
+    return budget.used;
+}
+function assertRequestByteLimit(value, label) {
+    canonicalJson(value, new Set(), 0, {
+        used: 0,
+        limit: DATA_SURFACE_MAX_REQUEST_BYTES,
+        label,
+    });
+}
+function boundarySafe(value, label) {
+    const clone = canonicalJson(value);
+    const inspect = (entry) => {
+        if (Array.isArray(entry)) {
+            for (const item of entry)
+                inspect(item);
+            return;
+        }
+        if (entry && typeof entry === 'object') {
+            for (const [key, item] of Object.entries(entry)) {
+                const normalizedKey = key.replaceAll(/[-_]/g, '').toLowerCase();
+                if (FORBIDDEN_BOUNDARY_KEYS.has(normalizedKey)) {
+                    throw new TypeError(`${label} cannot contain authority or SQL field: ${key}`);
+                }
+                inspect(item);
+            }
+        }
+    };
+    inspect(clone);
+    return clone;
+}
+function boundarySafeObject(value, label) {
+    const clone = boundarySafe(value, label);
+    if (Array.isArray(clone) || clone === null || typeof clone !== 'object') {
+        throw new TypeError(`${label} must be a JSON object`);
+    }
+    return clone;
+}
+function normalizeIdentity(value) {
+    const object = plainObject(value, 'DataSurface identity');
+    exactKeys(object, ['surfaceId', 'kind', 'subject'], 'DataSurface identity');
+    const kind = stringValue(object.kind, 'DataSurface kind');
+    if (!DATA_SURFACE_KINDS.has(kind)) {
+        throw new TypeError(`Unsupported DataSurface kind: ${kind}`);
+    }
+    let subject;
+    if (object.subject !== undefined) {
+        const source = plainObject(object.subject, 'DataSurface subject');
+        exactKeys(source, ['type', 'id', 'label'], 'DataSurface subject');
+        const label = optionalString(source.label, 'DataSurface subject label');
+        subject = {
+            type: stringValue(source.type, 'DataSurface subject type'),
+            id: stringValue(source.id, 'DataSurface subject id'),
+            ...(label ? { label } : {}),
+        };
+    }
+    return {
+        surfaceId: stringValue(object.surfaceId, 'DataSurface surface id'),
+        kind,
+        ...(subject ? { subject } : {}),
+    };
+}
+function identityKey(identity) {
+    return JSON.stringify([
+        identity.kind,
+        identity.surfaceId,
+        identity.subject ? [identity.subject.type, identity.subject.id] : null,
+    ]);
+}
+function cloneIdentity(identity) {
+    return normalizeIdentity(identity);
+}
+function normalizeStringArray(value, label, options = {}) {
+    if (!Array.isArray(value))
+        throw new TypeError(`${label} must be an array`);
+    if (value.length > MAX_JSON_CONTAINER_ITEMS) {
+        throw new TypeError(`${label} cannot contain more than ${MAX_JSON_CONTAINER_ITEMS} items`);
+    }
+    const values = value.map((entry) => stringValue(entry, label));
+    if (new Set(values).size !== values.length) {
+        throw new TypeError(`${label} cannot contain duplicates`);
+    }
+    return options.sort ? values.sort() : values;
+}
+function normalizeCapabilityArray(value, label) {
+    const capabilities = normalizeStringArray(value, label, { sort: true });
+    for (const capability of capabilities) {
+        if (!COLUMN_CAPABILITIES.has(capability)) {
+            throw new TypeError(`Unsupported DataSurface column capability: ${capability}`);
+        }
+    }
+    return capabilities;
+}
+function normalizeSensitivity(value, label) {
+    if (value === undefined)
+        return undefined;
+    const sensitivity = stringValue(value, label);
+    if (!SENSITIVITIES.has(sensitivity)) {
+        throw new TypeError(`Unsupported DataSurface sensitivity: ${sensitivity}`);
+    }
+    return sensitivity;
+}
+function normalizeSelection(value) {
+    const object = plainObject(value, 'DataSurface selection');
+    const scope = stringValue(object.scope, 'DataSurface selection scope');
+    if (!SELECTION_SCOPES.has(scope)) {
+        throw new TypeError(`Unsupported DataSurface selection scope: ${scope}`);
+    }
+    if (scope === 'current-page') {
+        exactKeys(object, ['scope'], 'DataSurface current-page selection');
+        return { scope };
+    }
+    if (scope === 'explicit-ids') {
+        exactKeys(object, ['scope', 'rowIds'], 'DataSurface explicit selection');
+        if (!Array.isArray(object.rowIds)) {
+            throw new TypeError('DataSurface explicit selection rowIds must be an array');
+        }
+        if (object.rowIds.length > MAX_JSON_CONTAINER_ITEMS) {
+            throw new TypeError(`DataSurface explicit selection cannot contain more than ${MAX_JSON_CONTAINER_ITEMS} row ids`);
+        }
+        const rowIds = new Map();
+        for (const rowId of object.rowIds) {
+            if (typeof rowId !== 'string' &&
+                (typeof rowId !== 'number' || !Number.isFinite(rowId))) {
+                throw new TypeError('DataSurface row ids must be finite strings or numbers');
+            }
+            const normalized = typeof rowId === 'number' && rowId === 0 ? 0 : rowId;
+            rowIds.set(`${typeof normalized}:${String(normalized)}`, normalized);
+        }
+        return {
+            scope,
+            rowIds: [...rowIds.values()].sort((left, right) => {
+                if (typeof left !== typeof right)
+                    return typeof left === 'number' ? -1 : 1;
+                if (typeof left === 'number' && typeof right === 'number')
+                    return left - right;
+                return left < right ? -1 : left > right ? 1 : 0;
+            }),
+        };
+    }
+    exactKeys(object, ['scope', 'queryFingerprint'], 'DataSurface all-matching selection');
+    return {
+        scope,
+        queryFingerprint: stringValue(object.queryFingerprint, 'DataSurface query fingerprint'),
+    };
+}
+export function normalizeDataSurfaceDescriptor(value) {
+    const object = plainObject(value, 'DataSurface descriptor');
+    exactKeys(object, [
+        'version',
+        'identity',
+        'schemaVersion',
+        'label',
+        'description',
+        'rowKey',
+        'columns',
+        'query',
+        'controls',
+        'actions',
+        'limits',
+    ], 'DataSurface descriptor');
+    if (object.version !== 1) {
+        throw new TypeError('Unsupported DataSurface descriptor version');
+    }
+    if (!Array.isArray(object.columns)) {
+        throw new TypeError('DataSurface descriptor columns must be an array');
+    }
+    const columns = object.columns.map((value) => {
+        const column = plainObject(value, 'DataSurface column');
+        exactKeys(column, ['id', 'label', 'description', 'sensitivity', 'capabilities'], 'DataSurface column');
+        const sensitivity = normalizeSensitivity(column.sensitivity, 'DataSurface column sensitivity');
+        const description = optionalString(column.description, 'DataSurface column description');
+        return {
+            id: stringValue(column.id, 'DataSurface column id'),
+            label: stringValue(column.label, 'DataSurface column label'),
+            ...(description ? { description } : {}),
+            ...(sensitivity ? { sensitivity } : {}),
+            capabilities: normalizeCapabilityArray(column.capabilities, 'DataSurface column capabilities'),
+        };
+    });
+    if (new Set(columns.map((column) => column.id)).size !== columns.length) {
+        throw new TypeError('DataSurface descriptor column ids must be unique');
+    }
+    const query = plainObject(object.query, 'DataSurface query capabilities');
+    exactKeys(query, ['modes', 'projectableColumnIds'], 'DataSurface query capabilities');
+    const modes = normalizeStringArray(query.modes, 'DataSurface query modes', {
+        sort: true,
+    });
+    for (const mode of modes) {
+        if (!QUERY_MODES.has(mode)) {
+            throw new TypeError(`Unsupported DataSurface query mode: ${mode}`);
+        }
+    }
+    const projectableColumnIds = normalizeStringArray(query.projectableColumnIds, 'DataSurface projectable column ids', { sort: true });
+    const knownColumns = new Set(columns.map((column) => column.id));
+    for (const columnId of projectableColumnIds) {
+        if (!knownColumns.has(columnId)) {
+            throw new TypeError(`Unknown projectable DataSurface column: ${columnId}`);
+        }
+    }
+    if (!Array.isArray(object.controls)) {
+        throw new TypeError('DataSurface controls must be an array');
+    }
+    const controls = object.controls.map((value) => {
+        const control = plainObject(value, 'DataSurface control');
+        exactKeys(control, ['id', 'label', 'description'], 'DataSurface control');
+        const description = optionalString(control.description, 'DataSurface control description');
+        return {
+            id: stringValue(control.id, 'DataSurface control id'),
+            label: stringValue(control.label, 'DataSurface control label'),
+            ...(description ? { description } : {}),
+        };
+    });
+    if (new Set(controls.map((control) => control.id)).size !== controls.length) {
+        throw new TypeError('DataSurface control ids must be unique');
+    }
+    if (!Array.isArray(object.actions)) {
+        throw new TypeError('DataSurface actions must be an array');
+    }
+    const actions = object.actions.map((value) => {
+        const action = plainObject(value, 'DataSurface action');
+        exactKeys(action, [
+            'id',
+            'label',
+            'description',
+            'sensitivity',
+            'selectionScopes',
+            'requiresConfirmation',
+        ], 'DataSurface action');
+        if (action.requiresConfirmation !== undefined &&
+            typeof action.requiresConfirmation !== 'boolean') {
+            throw new TypeError('DataSurface action requiresConfirmation must be boolean');
+        }
+        const scopes = normalizeStringArray(action.selectionScopes, 'DataSurface action selection scopes', { sort: true });
+        for (const scope of scopes) {
+            if (!SELECTION_SCOPES.has(scope)) {
+                throw new TypeError(`Unsupported DataSurface action selection scope: ${scope}`);
+            }
+        }
+        const sensitivity = normalizeSensitivity(action.sensitivity, 'DataSurface action sensitivity');
+        const description = optionalString(action.description, 'DataSurface action description');
+        return {
+            id: stringValue(action.id, 'DataSurface action id'),
+            label: stringValue(action.label, 'DataSurface action label'),
+            ...(description ? { description } : {}),
+            ...(sensitivity ? { sensitivity } : {}),
+            selectionScopes: scopes,
+            ...(action.requiresConfirmation === undefined
+                ? {}
+                : { requiresConfirmation: action.requiresConfirmation }),
+        };
+    });
+    if (new Set(actions.map((action) => action.id)).size !== actions.length) {
+        throw new TypeError('DataSurface action ids must be unique');
+    }
+    const limits = plainObject(object.limits, 'DataSurface limits');
+    exactKeys(limits, ['maxQueryRows', 'maxQueryBytes', 'maxSelectionSize'], 'DataSurface limits');
+    const maxQueryRows = positiveInteger(limits.maxQueryRows, 'DataSurface maxQueryRows');
+    if (maxQueryRows > MAX_QUERY_LIMIT) {
+        throw new TypeError(`DataSurface maxQueryRows cannot exceed ${MAX_QUERY_LIMIT}`);
+    }
+    const rowKey = stringValue(object.rowKey, 'DataSurface row key');
+    if (!knownColumns.has(rowKey)) {
+        throw new TypeError('DataSurface rowKey must name a declared column');
+    }
+    const description = optionalString(object.description, 'DataSurface description');
+    return {
+        version: 1,
+        identity: normalizeIdentity(object.identity),
+        schemaVersion: positiveInteger(object.schemaVersion, 'DataSurface schema version'),
+        label: stringValue(object.label, 'DataSurface label'),
+        ...(description ? { description } : {}),
+        rowKey,
+        columns,
+        query: { modes, projectableColumnIds },
+        controls,
+        actions,
+        limits: {
+            maxQueryRows,
+            maxQueryBytes: positiveInteger(limits.maxQueryBytes, 'DataSurface maxQueryBytes'),
+            maxSelectionSize: positiveInteger(limits.maxSelectionSize, 'DataSurface maxSelectionSize'),
+        },
+    };
+}
+export function normalizeDataSurfaceSnapshot(value) {
+    const object = plainObject(value, 'DataSurface snapshot');
+    exactKeys(object, ['version', 'descriptor', 'revision', 'state', 'selection'], 'DataSurface snapshot');
+    if (object.version !== 1) {
+        throw new TypeError('Unsupported DataSurface snapshot version');
+    }
+    return {
+        version: 1,
+        descriptor: normalizeDataSurfaceDescriptor(object.descriptor),
+        revision: revisionNumber(object.revision),
+        state: boundarySafeObject(object.state, 'DataSurface snapshot state'),
+        selection: object.selection === null || object.selection === undefined
+            ? null
+            : normalizeSelection(object.selection),
+    };
+}
+export function normalizeDataSurfaceVisibleCommand(value) {
+    const object = plainObject(value, 'DataSurface visible command');
+    exactKeys(object, [
+        'version',
+        'commandId',
+        'identity',
+        'expectedRevision',
+        'controlId',
+        'payload',
+    ], 'DataSurface visible command');
+    if (object.version !== 1) {
+        throw new TypeError('Unsupported DataSurface visible command version');
+    }
+    const commandId = stringValue(object.commandId, 'DataSurface command id');
+    if (commandId.length > MAX_REQUEST_ID_LENGTH) {
+        throw new TypeError('DataSurface command id is too long');
+    }
+    const commandIdentity = normalizeIdentity(object.identity);
+    const expectedRevision = revisionNumber(object.expectedRevision);
+    const controlId = stringValue(object.controlId, 'DataSurface control id');
+    assertRequestByteLimit(value, 'DataSurface visible command');
+    const normalized = {
+        version: 1,
+        commandId,
+        identity: commandIdentity,
+        expectedRevision,
+        controlId,
+        ...(object.payload === undefined
+            ? {}
+            : {
+                payload: boundarySafe(object.payload, 'DataSurface command payload'),
+            }),
+    };
+    assertRequestByteLimit(normalized, 'DataSurface visible command');
+    return normalized;
+}
+export function normalizeDataSurfaceQueryRequest(value) {
+    const object = plainObject(value, 'DataSurface query request');
+    const kind = stringValue(object.kind, 'DataSurface query kind');
+    if (object.version !== 1) {
+        throw new TypeError('Unsupported DataSurface query request version');
+    }
+    const requestId = stringValue(object.requestId, 'DataSurface query request id');
+    if (requestId.length > MAX_REQUEST_ID_LENGTH) {
+        throw new TypeError('DataSurface query request id is too long');
+    }
+    const identity = normalizeIdentity(object.identity);
+    if (kind === 'rows') {
+        exactKeys(object, [
+            'version',
+            'requestId',
+            'identity',
+            'kind',
+            'limit',
+            'cursor',
+            'projection',
+        ], 'DataSurface rows query request');
+        assertRequestByteLimit(value, 'DataSurface query request');
+        const limit = positiveInteger(object.limit, 'DataSurface rows query limit');
+        if (limit > MAX_QUERY_LIMIT) {
+            throw new TypeError(`DataSurface rows query limit cannot exceed ${MAX_QUERY_LIMIT}`);
+        }
+        const cursor = optionalString(object.cursor, 'DataSurface rows query cursor');
+        if (cursor && cursor.length > MAX_CURSOR_LENGTH) {
+            throw new TypeError('DataSurface rows query cursor is too long');
+        }
+        return {
+            version: 1,
+            requestId,
+            identity,
+            kind,
+            limit,
+            ...(cursor ? { cursor } : {}),
+            ...(object.projection === undefined
+                ? {}
+                : {
+                    projection: normalizeStringArray(object.projection, 'DataSurface query projection', { sort: true }),
+                }),
+        };
+    }
+    if (kind === 'count') {
+        exactKeys(object, ['version', 'requestId', 'identity', 'kind'], 'DataSurface count query request');
+        assertRequestByteLimit(value, 'DataSurface query request');
+        return { version: 1, requestId, identity, kind };
+    }
+    if (kind === 'facets') {
+        exactKeys(object, ['version', 'requestId', 'identity', 'kind', 'columnId', 'limit'], 'DataSurface facets query request');
+        assertRequestByteLimit(value, 'DataSurface query request');
+        const limit = positiveInteger(object.limit, 'DataSurface facets query limit');
+        if (limit > MAX_QUERY_LIMIT) {
+            throw new TypeError(`DataSurface facets query limit cannot exceed ${MAX_QUERY_LIMIT}`);
+        }
+        return {
+            version: 1,
+            requestId,
+            identity,
+            kind,
+            columnId: stringValue(object.columnId, 'DataSurface facets query column id'),
+            limit,
+        };
+    }
+    throw new TypeError(`Unsupported DataSurface query kind: ${kind}`);
+}
+export function normalizeDataSurfaceActionRequest(value) {
+    const object = plainObject(value, 'DataSurface action request');
+    exactKeys(object, [
+        'version',
+        'requestId',
+        'identity',
+        'actionId',
+        'phase',
+        'selection',
+        'payload',
+        'confirmationToken',
+    ], 'DataSurface action request');
+    if (object.version !== 1) {
+        throw new TypeError('Unsupported DataSurface action request version');
+    }
+    const requestId = stringValue(object.requestId, 'DataSurface action request id');
+    if (requestId.length > MAX_REQUEST_ID_LENGTH) {
+        throw new TypeError('DataSurface action request id is too long');
+    }
+    const phase = stringValue(object.phase, 'DataSurface action phase');
+    if (phase !== 'preview' && phase !== 'apply') {
+        throw new TypeError(`Unsupported DataSurface action phase: ${phase}`);
+    }
+    const confirmationToken = optionalString(object.confirmationToken, 'DataSurface confirmation token');
+    const actionIdentity = normalizeIdentity(object.identity);
+    const actionId = stringValue(object.actionId, 'DataSurface action id');
+    const selection = normalizeSelection(object.selection);
+    assertRequestByteLimit(value, 'DataSurface action request');
+    const normalized = {
+        version: 1,
+        requestId,
+        identity: actionIdentity,
+        actionId,
+        phase,
+        selection,
+        ...(object.payload === undefined
+            ? {}
+            : {
+                payload: boundarySafe(object.payload, 'DataSurface action payload'),
+            }),
+        ...(confirmationToken ? { confirmationToken } : {}),
+    };
+    assertRequestByteLimit(normalized, 'DataSurface action request');
+    return normalized;
+}
+function snapshotFrom(descriptor, input) {
+    return normalizeDataSurfaceSnapshot({
+        version: 1,
+        descriptor,
+        revision: input.revision,
+        state: input.state,
+        selection: input.selection ?? null,
+    });
+}
+function cloneSnapshot(snapshot) {
+    return normalizeDataSurfaceSnapshot(snapshot);
+}
+function cloneResult(result) {
+    return {
+        ok: result.ok,
+        commandId: result.commandId,
+        identity: cloneIdentity(result.identity),
+        ...(result.revision === undefined ? {} : { revision: result.revision }),
+        ...(result.snapshot ? { snapshot: cloneSnapshot(result.snapshot) } : {}),
+        ...(result.reason ? { reason: result.reason } : {}),
+    };
+}
+function sameIdentity(left, right) {
+    return identityKey(left) === identityKey(right);
+}
+function sameSnapshotContent(left, right) {
+    return snapshotContentSignature(left) === snapshotContentSignature(right);
+}
+function snapshotContentSignature(snapshot) {
+    return jsonSignature([snapshot.state, snapshot.selection]);
+}
+/** Create an isolated registry; applications choose how it is exposed. */
+export function createDataSurfaceRegistry() {
+    const entries = new Map();
+    const listeners = new Set();
+    let sequence = 0;
+    const readSnapshot = (entry) => {
+        const raw = snapshotFrom(entry.descriptor, entry.registration.getSnapshot());
+        if (raw.revision < entry.lastRevision) {
+            throw new RangeError('DataSurface revision must be monotonic');
+        }
+        const exposed = entry.registration.redact
+            ? normalizeDataSurfaceSnapshot(entry.registration.redact(cloneSnapshot(raw)))
+            : raw;
+        if (!sameIdentity(exposed.descriptor.identity, entry.descriptor.identity) ||
+            exposed.revision !== raw.revision) {
+            throw new TypeError('DataSurface redaction cannot change identity or revision');
+        }
+        const contentSignature = snapshotContentSignature(raw);
+        const exposedContentSignature = snapshotContentSignature(exposed);
+        if (entry.lastSnapshotContentSignature !== undefined &&
+            raw.revision === entry.lastRevision &&
+            (entry.lastSnapshotContentSignature !== contentSignature ||
+                entry.lastExposedSnapshotContentSignature !== exposedContentSignature)) {
+            entry.commandBlockedAtRevision = raw.revision;
+        }
+        entry.lastRevision = raw.revision;
+        entry.lastSnapshotContentSignature = contentSignature;
+        entry.lastExposedSnapshotContentSignature = exposedContentSignature;
+        return { raw, exposed };
+    };
+    const emit = (type, entry, revision, command, result) => {
+        const event = {
+            type,
+            sequence: ++sequence,
+            identity: cloneIdentity(entry.descriptor.identity),
+            revision,
+            ...(command
+                ? { command: normalizeDataSurfaceVisibleCommand(command) }
+                : {}),
+            ...(result ? { result: cloneResult(result) } : {}),
+        };
+        for (const listener of listeners) {
+            try {
+                listener({
+                    ...event,
+                    identity: cloneIdentity(event.identity),
+                    ...(event.command
+                        ? { command: normalizeDataSurfaceVisibleCommand(event.command) }
+                        : {}),
+                    ...(event.result ? { result: cloneResult(event.result) } : {}),
+                });
+            }
+            catch {
+                // Subscribers are observational and cannot alter registry operations.
+            }
+        }
+    };
+    const cacheResult = (entry, command, result) => {
+        entry.replay.set(command.commandId, {
+            signature: jsonSignature(command),
+            result: cloneResult(result),
+        });
+        while (entry.replay.size > DATA_SURFACE_MAX_REPLAY_ENTRIES) {
+            const oldestCommandId = entry.replay.keys().next().value;
+            if (oldestCommandId === undefined)
+                break;
+            entry.replay.delete(oldestCommandId);
+        }
+        emit('command', entry, result.revision ?? entry.lastRevision, command, result);
+        return cloneResult(result);
+    };
+    const validationForIdentity = (identity) => entries.get(identityKey(identity));
+    const serializeCommand = async (entry, run) => {
+        const previous = entry.commandQueue;
+        let releaseQueue;
+        entry.commandQueue = new Promise((resolve) => {
+            releaseQueue = resolve;
+        });
+        await previous;
+        try {
+            return await run();
+        }
+        finally {
+            releaseQueue();
+        }
+    };
+    return {
+        register(registration) {
+            const descriptor = normalizeDataSurfaceDescriptor(registration.descriptor);
+            const key = identityKey(descriptor.identity);
+            if (entries.has(key)) {
+                throw new Error(`DataSurface identity is already registered: ${key}`);
+            }
+            const entry = {
+                key,
+                descriptor,
+                registration,
+                lastRevision: -1,
+                replay: new Map(),
+                commandQueue: Promise.resolve(),
+            };
+            entries.set(key, entry);
+            try {
+                const snapshot = readSnapshot(entry);
+                emit('registered', entry, snapshot.exposed.revision);
+            }
+            catch (error) {
+                entries.delete(key);
+                throw error;
+            }
+            return () => {
+                if (entries.get(key) !== entry)
+                    return;
+                entries.delete(key);
+                emit('unregistered', entry, Math.max(0, entry.lastRevision));
+            };
+        },
+        unregister(identity) {
+            const normalized = normalizeIdentity(identity);
+            const entry = entries.get(identityKey(normalized));
+            if (!entry)
+                return;
+            entries.delete(entry.key);
+            emit('unregistered', entry, Math.max(0, entry.lastRevision));
+        },
+        list() {
+            return [...entries.values()]
+                .sort((left, right) => left.key.localeCompare(right.key))
+                .map((entry) => normalizeDataSurfaceDescriptor(entry.descriptor));
+        },
+        inspect(identity) {
+            const normalized = normalizeIdentity(identity);
+            const entry = entries.get(identityKey(normalized));
+            return entry ? cloneSnapshot(readSnapshot(entry).exposed) : undefined;
+        },
+        async execute(command) {
+            const normalized = normalizeDataSurfaceVisibleCommand(command);
+            const entry = entries.get(identityKey(normalized.identity));
+            const notFound = () => ({
+                ok: false,
+                commandId: normalized.commandId,
+                identity: cloneIdentity(normalized.identity),
+                reason: 'not_found',
+            });
+            if (!entry) {
+                return notFound();
+            }
+            return serializeCommand(entry, async () => {
+                if (entries.get(entry.key) !== entry) {
+                    return notFound();
+                }
+                const signature = jsonSignature(normalized);
+                const replay = entry.replay.get(normalized.commandId);
+                if (replay) {
+                    if (replay.signature === signature) {
+                        entry.replay.delete(normalized.commandId);
+                        entry.replay.set(normalized.commandId, replay);
+                        return cloneResult(replay.result);
+                    }
+                    const snapshot = readSnapshot(entry).exposed;
+                    const result = {
+                        ok: false,
+                        commandId: normalized.commandId,
+                        identity: cloneIdentity(entry.descriptor.identity),
+                        revision: snapshot.revision,
+                        snapshot,
+                        reason: 'idempotency_conflict',
+                    };
+                    emit('command', entry, snapshot.revision, normalized, result);
+                    return cloneResult(result);
+                }
+                const before = readSnapshot(entry);
+                if (entry.commandBlockedAtRevision !== undefined &&
+                    before.raw.revision <= entry.commandBlockedAtRevision) {
+                    return cacheResult(entry, normalized, {
+                        ok: false,
+                        commandId: normalized.commandId,
+                        identity: cloneIdentity(entry.descriptor.identity),
+                        revision: before.exposed.revision,
+                        snapshot: before.exposed,
+                        reason: 'non_monotonic_revision',
+                    });
+                }
+                entry.commandBlockedAtRevision = undefined;
+                if (before.raw.revision !== normalized.expectedRevision) {
+                    return cacheResult(entry, normalized, {
+                        ok: false,
+                        commandId: normalized.commandId,
+                        identity: cloneIdentity(entry.descriptor.identity),
+                        revision: before.exposed.revision,
+                        snapshot: before.exposed,
+                        reason: 'stale_revision',
+                    });
+                }
+                if (!entry.descriptor.controls.some((control) => control.id === normalized.controlId)) {
+                    return cacheResult(entry, normalized, {
+                        ok: false,
+                        commandId: normalized.commandId,
+                        identity: cloneIdentity(entry.descriptor.identity),
+                        revision: before.exposed.revision,
+                        snapshot: before.exposed,
+                        reason: 'unsupported',
+                    });
+                }
+                if (!entry.registration.execute) {
+                    return cacheResult(entry, normalized, {
+                        ok: false,
+                        commandId: normalized.commandId,
+                        identity: cloneIdentity(entry.descriptor.identity),
+                        revision: before.exposed.revision,
+                        snapshot: before.exposed,
+                        reason: 'unsupported',
+                    });
+                }
+                try {
+                    const execution = await entry.registration.execute(normalizeDataSurfaceVisibleCommand(normalized));
+                    if (entries.get(entry.key) !== entry)
+                        return notFound();
+                    const after = readSnapshot(entry);
+                    if (sameSnapshotContent(before.raw, after.raw) === false &&
+                        after.raw.revision <= before.raw.revision) {
+                        entry.commandBlockedAtRevision = after.raw.revision;
+                        return cacheResult(entry, normalized, {
+                            ok: false,
+                            commandId: normalized.commandId,
+                            identity: cloneIdentity(entry.descriptor.identity),
+                            revision: after.exposed.revision,
+                            snapshot: after.exposed,
+                            reason: 'non_monotonic_revision',
+                        });
+                    }
+                    if (execution && execution.ok === false) {
+                        return cacheResult(entry, normalized, {
+                            ok: false,
+                            commandId: normalized.commandId,
+                            identity: cloneIdentity(entry.descriptor.identity),
+                            revision: after.exposed.revision,
+                            snapshot: after.exposed,
+                            reason: 'denied',
+                        });
+                    }
+                    return cacheResult(entry, normalized, {
+                        ok: true,
+                        commandId: normalized.commandId,
+                        identity: cloneIdentity(entry.descriptor.identity),
+                        revision: after.exposed.revision,
+                        snapshot: after.exposed,
+                    });
+                }
+                catch {
+                    if (entries.get(entry.key) !== entry)
+                        return notFound();
+                    let current;
+                    try {
+                        current = readSnapshot(entry);
+                    }
+                    catch {
+                        // A teardown can make snapshot retrieval fail after the handler.
+                    }
+                    if (current &&
+                        sameSnapshotContent(before.raw, current.raw) === false &&
+                        current.raw.revision <= before.raw.revision) {
+                        entry.commandBlockedAtRevision = current.raw.revision;
+                        return cacheResult(entry, normalized, {
+                            ok: false,
+                            commandId: normalized.commandId,
+                            identity: cloneIdentity(entry.descriptor.identity),
+                            revision: current.exposed.revision,
+                            snapshot: current.exposed,
+                            reason: 'non_monotonic_revision',
+                        });
+                    }
+                    return cacheResult(entry, normalized, {
+                        ok: false,
+                        commandId: normalized.commandId,
+                        identity: cloneIdentity(entry.descriptor.identity),
+                        ...(current
+                            ? {
+                                revision: current.exposed.revision,
+                                snapshot: current.exposed,
+                            }
+                            : {}),
+                        reason: 'execution_failed',
+                    });
+                }
+            });
+        },
+        validateQuery(request) {
+            try {
+                const normalized = normalizeDataSurfaceQueryRequest(request);
+                const entry = validationForIdentity(normalized.identity);
+                if (!entry)
+                    return { ok: false, reason: 'not_found' };
+                if (!entry.descriptor.query.modes.includes(normalized.kind)) {
+                    return { ok: false, reason: 'unsupported' };
+                }
+                if (canonicalQueryByteLength(normalized) >
+                    entry.descriptor.limits.maxQueryBytes) {
+                    return { ok: false, reason: 'limit_exceeded' };
+                }
+                if ('limit' in normalized &&
+                    normalized.limit > entry.descriptor.limits.maxQueryRows) {
+                    return { ok: false, reason: 'limit_exceeded' };
+                }
+                if (normalized.kind === 'rows' && normalized.projection) {
+                    if (normalized.projection.some((columnId) => !entry.descriptor.query.projectableColumnIds.includes(columnId))) {
+                        return { ok: false, reason: 'projection_not_allowed' };
+                    }
+                }
+                if (normalized.kind === 'facets' &&
+                    !entry.descriptor.query.projectableColumnIds.includes(normalized.columnId)) {
+                    return { ok: false, reason: 'projection_not_allowed' };
+                }
+                return { ok: true };
+            }
+            catch {
+                return { ok: false, reason: 'invalid_request' };
+            }
+        },
+        validateAction(request) {
+            try {
+                const normalized = normalizeDataSurfaceActionRequest(request);
+                const entry = validationForIdentity(normalized.identity);
+                if (!entry)
+                    return { ok: false, reason: 'not_found' };
+                const action = entry.descriptor.actions.find((candidate) => candidate.id === normalized.actionId);
+                if (!action)
+                    return { ok: false, reason: 'unsupported' };
+                if (!action.selectionScopes.includes(normalized.selection.scope)) {
+                    return { ok: false, reason: 'selection_not_supported' };
+                }
+                if (normalized.selection.scope === 'explicit-ids' &&
+                    normalized.selection.rowIds.length >
+                        entry.descriptor.limits.maxSelectionSize) {
+                    return { ok: false, reason: 'limit_exceeded' };
+                }
+                if (normalized.phase === 'apply' &&
+                    action.requiresConfirmation !== false &&
+                    !normalized.confirmationToken) {
+                    return { ok: false, reason: 'confirmation_required' };
+                }
+                return { ok: true };
+            }
+            catch {
+                return { ok: false, reason: 'invalid_request' };
+            }
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+}