@veil-runtime/ui 0.0.0-stage → 0.3.0

package/dist/presentation-composition.js

@@ -0,0 +1,25 @@
+import { assertBoundedData, copyData } from "./validation-safety.js";
+import { z } from "zod";
+const emphasisSchema = z.enum(["normal", "prominent", "subtle"]);
+const densitySchema = z.enum(["comfortable", "compact"]);
+const groupSchema = z.object({ id: z.string().regex(/^[a-zA-Z0-9_-]+$/).max(48), title: z.string().min(1).max(80).optional(), description: z.string().min(1).max(240).optional(), emphasis: emphasisSchema, density: densitySchema, sections: z.array(z.string().min(1).max(120)).min(1).max(256) }).strict();
+export const presentationPlanSchema = z.object({ title: z.string().min(1).max(100).optional(), description: z.string().min(1).max(240).optional(), groups: z.array(groupSchema).max(12) }).strict();
+export function sectionId(kind, capability) { return kind + ":" + capability; }
+export function buildPresentationEnvelope(primary, related) { return { applicationSurface: primary.capability, sections: [{ id: sectionId("primary", primary.capability), capability: primary.capability, surface: primary.view.surface, label: primary.view.title, required: true, movable: false, groupable: false, defaultOrder: 0 }, ...related.map((section, index) => ({ id: sectionId("related", section.capability), capability: section.capability, surface: section.view?.surface ?? "error", label: section.label, required: true, movable: true, groupable: true, defaultOrder: index + 1 }))], immutable: ["capabilities", "fields", "metrics", "bindings", "workflow", "risk", "actions", "surface semantics", "execution"] }; }
+export function deterministicPresentation(envelope) { return { groups: envelope.sections.filter((section) => section.movable).map((section, index) => ({ id: "section_" + (index + 1), title: section.label, emphasis: "normal", density: "comfortable", sections: [section.id] })) }; }
+export function validatePresentationPlan(envelope, value) { assertBoundedData(envelope); assertBoundedData(value); const parsed = presentationPlanSchema.safeParse(value); if (!parsed.success)
+    throw new Error("Invalid generated composition: " + parsed.error.message); const allowed = envelope.sections.filter((section) => section.movable).map((section) => section.id), received = parsed.data.groups.flatMap((group) => group.sections); if (new Set(received).size !== received.length)
+    throw new Error("Generated composition duplicated a section"); if (received.some((id) => !allowed.includes(id)))
+    throw new Error("Generated composition referenced an unknown or fixed section"); if (allowed.length !== received.length || allowed.some((id) => !received.includes(id)))
+    throw new Error("Generated composition omitted a required section"); const groupIds = parsed.data.groups.map((group) => group.id); if (new Set(groupIds).size !== groupIds.length)
+    throw new Error("Generated composition duplicated a group id"); return parsed.data; }
+export async function composePresentation(envelope, strategy, generate) { const baseline = deterministicPresentation(envelope); if (strategy === "deterministic")
+    return { plan: baseline, provenance: { strategy: "deterministic", requestedStrategy: "deterministic", fallback: false, validated: true } }; try {
+    if (!generate)
+        throw new Error("No presentation provider configured");
+    const proposed = await generate(copyData(envelope));
+    return { plan: validatePresentationPlan(envelope, proposed), provenance: { strategy: "generative", requestedStrategy: "generative", fallback: false, validated: true } };
+}
+catch (error) {
+    return { plan: baseline, provenance: { strategy: "deterministic", requestedStrategy: "generative", fallback: true, validated: true, reason: error instanceof Error ? error.message : "generation-failed" } };
+} }

package/dist/presentation-context.d.ts

@@ -0,0 +1,6 @@
+export type DeviceContext = "desktop" | "mobile";
+export type InteractionMode = "full" | "compact";
+export interface ViewContext {
+    device: DeviceContext;
+    mode: InteractionMode;
+}

