RFC-0001: VhyxSeal Semantic Contract Layer

Version 1.0.0-rc.1 · Published 2026-05-27 · Repository: github.com/vhyxara/vhyxseal

1. Abstract

VhyxSeal is a framework-agnostic semantic contract layer for the web — a standard that gives every UI component a machine-readable declaration of what it does, what must be true before it can be used, what changes after it is used, and how safely an automated agent must proceed. It is not a component library. It is not a framework. It is the missing contract layer that makes web interfaces readable, navigable, and safe for both humans and AI agents simultaneously — without replacing or altering anything that already exists.

This document specifies VhyxSeal version 1.0.0-rc.1. It is addressed to three audiences: framework authors who will build adapters on top of the specification, application developers who will attach contracts to their components, and AI agent developers who will consume contracts to act on behalf of users. The specification is open for public comment for a minimum of 30 days from the published date above. All feedback is reviewed by Vhyxara Leadership before a final 1.0.0 release decision is made.

1.5. Prior Art and Differentiation

Several existing standards address adjacent problems. This section acknowledges each honestly.

Schema.org structured data gives pages machine-readable metadata about their content — articles, products, events, organizations. Search engines and knowledge graphs consume it. It solves content description well. It does not address interactive component behavior: there is no schema.org type for "this button places a purchase order that is reversible within 5 minutes and requires payment method confirmation". Schema.org describes what a page contains. VhyxSeal describes what a page can do.

OpenGraph solves a specific and valuable problem: telling social platforms how to render a preview of a URL. It has no notion of interactive components, agent authorization, safety levels, or action confirmation requirements. It is a metadata layer for passive display. VhyxSeal is a contract layer for active interaction.

ARIA and the accessibility tree give assistive technologies the information they need to navigate and describe UI to users with disabilities. ARIA is a human-assistive standard. It tells a screen reader what a button's label is. It does not tell an AI agent whether clicking that button will charge a credit card, whether a human must confirm first, or what the agent should do if the action fails. VhyxSeal builds on the semantic intent that ARIA establishes and extends it into the domain of agent safety and action authorization.

Browser computer use — screenshot-based agents can click buttons on any website without any standard at all. They operate by looking at screenshots and inferring intent from appearance. This works, up to a point. The problem is not whether agents can act — they already can. The problem is whether they can act correctly. An agent clicking "Confirm" from a screenshot has no way to know whether that action places a $500 order, saves a draft, or verifies an email address. VhyxSeal does not replace screenshot-based agents. It gives the button a voice — not a visual, a semantic contract. An agent that reads a contract before acting knows the intent, the preconditions, the consequences, and the safety level before it touches anything.

None of these approaches are wrong. Each solves a real problem in its domain. VhyxSeal is additive. It sits alongside Schema.org, OpenGraph, and ARIA as a fourth layer — one designed specifically for the era of AI agents acting on behalf of humans.

2. Motivation

An agent lands on a checkout page. It is helping a user complete a purchase. The page has a button labeled "Confirm". The agent has no additional information about what this button does. It could place a $500 order, finalize an address, save the cart as a draft, or confirm an email subscription. The agent acts. It places the $500 order when the user wanted to save a draft. The cost is real — a charge the user did not intend, a support ticket, a refund process. This is not a hypothetical. Every agent operating on web UI today faces this problem, on every page, with every interactive element whose purpose is not encoded in its label.

The problem compounds as agents become more capable. A less capable agent operating cautiously on a narrow set of tasks causes limited damage when it misunderstands a button. A highly capable agent, trusted with more consequential actions across a broader surface area, causes far more damage when it misunderstands the same button. Increased capability without increased semantic clarity does not reduce risk — it amplifies it. The gap between what agents can do and what they should do grows wider every time a new model is released without a corresponding improvement in the information available to them at the point of action.

The API world solved this problem a decade ago. Before OpenAPI, every API was a black box. You read documentation if it existed, you made requests and observed responses, and your integrations broke whenever the undocumented behavior changed. OpenAPI did not make APIs smarter. It did not add new capabilities to existing APIs. It gave them a contract — a machine-readable declaration of what each endpoint does, what parameters it accepts, what it returns, and what can go wrong. Consumers could understand what an API did before calling it. VhyxSeal does the same thing for UI components. It does not change what the button does. It gives the button a contract.

Without a standard, every framework builds its own agent integration and every agent must carry framework-specific knowledge to navigate. A React-based site requires one approach, a Vue-based site requires another, a server-rendered site with no framework requires a third. The web fragments into agent-readable islands and opaque surfaces, and the islands speak different dialects. This is the trajectory of a web without a contract standard. Standards work when they are adopted early, before fragmentation is entrenched. VhyxSeal is early.

3. The Contract Model

A component contract is a machine-readable declaration attached to a single UI component. It answers four questions an agent needs answered before acting:

