@veil-runtime/ui 0.0.0-stage → 0.1.0

package/dist/derive-output-view.js

@@ -0,0 +1,97 @@
+import { getOutputSchemaFields, isAggregateOutputSchema, } from "./output-schema.js";
+function humanise(value) {
+    return value
+        .replace(/[._-]+/g, " ")
+        .replace(/([a-z])([A-Z])/g, "$1 $2")
+        .replace(/\b\w/g, (character) => character.toUpperCase());
+}
+function deriveTableColumns(item) {
+    if (item.type !== "object" ||
+        !item.fields) {
+        return [];
+    }
+    return Object.keys(item.fields).map((key) => ({
+        key,
+        label: humanise(key),
+    }));
+}
+function deriveDetailFields(schema) {
+    return Object.entries(getOutputSchemaFields(schema)).map(([key, definition]) => ({
+        key,
+        label: humanise(key),
+        ...(definition.semantic && definition.semantic !== "time-series" && definition.semantic !== "category-series" ? { semantic: definition.semantic } : {}),
+        ...(definition.currency ? { currency: definition.currency } : {}),
+    }));
+}
+export function deriveOutputView(schema) {
+    if (!schema) {
+        return {
+            surface: "form",
+            derivation: { source: "input-schema", reason: "no-output-schema" },
+        };
+    }
+    if (isAggregateOutputSchema(schema)) {
+        return {
+            surface: "aggregate",
+            derivation: { source: "output-schema", reason: "authoritative-aggregate-object" },
+            aggregate: {
+                metrics: Object.entries(schema.fields).map(([key, definition]) => ({
+                    key,
+                    label: humanise(key),
+                    authoritativeType: definition.type,
+                    semantic: definition.semantic,
+                    ...(definition.currency ? { currency: definition.currency } : {}),
+                    derivation: { source: "authoritative-output-schema", reason: "metric-semantics" },
+                })),
+            },
+        };
+    }
+    const entries = Object.entries(getOutputSchemaFields(schema));
+    const categorySeries = entries.filter(([, definition]) => definition.semantic === "category-series");
+    if (categorySeries.length === 1) {
+        const [dataPath, collection] = categorySeries[0], itemFields = Object.entries(collection.items.fields), [dimensionKey, dimension] = itemFields.find(([, field]) => field.role === "dimension"), [measureKey, measure] = itemFields.find(([, field]) => field.role === "measure");
+        return { surface: "category-series", derivation: { source: "output-schema", reason: "authoritative-category-series" }, categorySeries: { dataPath, visualization: "bar", ordering: "source-order", dimension: { key: dimensionKey, label: humanise(dimensionKey), type: "string", ...(dimension.enum ? { enum: dimension.enum } : {}), role: "dimension" }, measure: { key: measureKey, label: humanise(measureKey), type: measure.type, semantic: measure.semantic, ...(measure.currency ? { currency: measure.currency } : {}), role: "measure" }, derivation: { source: "authoritative-output-schema", reason: "categorical-dimension-with-numeric-measure" } } };
+    }
+    const timeSeries = entries.filter(([, definition]) => definition.semantic === "time-series");
+    if (timeSeries.length === 1) {
+        const [dataPath, collection] = timeSeries[0];
+        const itemFields = Object.entries(collection.items.fields);
+        const [dimensionKey, dimension] = itemFields.find(([, field]) => field.role === "dimension");
+        const [measureKey, measure] = itemFields.find(([, field]) => field.role === "measure");
+        return { surface: "time-series", derivation: { source: "output-schema", reason: "authoritative-time-series" }, timeSeries: { dataPath, visualization: "line", dimension: { key: dimensionKey, label: humanise(dimensionKey), type: "string", format: dimension.format, role: "dimension" }, measure: { key: measureKey, label: humanise(measureKey), type: measure.type, semantic: measure.semantic, ...(measure.currency ? { currency: measure.currency } : {}), role: "measure" }, derivation: { source: "authoritative-output-schema", reason: "temporal-dimension-with-numeric-measure" } } };
+    }
+    // A single top-level array of objects naturally maps to a table.
+    if (entries.length === 1) {
+        const [key, definition] = entries[0];
+        if (definition.type === "array" &&
+            definition.items?.type === "object") {
+            return {
+                surface: "table",
+                derivation: { source: "output-schema", reason: "single-top-level-array-of-objects" },
+                table: {
+                    dataPath: key,
+                    columns: deriveTableColumns(definition.items),
+                },
+            };
+        }
+    }
+    // A flat object naturally maps to a detail surface.
+    const isFlatObject = entries.every(([, definition]) => definition.type !== "array" &&
+        definition.type !== "object");
+    if (isFlatObject) {
+        return {
+            surface: "detail",
+            derivation: { source: "output-schema", reason: "flat-output-object" },
+            detail: {
+                fields: deriveDetailFields(schema),
+            },
+        };
+    }
+    return {
+        surface: "detail",
+        derivation: { source: "output-schema", reason: "structured-output-object" },
+        detail: {
+            fields: deriveDetailFields(schema),
+        },
+    };
+}