package/dist/presentation-context.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,15 @@
+import { z } from "zod";
+export declare const generatedFieldPresentationSchema: z.ZodObject<{
+    name: z.ZodString;
+    label: z.ZodString;
+}, z.core.$strict>;
+export declare const generatedPresentationSchema: z.ZodObject<{
+    title: z.ZodString;
+    submitLabel: z.ZodString;
+    fields: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type GeneratedPresentation = z.infer<typeof generatedPresentationSchema>;
+export type GeneratedFieldPresentation = z.infer<typeof generatedFieldPresentationSchema>;

package/dist/presentation-suggestion-schema.js

@@ -0,0 +1,10 @@
+import { z } from "zod";
+export const generatedFieldPresentationSchema = z.object({
+    name: z.string().min(1).max(160),
+    label: z.string().min(1).max(160),
+}).strict();
+export const generatedPresentationSchema = z.object({
+    title: z.string().min(1).max(160),
+    submitLabel: z.string().min(1).max(160),
+    fields: z.array(generatedFieldPresentationSchema).max(256),
+}).strict();

package/dist/registry.d.ts

@@ -0,0 +1,21 @@
+import type { Capability } from "@veil-runtime/core";
+import type { ApplicationManifest, CapabilityRelationship, CapabilityTransition, DerivedApplication } from "./application.js";
+import { type CapabilityOutputSchema } from "./output-schema.js";
+import { type ApplicationValidationResult } from "./validate-application.js";
+export interface UIRegistryDefinitions {
+    capabilities: readonly Capability[];
+    applications: readonly ApplicationManifest[];
+    outputSchemas?: Readonly<Record<string, CapabilityOutputSchema>>;
+    relationships?: readonly CapabilityRelationship[];
+    transitions?: readonly CapabilityTransition[];
+}
+export interface UIRegistry {
+    listApplications(): ApplicationManifest[];
+    getApplication(applicationId: string): ApplicationManifest | undefined;
+    getOutputSchema(capabilityName: string): CapabilityOutputSchema | undefined;
+    getRelationships(capabilityName: string): CapabilityRelationship[];
+    getTransition(capabilityName: string): CapabilityTransition | undefined;
+    deriveApplication(applicationId: string): DerivedApplication | undefined;
+    validateApplication(application: DerivedApplication): ApplicationValidationResult;
+}
+export declare function createUIRegistry(definitions: UIRegistryDefinitions): UIRegistry;

package/dist/registry.js

@@ -0,0 +1,71 @@
+import { copyData } from "./validation-safety.js";
+import { validateRichInputSchema, } from "./input-schema.js";
+import { validateOutputSchema, } from "./output-schema.js";
+import { validateApplication, } from "./validate-application.js";
+export function createUIRegistry(definitions) {
+    // Snapshot caller metadata; executable functions stay host-owned and are never exposed.
+    definitions = {
+        capabilities: definitions.capabilities.map((capability) => ({
+            ...capability,
+            ...(capability.inputSchema ? { inputSchema: copyData(capability.inputSchema) } : {}),
+        })),
+        applications: copyData(definitions.applications),
+        ...(definitions.outputSchemas ? { outputSchemas: copyData(definitions.outputSchemas) } : {}),
+        ...(definitions.relationships ? { relationships: copyData(definitions.relationships) } : {}),
+        ...(definitions.transitions ? { transitions: copyData(definitions.transitions) } : {}),
+    };
+    const capabilities = new Map(definitions.capabilities.map((capability) => [capability.name, capability]));
+    const applications = new Map(definitions.applications.map((application) => [application.id, application]));
+    const outputSchemas = definitions.outputSchemas ?? {};
+    const relationships = definitions.relationships ?? [];
+    const transitions = definitions.transitions ?? [];
+    const getCapability = (name) => capabilities.get(name);
+    function deriveApplication(applicationId) {
+        const application = applications.get(applicationId);
+        if (!application)
+            return undefined;
+        const derivedCapabilities = application.capabilities.map((capabilityName) => {
+            const capability = getCapability(capabilityName);
+            if (!capability) {
+                throw new Error("Application \"" + applicationId + "\" references unknown capability: " + capabilityName);
+            }
+            const inputSchema = (capability.inputSchema ?? {});
+            validateRichInputSchema(inputSchema);
+            const outputSchema = Object.hasOwn(outputSchemas, capability.name)
+                ? outputSchemas[capability.name]
+                : undefined;
+            if (outputSchema)
+                validateOutputSchema(outputSchema);
+            const transition = transitions.find((candidate) => candidate.capability === capability.name);
+            return {
+                name: capability.name,
+                version: capability.version,
+                description: capability.description,
+                risk: capability.risk,
+                inputSchema,
+                ...(outputSchema ? { outputSchema } : {}),
+                relationships: relationships.filter((relationship) => relationship.sourceCapability === capability.name),
+                ...(transition ? { transition } : {}),
+            };
+        });
+        return copyData({
+            id: application.id,
+            title: application.title,
+            ...(application.description
+                ? { description: application.description }
+                : {}),
+            entryCapability: application.entryCapability,
+            capabilities: derivedCapabilities,
+            ...(application.workflow ? { workflow: application.workflow } : {}),
+        });
+    }
+    return {
+        listApplications: () => copyData([...applications.values()]),
+        getApplication: (applicationId) => copyData(applications.get(applicationId)),
+        getOutputSchema: (capabilityName) => copyData(Object.hasOwn(outputSchemas, capabilityName) ? outputSchemas[capabilityName] : undefined),
+        getRelationships: (capabilityName) => copyData(relationships.filter((relationship) => relationship.sourceCapability === capabilityName)),
+        getTransition: (capabilityName) => copyData(transitions.find((transition) => transition.capability === capabilityName)),
+        deriveApplication,
+        validateApplication: (application) => validateApplication(application, getCapability),
+    };
+}

package/dist/relationship-interpretation.d.ts

@@ -0,0 +1,9 @@
+export type RelationshipRole = "action" | "navigate" | "related";
+export type RelationshipInteraction = "application-action" | "contextual-action" | "row-action" | "navigation" | "related-read";
+export interface InterpretableRelationship {
+    role?: RelationshipRole;
+    bindings: Record<string, string>;
+    conditions?: readonly unknown[];
+}
+export declare function interpretRelationship(relationship: InterpretableRelationship, source: "application-entry" | "table-row" | "detail"): RelationshipInteraction;
+export declare function isExplicitAction(interaction: RelationshipInteraction): boolean;

package/dist/relationship-interpretation.js

@@ -0,0 +1,16 @@
+export function interpretRelationship(relationship, source) {
+    if (relationship.role === "related")
+        return "related-read";
+    if (relationship.role === "navigate")
+        return "navigation";
+    const contextual = Object.keys(relationship.bindings).length > 0
+        || (relationship.conditions?.length ?? 0) > 0;
+    if (source === "table-row" && contextual)
+        return "row-action";
+    if (contextual)
+        return "contextual-action";
+    return "application-action";
+}
+export function isExplicitAction(interaction) {
+    return interaction !== "related-read";
+}

package/dist/validate-application.d.ts

@@ -0,0 +1,24 @@
+import type { Capability } from "@veil-runtime/core";
+import type { DerivedApplication } from "./application.js";
+export type ApplicationValidationSeverity = "error" | "warning";
+export type ApplicationValidationIssueCode = "ENTRY_CAPABILITY_NOT_FOUND" | "DUPLICATE_CAPABILITY" | "RELATIONSHIP_TARGET_NOT_FOUND" | "TRANSITION_TARGET_NOT_FOUND" | "RELATIONSHIP_SOURCE_FIELD_NOT_FOUND" | "RELATIONSHIP_TARGET_FIELD_NOT_FOUND" | "RELATIONSHIP_REQUIRED_INPUT_UNBOUND" | "CAPABILITY_RISK_MISMATCH" | "WORKFLOW_STATE_FIELD_NOT_FOUND" | "WORKFLOW_ENTRY_STATE_NOT_FOUND" | "DUPLICATE_WORKFLOW_STATE" | "WORKFLOW_STATE_NOT_FOUND" | "WORKFLOW_CAPABILITY_NOT_FOUND" | "CONDITION_FIELD_NOT_FOUND" | "RESULT_BINDING_SOURCE_FIELD_NOT_FOUND" | "RESULT_BINDING_TARGET_FIELD_NOT_FOUND" | "RESULT_BINDING_REQUIRED_INPUT_UNBOUND" | "RELATED_TARGET_NOT_READ" | "RELATED_SELF_REFERENCE" | "RELATED_DIRECT_CYCLE" | "DUPLICATE_RELATED_CAPABILITY" | "RELATED_BINDING_TYPE_MISMATCH" | "RELATED_REQUIRED_INPUT_UNBOUND" | "INVALID_RELATIONSHIP_ROLE" | "UNSUPPORTED_NESTED_RELATED_COMPOSITION";
+export interface ApplicationValidationIssue {
+    code: ApplicationValidationIssueCode;
+    severity: ApplicationValidationSeverity;
+    message: string;
+    applicationId: string;
+    capability?: string;
+    targetCapability?: string;
+    field?: string;
+}
+export interface ApplicationValidationResult {
+    valid: boolean;
+    issues: ApplicationValidationIssue[];
+}
+export interface AuthoritativeCapabilityMetadata {
+    name: Capability["name"];
+    risk: Capability["risk"];
+    inputSchema?: Capability["inputSchema"];
+}
+export type CapabilityMetadataResolver = (capabilityName: string) => AuthoritativeCapabilityMetadata | undefined;
+export declare function validateApplication(application: DerivedApplication, resolveCapability: CapabilityMetadataResolver): ApplicationValidationResult;

package/dist/validate-application.js

@@ -0,0 +1,253 @@
+import { assertBoundedData } from "./validation-safety.js";
+import { getOutputSchemaFields } from "./output-schema.js";
+function hasTopLevelOutputField(schema, fieldName) {
+    return Boolean(schema && Object.hasOwn(getOutputSchemaFields(schema), fieldName));
+}
+function getRelationshipSourceField(schema, fieldName) {
+    if (!schema)
+        return undefined;
+    const fields = getOutputSchemaFields(schema);
+    const definitions = Object.values(fields);
+    if (definitions.length === 1 && definitions[0]?.type === "array" && definitions[0].items?.type === "object")
+        return definitions[0].items.fields?.[fieldName];
+    return fields[fieldName];
+}
+function hasRelationshipSourceField(schema, fieldName) {
+    if (!schema) {
+        return false;
+    }
+    const definitions = Object.values(schema);
+    if (definitions.length === 1) {
+        const definition = definitions[0];
+        if (definition.type === "array" && definition.items?.type === "object") {
+            return Boolean(definition.items.fields && Object.hasOwn(definition.items.fields, fieldName));
+        }
+    }
+    return hasTopLevelOutputField(schema, fieldName);
+}
+function validateCapabilityRisk(application, capability, resolveCapability, issues) {
+    const authoritative = resolveCapability(capability.name);
+    if (authoritative &&
+        authoritative.risk !== capability.risk) {
+        issues.push({
+            code: "CAPABILITY_RISK_MISMATCH",
+            severity: "error",
+            message: `Capability "${capability.name}" has derived risk "${capability.risk}" but authoritative risk "${authoritative.risk}".`,
+            applicationId: application.id,
+            capability: capability.name,
+        });
+    }
+}
+function validateRelationship(application, source, capabilityNames, resolveCapability, issues) {
+    for (const relationship of source.relationships) {
+        const targetName = relationship.targetCapability;
+        if (!capabilityNames.has(targetName)) {
+            issues.push({
+                code: "RELATIONSHIP_TARGET_NOT_FOUND",
+                severity: "error",
+                message: `Relationship from "${source.name}" targets capability "${targetName}", which is not in application "${application.id}".`,
+                applicationId: application.id,
+                capability: source.name,
+                targetCapability: targetName,
+            });
+        }
+        const targetCapability = resolveCapability(targetName);
+        for (const [targetField, sourceField] of Object.entries(relationship.bindings)) {
+            if (!hasRelationshipSourceField(source.outputSchema, sourceField)) {
+                issues.push({
+                    code: "RELATIONSHIP_SOURCE_FIELD_NOT_FOUND",
+                    severity: "error",
+                    message: `Relationship from "${source.name}" binds unknown source output field "${sourceField}".`,
+                    applicationId: application.id,
+                    capability: source.name,
+                    targetCapability: targetName,
+                    field: sourceField,
+                });
+            }
+            if (targetCapability &&
+                !Object.hasOwn(targetCapability.inputSchema ?? {}, targetField)) {
+                issues.push({
+                    code: "RELATIONSHIP_TARGET_FIELD_NOT_FOUND",
+                    severity: "error",
+                    message: `Relationship to "${targetName}" binds unknown target input field "${targetField}".`,
+                    applicationId: application.id,
+                    capability: source.name,
+                    targetCapability: targetName,
+                    field: targetField,
+                });
+            }
+        }
+        for (const condition of relationship.conditions ?? []) {
+            if (!hasRelationshipSourceField(source.outputSchema, condition.field)) {
+                issues.push({
+                    code: "CONDITION_FIELD_NOT_FOUND",
+                    severity: "error",
+                    message: `Relationship from "${source.name}" conditions on unknown output field "${condition.field}".`,
+                    applicationId: application.id,
+                    capability: source.name,
+                    targetCapability: targetName,
+                    field: condition.field,
+                });
+            }
+        }
+        if (targetCapability) {
+            for (const [fieldName, field] of Object.entries(targetCapability.inputSchema ?? {})) {
+                if (field.required &&
+                    !Object.prototype.hasOwnProperty.call(relationship.bindings, fieldName)) {
+                    issues.push({
+                        code: "RELATIONSHIP_REQUIRED_INPUT_UNBOUND",
+                        severity: "warning",
+                        message: `Relationship from "${source.name}" does not bind required input "${fieldName}" on "${targetName}".`,
+                        applicationId: application.id,
+                        capability: source.name,
+                        targetCapability: targetName,
+                        field: fieldName,
+                    });
+                }
+            }
+        }
+        /*
+         * Duplicate target binding keys cannot be represented by the
+         * authoritative Record<string, string> binding type.
+         */
+    }
+}
+export function validateApplication(application, resolveCapability) {
+    assertBoundedData(application);
+    const issues = [];
+    const capabilityNames = new Set();
+    const duplicateNames = new Set();
+    for (const capability of application.capabilities) {
+        if (capabilityNames.has(capability.name) &&
+            !duplicateNames.has(capability.name)) {
+            duplicateNames.add(capability.name);
+            issues.push({
+                code: "DUPLICATE_CAPABILITY",
+                severity: "error",
+                message: `Application "${application.id}" contains capability "${capability.name}" more than once.`,
+                applicationId: application.id,
+                capability: capability.name,
+            });
+        }
+        capabilityNames.add(capability.name);
+    }
+    if (!capabilityNames.has(application.entryCapability)) {
+        issues.push({
+            code: "ENTRY_CAPABILITY_NOT_FOUND",
+            severity: "error",
+            message: `Entry capability "${application.entryCapability}" is not in application "${application.id}".`,
+            applicationId: application.id,
+            capability: application.entryCapability,
+        });
+    }
+    for (const capability of application.capabilities) {
+        for (const relationship of capability.relationships)
+            if (relationship.role !== undefined && !["action", "navigate", "related"].includes(relationship.role))
+                issues.push({ code: "INVALID_RELATIONSHIP_ROLE", severity: "error", message: "Invalid relationship role.", applicationId: application.id, capability: capability.name, targetCapability: relationship.targetCapability });
+        const related = capability.relationships.filter((relationship) => relationship.role === "related");
+        const seenRelated = new Set();
+        for (const relationship of related) {
+            const target = application.capabilities.find((candidate) => candidate.name === relationship.targetCapability);
+            if (seenRelated.has(relationship.targetCapability))
+                issues.push({ code: "DUPLICATE_RELATED_CAPABILITY", severity: "error", message: "Related capability is declared more than once: " + relationship.targetCapability, applicationId: application.id, capability: capability.name, targetCapability: relationship.targetCapability });
+            seenRelated.add(relationship.targetCapability);
+            if (relationship.targetCapability === capability.name)
+                issues.push({ code: "RELATED_SELF_REFERENCE", severity: "error", message: "A capability cannot compose itself automatically.", applicationId: application.id, capability: capability.name, targetCapability: relationship.targetCapability });
+            if (target?.risk !== "read")
+                issues.push({ code: "RELATED_TARGET_NOT_READ", severity: "error", message: "Automatic related capability must be read-only: " + relationship.targetCapability, applicationId: application.id, capability: capability.name, targetCapability: relationship.targetCapability });
+            if (target?.relationships.some((candidate) => candidate.role === "related"))
+                issues.push({ code: "UNSUPPORTED_NESTED_RELATED_COMPOSITION", severity: "error", message: "Nested automatic related composition is not supported.", applicationId: application.id, capability: capability.name, targetCapability: relationship.targetCapability });
+            if (target?.relationships.some((candidate) => candidate.role === "related" && candidate.targetCapability === capability.name))
+                issues.push({ code: "RELATED_DIRECT_CYCLE", severity: "error", message: "Direct automatic-related cycle detected.", applicationId: application.id, capability: capability.name, targetCapability: relationship.targetCapability });
+            for (const [targetField, sourceField] of Object.entries(relationship.bindings)) {
+                const sourceDefinition = getRelationshipSourceField(capability.outputSchema, sourceField);
+                const targetDefinition = target?.inputSchema[targetField];
+                if (sourceDefinition && targetDefinition && sourceDefinition.type !== targetDefinition.type)
+                    issues.push({ code: "RELATED_BINDING_TYPE_MISMATCH", severity: "error", message: "Related binding type mismatch for " + targetField, applicationId: application.id, capability: capability.name, targetCapability: relationship.targetCapability, field: targetField });
+            }
+            for (const [field, definition] of Object.entries(target?.inputSchema ?? {}))
+                if (definition.required && !Object.prototype.hasOwnProperty.call(relationship.bindings, field))
+                    issues.push({ code: "RELATED_REQUIRED_INPUT_UNBOUND", severity: "error", message: "Automatic related capability is missing required binding: " + field, applicationId: application.id, capability: capability.name, targetCapability: relationship.targetCapability, field });
+        }
+        validateCapabilityRisk(application, capability, resolveCapability, issues);
+        validateRelationship(application, capability, capabilityNames, resolveCapability, issues);
+        const transitionTarget = capability.transition?.onSuccess?.capability;
+        if (transitionTarget &&
+            !capabilityNames.has(transitionTarget)) {
+            issues.push({
+                code: "TRANSITION_TARGET_NOT_FOUND",
+                severity: "error",
+                message: `Transition from "${capability.name}" targets capability "${transitionTarget}", which is not in application "${application.id}".`,
+                applicationId: application.id,
+                capability: capability.name,
+                targetCapability: transitionTarget,
+            });
+        }
+        const resultBindings = capability.transition?.onSuccess?.resultBindings ?? {};
+        const targetCapability = transitionTarget ? resolveCapability(transitionTarget) : undefined;
+        for (const [targetField, sourceField] of Object.entries(resultBindings)) {
+            if (!hasTopLevelOutputField(capability.outputSchema, sourceField)) {
+                issues.push({
+                    code: "RESULT_BINDING_SOURCE_FIELD_NOT_FOUND", severity: "error",
+                    message: `Transition from "${capability.name}" binds unknown result field "${sourceField}".`,
+                    applicationId: application.id, capability: capability.name, ...(transitionTarget ? { targetCapability: transitionTarget } : {}), field: sourceField,
+                });
+            }
+            if (targetCapability && !Object.hasOwn(targetCapability.inputSchema ?? {}, targetField)) {
+                issues.push({
+                    code: "RESULT_BINDING_TARGET_FIELD_NOT_FOUND", severity: "error",
+                    message: `Transition to "${transitionTarget}" binds unknown input "${targetField}".`,
+                    applicationId: application.id, capability: capability.name, ...(transitionTarget ? { targetCapability: transitionTarget } : {}), field: targetField,
+                });
+            }
+        }
+        if (targetCapability && capability.transition?.onSuccess) {
+            for (const [field, definition] of Object.entries(targetCapability.inputSchema ?? {})) {
+                if (definition.required && !Object.prototype.hasOwnProperty.call(resultBindings, field)) {
+                    issues.push({
+                        code: "RESULT_BINDING_REQUIRED_INPUT_UNBOUND", severity: "error",
+                        message: `Transition from "${capability.name}" cannot supply required input "${field}" on "${transitionTarget}".`,
+                        applicationId: application.id, capability: capability.name, ...(transitionTarget ? { targetCapability: transitionTarget } : {}), field,
+                    });
+                }
+            }
+        }
+        /*
+         * CapabilityTransition contains navigation metadata only.
+         * Its type has no risk field, so it cannot override risk.
+         */
+    }
+    const workflow = application.workflow;
+    if (workflow) {
+        const stateFields = application.capabilities
+            .map((capability) => getRelationshipSourceField(capability.outputSchema, workflow.stateField))
+            .filter((field) => Boolean(field));
+        if (stateFields.length === 0) {
+            issues.push({
+                code: "WORKFLOW_STATE_FIELD_NOT_FOUND",
+                severity: "error",
+                message: `Workflow state field "${workflow.stateField}" is absent from authoritative output metadata.`,
+                applicationId: application.id,
+                field: workflow.stateField,
+            });
+        }
+        const states = new Set();
+        for (const state of workflow.states) {
+            if (states.has(state.id))
+                issues.push({ code: "DUPLICATE_WORKFLOW_STATE", severity: "error", message: `Workflow state "${state.id}" is duplicated.`, applicationId: application.id });
+            states.add(state.id);
+        }
+        if (!states.has(workflow.entryState))
+            issues.push({ code: "WORKFLOW_ENTRY_STATE_NOT_FOUND", severity: "error", message: `Workflow entry state "${workflow.entryState}" is not declared.`, applicationId: application.id });
+        for (const transition of workflow.transitions) {
+            if (!states.has(transition.from) || !states.has(transition.to))
+                issues.push({ code: "WORKFLOW_STATE_NOT_FOUND", severity: "error", message: `Workflow transition "${transition.capability}" references an unknown state.`, applicationId: application.id, capability: transition.capability });
+            if (!capabilityNames.has(transition.capability))
+                issues.push({ code: "WORKFLOW_CAPABILITY_NOT_FOUND", severity: "error", message: `Workflow transition references capability "${transition.capability}" outside the application.`, applicationId: application.id, capability: transition.capability });
+        }
+    }
+    return {
+        valid: !issues.some((issue) => issue.severity === "error"),
+        issues,
+    };
+}

package/dist/validation-safety.d.ts

@@ -0,0 +1,6 @@
+export declare function assertSafeKey(key: string): void;
+/** Inspect descriptors, never getters; bound work before recursive or Zod validation. */
+export declare function assertBoundedData(value: unknown): void;
+export declare function copyData<T>(value: T): T;
+export declare function isCalendarDate(value: string): boolean;
+export declare function isUTCInstant(value: string): boolean;

package/dist/validation-safety.js

@@ -0,0 +1,90 @@
+/** Internal transport limits. Hosts must also limit bytes before decoding JSON. */
+const limits = { depth: 32, nodes: 10000, keys: 256, items: 1000, string: 65536, bytes: 1048576 };
+const reserved = new Set(["__proto__", "prototype", "constructor"]);
+export function assertSafeKey(key) {
+    if (reserved.has(key))
+        throw new Error(`Reserved data key: ${key}`);
+}
+/** Inspect descriptors, never getters; bound work before recursive or Zod validation. */
+export function assertBoundedData(value) {
+    const ancestors = new Set();
+    let nodes = 0;
+    let bytes = 0;
+    function visit(item, depth) {
+        if (++nodes > limits.nodes || depth > limits.depth)
+            throw new Error("Data traversal limit exceeded");
+        bytes += 8;
+        if (typeof item === "number" && !Number.isFinite(item))
+            throw new Error("Data value must be numeric and finite");
+        if (typeof item === "string") {
+            if (item.length > limits.string)
+                throw new Error("Data string limit exceeded");
+            bytes += item.length * 3; // Conservative UTF-8 upper bound for UTF-16 input.
+        }
+        else if (item !== null && typeof item === "object") {
+            if (ancestors.has(item))
+                throw new Error("Cyclic data is not supported");
+            const array = Array.isArray(item);
+            const proto = Object.getPrototypeOf(item);
+            if (!array && proto !== Object.prototype && proto !== null)
+                throw new Error("Data must use plain own properties");
+            if (array && item.length > limits.items)
+                throw new Error("Data collection limit exceeded");
+            const keys = Reflect.ownKeys(item);
+            if (keys.length > (array ? limits.items + 1 : limits.keys))
+                throw new Error("Data property limit exceeded");
+            if (array && keys.length !== item.length + 1)
+                throw new Error("Data arrays must be dense without extra properties");
+            ancestors.add(item);
+            for (const key of keys) {
+                if (array && key === "length")
+                    continue;
+                if (typeof key !== "string")
+                    throw new Error("Symbol data keys are not supported");
+                if (array && (!/^(0|[1-9]\d*)$/.test(key) || Number(key) >= item.length))
+                    throw new Error("Data arrays cannot contain extra properties");
+                if (key.length > limits.string)
+                    throw new Error("Data key limit exceeded");
+                assertSafeKey(key);
+                const descriptor = Object.getOwnPropertyDescriptor(item, key);
+                if (!descriptor.enumerable || !("value" in descriptor))
+                    throw new Error("Non-enumerable or accessor data is not supported");
+                bytes += key.length * 3;
+                visit(descriptor.value, depth + 1);
+            }
+            ancestors.delete(item);
+        }
+        else if (!["undefined", "boolean", "number"].includes(typeof item) && item !== null) {
+            throw new Error("Unsupported data value");
+        }
+        if (bytes > limits.bytes)
+            throw new Error("Data byte limit exceeded");
+    }
+    visit(value, 0);
+}
+export function copyData(value) {
+    assertBoundedData(value);
+    function copy(item) {
+        if (Array.isArray(item))
+            return item.map(copy);
+        if (item !== null && typeof item === "object") {
+            return Object.fromEntries(Object.entries(item).map(([key, child]) => [key, copy(child)]));
+        }
+        return item;
+    }
+    return copy(value);
+}
+export function isCalendarDate(value) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return false;
+    const date = new Date(`${value}T00:00:00.000Z`);
+    return Number.isFinite(date.getTime()) && date.toISOString().slice(0, 10) === value;
+}
+export function isUTCInstant(value) {
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(value))
+        return false;
+    if (!isCalendarDate(value.slice(0, 10)))
+        return false;
+    const date = new Date(value);
+    return Number.isFinite(date.getTime()) && date.toISOString() === (value.length === 20 ? value.replace("Z", ".000Z") : value);
+}