• Intent: What does this component do? (place-order, delete-item, search)
• Preconditions: What must be true before an agent can interact? (user authenticated, cart non-empty, payment method saved)
• Consequences: What changes after interaction? (order created, payment charged, data deleted)
• Safety: How carefully must the agent proceed? (low → high → critical → sensitive)

Contracts are declared by developers and consumed by agents. The visual component renders exactly as it does today — the contract runs alongside it without modifying any existing behavior.

The Four Adoption Levels

VhyxSeal is designed for progressive adoption. Each level adds value independently. No level is a prerequisite for the next.

Level 0 — Zero Effort. The library infers a contract from HTML semantics, element type, ARIA labels, and text content. No developer action required. An inferred contract is imprecise but actionable — an agent knows more than it would from the raw DOM alone. DevTools marks inferred contracts with a yellow indicator.

Level 1 — Single Intent Prop. The developer provides one intent string. The library looks up the intent in the built-in vocabulary and fills in safety level, confirmation requirements, and reversibility from known defaults. One prop turns an opaque button into a partially-specified contract.

Level 2 — Partial Overrides. The developer provides an intent and overrides specific fields — preconditions, safety level, reversible window. The library merges overrides with vocabulary defaults. Fields not specified still come from the vocabulary.

Level 3 — Full Contract. The developer calls defineContract() with a complete contract object. The result is frozen, fingerprinted, versioned, and fully specified. DevTools marks these green. Agents have maximum information. This is the pattern for high-safety components where precision matters.

import { defineContract } from '@vhyxseal/core'

const orderContract = defineContract({
  id: "checkout-submit-btn",
  type: "action",
  intent: "place-order",
  description: "Submits the current cart as a purchase order",
  requires: [
    { field: "user.authenticated", operator: "===", value: true, description: "User must be logged in" },
    { field: "cart.hasItems", operator: "===", value: true, description: "Cart must have at least one item" },
    { field: "user.hasPaymentMethod", operator: "===", value: true, description: "Payment method must be saved" }
  ],
  requiredPermissions: ["write:orders", "read:payment"],
  consequence: "Creates order record, charges payment method, triggers fulfillment",
  affects: ["cart", "orders", "payment", "inventory"],
  reversible: true,
  reversibleWindow: 300,
  safetyLevel: "high",
  requiresConfirmation: true,
  destructive: false,
  nextExpected: ["order-confirmation-display", "payment-error-display"],
  errorStates: [
    { trigger: "payment declined", display: "red banner with message payment failed", recovery: "navigate to update-payment-method input" }
  ],
  contractVersion: "1.0.0"
})

The Intent Vocabulary

The intent vocabulary is a built-in dictionary of 25 common user actions, each mapped to sensible defaults for safety level, reversibility, confirmation requirements, and destructiveness. When a developer provides an intent string, the library resolves these defaults automatically.

The vocabulary is extensible. Developers register domain-specific intents using registerIntent():

import { registerIntent } from '@vhyxseal/core'

registerIntent("request-refund", {
  safetyLevel: "high",
  reversible: false,
  requiresConfirmation: true,
  destructive: false,
})

Community contributions to the vocabulary are accepted through the standard RFC process.

The Relationship System

Individual contracts describe single components. The relationship system describes how components connect to form flows. Three relationship types cover all cases.

Composition — components that belong together structurally. A form and its fields. The parent cannot complete its action until specified children are in a valid state.

Sequence — components with a defined order. A checkout flow: cart → shipping → payment → confirmation. Each step declares what happens on success and what happens on failure. Steps can be marked as skippable under defined conditions.

Dependency — one component's state gates another's behavior. A payment method input that enables the checkout button. The dependency specifies the condition evaluated on the source component and the effect produced on the target: enables, disables, shows, hides, or modifies.

Relationships are defined using defineRelationship() and defineSequence().

The Capability System

Capabilities are the highest level of abstraction — what agents actually think in. An agent thinks "I want to purchase this item", not "click button id checkout-btn". A capability groups the components and relationships that together fulfill a user-facing goal.

defineCapability() creates a capability with an entry point, all possible exit points (success, failure, cancelled), the relationships involved, an estimated step count to help agents plan, and a safety level reflecting the highest safety level anywhere in the capability chain.

When a capability spans multiple pages — for example, a checkout that runs across /cart, /checkout, and /confirmation — each page manifest references the capability id and declares the current page's position in the sequence.

Safety Levels

Safety levels determine how cautiously an agent must proceed:

Agents must treat critical and sensitive components as requiring human presence in the loop regardless of other contract settings.

4. The Manifest

The manifest is a page-level aggregation of all registered component contracts. It is auto-generated from the contracts on the page — never hand-written. Agents fetch the manifest before acting to understand everything a page can do.

The /__agent__/manifest.json Convention

Every VhyxSeal-enabled site serves its manifest at /__agent__/manifest.json. This is the canonical URL. Agents know where to look without any site-specific configuration.