package/dist/execution-request.d.ts

@@ -0,0 +1,13 @@
+export type ApplicationInvocationContext = {
+    kind: "relationship";
+    sourceExecutionToken: string;
+    sourceValues: Record<string, unknown>;
+} | {
+    kind: "success-transition";
+    sourceExecutionToken: string;
+};
+export interface ApplicationExecutionRequest {
+    humanInput: Record<string, unknown>;
+    context?: ApplicationInvocationContext;
+}
+export declare function parseApplicationExecutionRequest(value: unknown): ApplicationExecutionRequest;

package/dist/execution-request.js

@@ -0,0 +1,58 @@
+import { assertBoundedData } from "./validation-safety.js";
+export function parseApplicationExecutionRequest(value) {
+    assertBoundedData(value);
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Application execution request must be an object");
+    }
+    const record = value;
+    for (const key of Object.keys(record)) {
+        if (key !== "humanInput" && key !== "context") {
+            throw new Error(`Unexpected application execution property: ${key}`);
+        }
+    }
+    const humanInput = record.humanInput;
+    if (!humanInput || typeof humanInput !== "object" || Array.isArray(humanInput)) {
+        throw new Error("Application execution humanInput must be an object");
+    }
+    if (record.context === undefined) {
+        return { humanInput: humanInput };
+    }
+    if (!record.context || typeof record.context !== "object" || Array.isArray(record.context)) {
+        throw new Error("Application execution context must be an object");
+    }
+    const context = record.context;
+    if (context.kind !== "relationship" && context.kind !== "success-transition") {
+        throw new Error("Unknown application execution context kind");
+    }
+    const allowed = context.kind === "relationship"
+        ? new Set(["kind", "sourceExecutionToken", "sourceValues"])
+        : new Set(["kind", "sourceExecutionToken"]);
+    for (const key of Object.keys(context)) {
+        if (!allowed.has(key)) {
+            throw new Error(`Unexpected application execution context property: ${key}`);
+        }
+    }
+    if (typeof context.sourceExecutionToken !== "string" || !context.sourceExecutionToken) {
+        throw new Error("Application execution context requires a source token");
+    }
+    if (context.kind === "success-transition") {
+        return {
+            humanInput: humanInput,
+            context: {
+                kind: "success-transition",
+                sourceExecutionToken: context.sourceExecutionToken,
+            },
+        };
+    }
+    if (!context.sourceValues || typeof context.sourceValues !== "object" || Array.isArray(context.sourceValues)) {
+        throw new Error("Relationship execution context requires sourceValues");
+    }
+    return {
+        humanInput: humanInput,
+        context: {
+            kind: "relationship",
+            sourceExecutionToken: context.sourceExecutionToken,
+            sourceValues: context.sourceValues,
+        },
+    };
+}

package/dist/experience-orchestration.d.ts

