@veil-runtime/ui 0.0.0-stage → 0.3.0

package/dist/interface.js

@@ -0,0 +1,375 @@
+import { assertBoundedData, assertSafeKey, copyData } from "./validation-safety.js";
+import { attachInterfaceRenderers, detachInterfaceRenderers } from "./interface-transaction.js";
+const identifier = /^[A-Za-z][A-Za-z0-9._-]{0,127}$/;
+const commonProperties = ["key", "component", "visible", "ariaLabel"];
+const vocabulary = {
+    Stack: { properties: [...commonProperties, "children"], required: [], children: true, event: null },
+    Row: { properties: [...commonProperties, "children"], required: [], children: true, event: null },
+    Text: { properties: [...commonProperties, "text"], required: [], children: false, event: null },
+    Heading: { properties: [...commonProperties, "text"], required: ["text"], children: false, event: null },
+    Status: { properties: [...commonProperties, "text"], required: [], children: false, event: null },
+    Input: { properties: [...commonProperties, "label", "binding", "inputType"], required: ["label", "binding"], children: false, event: "state change" },
+    Button: { properties: [...commonProperties, "text", "action"], required: ["text", "action"], children: false, event: "action" },
+    Table: { properties: [...commonProperties, "binding", "columns"], required: ["binding", "columns"], children: false, event: null },
+    List: { properties: [...commonProperties, "binding"], required: ["binding"], children: false, event: null },
+};
+const builtins = new Set(Object.keys(vocabulary));
+const nodeKeys = new Set(["key", "component", "children", "text", "binding", "visible", "action", "label", "inputType", "columns", "ariaLabel"]);
+/** JSON-safe description of the built-in vocabulary. Host extensions are trusted code and are never advertised here. */
+export function getInterfaceCapabilities() {
+    return copyData({ version: 1, components: vocabulary, bindings: { sources: ["data", "state"], path: "dot-separated own-property path", missing: "empty display", visibility: "strict scalar equality" },
+        propertyTypes: { key: "identifier", component: "component name", children: "node array", text: "string or binding", binding: "binding", visible: "{binding,equals:scalar}", action: "declared action identifier", label: "string", inputType: ["text", "number", "checkbox"], columns: "array of {key:identifier,label:string}", ariaLabel: "string" },
+        events: { action: { fields: ["action", "source", "state", "revision"], declaration: "definition.actions and host allowedActions" }, state: { type: "scalar", source: "state binding" } },
+        limits: { treeDepth: 16, nodes: 512, textLength: 4096, tableRows: 100, tableColumns: 20, listItems: 100, transportBytes: 1048576 } });
+}
+const plain = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const exact = (value, allowed) => {
+    for (const key of Object.keys(value))
+        if (!allowed.has(key))
+            throw new Error(`Unknown interface property: ${key}`);
+};
+const name = (value) => typeof value === "string" && identifier.test(value);
+const scalar = (value) => value === null || typeof value === "string" || typeof value === "boolean" || (typeof value === "number" && Number.isFinite(value));
+function binding(value) {
+    if (!plain(value))
+        throw new Error("Invalid binding");
+    exact(value, new Set(["source", "path"]));
+    if ((value.source !== "data" && value.source !== "state") || !name(value.path))
+        throw new Error("Invalid binding");
+    for (const part of value.path.split("."))
+        assertSafeKey(part);
+}
+function valueAt(source, path) {
+    let value = source;
+    for (const part of path.split("."))
+        value = plain(value) && Object.hasOwn(value, part) ? value[part] : undefined;
+    return value;
+}
+function visitNodes(node, callback) {
+    callback(node);
+    for (const child of node.children ?? [])
+        visitNodes(child, callback);
+}
+function validateBindings(definition, data, state) {
+    visitNodes(definition.screen, (node) => {
+        if (node.component === "Table") {
+            const rows = valueAt(node.binding.source === "data" ? data : state, node.binding.path);
+            if (rows === undefined)
+                return;
+            if (!Array.isArray(rows) || rows.length > 100 || rows.some((row) => !plain(row)))
+                throw new Error("Invalid or oversized table rows");
+            for (const row of rows)
+                for (const col of node.columns ?? [])
+                    if (Object.hasOwn(row, col.key) && !scalar(row[col.key]))
+                        throw new Error("Invalid table cell");
+        }
+        if (node.component === "List") {
+            const items = valueAt(node.binding.source === "data" ? data : state, node.binding.path);
+            if (items !== undefined && (!Array.isArray(items) || items.length > 100 || items.some((item) => !scalar(item))))
+                throw new Error("Invalid or oversized list items");
+        }
+        if (node.component === "Input") {
+            const current = valueAt(state, node.binding.path);
+            if (current !== undefined && !scalar(current))
+                throw new Error("Invalid input state");
+        }
+    });
+}
+/** A definition owns its state shape. Retain values only for unchanged input identities. */
+function retainedState(previous, next, oldState) {
+    const state = copyData(next.state ?? {});
+    if (previous.id !== next.id)
+        return state;
+    const inputs = new Map();
+    visitNodes(previous.screen, (node) => { if (node.component === "Input")
+        inputs.set(node.key, node); });
+    visitNodes(next.screen, (node) => {
+        if (node.component !== "Input")
+            return;
+        const old = inputs.get(node.key);
+        if (!old || old.inputType !== node.inputType || old.binding?.path !== node.binding?.path)
+            return;
+        const path = node.binding.path;
+        const oldValue = valueAt(oldState, path);
+        const defaultValue = valueAt(state, path);
+        if (!scalar(oldValue) || defaultValue === undefined || typeof oldValue !== typeof defaultValue)
+            return;
+        const parts = path.split(".");
+        let target = state;
+        for (const part of parts.slice(0, -1)) {
+            if (!plain(target[part]))
+                return;
+            target = target[part];
+        }
+        target[parts.at(-1)] = oldValue;
+    });
+    return state;
+}
+export function defineInterface(definition) { return definition; }
+/** Validate untrusted structured data before creating a controller or mounting it. */
+export function validateInterfaceDefinition(value, components = []) {
+    assertBoundedData(value);
+    if (!plain(value))
+        throw new Error("Invalid interface definition");
+    exact(value, new Set(["id", "screen", "actions", "data", "state"]));
+    if (!name(value.id) || !plain(value.screen))
+        throw new Error("Invalid interface identity or screen");
+    for (const key of ["data", "state"])
+        if (value[key] !== undefined && !plain(value[key]))
+            throw new Error(`Invalid ${key}`);
+    if (value.actions !== undefined && (!Array.isArray(value.actions) || value.actions.some((action) => !name(action)) || new Set(value.actions).size !== value.actions.length))
+        throw new Error("Invalid actions");
+    const actions = (value.actions ?? []);
+    if (components.some((component) => !name(component) || builtins.has(component)) || new Set(components).size !== components.length)
+        throw new Error("Invalid component registry");
+    const known = new Set([...builtins, ...components]);
+    const keys = new Set();
+    let count = 0;
+    function visit(node, depth) {
+        if (!plain(node) || depth > 16 || ++count > 512)
+            throw new Error("Interface tree limit exceeded");
+        exact(node, nodeKeys);
+        if (!name(node.key) || keys.has(node.key))
+            throw new Error("Invalid or duplicate node key");
+        keys.add(node.key);
+        if (typeof node.component !== "string" || !known.has(node.component))
+            throw new Error(`Unknown component: ${String(node.component)}`);
+        if (builtins.has(node.component)) {
+            const spec = vocabulary[node.component];
+            for (const property of Object.keys(node))
+                if (!spec.properties.includes(property))
+                    throw new Error(`Unsupported ${node.component} property: ${property}`);
+            for (const property of spec.required)
+                if (node[property] === undefined)
+                    throw new Error(`${node.component} needs ${property}`);
+        }
+        if (node.text !== undefined) {
+            if (typeof node.text === "string") {
+                if (node.text.length > 4096)
+                    throw new Error("Text limit exceeded");
+            }
+            else
+                binding(node.text);
+        }
+        if (node.binding !== undefined)
+            binding(node.binding);
+        if (node.visible !== undefined) {
+            if (!plain(node.visible))
+                throw new Error("Invalid visibility condition");
+            exact(node.visible, new Set(["binding", "equals"]));
+            binding(node.visible.binding);
+            if (!scalar(node.visible.equals))
+                throw new Error("Invalid visibility condition");
+        }
+        for (const field of ["label", "ariaLabel"])
+            if (node[field] !== undefined && (typeof node[field] !== "string" || node[field].length > 256))
+                throw new Error(`Invalid ${field}`);
+        if (node.action !== undefined && (!name(node.action) || !actions.includes(node.action)))
+            throw new Error("Action is not declared by the host");
+        if (node.inputType !== undefined && !["text", "number", "checkbox"].includes(node.inputType))
+            throw new Error("Invalid input type");
+        if (node.columns !== undefined) {
+            if (!Array.isArray(node.columns) || node.columns.length < 1 || node.columns.length > 20 || node.columns.some((col) => !plain(col) || Object.keys(col).some((key) => key !== "key" && key !== "label") || !name(col.key) || typeof col.label !== "string" || col.label.length > 256))
+                throw new Error("Invalid table columns");
+        }
+        if (node.component === "Input" && (!node.binding || node.binding.source !== "state" || !node.label))
+            throw new Error("Input needs a state binding and label");
+        if (node.component === "Button" && (!node.action || !node.text))
+            throw new Error("Button needs an action and text");
+        if (node.component === "Table" && (!node.binding || !node.columns))
+            throw new Error("Table needs rows and columns");
+        if (node.component !== "Button" && node.action !== undefined)
+            throw new Error("Only Button accepts an action");
+        if (node.component !== "Input" && node.inputType !== undefined)
+            throw new Error("Only Input accepts inputType");
+        if (node.component !== "Table" && node.columns !== undefined)
+            throw new Error("Only Table accepts columns");
+        if (node.children !== undefined && (!Array.isArray(node.children) || (!(["Stack", "Row"].includes(node.component)) && !components.includes(node.component))))
+            throw new Error("Invalid children");
+        for (const child of node.children ?? [])
+            visit(child, depth + 1);
+    }
+    visit(value.screen, 0);
+    validateBindings(value, (value.data ?? {}), (value.state ?? {}));
+}
+export function createInterfaceController(definition, options = {}) {
+    const components = options.components ?? [];
+    validateInterfaceDefinition(definition, components);
+    if (options.allowedActions && definition.actions?.some((action) => !options.allowedActions.includes(action)))
+        throw new Error("Action is not allowed by host");
+    let current = copyData(definition);
+    let data = copyData(definition.data ?? {});
+    let state = copyData(definition.state ?? {});
+    validateBindings(current, data, state);
+    let revision = 0;
+    let disposed = false;
+    let dispatching = false;
+    let emitting = false;
+    let pending = false;
+    let updating = false;
+    const listeners = new Set();
+    const participants = new Set();
+    const copySnapshot = (value) => ({
+        definition: copyData(value.definition), data: copyData(value.data), state: copyData(value.state), revision: value.revision,
+    });
+    const snapshot = () => copySnapshot({ definition: current, data, state, revision });
+    const report = (error) => { try {
+        options.onError?.(error);
+    }
+    catch { /* Error reporting must not enter the interface runtime. */ } };
+    const emit = () => {
+        if (emitting) {
+            pending = true;
+            return;
+        }
+        emitting = true;
+        try {
+            let passes = 0;
+            do {
+                pending = false;
+                const accepted = snapshot();
+                for (const listener of listeners) {
+                    try {
+                        listener(copySnapshot(accepted));
+                    }
+                    catch (error) {
+                        report(error);
+                    }
+                    if (revision !== accepted.revision) {
+                        pending = true;
+                        break;
+                    }
+                }
+                if (++passes >= 32 && pending) {
+                    report(new Error("Interface update loop limit exceeded"));
+                    pending = false;
+                    break;
+                }
+            } while (pending && !disposed);
+        }
+        finally {
+            emitting = false;
+        }
+    };
+    const accept = (nextDefinition, nextData, nextState) => {
+        if (updating)
+            throw new Error("Interface update already in progress");
+        updating = true;
+        const prepared = [];
+        try {
+            const candidate = { definition: nextDefinition, data: nextData, state: nextState, revision: revision + 1 };
+            for (const renderer of participants)
+                prepared.push(renderer(copySnapshot(candidate)));
+            if (disposed)
+                throw new Error("Interface controller was disposed during update");
+            for (const renderer of prepared)
+                renderer.commit();
+            current = nextDefinition;
+            data = nextData;
+            state = nextState;
+            revision++;
+        }
+        catch (error) {
+            for (const renderer of prepared.reverse()) {
+                try {
+                    renderer.discard();
+                }
+                catch (cleanupError) {
+                    report(cleanupError);
+                }
+            }
+            throw error;
+        }
+        finally {
+            updating = false;
+        }
+        emit();
+    };
+    const controller = {
+        snapshot,
+        updateData(next, expectedRevision) { if (disposed || (expectedRevision !== undefined && expectedRevision !== revision))
+            return false; if (updating)
+            throw new Error("Interface update already in progress"); assertBoundedData(next); if (!plain(next))
+            throw new Error("Invalid data"); const copy = copyData(next); validateBindings(current, copy, state); accept(current, copy, state); return true; },
+        updateDefinition(next, expectedRevision) {
+            if (disposed || (expectedRevision !== undefined && expectedRevision !== revision))
+                return false;
+            if (updating)
+                throw new Error("Interface update already in progress");
+            validateInterfaceDefinition(next, components);
+            if (options.allowedActions && next.actions?.some((action) => !options.allowedActions.includes(action)))
+                throw new Error("Action is not allowed by host");
+            const copy = copyData(next);
+            const nextData = copyData(copy.data ?? {});
+            const nextState = retainedState(current, copy, state);
+            assertBoundedData(nextState);
+            validateBindings(copy, nextData, nextState);
+            accept(copy, nextData, nextState);
+            return true;
+        },
+        setState(path, value) {
+            if (disposed)
+                return;
+            if (updating)
+                throw new Error("Interface update already in progress");
+            if (!name(path) || !scalar(value))
+                throw new Error("Invalid state update");
+            const parts = path.split(".");
+            for (const part of parts)
+                assertSafeKey(part);
+            const next = copyData(state);
+            let target = next;
+            for (const part of parts.slice(0, -1)) {
+                const child = target[part];
+                if (child !== undefined && !plain(child))
+                    throw new Error("State path is not an object");
+                if (child === undefined)
+                    target[part] = {};
+                target = target[part];
+            }
+            target[parts.at(-1)] = value;
+            assertBoundedData(next);
+            validateBindings(current, data, next);
+            accept(current, data, next);
+        },
+        dispatch(action, source) {
+            if (disposed || dispatching)
+                return;
+            if (updating)
+                throw new Error("Interface update already in progress");
+            if (!current.actions?.includes(action) || !findAction(current.screen, source, action, data, state))
+                throw new Error("Action is not available");
+            dispatching = true;
+            try {
+                const result = options.onEvent?.({ action, source, state: copyData(state), revision });
+                if (result && typeof result === "object" && "then" in result)
+                    void Promise.resolve(result).catch(report);
+            }
+            catch (error) {
+                report(error);
+            }
+            finally {
+                dispatching = false;
+            }
+        },
+        subscribe(listener) { if (disposed)
+            throw new Error("Interface controller is disposed"); listeners.add(listener); try {
+            listener(snapshot());
+        }
+        catch (error) {
+            listeners.delete(listener);
+            throw error;
+        } return () => { listeners.delete(listener); }; },
+        dispose() { disposed = true; listeners.clear(); participants.clear(); detachInterfaceRenderers(controller); },
+    };
+    attachInterfaceRenderers(controller, participants);
+    return controller;
+}
+function findAction(node, key, action, data, state) {
+    if (node.visible && valueAt(node.visible.binding.source === "data" ? data : state, node.visible.binding.path) !== node.visible.equals)
+        return false;
+    return (node.key === key && node.action === action) || (node.children?.some((child) => findAction(child, key, action, data, state)) ?? false);
+}
+export function resolveInterfaceBinding(snapshot, bindingValue) {
+    return valueAt(bindingValue.source === "data" ? snapshot.data : snapshot.state, bindingValue.path);
+}