The manifest is served via a URL rewrite, making the convention framework-transparent. For Next.js, @vhyxseal/nextjs automatically injects the rewrite from /__agent__/manifest.json to the framework's actual handler route. Agents and tools built against the spec require no framework-specific knowledge.

Version Negotiation

Agents include version preference headers in their manifest request:

vhyxseal-version: 1.0.0
vhyxseal-fallback: 0.9.0

The site applies a four-step fallback algorithm:

1. Exact match — the requested version is available. Return it.
2. Compatible — same major version, served minor ≥ requested minor. Return with compatibility note.
3. Fallback — serve the highest version compatible with the fallback header.
4. Incompatible — no compatible version available. Return degradation message.

The response includes:

X-VhyxSeal-Version: 1.0.0
X-VhyxSeal-Domain: example.com
Cache-Control: public, max-age=3600, stale-while-revalidate=86400
ETag: "{manifest fingerprint}"

Manifest Structure

The full manifest structure is defined in Section 10. The top-level fields are:

Manifest Signing

Manifests are signed using HMAC-SHA256. The HMAC input is the JSON-serialized manifest with the signature and signedAt fields excluded — this is the standard pattern for self-describing signed documents.

Agents must verify the signature before trusting any contract data in the manifest. Signature failure means rejecting the entire manifest and applying maximum safety defaults.

Signing requires a key registered with @vhyxseal/core's key management module. Public verification is performed using the same key. Key rotation is supported — tokens issued before rotation remain verifiable because the signing key ID is stored at issuance time.

HTTP Response Requirements

Content-Type: application/json
Cache-Control: public, max-age=3600, stale-while-revalidate=86400
ETag: "{manifest fingerprint}"
X-VhyxSeal-Version: 1.0.0
X-VhyxSeal-Domain: example.com

5. Security Model

VhyxSeal sits between AI agents and the websites they act on. This position requires a serious and layered security posture built in from the beginning, not added later.

Threat Model

The threats this specification addresses:

• Prompt injection via contract fields — a malicious actor embedding agent-manipulating instructions in contract string fields (description, consequence, intent)
• Manifest tampering — an attacker modifying the manifest in transit or at rest to misrepresent what components do
• Replay attacks on action tokens — an attacker capturing and re-submitting an action token to trigger an action multiple times
• Domain spoofing — a manifest claiming to belong to a domain it does not actually serve
• Agent abuse via missing rate limits — agents hammering the manifest endpoint or executing actions at unlimited rate

Defenses

Injection detection. All contract string fields pass through a sanitization layer before the manifest is generated. The library checks against 14 injection pattern categories covering known prompt injection signatures. Fields that fail sanitization are rejected; the affected contract is excluded from the manifest and a typed error is emitted.

Field length limits. Hard limits are enforced on all string fields:

• description: 500 characters maximum
• intent: 50 characters maximum
• consequence: 300 characters maximum
• condition.description: 200 characters maximum

Structural trust over textual trust. Agent safety decisions must derive from the typed fields — safetyLevel, requiresConfirmation, destructive — not from the text of description or consequence. This is documented in the agent SDK. No agent implementation should make safety decisions based solely on free-text fields.

Manifest integrity. Every manifest is HMAC-SHA256 signed. Agents verify the signature before reading any contract data. A failed signature means reject and default to maximum safety.

Action tokens. Every agent action generates a single-use cryptographic token. The token expires in 60 seconds and is consumed on first use. A replay attempt fails because the token is either expired or already marked used. Verification executes six ordered checks: token existence, expiry, contract ID match, component ID match, intent match, used-flag check and atomic mark.

Domain binding. Manifests are cryptographically bound to their verified domain using HMAC-signed verification tokens. An agent receiving a manifest for example.com verifies that the manifest's domain token was issued for example.com before trusting any contract within it.

Agent policy defaults. The agentPolicy field in every manifest gives site owners explicit control over which agents may act and what they may do. The default policy allows all agents with reasonable rate limits. Site owners who want stricter controls can specify allowedAgents, blockedAgents, blockedActions, requiresConfirmation, and requiresHumanPresent lists.

What Is Not In Scope

• Consuming application security. VhyxSeal does not protect the application itself — only the contract layer.
• Network transport security. Use HTTPS. VhyxSeal assumes a secure transport layer.
• Agent authentication. Verifying the identity of the agent making requests is out of scope for this RFC. This is a planned future extension.

Known Limitations

• Rate limiting: AgentPolicy.rateLimits is defined in the schema. Enforcement requires server-side middleware that is not included in this release.
• Registry backend: Domain verification tokens are issued and verified locally. A hosted registry for cross-domain verification is planned for a future release.
• Multi-framework contract inheritance: Contracts defined in one framework adapter are not automatically available to another. Unified registry is planned.

These are intentional sequencing decisions, not design gaps. The schema is stable. The enforcement comes next.

6. Framework Implementation Guide

This section specifies what a VhyxSeal-compliant framework adapter must provide. It is written for framework authors building adapters for React, Vue, Angular, Svelte, or other UI frameworks.