package/dist/workflow.d.ts

@@ -0,0 +1,18 @@
+/** Declarative application metadata. This module does not execute workflows. */
+export interface ApplicationWorkflowState {
+    id: string;
+    label: string;
+    terminal?: boolean;
+}
+export interface ApplicationWorkflowTransition {
+    capability: string;
+    from: string;
+    to: string;
+}
+export interface ApplicationWorkflowDefinition {
+    stateField: string;
+    entryState: string;
+    states: ApplicationWorkflowState[];
+    transitions: ApplicationWorkflowTransition[];
+}
+export declare function defineWorkflow<T extends ApplicationWorkflowDefinition>(workflow: T): T;

package/dist/workflow.js

@@ -0,0 +1,3 @@
+export function defineWorkflow(workflow) {
+    return workflow;
+}

package/docs/API.md

@@ -0,0 +1,19 @@
+# Public API inventory
+
+The v0.3.0-rc.2 candidate adds `@veil-runtime/ui/interface` (`defineInterface`, `validateInterfaceDefinition`, `createInterfaceController`, `getInterfaceCapabilities`, `resolveInterfaceBinding`, and types including `BuiltinInterfaceDefinition`) and `mountInterface`, `createMountedInterface`, plus `InterfaceDOMComponentInstance` in `/dom`. `InterfaceDOMComponent` may still return an `HTMLElement`; it may now return `{ element, update?, dispose? }`. Updates prepare detached custom instances before controller acceptance. See [UNIVERSAL-INTERFACE.md](UNIVERSAL-INTERFACE.md). The v0.2.0 composition API remains available through `/composition` and `/dom`. The inventory below describes preserved v0.1.0 APIs.
+
+The preview keeps all existing root exports; no existing symbol or subpath was removed. The root index exports modules below. All interfaces/types exported by those modules remain available in the declarations. Package consumers import through the root or documented `/inspection`, `/composition`, `/interface`, and `/dom` subpaths, not paths inside dist.
+
+| Area | Root modules / representative API |
+|---|---|
+| Input contracts | `input-schema`, `defineInputSchema`, `validateRichInputSchema`, `validateRichInputField`, `validateRichCapabilityInput`, `validateRichInputValue` |
+| Output contracts | `output-schema`, `defineOutputSchema`, `validateOutputSchema`, `validateCapabilityOutput`, `getOutputSchemaFields`, `isAggregateOutputSchema` |
+| Registry and graphs | `application`, `registry`, `createUIRegistry`, `validate-application`, `validateApplication` |
+| Descriptive views | `capability-view`, `derive-input-fields`, `deriveUIField`, `deriveUIFields`, `derive-output-view`, `deriveOutputView`, `deriveDeterministicCapabilityView` |
+| Interaction | `interaction-resolution`, `resolveCapabilityInteraction`, `validateFieldValue`, `serializeDateTimeLocal`, `buildCapabilityExecutionPayload`, `execution-request`, `parseApplicationExecutionRequest` |
+| Composition semantics | `relationship-interpretation`, `interpretRelationship`, `workflow`, `experience-orchestration`, `deriveApplicationExperience`, `deriveApplicationActions` |
+| Presentation types and formatting | `presentation-context`, `composed-surface`, `format-semantic-value`, `formatSemanticValue` |
+| Experimental optional presentation | `capability-view-derivation` provider interfaces and `deriveCapabilityView`; `presentation-composition`, `buildPresentationEnvelope`, `deterministicPresentation`, `validatePresentationPlan`, `composePresentation`, `presentationPlanSchema`, `sectionId` |
+| Inspection subpath | `@veil-runtime/ui/inspection`: `buildCompositionInspection` and inspection model types |
+
+Qualification exercises the legacy Core capability API and the independent universal interface subpaths, strict public declarations, and browser bundling. Published export conditions intentionally support ESM import, not direct CommonJS require. Core is an optional peer and is unnecessary for `/interface` and `/dom` consumers. UI has no compiled Core runtime import. A host may use UI's descriptors in a browser and keep Core execution on its server.