@@ -0,0 +1,13 @@
+import type { DerivedApplication, DerivedApplicationCapability } from "./application.js";
+export type ApplicationExperienceRole = "entry-primary" | "supporting-related" | "navigation-target" | "contextual-action" | "transition-target" | "developer-only";
+export interface ApplicationExperienceCapability {
+    capability: DerivedApplicationCapability;
+    roles: ApplicationExperienceRole[];
+}
+export interface ApplicationExperienceAction {
+    capability: string;
+    label: string;
+    bindings: Record<string, string>;
+}
+export declare function deriveApplicationExperience(application: DerivedApplication): ApplicationExperienceCapability[];
+export declare function deriveApplicationActions(application: DerivedApplication): ApplicationExperienceAction[];

package/dist/experience-orchestration.js

@@ -0,0 +1,31 @@
+import { interpretRelationship } from "./relationship-interpretation.js";
+function addRole(roles, capability, role) { roles.get(capability)?.add(role); }
+export function deriveApplicationExperience(application) {
+    const roles = new Map(application.capabilities.map((capability) => [capability.name, new Set()]));
+    addRole(roles, application.entryCapability, "entry-primary");
+    for (const source of application.capabilities) {
+        for (const relationship of source.relationships) {
+            addRole(roles, relationship.targetCapability, interpretRelationship(relationship, source.name === application.entryCapability ? "application-entry" : "detail") === "related-read"
+                ? "supporting-related"
+                : interpretRelationship(relationship, source.name === application.entryCapability ? "application-entry" : "detail") === "navigation"
+                    ? "navigation-target"
+                    : "contextual-action");
+        }
+        const transition = source.transition?.onSuccess;
+        if (transition)
+            addRole(roles, transition.capability, "transition-target");
+    }
+    return application.capabilities.map((capability) => {
+        const capabilityRoles = roles.get(capability.name);
+        if (capabilityRoles.size === 0)
+            capabilityRoles.add("developer-only");
+        return { capability, roles: [...capabilityRoles] };
+    });
+}
+function isApplicationAction(relationship) {
+    return interpretRelationship(relationship, "application-entry") === "application-action";
+}
+export function deriveApplicationActions(application) {
+    const entry = application.capabilities.find((capability) => capability.name === application.entryCapability);
+    return (entry?.relationships ?? []).filter(isApplicationAction).map((relationship) => ({ capability: relationship.targetCapability, label: relationship.label, bindings: relationship.bindings }));
+}

package/dist/format-semantic-value.d.ts

@@ -0,0 +1,4 @@
+export declare function formatSemanticValue(value: unknown, field?: {
+    semantic?: "currency" | "count" | "ratio";
+    currency?: string;
+}): unknown;

package/dist/format-semantic-value.js