Required Adapter Components

A compliant adapter must provide:

1. A context provider — equivalent to SealProvider in @vhyxseal/react. This component owns the registry of contracts for the current render tree and exposes the manifest to any consumer.
2. registerContract() and unregisterContract() APIs — called by components on mount and unmount respectively. Registration includes the full ComponentContract object. Unregistration removes it from the manifest.
3. generateManifest() integration — the provider must call generateManifest() from @vhyxseal/core with the set of currently mounted component IDs. It must not implement custom manifest generation logic.
4. An inference engine for Level 0 adoption — the adapter must be able to infer a partial contract from HTML semantics, ARIA attributes, element type, and text content when no contract is explicitly provided.
5. DevTools integration (recommended, not required) — the adapter should integrate with @vhyxseal/devtools to provide the development-time contract overlay and panel.

SealProvider Responsibilities

The context provider:

• Owns a Map<string, ComponentContract> of all contracts registered in its subtree
• Exposes registerContract(contract) and unregisterContract(id) as stable callbacks to child components
• Passes the set of mounted component IDs to generateManifest() when generating the manifest — this allows output-time scoping that prevents cross-provider contract bleed
• Returns a Readonly<VhyxSealManifest> or null from its context value
• Must never render its own visible UI

Component Registration Protocol

Components register their contracts on mount and unregister on unmount:

// On mount
registerContract(contract)

// On unmount
unregisterContract(contract.id)

A contract that fails validation is silently excluded from the manifest in production. In development, a VhyxSealError is emitted and displayed in DevTools. The component renders normally in both cases — contract errors never affect the visual layer (DECISION-008).

Manifest Generation Requirements

Adapters must call generateManifest() from @vhyxseal/core:

import { generateManifest } from '@vhyxseal/core'

const manifest = generateManifest(
  contractArray,
  {
    domain: "example.com",
    domainVerified: true,
    verificationToken: "...",
    agentPolicy: { ... }
  },
  mountedComponentIds  // Set<string> — output-time scoping
)

Custom manifest generation is not permitted. All adapters must use this function to ensure that schema validation, fingerprinting, and policy merging behavior are consistent across frameworks.

Reference Implementations

Three reference implementations are available:

• @vhyxseal/react — React 18+ adapter with SealProvider, HOC (withAgentContract), hooks (useContract, useCapability, useAgentAction), and components (Button, Input, Form, Nav, Display, Confirmation)
• @vhyxseal/vue — Vue 3 adapter with plugin, composables (useSeal, useContract, useCapability, useAgentAction), and the same six components
• @vhyxseal/vanilla — Web Components adapter with SealButton, SealInput, SealForm, SealNav, SealDisplay, SealConfirmation custom elements and createSealRegistry()

Community adapters for other frameworks should follow the same patterns as the reference implementations. An adapter specification document is available in the repository.

6.5. Compliance Levels

This section formally defines three levels of VhyxSeal compliance. These levels are cumulative — Level 3 implies Level 2, which implies Level 1.

Level 1 — Manifest Compliant

Requirements:

• The site generates a valid /__agent__/manifest.json response
• The manifest declares a vhyxseal schema version field
• The manifest is served with correct Content-Type: application/json

What agents can do at this level:

• Discover that the site has a VhyxSeal-enabled manifest
• Read the schema version
• Determine that the site participates in the VhyxSeal standard

Level 1 compliance is the minimum for agent discovery. Component-level contracts are not required.

Level 2 — Contract Compliant

Requirements:

• All interactive components on the page have contracts (explicit or inferred)
• The inference engine is implemented so Level 0 developer adoption works
• DevTools integration is present for development visibility

What agents can do at this level:

• Read component intent, safety level, and confirmation requirements before acting
• Understand preconditions and avoid attempting actions that will fail
• Navigate relationships between components to understand multi-step flows
• Plan capability execution using entry points and estimated step counts

Level 2 is the target compliance level for most applications.

Level 3 — Security Compliant

Requirements:

• HMAC-SHA256 manifest signing is implemented and active
• Single-use action tokens are implemented and enforced
• Domain verification tokens are issued and verified

What agents can do at this level:

• Cryptographically verify manifest integrity before trusting any contract data
• Use single-use tokens for high-safety confirmed actions
• Trust domain binding — the manifest is proven to belong to the claimed domain

Note: VhyxSeal ships at Level 2 compliance by default. Level 3 requires @vhyxseal/nextjs and key configuration.

7. Versioning Commitment

VhyxSeal version 1.0.0 carries a formal stability guarantee. This section defines precisely what that guarantee covers and what it does not.

Semantic Versioning Policy

VhyxSeal follows semantic versioning. Within a major version, changes are additive only. Fields are never removed. Fields are never renamed. New optional fields may be added with documented defaults.

What Constitutes a Breaking Change

The following changes require a major version bump and the full RFC process with a 12-month migration window:

• Removing a field from the contract schema
• Changing the manifest URL convention (/__agent__/manifest.json)
• Changing the version negotiation algorithm
• Removing a built-in intent from the vocabulary
• Changing the string value of any ErrorCode enum member

What Does Not Constitute a Breaking Change

The following changes are permitted within a major version:

• Adding new optional fields to any schema interface
• Adding new built-in intents to the vocabulary
• Adding new ErrorCode enum members
• Performance improvements to library internals
• Bug fixes that do not alter documented behavior

Deprecation Policy

Fields marked as deprecated remain in the schema for the full duration of the current major version. Deprecation is announced in the project CHANGELOG.md and, for significant deprecations, through a new RFC. The minimum deprecation window before removal is 12 months. No silent removals — every removal is announced at least 6 months before it takes effect.

The 1.0.0 Stability Guarantee

What it guarantees:

• The contract schema fields and types defined in this RFC will not change without a major version bump
• The /__agent__/manifest.json URL convention is stable
• The version negotiation algorithm described in Section 4 is stable
• Additions to the built-in intent vocabulary are backward compatible — existing agent behavior is unaffected
• ErrorCode string values are stable — agents and tooling may depend on them

What it does not guarantee:

• Implementation internals of @vhyxseal/core — internal functions not part of the public API may change
• Framework adapter APIs — @vhyxseal/react, @vhyxseal/vue, and @vhyxseal/vanilla are versioned independently
• DevTools, CLI, and extension UI — tooling surfaces evolve independently of the schema

8. What Is Not In This RFC

The following capabilities are defined in this RFC but not yet enforced in 1.0.0-rc.1:

Rate limiting. The AgentPolicy.rateLimits object is fully defined in the schema with fields for actionsPerMinute, actionsPerHour, manifestRequestsPerMinute, and perAgentSession. Declaring these values in a manifest has no enforcement effect in 1.0.0-rc.1. Server-side middleware that reads and enforces these limits is planned and will ship as a separate module. This is a sequencing decision — the schema is stable; the enforcement runtime comes next.

Registry backend. Domain verification tokens are currently issued and verified within the same process using local HMAC operations. There is no centralized registry that allows cross-domain verification or independent token validation. A hosted registry is planned for a future release. In the meantime, domain verification provides meaningful security within a single deployment but does not support scenarios requiring external trust chains.

Multi-framework contract inheritance. Contracts registered in a SealProvider in a React application are not visible to a Vue component rendered in a different subtree. Each framework adapter maintains its own registry. A unified cross-framework registry is planned. Until that ships, cross-framework contract sharing requires manual coordination.

9. RFC Process

How to Comment

Submit feedback through GitHub Discussions on the vhyxara/vhyxseal repository.

Apply the label RFC-0001 to your discussion thread.

The comment period is open for a minimum of 30 days from the published date of this document. Early closure does not occur — the period may be extended if significant feedback is still arriving.

What Feedback Is In Scope

The following are in scope for this RFC:

• Contract schema fields and types — are they sufficient, is anything missing, are any types wrong
• Manifest structure and the /__agent__/manifest.json URL convention
• Security model design — threat coverage, defense adequacy, known limitations
• Compliance level definitions — are the three levels the right divisions
• Versioning policy — breaking change definitions, deprecation window length

What Feedback Is Out of Scope

The following are out of scope for this RFC:

• Framework-specific implementation details — how @vhyxseal/react renders components, what the hook APIs look like
• VhyxUI component library decisions — visual design, styling, theme systems
• Infrastructure and hosting decisions — where the registry backend runs, deployment architecture

Out-of-scope feedback will not be dismissed — it will be routed to the appropriate venue. The RFC process is specifically for the schema, manifest, and specification decisions in this document.

How Decisions Are Made

All feedback is reviewed by Vhyxara Super Leaders. Every piece of feedback receives a response — either acknowledgment and incorporation, or a reasoned explanation of why it was not adopted.

Significant changes to the specification require an updated RFC draft to be published and a new comment period. Breaking changes to the schema require a new RFC version (RFC-0001.1 or a new RFC-0002 as appropriate). Minor clarifications — typo fixes, improved wording, additional examples — are merged directly without a new comment period.

After the RFC Closes

When the minimum comment period ends:

1. All feedback is reviewed and addressed or documented as rejected with reasons
2. Any required revisions are made to the specification
3. Vhyxara Leadership makes the 1.0.0 release decision
4. RFC-0001 is marked as Accepted (if adopted as written) or Revised (if significant changes were incorporated before acceptance)
5. The 1.0.0 npm release follows the acceptance decision

10. Reference

10.1. Contract Schema

The following TypeScript interfaces define the complete contract schema as implemented in packages/core/src/schema/contract.ts.

/** Category of a UI component — determines how agents interpret and interact with it. */
export type ComponentType =
  | "action"        // buttons, triggers — does something
  | "input"         // forms, search, filters — collects data
  | "navigation"    // links, menus, tabs — moves somewhere
  | "display"       // shows current state — read only
  | "confirmation"; // gates a decision — dialogs, modals