package/dist/output-presentation-suggestion-schema.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+export declare const generatedOutputFieldSchema: z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodString;
+}, z.core.$strict>;
+export declare const generatedOutputPresentationSchema: z.ZodObject<{
+    fields: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type GeneratedOutputPresentation = z.infer<typeof generatedOutputPresentationSchema>;

package/dist/output-presentation-suggestion-schema.js

@@ -0,0 +1,8 @@
+import { z } from "zod";
+export const generatedOutputFieldSchema = z.object({
+    key: z.string().min(1).max(160),
+    label: z.string().min(1).max(160),
+}).strict();
+export const generatedOutputPresentationSchema = z.object({
+    fields: z.array(generatedOutputFieldSchema).max(256),
+}).strict();

package/dist/output-schema.d.ts

@@ -0,0 +1,26 @@
+export interface OutputFieldDefinition {
+    type: "string" | "number" | "integer" | "boolean" | "object" | "array";
+    description: string;
+    required?: boolean;
+    format?: "date" | "date-time";
+    semantic?: "currency" | "count" | "ratio" | "time-series" | "category-series";
+    role?: "dimension" | "measure";
+    enum?: string[];
+    currency?: string;
+    minimum?: number;
+    maximum?: number;
+    fields?: Record<string, OutputFieldDefinition>;
+    items?: OutputFieldDefinition;
+}
+export interface AggregateCapabilityOutputSchema {
+    type: "object";
+    semantic: "aggregate";
+    description: string;
+    fields: Record<string, OutputFieldDefinition>;
+}
+export type CapabilityOutputSchema = Record<string, OutputFieldDefinition> | AggregateCapabilityOutputSchema;
+export declare function defineOutputSchema<T extends CapabilityOutputSchema>(schema: T): T;
+export declare function isAggregateOutputSchema(schema: CapabilityOutputSchema): schema is AggregateCapabilityOutputSchema;
+export declare function getOutputSchemaFields(schema: CapabilityOutputSchema): Record<string, OutputFieldDefinition>;
+export declare function validateOutputSchema(schema: CapabilityOutputSchema): void;
+export declare function validateCapabilityOutput(schema: CapabilityOutputSchema, value: unknown): void;

package/dist/output-schema.js

@@ -0,0 +1,213 @@
+import { assertBoundedData, isCalendarDate, isUTCInstant } from "./validation-safety.js";
+export function defineOutputSchema(schema) {
+    return schema;
+}
+export function isAggregateOutputSchema(schema) {
+    return schema.type === "object" && schema.semantic === "aggregate";
+}
+export function getOutputSchemaFields(schema) {
+    return isAggregateOutputSchema(schema) ? schema.fields : schema;
+}
+function validateTimeSeriesField(name, field) {
+    if (field.type !== "array")
+        throw new Error("Time-series semantics require an array output: " + name);
+    if (field.items?.type !== "object" || !field.items.fields)
+        throw new Error("Time-series items must be objects: " + name);
+    const entries = Object.entries(field.items.fields);
+    if (entries.length === 0)
+        throw new Error("Time-series item schema cannot be empty: " + name);
+    const dimensions = entries.filter(([, definition]) => definition.role === "dimension");
+    const measures = entries.filter(([, definition]) => definition.role === "measure");
+    if (dimensions.length !== 1)
+        throw new Error("Time-series requires exactly one dimension: " + name);
+    if (measures.length !== 1)
+        throw new Error("Time-series requires exactly one measure in this slice: " + name);
+    const [dimensionName, dimension] = dimensions[0];
+    if (dimension.type !== "string" || (dimension.format !== "date" && dimension.format !== "date-time"))
+        throw new Error("Time-series dimension must be a temporal string: " + dimensionName);
+    const [measureName, measure] = measures[0];
+    if (measure.type !== "number" && measure.type !== "integer")
+        throw new Error("Time-series measure must be numeric: " + measureName);
+    if (!measure.semantic || !["count", "currency", "ratio"].includes(measure.semantic))
+        throw new Error("Time-series measure requires supported numeric semantics: " + measureName);
+    if (measure.semantic === "currency" && !measure.currency)
+        throw new Error("Currency measure requires a currency code: " + measureName);
+    if (measure.semantic === "ratio" && ((measure.minimum !== undefined && measure.minimum < 0) || (measure.maximum !== undefined && measure.maximum > 1)))
+        throw new Error("Ratio measure constraints must remain within 0..1: " + measureName);
+    for (const [fieldName, definition] of entries)
+        if ((definition.type === "object" || definition.type === "array") && definition.role)
+            throw new Error("Nested time-series roles are unsupported: " + fieldName);
+}
+function validateCategorySeriesField(name, field) {
+    if (field.type !== "array")
+        throw new Error("Category-series semantics require an array output: " + name);
+    if (field.items?.type !== "object" || !field.items.fields)
+        throw new Error("Category-series items must be objects: " + name);
+    const entries = Object.entries(field.items.fields);
+    if (entries.length === 0)
+        throw new Error("Category-series item schema cannot be empty: " + name);
+    const dimensions = entries.filter(([, definition]) => definition.role === "dimension"), measures = entries.filter(([, definition]) => definition.role === "measure");
+    if (dimensions.length !== 1)
+        throw new Error("Category-series requires exactly one dimension: " + name);
+    if (measures.length !== 1)
+        throw new Error("Category-series requires exactly one measure in this slice: " + name);
+    const [dimensionName, dimension] = dimensions[0];
+    if (dimension.type !== "string")
+        throw new Error("Category dimension must be a string: " + dimensionName);
+    if (dimension.enum && (dimension.enum.length === 0 || new Set(dimension.enum).size !== dimension.enum.length))
+        throw new Error("Category enum must contain unique values: " + dimensionName);
+    const [measureName, measure] = measures[0];
+    if (measure.type !== "number" && measure.type !== "integer")
+        throw new Error("Category-series measure must be numeric: " + measureName);
+    if (!measure.semantic || !["count", "currency", "ratio"].includes(measure.semantic))
+        throw new Error("Category-series measure requires supported numeric semantics: " + measureName);
+    if (measure.semantic === "currency" && !measure.currency)
+        throw new Error("Currency measure requires a currency code: " + measureName);
+    if (measure.semantic === "ratio" && ((measure.minimum !== undefined && measure.minimum < 0) || (measure.maximum !== undefined && measure.maximum > 1)))
+        throw new Error("Ratio measure constraints must remain within 0..1: " + measureName);
+    for (const [fieldName, definition] of entries)
+        if ((definition.type === "object" || definition.type === "array") && definition.role)
+            throw new Error("Nested category-series roles are unsupported: " + fieldName);
+}
+export function validateOutputSchema(schema) {
+    assertBoundedData(schema);
+    const candidate = schema;
+    if (candidate.semantic === "aggregate" && candidate.type !== "object")
+        throw new Error("Aggregate semantics require an object output");
+    const aggregate = isAggregateOutputSchema(schema);
+    const entries = Object.entries(getOutputSchemaFields(schema));
+    if (aggregate && entries.length === 0)
+        throw new Error("Aggregate output must contain at least one renderable metric");
+    for (const [name, field] of entries) {
+        if (field.semantic === "time-series")
+            validateTimeSeriesField(name, field);
+        if (field.semantic === "category-series")
+            validateCategorySeriesField(name, field);
+        if (field.role)
+            throw new Error("Dimension/measure roles are only valid inside time-series items: " + name);
+        if (aggregate && (field.type === "object" || field.type === "array"))
+            throw new Error("Nested aggregate metric is unsupported: " + name);
+        if (aggregate && (!field.semantic || !["count", "currency", "ratio"].includes(field.semantic)))
+            throw new Error("Unsupported aggregate field semantic: " + name);
+        if (field.semantic === "count" && field.type !== "integer" && field.type !== "number")
+            throw new Error("Count semantics require a numeric field: " + name);
+        if (field.semantic === "currency" && ((field.type !== "integer" && field.type !== "number") || !field.currency))
+            throw new Error("Currency semantics require a numeric field and currency code: " + name);
+        if (field.semantic === "ratio") {
+            if (field.type !== "number")
+                throw new Error("Ratio semantics require a number field: " + name);
+            if ((field.minimum !== undefined && field.minimum < 0) || (field.maximum !== undefined && field.maximum > 1) || (field.minimum !== undefined && field.maximum !== undefined && field.minimum > field.maximum))
+                throw new Error("Ratio constraints must remain within 0..1: " + name);
+        }
+    }
+}
+function missingOutput(value) {
+    return value === undefined || value === null;
+}
+function validateOutputValue(field, value, path) {
+    if (missingOutput(value)) {
+        if (field.required !== false) {
+            throw new Error(`Required output omitted: ${path}`);
+        }
+        return;
+    }
+    if (field.type === "string") {
+        if (typeof value !== "string")
+            throw new Error(`Output "${path}" must be a string`);
+        if (field.enum && !field.enum.includes(value))
+            throw new Error(`Output "${path}" is not an allowed enum value`);
+        if (field.format === "date" && !isCalendarDate(value))
+            throw new Error(`Output "${path}" must use YYYY-MM-DD`);
+        if (field.format === "date-time" && !isUTCInstant(value))
+            throw new Error(`Output "${path}" must be an ISO-8601 UTC instant`);
+        return;
+    }
+    if (field.type === "number" || field.type === "integer") {
+        if (typeof value !== "number" || !Number.isFinite(value))
+            throw new Error(`Output "${path}" must be numeric`);
+        if (field.type === "integer" && !Number.isInteger(value))
+            throw new Error(`Output "${path}" must be an integer`);
+        if (field.minimum !== undefined && value < field.minimum)
+            throw new Error(`Output "${path}" is below minimum`);
+        if (field.maximum !== undefined && value > field.maximum)
+            throw new Error(`Output "${path}" exceeds maximum`);
+        if (field.semantic === "ratio" && (value < 0 || value > 1))
+            throw new Error(`Output ratio "${path}" must remain within 0..1`);
+        return;
+    }
+    if (field.type === "boolean") {
+        if (typeof value !== "boolean")
+            throw new Error(`Output "${path}" must be boolean`);
+        return;
+    }
+    if (field.type === "object") {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new Error(`Output "${path}" must be an object`);
+        const record = value;
+        for (const key of Object.keys(record)) {
+            if (!Object.hasOwn(field.fields ?? {}, key))
+                throw new Error(`Unexpected nested output: ${path}.${key}`);
+        }
+        for (const [name, child] of Object.entries(field.fields ?? {})) {
+            validateOutputValue(child, Object.hasOwn(record, name) ? record[name] : undefined, `${path}.${name}`);
+        }
+        return;
+    }
+    if (!Array.isArray(value))
+        throw new Error(`Output "${path}" must be an array`);
+    if (!field.items)
+        throw new Error(`Output array "${path}" lacks an item schema`);
+    value.forEach((item, index) => validateOutputValue(field.items, item, `${path}[${index}]`));
+}
+export function validateCapabilityOutput(schema, value) {
+    assertBoundedData(schema);
+    assertBoundedData(value);
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Capability output must be an object");
+    }
+    const result = value;
+    const fields = getOutputSchemaFields(schema);
+    for (const key of Object.keys(result)) {
+        if (!Object.hasOwn(fields, key))
+            throw new Error(`Unexpected supplied output: ${key}`);
+    }
+    for (const [name, field] of Object.entries(fields)) {
+        validateOutputValue(field, Object.hasOwn(result, name) ? result[name] : undefined, name);
+    }
+    for (const [name, field] of Object.entries(fields)) {
+        if (missingOutput(result[name]) && field.required === false)
+            continue;
+        if (field.semantic === "category-series") {
+            const points = result[name];
+            const entries = Object.entries(field.items.fields);
+            const [dimensionName] = entries.find(([, definition]) => definition.role === "dimension");
+            const seen = new Set();
+            for (const point of points) {
+                const category = point[dimensionName];
+                if (seen.has(category))
+                    throw new Error("Duplicate category is not allowed: " + category);
+                seen.add(category);
+            }
+            continue;
+        }
+        if (field.semantic === "time-series") {
+            const points = result[name];
+            const entries = Object.entries(field.items.fields);
+            const [dimensionName, dimension] = entries.find(([, definition]) => definition.role === "dimension");
+            let previous;
+            for (const point of points) {
+                const current = point[dimensionName];
+                const previousInstant = previous === undefined
+                    ? undefined
+                    : Date.parse(previous);
+                const currentInstant = dimension.format === "date-time"
+                    ? Date.parse(current)
+                    : Date.parse(`${current}T00:00:00.000Z`);
+                if (previousInstant !== undefined && currentInstant < previousInstant) {
+                    throw new Error("Time-series points must preserve chronological order");
+                }
+                previous = current;
+            }
+        }
+    }
+}

package/dist/presentation-composition.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import type { PresentationEnvelope, PresentationPlan, PresentationProvenance, SurfaceExecution, RelatedSurfaceExecution } from "./composed-surface.js";
+export declare const presentationPlanSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    groups: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        emphasis: z.ZodEnum<{
+            normal: "normal";
+            prominent: "prominent";
+            subtle: "subtle";
+        }>;
+        density: z.ZodEnum<{
+            comfortable: "comfortable";
+            compact: "compact";
+        }>;
+        sections: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare function sectionId(kind: "primary" | "related", capability: string): string;
+export declare function buildPresentationEnvelope(primary: SurfaceExecution, related: RelatedSurfaceExecution[]): PresentationEnvelope;
+export declare function deterministicPresentation(envelope: PresentationEnvelope): PresentationPlan;
+export declare function validatePresentationPlan(envelope: PresentationEnvelope, value: unknown): PresentationPlan;
+export declare function composePresentation(envelope: PresentationEnvelope, strategy: "deterministic" | "generative", generate?: (envelope: PresentationEnvelope) => Promise<unknown>): Promise<{
+    plan: PresentationPlan;
+    provenance: PresentationProvenance;
+}>;