@@ -0,0 +1,15 @@
+export function formatSemanticValue(value, field) {
+    if (field?.semantic === "currency" && typeof value === "number" && field.currency) {
+        return new Intl.NumberFormat(undefined, {
+            style: "currency",
+            currency: field.currency,
+        }).format(value);
+    }
+    if (field?.semantic === "count" && typeof value === "number") {
+        return new Intl.NumberFormat(undefined, { maximumFractionDigits: 0 }).format(value);
+    }
+    if (field?.semantic === "ratio" && typeof value === "number") {
+        return new Intl.NumberFormat(undefined, { style: "percent", maximumFractionDigits: 1 }).format(value);
+    }
+    return value;
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export * from "./input-schema.js";
+export * from "./output-schema.js";
+export * from "./application.js";
+export * from "./capability-view.js";
+export * from "./composed-surface.js";
+export * from "./workflow.js";
+export * from "./relationship-interpretation.js";
+export * from "./validate-application.js";
+export * from "./registry.js";
+export * from "./derive-input-fields.js";
+export * from "./derive-output-view.js";
+export * from "./capability-view-derivation.js";
+export * from "./interaction-resolution.js";
+export * from "./experience-orchestration.js";
+export * from "./presentation-context.js";
+export * from "./presentation-composition.js";
+export * from "./execution-request.js";
+export * from "./format-semantic-value.js";

package/dist/index.js

@@ -0,0 +1,18 @@
+export * from "./input-schema.js";
+export * from "./output-schema.js";
+export * from "./application.js";
+export * from "./capability-view.js";
+export * from "./composed-surface.js";
+export * from "./workflow.js";
+export * from "./relationship-interpretation.js";
+export * from "./validate-application.js";
+export * from "./registry.js";
+export * from "./derive-input-fields.js";
+export * from "./derive-output-view.js";
+export * from "./capability-view-derivation.js";
+export * from "./interaction-resolution.js";
+export * from "./experience-orchestration.js";
+export * from "./presentation-context.js";
+export * from "./presentation-composition.js";
+export * from "./execution-request.js";
+export * from "./format-semantic-value.js";

package/dist/input-schema.d.ts

@@ -0,0 +1,23 @@
+import type { CapabilityInputField } from "@veil-runtime/core";
+export type RichStringFormat = "date" | "date-time" | "multiline";
+export interface RichCapabilityInputField extends CapabilityInputField {
+    type: "string" | "number" | "integer" | "boolean" | "object" | "array";
+    enum?: Array<string | number | boolean>;
+    format?: RichStringFormat;
+    semantic?: "currency";
+    currency?: string;
+    fields?: RichCapabilityInputSchema;
+    items?: RichCapabilityInputField;
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    minItems?: number;
+    maxItems?: number;
+}
+export type RichCapabilityInputSchema = Record<string, RichCapabilityInputField>;
+export declare function defineInputSchema<T extends RichCapabilityInputSchema>(schema: T): T;
+export declare function validateRichInputField(field: RichCapabilityInputField, path: string): void;
+export declare function validateRichInputSchema(schema: RichCapabilityInputSchema): void;
+export declare function validateRichInputValue(value: unknown, field: RichCapabilityInputField, path: string): void;
+export declare function validateRichCapabilityInput(schema: RichCapabilityInputSchema, input: unknown): asserts input is Record<string, unknown>;

package/dist/input-schema.js

@@ -0,0 +1,131 @@
+import { assertBoundedData, isCalendarDate, isUTCInstant } from "./validation-safety.js";
+export function defineInputSchema(schema) {
+    return schema;
+}
+function assertConstraintPair(minimum, maximum, path) {
+    if (minimum !== undefined && maximum !== undefined && minimum > maximum) {
+        throw new Error(`Invalid input schema at "${path}": minimum exceeds maximum`);
+    }
+}
+export function validateRichInputField(field, path) {
+    assertBoundedData(field);
+    const supported = ["string", "number", "integer", "boolean", "object", "array"];
+    if (!supported.includes(field.type)) {
+        throw new Error(`Unsupported input type "${field.type}" at "${path}"`);
+    }
+    if (field.enum) {
+        if (field.enum.length === 0)
+            throw new Error(`Empty enum at "${path}"`);
+        const primitive = field.type === "integer" ? "number" : field.type;
+        if (field.enum.some((value) => typeof value !== primitive)) {
+            throw new Error(`Enum value is incompatible with "${field.type}" at "${path}"`);
+        }
+    }
+    if (field.format && field.type !== "string") {
+        throw new Error(`Format requires a string field at "${path}"`);
+    }
+    if (field.semantic === "currency") {
+        if (!["number", "integer"].includes(field.type) || !field.currency) {
+            throw new Error(`Currency semantics require a numeric type and currency code at "${path}"`);
+        }
+    }
+    assertConstraintPair(field.minLength, field.maxLength, path);
+    assertConstraintPair(field.minimum, field.maximum, path);
+    assertConstraintPair(field.minItems, field.maxItems, path);
+    if (field.type === "object") {
+        if (!field.fields)
+            throw new Error(`Object field lacks nested fields at "${path}"`);
+        for (const [name, nested] of Object.entries(field.fields)) {
+            validateRichInputField(nested, `${path}.${name}`);
+        }
+    }
+    if (field.type === "array") {
+        if (!field.items)
+            throw new Error(`Array field lacks an item schema at "${path}"`);
+        validateRichInputField(field.items, `${path}[]`);
+    }
+}
+export function validateRichInputSchema(schema) {
+    assertBoundedData(schema);
+    for (const [name, field] of Object.entries(schema)) {
+        validateRichInputField(field, name);
+    }
+}
+function missing(value) {
+    return value === undefined || value === null || value === "";
+}
+export function validateRichInputValue(value, field, path) {
+    assertBoundedData(value);
+    assertBoundedData(field);
+    if (missing(value)) {
+        if (field.required)
+            throw new Error(`Required input omitted: ${path}`);
+        return;
+    }
+    if (field.enum && !field.enum.includes(value))
+        throw new Error(`Input "${path}" is not an allowed enum value`);
+    if (field.type === "string") {
+        if (typeof value !== "string")
+            throw new Error(`Input "${path}" must be a string`);
+        if (field.minLength !== undefined && value.length < field.minLength)
+            throw new Error(`Input "${path}" is shorter than minLength`);
+        if (field.maxLength !== undefined && value.length > field.maxLength)
+            throw new Error(`Input "${path}" exceeds maxLength`);
+        if (field.format === "date" && !isCalendarDate(value))
+            throw new Error(`Input "${path}" must use YYYY-MM-DD`);
+        if (field.format === "date-time" && !isUTCInstant(value))
+            throw new Error(`Input "${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(`Input "${path}" must be numeric`);
+        if (field.type === "integer" && !Number.isInteger(value))
+            throw new Error(`Input "${path}" must be an integer`);
+        if (field.minimum !== undefined && value < field.minimum)
+            throw new Error(`Input "${path}" is below minimum`);
+        if (field.maximum !== undefined && value > field.maximum)
+            throw new Error(`Input "${path}" exceeds maximum`);
+        return;
+    }
+    if (field.type === "boolean") {
+        if (typeof value !== "boolean")
+            throw new Error(`Input "${path}" must be boolean`);
+        return;
+    }
+    if (field.type === "object") {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new Error(`Input "${path}" must be an object`);
+        const record = value;
+        const fields = field.fields ?? {};
+        for (const key of Object.keys(record))
+            if (!Object.hasOwn(fields, key))
+                throw new Error(`Unexpected nested field: ${path}.${key}`);
+        for (const [key, child] of Object.entries(fields))
+            validateRichInputValue(Object.hasOwn(record, key) ? record[key] : undefined, child, `${path}.${key}`);
+        return;
+    }
+    if (field.type === "array") {
+        if (!Array.isArray(value))
+            throw new Error(`Input "${path}" must be an array`);
+        if (field.minItems !== undefined && value.length < field.minItems)
+            throw new Error(`Input "${path}" is below minItems`);
+        if (field.maxItems !== undefined && value.length > field.maxItems)
+            throw new Error(`Input "${path}" exceeds maxItems`);
+        if (!field.items)
+            throw new Error(`Input "${path}" lacks an item schema`);
+        value.forEach((item, index) => validateRichInputValue(item, field.items, `${path}[${index}]`));
+    }
+}
+export function validateRichCapabilityInput(schema, input) {
+    assertBoundedData(schema);
+    assertBoundedData(input);
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        throw new Error("Capability input must be an object");
+    const record = input;
+    for (const key of Object.keys(record))
+        if (!Object.hasOwn(schema, key))
+            throw new Error(`Unexpected supplied input: ${key}`);
+    for (const [key, field] of Object.entries(schema))
+        validateRichInputValue(Object.hasOwn(record, key) ? record[key] : undefined, field, key);
+}

package/dist/interaction-resolution.d.ts

@@ -0,0 +1,27 @@
+import type { CapabilityView, UIField } from "./capability-view.js";
+export interface AuthoritativeInputBinding {
+    sourceField: string;
+    value: unknown;
+}
+export type AuthoritativeInputBindings = Record<string, AuthoritativeInputBinding>;
+export type CapabilityInteractionMode = "form" | "action" | "confirmation" | "read";
+export interface ResolvedCapabilityInput {
+    name: string;
+    source: "human" | "binding";
+    value?: unknown;
+    sourceField?: string;
+    field: UIField;
+}
+export interface CapabilityInteractionResolution {
+    mode: CapabilityInteractionMode;
+    suppliedInputs: Record<string, unknown>;
+    boundInputNames: string[];
+    humanFields: UIField[];
+    inputs: ResolvedCapabilityInput[];
+    unresolvedRequiredInputs: string[];
+    reason: string;
+}
+export declare function serializeDateTimeLocal(value: string): string;
+export declare function validateFieldValue(value: unknown, field: UIField, path: string): void;
+export declare function resolveCapabilityInteraction(view: CapabilityView, bindings?: AuthoritativeInputBindings): CapabilityInteractionResolution;
+export declare function buildCapabilityExecutionPayload(resolution: CapabilityInteractionResolution, humanValues: Record<string, unknown>): Record<string, unknown>;

package/dist/interaction-resolution.js

@@ -0,0 +1,179 @@
+import { assertBoundedData, isCalendarDate, isUTCInstant } from "./validation-safety.js";
+function valueMatchesField(value, field) {
+    try {
+        validateFieldValue(value, field, field.name);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function serializeDateTimeLocal(value) {
+    return new Date(value).toISOString();
+}
+export function validateFieldValue(value, field, path) {
+    assertBoundedData(value);
+    assertBoundedData(field);
+    if (value === undefined || value === null || value === "") {
+        if (field.required)
+            throw new Error(`Required input omitted: ${path}`);
+        return;
+    }
+    if (field.options && !field.options.includes(value)) {
+        throw new Error(`Input "${path}" is not an allowed enum value`);
+    }
+    if (field.authoritativeType === "string") {
+        if (typeof value !== "string")
+            throw new Error(`Input "${path}" must be a string`);
+        if (field.minLength !== undefined && value.length < field.minLength)
+            throw new Error(`Input "${path}" is shorter than minLength`);
+        if (field.maxLength !== undefined && value.length > field.maxLength)
+            throw new Error(`Input "${path}" exceeds maxLength`);
+        if (field.format === "date" && !isCalendarDate(value))
+            throw new Error(`Input "${path}" must use YYYY-MM-DD`);
+        if (field.format === "date-time" && !isUTCInstant(value)) {
+            throw new Error(`Input "${path}" must be an ISO-8601 UTC instant`);
+        }
+        return;
+    }
+    if (field.authoritativeType === "number" || field.authoritativeType === "integer") {
+        if (typeof value !== "number" || !Number.isFinite(value))
+            throw new Error(`Input "${path}" must be numeric`);
+        if (field.authoritativeType === "integer" && !Number.isInteger(value))
+            throw new Error(`Input "${path}" must be an integer`);
+        if (field.minimum !== undefined && value < field.minimum)
+            throw new Error(`Input "${path}" is below minimum`);
+        if (field.maximum !== undefined && value > field.maximum)
+            throw new Error(`Input "${path}" exceeds maximum`);
+        return;
+    }
+    if (field.authoritativeType === "boolean") {
+        if (typeof value !== "boolean")
+            throw new Error(`Input "${path}" must be boolean`);
+        return;
+    }
+    if (field.authoritativeType === "object") {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new Error(`Input "${path}" must be an object`);
+        const record = value;
+        const children = field.fields ?? [];
+        const names = new Set(children.map((child) => child.name));
+        for (const key of Object.keys(record))
+            if (!names.has(key))
+                throw new Error(`Unexpected nested field: ${path}.${key}`);
+        for (const child of children)
+            validateFieldValue(Object.hasOwn(record, child.name) ? record[child.name] : undefined, child, `${path}.${child.name}`);
+        return;
+    }
+    if (field.authoritativeType === "array") {
+        if (!Array.isArray(value))
+            throw new Error(`Input "${path}" must be an array`);
+        if (field.minItems !== undefined && value.length < field.minItems)
+            throw new Error(`Input "${path}" is below minItems`);
+        if (field.maxItems !== undefined && value.length > field.maxItems)
+            throw new Error(`Input "${path}" exceeds maxItems`);
+        if (!field.item)
+            throw new Error(`Input "${path}" lacks an item schema`);
+        value.forEach((item, index) => validateFieldValue(item, field.item, `${path}[${index}]`));
+    }
+}
+export function resolveCapabilityInteraction(view, bindings = {}) {
+    assertBoundedData(view);
+    assertBoundedData(bindings);
+    const fieldsByName = new Map(view.fields.map((field) => [field.name, field]));
+    const suppliedInputs = {};
+    const boundInputNames = Object.keys(bindings);
+    const inputs = [];
+    for (const [name, binding] of Object.entries(bindings)) {
+        const field = fieldsByName.get(name);
+        if (!field) {
+            throw new Error(`Authoritative binding references unknown input: ${name}`);
+        }
+        if (binding.value === undefined || binding.value === null || binding.value === "") {
+            if (field.required) {
+                throw new Error(`Required bound input "${name}" has no runtime value`);
+            }
+            inputs.push({
+                name, source: "binding", value: binding.value,
+                sourceField: binding.sourceField, field,
+            });
+            continue;
+        }
+        if (!valueMatchesField(binding.value, field)) {
+            throw new Error(`Bound input "${name}" does not match declared type "${field.type}"`);
+        }
+        suppliedInputs[name] = binding.value;
+        inputs.push({
+            name,
+            source: "binding",
+            value: binding.value,
+            sourceField: binding.sourceField,
+            field,
+        });
+    }
+    const boundNames = new Set(boundInputNames);
+    const humanFields = view.fields.filter((field) => !boundNames.has(field.name));
+    for (const field of humanFields) {
+        inputs.push({ name: field.name, source: "human", field });
+    }
+    const unresolvedRequiredInputs = humanFields
+        .filter((field) => field.required)
+        .map((field) => field.name);
+    const mode = humanFields.length > 0
+        ? "form"
+        : view.risk === "destructive"
+            ? "confirmation"
+            : view.risk === "read"
+                ? "read"
+                : "action";
+    if (mode === "confirmation" && !view.confirmation?.required) {
+        throw new Error("Destructive zero-input interaction is missing confirmation metadata");
+    }
+    const reason = humanFields.length > 0
+        ? `${humanFields.length} input${humanFields.length === 1 ? "" : "s"} remain for the human`
+        : mode === "confirmation"
+            ? 'all inputs are supplied and authoritative risk is "destructive"'
+            : mode === "read"
+                ? "all inputs are supplied and the capability is read-only"
+                : "all inputs are supplied and the capability is a write";
+    return {
+        mode,
+        suppliedInputs,
+        boundInputNames,
+        humanFields,
+        inputs,
+        unresolvedRequiredInputs,
+        reason,
+    };
+}
+export function buildCapabilityExecutionPayload(resolution, humanValues) {
+    assertBoundedData(resolution);
+    assertBoundedData(humanValues);
+    const humanNames = new Set(resolution.humanFields.map((field) => field.name));
+    const boundNames = new Set(resolution.boundInputNames);
+    for (const name of Object.keys(humanValues)) {
+        if (boundNames.has(name)) {
+            throw new Error(`Human input cannot overwrite authoritative bound input: ${name}`);
+        }
+        if (!humanNames.has(name)) {
+            throw new Error(`Unexpected supplied input: ${name}`);
+        }
+    }
+    const payload = {};
+    for (const field of resolution.humanFields) {
+        const value = Object.hasOwn(humanValues, field.name) ? humanValues[field.name] : undefined;
+        if (field.required && (value === undefined || value === null || value === "")) {
+            throw new Error(`Required human input omitted: ${field.name}`);
+        }
+        if (value !== undefined && value !== "") {
+            validateFieldValue(value, field, field.name);
+            payload[field.name] = value;
+        }
+    }
+    for (const name of resolution.unresolvedRequiredInputs) {
+        if (!Object.prototype.hasOwnProperty.call(payload, name)) {
+            throw new Error(`Resolved execution payload is missing required input: ${name}`);
+        }
+    }
+    return payload;
+}

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();