/** How carefully an agent must proceed before interacting with a component. */
export type SafetyLevel =
  | "low"       // read, filter, sort — agent can proceed freely
  | "medium"    // send message, save draft — proceed with care
  | "high"      // place order, submit form — confirm with human
  | "critical"  // delete account, payment — always require human
  | "sensitive"; // medical, financial data — extra protections apply

/** A precondition that must be satisfied before an agent interacts with a component. */
export interface Condition {
  /** Abstract field reference — never expose internal data structure e.g. "user.hasPaymentMethod". */
  field: string;
  operator: "===" | "!==" | ">" | "<" | ">=" | "<=" | "includes" | "excludes";
  /** The value to compare against. */
  value: unknown;
  /** Human readable description e.g. "User must have a payment method saved". */
  description: string;
}

/** A known failure mode for a component and how an agent should recover from it. */
export interface ErrorState {
  /** What causes this error e.g. "payment declined". */
  trigger: string;
  /** What the UI shows e.g. "red banner with payment failed message". */
  display: string;
  /** What the agent should do e.g. "navigate to update-payment-method". */
  recovery: string;
}

/** A record of a change to a component contract — used by agents to detect breaking changes. */
export interface ContractChangelog {
  /** Semver version when this change was made e.g. "1.2.0". */
  version: string;
  /** ISO date string of when this change occurred. */
  date: string;
  /** Description of what changed. */
  change: string;
  /** True if agents relying on the previous contract behavior must update their logic. */
  breakingForAgents: boolean;
}

/**
 * The semantic contract for a single UI component.
 *
 * Describes what a component does, what conditions must be true before an agent
 * interacts with it, what consequences follow from interaction, and how safely
 * an agent must proceed.
 */
export interface ComponentContract {
  // IDENTITY
  /** Unique identifier for this component on the page. */
  id: string;
  /** Category of component — how agents interpret it. */
  type: ComponentType;
  /** Machine readable intent e.g. "place-order". */
  intent: string;
  /** Human readable explanation for agent reasoning. Max 500 characters. */
  description: string;

  // PRECONDITIONS
  /** Conditions that must all be satisfied before interaction. */
  requires: readonly Condition[];
  /** Permission scopes required e.g. ["write:orders", "read:payment"]. */
  requiredPermissions: readonly string[];

  // CONSEQUENCE
  /** Plain description of what changes after interaction. Max 300 characters. */
  consequence: string;
  /** System areas affected by this action e.g. ["cart", "orders"]. */
  affects: readonly string[];
  /** Whether this action can be undone. */
  reversible: boolean;
  /** Seconds within which the action can be undone. Only meaningful when reversible is true. */
  reversibleWindow?: number;

  // SAFETY
  /** How carefully the agent must proceed before interacting. */
  safetyLevel: SafetyLevel;
  /** Whether the agent must obtain human approval before acting. */
  requiresConfirmation: boolean;
  /** Whether this action permanently deletes or modifies data. */
  destructive: boolean;

  // AGENT NAVIGATION HINTS
  /** Component ids with similar function the agent can try if this one is unavailable. */
  alternatives?: readonly string[];
  /** Component ids typically interacted with after this one. */
  nextExpected?: readonly string[];
  /** Known failure modes and recovery paths. */
  errorStates?: readonly ErrorState[];

  // CONTRACT METADATA
  /** Developer managed semver e.g. "1.0.0". */
  contractVersion: string;
  /** Auto generated — hash of contract content. */
  fingerprint?: string;
  /** ISO date — when this contract was last confirmed against component behavior. */
  lastVerified?: string;
  verifiedBy?: "auto" | "manual" | "test";
  changelog?: readonly ContractChangelog[];
}

10.2. Relationship Schema

The following TypeScript interfaces define the relationship schema as implemented in packages/core/src/schema/relationships.ts.

/** The three categories of relationship between components. */
export type RelationshipType = "composition" | "sequence" | "dependency";

/**
 * A composition relationship — components that belong together structurally.
 */
export interface CompositionRelationship {
  type: "composition";
  /** Unique identifier for this relationship. */
  id: string;
  /** Component id of the parent. */
  parent: string;
  /** Component ids of children in order. */
  children: readonly string[];
  /** Child component ids that must be valid before the parent can act. */
  completionRequires: readonly string[];
  description: string;
}

/** A single step in a sequence relationship. */
export interface SequenceStep {
  /** Position of this step in the sequence — starts at 1. */
  order: number;
  /** Component id at this step. */
  componentId: string;
  /** Whether the agent can skip this step. */
  canSkip: boolean;
  /** Condition string under which this step can be skipped. Only meaningful when canSkip is true. */
  skipCondition?: string;
  /** Component id to navigate to on successful completion of this step. */
  onComplete: string;
  /** Component id to navigate to when this step fails. */
  onFail: string;
}

/**
 * A sequence relationship — components with a defined order or flow.
 */
