Schema Reference

export interface ComponentContract {
  // IDENTITY
  id: string;
  type: ComponentType;
  intent: string;
  description: string;

  // PRECONDITIONS
  requires: readonly Condition[];
  requiredPermissions: readonly string[];

  // CONSEQUENCE
  consequence: string;
  affects: readonly string[];
  reversible: boolean;
  reversibleWindow?: number;

  // SAFETY
  safetyLevel: SafetyLevel;
  requiresConfirmation: boolean;
  destructive: boolean;

  // AGENT NAVIGATION HINTS
  alternatives?: readonly string[];
  nextExpected?: readonly string[];
  errorStates?: readonly ErrorState[];

  // CONTRACT METADATA
  contractVersion: string;
  fingerprint?: string;
  lastVerified?: string;
  verifiedBy?: "auto" | "manual" | "test";
  changelog?: readonly ContractChangelog[];
}

import { defineContract } from '@vhyxseal/core'

const checkoutContract = defineContract({
  id: "checkout-submit-btn",
  type: "action",
  intent: "place-order",
  description: "Submits the 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 items" },
  ],
  requiredPermissions: ["write:orders"],
  consequence: "Creates order, charges payment, triggers fulfillment",
  affects: ["cart", "orders", "payment"],
  reversible: true,
  reversibleWindow: 300,
  safetyLevel: "high",
  requiresConfirmation: true,
  destructive: false,
  contractVersion: "1.0.0",
})

export interface Condition {
  /** Abstract field reference — never expose internals e.g. "user.hasPaymentMethod" */
  field: string;
  operator: "===" | "!==" | ">" | "<" | ">=" | "<=" | "includes" | "excludes";
  value: unknown;
  description: string;
}

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;
}

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

export type SafetyLevel =
  | "low"       // read, filter, sort — agent proceeds 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

export interface CompositionRelationship {
  type: "composition";
  id: string;
  parent: string;
  children: readonly string[];
  completionRequires: readonly string[];
  description: string;
}

export interface SequenceStep {
  order: number;
  componentId: string;
  canSkip: boolean;
  skipCondition?: string;
  onComplete: string;
  onFail: string;
}

export interface SequenceRelationship {
  type: "sequence";
  id: string;
  description: string;
  steps: readonly SequenceStep[];
  linear: boolean;
}

export type DependencyEffect =
  | "enables" | "disables" | "shows" | "hides" | "modifies";

export interface DependencyRelationship {
  type: "dependency";
  id: string;
  source: string;
  target: string;
  condition: Condition;
  effect: DependencyEffect;
  description: string;
}

export interface Capability {
  id: string;
  description: string;
  entryPoint: string;
  exitPoints: readonly ExitPoint[];
  relationships: readonly CapabilityRelationshipRef[];
  estimatedSteps: number;
  requiresAuth: boolean;
  safetyLevel: SafetyLevel;
  spanPages?: readonly string[];
}

import { defineCapability } from '@vhyxseal/core'

const purchaseCapability = defineCapability({
  id: "purchase-item",
  description: "Browse, select, and purchase a product",
  entryPoint: "product-add-to-cart-btn",
  exitPoints: [
    { componentId: "order-confirmation-display", outcome: "success", description: "Order placed" },
    { componentId: "payment-error-display", outcome: "failure", description: "Payment failed" },
  ],
  relationships: [],
  estimatedSteps: 4,
  requiresAuth: true,
  safetyLevel: "high",
})

export interface VhyxSealManifest {
  // Schema identification
  vhyxseal: string;          // schema version e.g. "1.0.0"
  schemaUrl: string;

  // Site identification
  domain: string;
  domainVerified: boolean;
  verificationToken: string;

  // Integrity
  signature: string;         // HMAC-SHA256 or "unsigned" (stub)
  signedAt: string;
  fingerprint: string;

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

  // Policy
  agentPolicy: AgentPolicy;

  // Cache and freshness
  generatedAt: string;       // ISO datetime
  expiresAt: string;
}

// GET /__agent__/manifest.json
{
  "vhyxseal": "1.0.0",
  "domain": "example.com",
  "domainVerified": true,
  "signature": "unsigned",
  "fingerprint": "vhyxs_a3f8b2c1",
  "components": [...],
  "relationships": [],
  "capabilities": [...],
  "agentPolicy": {
    "allowedAgents": ["*"],
    "blockedAgents": [],
    "allowedActions": ["*"],
    "blockedActions": [],
    "requiresConfirmation": ["place-order", "delete-account"],
    "rateLimits": {
      "actionsPerMinute": 60,
      "actionsPerHour": 500,
      "manifestRequestsPerMinute": 10,
      "perAgentSession": true
    }
  },
  "generatedAt": "2026-05-27T10:00:00.000Z",
  "expiresAt": "2026-05-27T11:00:00.000Z"
}

export interface AgentPolicy {
  allowedAgents: readonly string[];          // ["*"] for all
  blockedAgents: readonly string[];
  requireAgentIdentification: boolean;
  rateLimits: RateLimits;
  allowedActions: readonly string[];         // intent ids; ["*"] for all
  blockedActions: readonly string[];
  requiresConfirmation: readonly string[];   // intent ids
  requiresHumanPresent: readonly string[];   // intent ids
  manifestAccess: "public" | "private";
  manifestAuth?: "bearer-token";             // only when manifestAccess is "private"
}

export interface RateLimits {
  actionsPerMinute: number;
  actionsPerHour: number;
  manifestRequestsPerMinute: number;
  perAgentSession: boolean;
}