export interface SequenceRelationship {
  type: "sequence";
  /** Unique identifier for this relationship. */
  id: string;
  description: string;
  steps: readonly SequenceStep[];
  /** True if the agent must follow exact step order. False if steps can be skipped or reordered. */
  linear: boolean;
}

/** The effect that one component's state has on another component. */
export type DependencyEffect =
  | "enables"
  | "disables"
  | "shows"
  | "hides"
  | "modifies";

/**
 * A dependency relationship — one component's state gates another's behavior.
 */
export interface DependencyRelationship {
  type: "dependency";
  /** Unique identifier for this relationship. */
  id: string;
  /** Component id whose state matters. */
  source: string;
  /** Component id affected by the source component's state. */
  target: string;
  /** The specific condition being evaluated on the source component. */
  condition: Condition;
  /** How the target component is affected when the condition is met. */
  effect: DependencyEffect;
  description: string;
}

/** A relationship between components — composition, sequence, or dependency. */
export type Relationship =
  | CompositionRelationship
  | SequenceRelationship
  | DependencyRelationship;

10.3. Capability Schema

The following TypeScript interfaces define the capability schema as implemented in packages/core/src/schema/capability.ts.

/** One possible end state of a capability — success, failure, or cancellation. */
export interface ExitPoint {
  /** Component id where this exit point is reached. */
  componentId: string;
  outcome: "success" | "failure" | "cancelled";
  description: string;
}

/** A reference to a relationship that is part of a capability. */
export interface CapabilityRelationshipRef {
  type: RelationshipType;
  ref: Relationship;
}

/**
 * A capability — a complete user-facing goal an agent can accomplish on a site.
 */
export interface Capability {
  /** Unique identifier e.g. "purchase-item". */
  id: string;
  /** Human and agent readable description e.g. "browse, select and purchase a product". */
  description: string;
  /** Component id where the agent starts this capability. */
  entryPoint: string;
  /** All possible end states — success, failure, and cancellation paths. */
  exitPoints: readonly ExitPoint[];
  relationships: readonly CapabilityRelationshipRef[];
  /** Approximate number of steps — helps agent plan before executing. */
  estimatedSteps: number;
  /** Whether the user must be authenticated to complete this capability. */
  requiresAuth: boolean;
  /** Highest safety level anywhere in the capability chain. */
  safetyLevel: SafetyLevel;
  /** Routes this capability spans when it crosses multiple pages. */
  spanPages?: readonly string[];
}

10.4. Manifest Schema

The following TypeScript interfaces define the manifest schema as implemented in packages/core/src/manifest/types.ts.

/** Per-agent action and manifest request rate limits. */
export interface RateLimits {
  actionsPerMinute: number;
  actionsPerHour: number;
  manifestRequestsPerMinute: number;
  perAgentSession: boolean;
}

/**
 * Access policy controlling which agents may act on a site and what they may do.
 * Site owners set this. `manifestAuth` is only meaningful when `manifestAccess` is `"private"`.
 */
export interface AgentPolicy {
  /** Agent identifiers allowed. Use `["*"]` for all agents. */
  allowedAgents: readonly string[];
  /** Agent identifier patterns to block. */
  blockedAgents: readonly string[];
  /** Whether agents must identify themselves before acting. */
  requireAgentIdentification: boolean;
  rateLimits: RateLimits;
  /** Intent ids the agent is allowed to execute. Use `["*"]` for all. */
  allowedActions: readonly string[];
  /** Intent ids the agent is explicitly blocked from executing. */
  blockedActions: readonly string[];
  /** Intent ids that always require human confirmation regardless of contract settings. */
  requiresConfirmation: readonly string[];
  /** Intent ids that require a verified human to be present in the loop. */
  requiresHumanPresent: readonly string[];
  manifestAccess: "public" | "private";
  /** Authentication scheme required when `manifestAccess` is `"private"`. */
  manifestAuth?: "bearer-token";
}

/**
 * The complete VhyxSeal manifest for a page or site.
 * Auto-generated — never hand-written. Served at `/__agent__/manifest.json`.
 */
export interface VhyxSealManifest {
  // Schema identification
  /** VhyxSeal schema version this manifest conforms to e.g. "1.0.0". */
  vhyxseal: string;
  /** Permanent URL to the schema definition for this version. */
  schemaUrl: string;

  // Site identification
  /** Verified domain this manifest belongs to e.g. "example.com". */
  domain: string;
  domainVerified: boolean;
  /** Verification token issued by the VhyxSeal registry after domain ownership confirmation. */
  verificationToken: string;

  // Integrity
  /** HMAC-SHA256 signature of the manifest content. */
  signature: string;
  /** ISO datetime when the manifest was signed. */
  signedAt: string;
  /** Deterministic content fingerprint for drift detection. NOT a cryptographic signature. */
  fingerprint: string;

  // Content
  capabilities: readonly Capability[];
  components: readonly ComponentContract[];
  relationships: readonly Relationship[];

  // Policy
  agentPolicy: AgentPolicy;

  // Cache and freshness
  /** ISO datetime when this manifest was generated. */
  generatedAt: string;
  /** ISO datetime after which agents should re-fetch the manifest. */
  expiresAt: string;
}

10.5. Error System

The following types define the error system as implemented in packages/core/src/errors/index.ts.

/**
 * Severity of a VhyxSeal error.
 * Errors at any severity level never crash the visual layer.
 */
export type ErrorSeverity =
  | "fatal"   // stops everything — invalid schema, corrupt manifest
  | "error"   // this component broken — contract invalid, field wrong
  | "warning" // degraded experience — contract inferred not specified
  | "info";   // informational — new fields available in newer version

/**
 * All VhyxSeal error codes.
 * SCREAMING_SNAKE_CASE. Every code prefixed with VHYX_.
 * Never remove or rename codes — agents and tooling may depend on them.
 */
export enum ErrorCode {
  // Schema errors
  VHYX_INVALID_SCHEMA_VERSION = "VHYX_INVALID_SCHEMA_VERSION",
  VHYX_CONTRACT_VALIDATION_FAILED = "VHYX_CONTRACT_VALIDATION_FAILED",
  VHYX_UNKNOWN_INTENT = "VHYX_UNKNOWN_INTENT",
  VHYX_INVALID_SAFETY_LEVEL = "VHYX_INVALID_SAFETY_LEVEL",
  VHYX_FIELD_TOO_LONG = "VHYX_FIELD_TOO_LONG",
  VHYX_INJECTION_DETECTED = "VHYX_INJECTION_DETECTED",

  // Manifest errors
  VHYX_MANIFEST_GENERATION_FAILED = "VHYX_MANIFEST_GENERATION_FAILED",
  VHYX_MANIFEST_SIGNING_FAILED = "VHYX_MANIFEST_SIGNING_FAILED",
  VHYX_MANIFEST_VERIFICATION_FAILED = "VHYX_MANIFEST_VERIFICATION_FAILED",
  VHYX_DOMAIN_MISMATCH = "VHYX_DOMAIN_MISMATCH",

  // Contract errors
  VHYX_CONTRACT_DRIFT_DETECTED = "VHYX_CONTRACT_DRIFT_DETECTED",
  VHYX_CONTRACT_STALE = "VHYX_CONTRACT_STALE",
  VHYX_DUPLICATE_COMPONENT_ID = "VHYX_DUPLICATE_COMPONENT_ID",
  VHYX_DUPLICATE_INTENT = "VHYX_DUPLICATE_INTENT",

  // Relationship errors
  VHYX_INVALID_RELATIONSHIP = "VHYX_INVALID_RELATIONSHIP",
  VHYX_CIRCULAR_DEPENDENCY = "VHYX_CIRCULAR_DEPENDENCY",
  VHYX_MISSING_COMPONENT_REF = "VHYX_MISSING_COMPONENT_REF",

  // Security errors
  VHYX_RATE_LIMIT_EXCEEDED = "VHYX_RATE_LIMIT_EXCEEDED",
  VHYX_TOKEN_EXPIRED = "VHYX_TOKEN_EXPIRED",
  VHYX_TOKEN_ALREADY_USED = "VHYX_TOKEN_ALREADY_USED",
  VHYX_AGENT_NOT_ALLOWED = "VHYX_AGENT_NOT_ALLOWED",
}

/** Configuration object passed to the VhyxSealError constructor. */
export interface VhyxSealErrorConfig {
  /** Error code from the ErrorCode enum — machine readable identifier. */
  code: ErrorCode;
  /** Human readable description of what went wrong. */
  message: string;
  /** Structured context relevant to this specific error instance. */
  context: Record<string, unknown>;
  /** How severe this error is — determines library and DevTools response. */
  severity: ErrorSeverity;
  /** Whether the caller can recover from this error and continue. */
  recoverable: boolean;
  /** Concrete action the developer should take to fix this error. */
  suggestion: string;
}

/**
 * The base error class for all errors thrown by VhyxSeal.
 * All VhyxSeal packages throw this class — never a plain Error.
 */
export class VhyxSealError extends Error {
  readonly code: ErrorCode;
  readonly context: Record<string, unknown>;
  readonly severity: ErrorSeverity;
  readonly recoverable: boolean;
  readonly suggestion: string;

  constructor(config: VhyxSealErrorConfig) { /* ... */ }
}

Error Code Reference

10.6. Intent Vocabulary

All 25 built-in intents and their default contract field values. These defaults are applied when a developer provides only an intent string (Level 1 adoption) or when resolveIntentDefaults() is called directly.

Extend the vocabulary using registerIntent(). See Section 3 for the API signature and an example.

RFC-0001 — VhyxSeal Semantic Contract Layer — Version 1.0.0-rc.1
Published 2026-05-27 — Open for comment — github.com/vhyxara/vhyxseal/discussions