@enterstellar-ai/types 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2297 @@
+import { z } from 'zod';
+
+/**
+ * @module @enterstellar-ai/types/version
+ * @description Enterstellar Types package version constant.
+ *
+ * Exported for runtime compatibility checks and DevTools version display.
+ * @see Design Choice T14
+ */
+/** Current version of the @enterstellar-ai/types package. Follows semver. */
+declare const ENTERSTELLAR_TYPES_VERSION: "0.1.0";
+
+/**
+ * @module @enterstellar-ai/types/brands
+ * @description Branded types for type-safe identifiers across the Enterstellar ecosystem.
+ *
+ * Branded types prevent accidentally passing a zone name where a component ID
+ * is expected, or using a plain string where a trace ID is required.
+ *
+ * @see Design Choice T10
+ *
+ * @example
+ * ```ts
+ * import { createComponentId, createZoneId, createTraceId } from '@enterstellar-ai/types';
+ *
+ * const compId = createComponentId('PatientVitals');
+ * const zoneId = createZoneId('main-content');
+ * const traceId = createTraceId();
+ * ```
+ */
+/**
+ * A branded string identifying a registered component.
+ * Prevents accidental misuse of plain strings as component identifiers.
+ */
+type ComponentId = string & {
+    readonly __brand: 'ComponentId';
+};
+/**
+ * A branded string identifying an Zone instance.
+ * Ensures zone references are explicit and type-checked.
+ */
+type ZoneId = string & {
+    readonly __brand: 'ZoneId';
+};
+/**
+ * A branded string identifying an AgentTrace record.
+ * Guarantees trace references are unique and type-safe.
+ */
+type TraceId = string & {
+    readonly __brand: 'TraceId';
+};
+/**
+ * Creates a type-safe `ComponentId` from a PascalCase component name.
+ *
+ * @param name - PascalCase component name, must be non-empty.
+ * @returns A branded `ComponentId`.
+ * @throws {EnterstellarError} `ENS-1009` if `name` is empty or contains only whitespace.
+ *
+ * @example
+ * ```ts
+ * const id = createComponentId('PatientVitals');
+ * ```
+ */
+declare function createComponentId(name: string): ComponentId;
+/**
+ * Creates a type-safe `ZoneId` from a zone name.
+ *
+ * @param name - Zone name, must be non-empty. Typically kebab-case.
+ * @returns A branded `ZoneId`.
+ * @throws {EnterstellarError} `ENS-1009` if `name` is empty or contains only whitespace.
+ *
+ * @example
+ * ```ts
+ * const id = createZoneId('patient-sidebar');
+ * ```
+ */
+declare function createZoneId(name: string): ZoneId;
+/**
+ * Creates a type-safe `TraceId` using a UUIDv4.
+ *
+ * @returns A branded `TraceId` backed by a cryptographically random UUID.
+ *
+ * @example
+ * ```ts
+ * const id = createTraceId();
+ * // e.g., "c0a80164-b1c2-4d3e-a456-789012345678"
+ * ```
+ */
+declare function createTraceId(): TraceId;
+
+/**
+ * @module @enterstellar-ai/types/errors
+ * @description Enterstellar error class and error code taxonomy.
+ *
+ * All Enterstellar errors extend `EnterstellarError`, carrying a machine-readable `code`,
+ * the originating `module`, and whether the error is `recoverable`.
+ *
+ * Error code ranges:
+ * - `ENS-1xxx` — Registry errors
+ * - `ENS-2xxx` — Compiler errors
+ * - `ENS-3xxx` — Lifecycle / Zone errors
+ * - `ENS-4xxx` — Forge / State errors
+ * - `ENS-5xxx` — Cloud / Index errors
+ * - `ENS-6xxx` — Normalizer errors
+ * - `ENS-7xxx` — Adapter errors
+ * - `ENS-8xxx` — Agent SDK errors
+ * - `ENS-9xxx` — CLI errors
+ *
+ * @see Coding Rules — Error Taxonomy
+ * @see Design Choice C14
+ */
+/**
+ * Machine-readable error code following the `ENS-XXXX` convention.
+ * Each code maps to documentation at `enterstellar.dev/errors/ENS-XXXX`.
+ */
+type EnterstellarErrorCode = 'ENS-1001' | 'ENS-1002' | 'ENS-1003' | 'ENS-1004' | 'ENS-1005' | 'ENS-1006' | 'ENS-1007' | 'ENS-1008' | 'ENS-1009' | 'ENS-1010' | 'ENS-2001' | 'ENS-2002' | 'ENS-2003' | 'ENS-2004' | 'ENS-2005' | 'ENS-2006' | 'ENS-2007' | 'ENS-2008' | 'ENS-2009' | 'ENS-2010' | 'ENS-3001' | 'ENS-3002' | 'ENS-3003' | 'ENS-3004' | 'ENS-3005' | 'ENS-3010' | 'ENS-4001' | 'ENS-4002' | 'ENS-4003' | 'ENS-4004' | 'ENS-4005' | 'ENS-4006' | 'ENS-4007' | 'ENS-5001' | 'ENS-5002' | 'ENS-5003' | 'ENS-5004' | 'ENS-5005' | 'ENS-5006' | 'ENS-5007' | 'ENS-5008' | 'ENS-5009' | 'ENS-5010' | 'ENS-5020' | 'ENS-5021' | 'ENS-5022' | 'ENS-5023' | 'ENS-5024' | 'ENS-5025' | 'ENS-6001' | 'ENS-6002' | 'ENS-6003' | 'ENS-6004' | 'ENS-6005' | 'ENS-7001' | 'ENS-7002' | 'ENS-7003' | 'ENS-7004' | 'ENS-7005' | 'ENS-8001' | 'ENS-8002' | 'ENS-8003' | 'ENS-8004' | 'ENS-8005' | 'ENS-9001' | 'ENS-9002' | 'ENS-9003' | 'ENS-9004' | 'ENS-9005' | 'ENS-9006' | 'ENS-5030' | 'ENS-5031' | 'ENS-5032' | 'ENS-5033' | 'ENS-5034' | 'ENS-5035';
+/** The Enterstellar module that originated the error. */
+type EnterstellarErrorModule = 'types' | 'registry' | 'compiler' | 'state' | 'telemetry' | 'react' | 'connection' | 'lifecycle' | 'normalizer' | 'forge' | 'cache' | 'semantic-index' | 'cloud' | 'global-index' | 'agent-sdk' | 'devtools' | 'test' | 'cli' | 'adapters';
+/**
+ * Base error class for all Enterstellar errors.
+ *
+ * Extends the native `Error` with structured metadata for observability,
+ * DevTools integration, and programmatic error handling.
+ *
+ * @example
+ * ```ts
+ * throw new EnterstellarError(
+ *   'ENS-1001',
+ *   'registry',
+ *   'Component "Foo" is already registered.',
+ *   true, // recoverable
+ * );
+ * ```
+ */
+declare class EnterstellarError extends Error {
+    /**
+     * Machine-readable error code.
+     * Maps to documentation at `enterstellar.dev/errors/{code}`.
+     */
+    readonly code: EnterstellarErrorCode;
+    /** The Enterstellar module that originated this error. */
+    readonly module: EnterstellarErrorModule;
+    /**
+     * Whether the error is recoverable.
+     * Recoverable errors can be retried or handled gracefully.
+     * Non-recoverable errors indicate fatal conditions.
+     */
+    readonly recoverable: boolean;
+    /**
+     * ISO 8601 timestamp of when the error was created.
+     * Useful for trace correlation and debugging.
+     */
+    readonly timestamp: string;
+    /**
+     * Creates a new `EnterstellarError`.
+     *
+     * @param code - Machine-readable error code (e.g., `'ENS-1001'`).
+     * @param module - The Enterstellar module that originated the error.
+     * @param message - Human-readable error message.
+     * @param recoverable - Whether the error can be retried or handled gracefully.
+     * @param cause - Optional underlying error that caused this error.
+     */
+    constructor(code: EnterstellarErrorCode, module: EnterstellarErrorModule, message: string, recoverable?: boolean, cause?: unknown);
+    /**
+     * Serializes the error to a plain object for logging, telemetry, or DevTools.
+     *
+     * @returns A plain object representation of the error.
+     */
+    toJSON(): {
+        name: string;
+        code: EnterstellarErrorCode;
+        module: EnterstellarErrorModule;
+        message: string;
+        recoverable: boolean;
+        timestamp: string;
+        stack: string | undefined;
+    };
+}
+
+/**
+ * @module @enterstellar-ai/types/contract
+ * @description ComponentContract — the canonical data shape for registering
+ * a component in the Enterstellar ecosystem.
+ *
+ * A `ComponentContract` is pure data: schema, metadata, accessibility, and
+ * design tokens. It has **no `render` field** — rendering is handled by
+ * platform-specific renderer packages (`@enterstellar-ai/react`, `@enterstellar-ai/render-native`, etc.)
+ * per Design Choice R6.
+ *
+ * @see Bible §3.1
+ * @see Design Choices R1–R20, T1, T5, T9, T11
+ */
+
+/**
+ * Predefined component categories.
+ * Extensible via `custom:{name}` prefix for domain-specific categories.
+ *
+ * @see Design Choice R11
+ */
+type ComponentCategory = 'clinical' | 'admin' | 'navigation' | 'data-display' | 'form' | 'feedback' | 'layout' | 'utility' | `custom:${string}`;
+/**
+ * Origin metadata for contracts fetched from federated registries.
+ * Populated when a contract is published or discovered remotely.
+ */
+type ContractOrigin = {
+    /** URL of the remote registry that published this contract. */
+    readonly registryUrl: string;
+    /** Publisher identifier (e.g., org name or developer handle). */
+    readonly publisher: string;
+    /** ISO 8601 timestamp when the contract was verified. */
+    readonly verifiedAt?: string;
+};
+/**
+ * Internal metadata attached to every contract.
+ * Used for DevTools, telemetry, and Forge tracking.
+ */
+type ContractMeta = {
+    /** Whether this contract was generated by the Forge. */
+    readonly forged: boolean;
+    /** Semantic version of the contract definition. */
+    readonly version: string;
+    /** ISO 8601 timestamp when the contract was created. */
+    readonly createdAt: string;
+};
+/**
+ * Accessibility configuration for a component.
+ * Enforced by the compiler's accessibility audit step.
+ */
+type ComponentAccessibility = {
+    /** WAI-ARIA role for the component's root element. */
+    readonly role: string;
+    /** Accessible label describing the component. */
+    readonly ariaLabel: string;
+    /** Whether screen readers should announce dynamic updates. */
+    readonly announceOnUpdate: boolean;
+};
+/**
+ * Data source configuration for adapter-driven data fetching.
+ * Optional — components without a data source receive props directly.
+ */
+type ComponentDataSource = {
+    /** Adapter type used to fetch data (e.g., `'supabase'`, `'firebase'`). */
+    readonly adapter: string;
+    /** The resource/table/collection to query. */
+    readonly resource: string;
+    /** Static query parameters merged with runtime params. */
+    readonly params?: Readonly<Record<string, unknown>>;
+};
+/**
+ * Auth requirements for rendering a component.
+ * When defined, the `AuthAdapter` gates component visibility.
+ */
+type ComponentAuth = {
+    /** Whether the user must be authenticated to view this component. */
+    readonly required: boolean;
+    /** Roles permitted to view this component. Empty = any authenticated user. */
+    readonly roles: readonly string[];
+};
+/**
+ * Example data for a component contract.
+ * Powers the test harness, semantic index warmup, and DevTools previews.
+ *
+ * @see Design Choice R10
+ */
+type ComponentExample = {
+    /** Machine-readable canonical intent query for this component. */
+    readonly intent: string;
+    /** Example props matching the component's schema. */
+    readonly props: Readonly<Record<string, unknown>>;
+};
+/**
+ * Lifecycle state renderers — each component must declare placeholder
+ * content for all four lifecycle states.
+ *
+ * @see Principle L9
+ */
+type ComponentStates = {
+    /** Renderer key or content for the loading state. */
+    readonly loading: string;
+    /** Renderer key or content for the error state. */
+    readonly error: string;
+    /** Renderer key or content for the empty state. */
+    readonly empty: string;
+    /** Renderer key or content for the ready state. */
+    readonly ready: string;
+};
+/**
+ * The canonical data shape for a registered Enterstellar component.
+ *
+ * A `ComponentContract` is the "API surface" of a UI component within the
+ * Enterstellar ecosystem. It declares the component's schema (via Zod), semantics,
+ * accessibility requirements, design tokens, and lifecycle states.
+ *
+ * **Important:** This type has NO `render` field. Rendering is decoupled
+ * from the contract and handled by platform-specific renderers (L15, R6).
+ *
+ * @see Bible §3.1
+ */
+type ComponentContract = {
+    /** PascalCase component name, unique within the registry. */
+    readonly name: string;
+    /** Branded component identifier derived from the name. */
+    readonly id: ComponentId;
+    /** Concise human-readable description. Max 120 characters (R2). */
+    readonly description: string;
+    /** Component category for classification and Forge routing. */
+    readonly category: ComponentCategory;
+    /** Semantic tags for fuzzy matching. Overlap between components is expected (R12). */
+    readonly tags: readonly string[];
+    /**
+     * Zod schema defining the component's prop interface.
+     * Used by the compiler for validation and self-correction.
+     */
+    readonly props: z.ZodType;
+    /** Design tokens referenced by this component. Values are symbolic (e.g., `'token:danger'`). */
+    readonly tokens: Readonly<Record<string, string>>;
+    /** Accessibility configuration. Enforced by the compiler. */
+    readonly accessibility: ComponentAccessibility;
+    /** Lifecycle state renderers. All four states are required (L9). */
+    readonly states: ComponentStates;
+    /** Example data for testing, warmup, and previews. */
+    readonly examples: readonly ComponentExample[];
+    /** Optional data source configuration for adapter-driven fetching. */
+    readonly dataSource?: ComponentDataSource;
+    /** Optional auth requirements for gating component visibility. */
+    readonly auth?: ComponentAuth;
+    /** Optional origin metadata for federated/remote contracts. */
+    readonly origin?: ContractOrigin;
+    /** Internal metadata for DevTools and telemetry. */
+    readonly _meta: ContractMeta;
+};
+/**
+ * Zod schema for validating `ComponentContract` data at runtime.
+ *
+ * Used by consumers to validate contracts fetched from remote registries,
+ * and internally by `@enterstellar-ai/registry` during registration.
+ *
+ * @see Design Choice T7
+ */
+declare const ComponentContractSchema: z.ZodObject<{
+    name: z.ZodString;
+    id: z.ZodString;
+    description: z.ZodString;
+    category: z.ZodString;
+    tags: z.ZodArray<z.ZodString>;
+    props: z.ZodUnknown;
+    tokens: z.ZodRecord<z.ZodString, z.ZodString>;
+    accessibility: z.ZodObject<{
+        role: z.ZodString;
+        ariaLabel: z.ZodString;
+        announceOnUpdate: z.ZodBoolean;
+    }, z.core.$strip>;
+    states: z.ZodObject<{
+        loading: z.ZodString;
+        error: z.ZodString;
+        empty: z.ZodString;
+        ready: z.ZodString;
+    }, z.core.$strip>;
+    examples: z.ZodArray<z.ZodObject<{
+        intent: z.ZodString;
+        props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>;
+    dataSource: z.ZodOptional<z.ZodObject<{
+        adapter: z.ZodString;
+        resource: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+    auth: z.ZodOptional<z.ZodObject<{
+        required: z.ZodBoolean;
+        roles: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    origin: z.ZodOptional<z.ZodObject<{
+        registryUrl: z.ZodURL;
+        publisher: z.ZodString;
+        verifiedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    _meta: z.ZodObject<{
+        forged: z.ZodBoolean;
+        version: z.ZodString;
+        createdAt: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+
+/**
+ * @module @enterstellar-ai/types/token
+ * @description Design token types and resolver interface.
+ *
+ * Design tokens are symbolic references (e.g., `'token:danger'`) that the
+ * compiler validates and the renderer resolves to concrete CSS values at
+ * render time. This keeps contracts platform-agnostic and theme-portable.
+ *
+ * @see Bible §3.1b
+ * @see Design Choices R13, R14
+ * @see Appendix F T3 (W3C DTCG compliance)
+ */
+
+/**
+ * A map of token names to symbolic token values.
+ *
+ * Values follow the `token:{name}` convention (e.g., `'token:danger'`,
+ * `'token:card-bg'`). Actual CSS values are resolved at render time
+ * by the platform-specific `TokenResolver`.
+ *
+ * @see Design Choice R13 — tokens resolved at render time, not registration.
+ * @see Design Choice R14 — no theming in DesignTokenSet; renderer handles themes.
+ */
+type DesignTokenSet = Readonly<Record<string, string>>;
+/**
+ * Zod schema for validating a `DesignTokenSet` at runtime.
+ * Ensures all values are non-empty strings.
+ */
+declare const DesignTokenSetSchema: z.ZodType<Record<string, string>>;
+/**
+ * Contextual information provided to the `TokenResolver` during
+ * token resolution. Enables platform-aware and theme-aware lookups.
+ */
+type TokenResolverContext = {
+    /** Active platform for resolution (e.g., `'web'`, `'native'`, `'desktop'`). */
+    readonly platform?: string;
+    /** Active theme (e.g., `'light'`, `'dark'`). */
+    readonly theme?: string;
+    /** Display density (e.g., `'compact'`, `'comfortable'`, `'spacious'`). */
+    readonly density?: string;
+};
+/**
+ * Resolves symbolic design token paths to concrete CSS (or platform-specific) values.
+ *
+ * Implementations map W3C DTCG-compliant token paths to concrete values
+ * based on the active platform, theme, and density context.
+ *
+ * @see Appendix F T3 — W3C DTCG path mapping.
+ * @see Design Choice R13 — resolution happens at render time.
+ * @see Design Choice R14 — the resolver handles light/dark mode, not the contract.
+ *
+ * @example
+ * ```ts
+ * const resolver: TokenResolver = {
+ *   resolve: (path, ctx) => {
+ *     if (path === 'token:danger') {
+ *       return ctx?.theme === 'dark' ? '#ff4444' : '#ff0000';
+ *     }
+ *     return undefined;
+ *   },
+ *   validate: (path) => path.startsWith('token:'),
+ * };
+ * ```
+ */
+interface TokenResolver {
+    /**
+     * Resolves a token path to a concrete value.
+     *
+     * @param tokenPath - The symbolic token path (e.g., `'token:danger'`).
+     * @param context - Optional resolution context (platform, theme, density).
+     * @returns The resolved concrete value, or `undefined` if the token is unknown.
+     */
+    resolve(tokenPath: string, context?: TokenResolverContext): string | undefined;
+    /**
+     * Validates whether a token path exists in the active token set.
+     *
+     * @param tokenPath - The symbolic token path to validate.
+     * @returns `true` if the token path is known and resolvable.
+     */
+    validate(tokenPath: string): boolean;
+}
+
+/**
+ * @module @enterstellar-ai/types/intent
+ * @description ComponentIntent — the normalized message from an AI agent
+ * to the Enterstellar rendering pipeline.
+ *
+ * A `ComponentIntent` is what the normalizer produces from any protocol
+ * (AG-UI, A2UI, MCP, WebSocket, SSE). It is the universal input to the
+ * compiler.
+ *
+ * @see Bible §3.2
+ * @see Design Choices T3, T11
+ * @see Appendix E P2 (correlationId), P8 (mode, interaction)
+ */
+
+/**
+ * Protocol that produced this intent.
+ * Each normalizer handles one protocol.
+ *
+ * @see Bible §4.9 — Normalizer
+ */
+type IntentProtocol = 'ag-ui' | 'a2ui' | 'mcp' | 'websocket' | 'sse' | 'custom';
+/**
+ * Layout hint for multi-zone rendering.
+ * Used by the resolver to position components within a zone.
+ */
+type IntentLayout = 'single' | 'split' | 'grid' | 'stack' | 'tabs';
+/**
+ * Interaction mode for the component.
+ * Closed enum — 3 values are exhaustive.
+ *
+ * @see Appendix E P8
+ */
+type IntentInteraction = 'read-only' | 'editable' | 'actionable';
+/**
+ * Source metadata injected by the normalizer.
+ * Preserves protocol-specific context for tracing and debugging.
+ */
+type IntentSource = {
+    /** The protocol that produced this intent. */
+    readonly protocol: IntentProtocol;
+    /** Raw event ID from the source protocol, if available. */
+    readonly rawEventId?: string;
+    /**
+     * Correlation ID tying related events across a multi-step interaction chain.
+     * Extracted from the protocol (AG-UI `runId`, MCP `requestId`) or UUIDv4-generated.
+     *
+     * @see Appendix E P2
+     */
+    readonly correlationId?: string;
+    /** Raw payload from the source protocol, preserved for debugging. */
+    readonly raw?: unknown;
+};
+/**
+ * The normalized message from an AI agent to the Enterstellar rendering pipeline.
+ *
+ * Produced by the normalizer from any supported protocol. Consumed by the
+ * compiler for validation, token enforcement, and accessibility auditing.
+ *
+ * @see Bible §3.2
+ */
+type ComponentIntent = {
+    /** PascalCase name of the target component in the registry. */
+    readonly component: string;
+    /** Props to pass to the component, validated by the compiler against the contract schema. */
+    readonly props: Readonly<Record<string, unknown>>;
+    /**
+     * Confidence score from the agent (0.0–1.0).
+     * Used by the compiler for fallback decisions and trace reporting.
+     */
+    readonly confidence: number;
+    /** Optional layout hint for multi-zone rendering. */
+    readonly layout?: IntentLayout;
+    /**
+     * Display mode hint for disambiguation.
+     * Open type — allows domain-specific modes without requiring `@enterstellar-ai/types` releases.
+     * Recommended values: `'snapshot'`, `'time-series'`, `'comparison'`, `'detail'`,
+     * `'summary'`, `'list'`.
+     *
+     * @see Appendix E P8
+     */
+    readonly mode?: string;
+    /**
+     * Interaction mode for the component.
+     * Helps the semantic index disambiguate (e.g., "show vitals" vs "edit vitals").
+     *
+     * @see Appendix E P8
+     */
+    readonly interaction?: IntentInteraction;
+    /** Protocol-specific source metadata injected by the normalizer. */
+    readonly _source?: IntentSource;
+};
+/**
+ * Zod schema for validating `ComponentIntent` data at runtime.
+ *
+ * @see Design Choice T7
+ */
+declare const ComponentIntentSchema: z.ZodObject<{
+    component: z.ZodString;
+    props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    confidence: z.ZodNumber;
+    layout: z.ZodOptional<z.ZodEnum<{
+        split: "split";
+        single: "single";
+        grid: "grid";
+        stack: "stack";
+        tabs: "tabs";
+    }>>;
+    mode: z.ZodOptional<z.ZodString>;
+    interaction: z.ZodOptional<z.ZodEnum<{
+        "read-only": "read-only";
+        editable: "editable";
+        actionable: "actionable";
+    }>>;
+    _source: z.ZodOptional<z.ZodObject<{
+        protocol: z.ZodEnum<{
+            custom: "custom";
+            "ag-ui": "ag-ui";
+            a2ui: "a2ui";
+            mcp: "mcp";
+            websocket: "websocket";
+            sse: "sse";
+        }>;
+        rawEventId: z.ZodOptional<z.ZodString>;
+        correlationId: z.ZodOptional<z.ZodString>;
+        raw: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+
+/**
+ * @module @enterstellar-ai/types/compiler
+ * @description Compilation result types — the output of the Enterstellar UI Compiler.
+ *
+ * After the compiler validates a `ComponentIntent` against its
+ * `ComponentContract`, it produces a `CompilationResult` with provenance,
+ * validation status, and any errors encountered.
+ *
+ * @see Bible §3.3
+ * @see Design Choices C1–C20, T1, T5, T11
+ */
+
+/**
+ * Compilation outcome status.
+ * - `'pass'` — intent validated successfully, component is safe to render.
+ * - `'fail'` — validation failed, fallback should be rendered.
+ * - `'corrected'` — LLM self-correction fixed the original errors.
+ */
+type CompilationStatus = 'pass' | 'fail' | 'corrected';
+/**
+ * Provenance metadata attached to every compilation result.
+ * Tracks the agent, registry, and compiler that produced the result
+ * for auditability and the trust frame.
+ *
+ * @see Design Choice C12 — consumer passes `agent` via explicit parameter.
+ */
+type CompilationProvenance = {
+    /** Identifier of the AI agent/model that generated the intent (e.g., `'gpt-4o'`). */
+    readonly agent: string;
+    /** URL or name of the registry used for component resolution. */
+    readonly registry: string;
+    /** ISO 8601 timestamp when compilation occurred. */
+    readonly compiledAt: string;
+    /** Semantic version of the compiler that produced this result. */
+    readonly compilerVersion: string;
+    /** Forge mode used, if the component was forged. `undefined` for registry components. */
+    readonly forgeMode?: 'local' | 'cloud';
+    /** Origin metadata for the resolved contract, if it came from a remote registry. */
+    readonly contractOrigin?: {
+        /** URL of the originating registry. */
+        readonly registryUrl: string;
+        /** Publisher of the contract. */
+        readonly publisher: string;
+    };
+};
+/**
+ * Machine-readable suggestion for fixing a compilation error.
+ * Enables auto-fix in DevTools, self-correction loops, and CI reporting.
+ *
+ * @see Design Choice C15
+ */
+type CompilationFix = {
+    /** The prop field path that should be changed (e.g., `'tokens.color'`). */
+    readonly field: string;
+    /** The invalid value that was provided. */
+    readonly was: unknown;
+    /** The correct value that should be used instead. */
+    readonly shouldBe: unknown;
+};
+/**
+ * A single compilation error with a machine-readable code, path, and optional fix.
+ *
+ * @see Design Choice C14 — `ENS-2xxx` codes for compiler errors.
+ * @see Design Choice C15 — all errors include a `fix` suggestion where applicable.
+ */
+type CompilationError = {
+    /** Machine-readable error code (e.g., `'ENS-2001'`). */
+    readonly code: string;
+    /** Dot-path to the invalid field (e.g., `'props.riskLevel'`). */
+    readonly path: string;
+    /** Human-readable error message. */
+    readonly message: string;
+    /** The value that was received. */
+    readonly received?: unknown;
+    /** The value that was expected. */
+    readonly expected?: unknown;
+    /** Machine-readable fix suggestion, if applicable. */
+    readonly fix?: CompilationFix;
+};
+/**
+ * The output of the Enterstellar UI Compiler after validating a `ComponentIntent`.
+ *
+ * Contains the resolved component name, validated props, compilation status,
+ * provenance for auditability, and any errors encountered during validation.
+ *
+ * @see Bible §3.3
+ */
+type CompilationResult = {
+    /** PascalCase name of the resolved component. */
+    readonly componentName: string;
+    /** Validated props after schema parsing, token enforcement, and accessibility injection. */
+    readonly props: Readonly<Record<string, unknown>>;
+    /** Compilation outcome status. */
+    readonly status: CompilationStatus;
+    /** Provenance metadata for tracing and the trust frame. */
+    readonly provenance: CompilationProvenance;
+    /** Validation errors encountered during compilation. Empty if `status === 'pass'`. */
+    readonly errors: readonly CompilationError[];
+    /** Number of self-correction attempts made before final result. */
+    readonly selfCorrectionAttempts: number;
+    /**
+     * Diff between raw LLM props and final compiled props.
+     * Included when `includeDiff` config flag is `true` (default in dev, off in prod).
+     *
+     * @see Design Choice C13
+     */
+    readonly diff?: {
+        /** The raw props as received from the agent. */
+        readonly raw: Readonly<Record<string, unknown>>;
+        /** The final compiled props after correction, stripping, and injection. */
+        readonly compiled: Readonly<Record<string, unknown>>;
+    };
+    /**
+     * Correction trace for DevTools and performance profiling.
+     *
+     * Populated when `selfCorrection.trace === true` in the compiler config.
+     * Each entry records a single correction applied by Tier 1 (deterministic)
+     * or Tier 2 (template), including the field, original value, corrected value,
+     * and the strategy used.
+     *
+     * Default: omitted in production. Enabled automatically when DevTools are
+     * attached, or explicitly via `selfCorrection: { trace: true }`.
+     *
+     * @see Design Choice SC-11 — correction trace entry design.
+     * @see Design Choice SC-08 — `trace` flag in `SelfCorrectionConfig`.
+     */
+    readonly correctionTrace?: readonly {
+        /** Which tier applied this correction (`1` = deterministic, `2` = template). */
+        readonly tier: 1 | 2;
+        /** The error code that was corrected (e.g., `'ENS-2001'`). */
+        readonly errorCode: string;
+        /** The field path that was corrected. */
+        readonly field: string;
+        /** The original invalid value. */
+        readonly was: unknown;
+        /** The corrected value. */
+        readonly correctedTo: unknown;
+        /** The correction strategy used (e.g., `'type-coercion'`, `'enum-nearest'`). */
+        readonly strategy: string;
+    }[];
+};
+/**
+ * Zod schema for validating a `CompilationError` at runtime.
+ *
+ * @see Design Choice T7
+ */
+declare const CompilationErrorSchema: z.ZodObject<{
+    code: z.ZodString;
+    path: z.ZodString;
+    message: z.ZodString;
+    received: z.ZodOptional<z.ZodUnknown>;
+    expected: z.ZodOptional<z.ZodUnknown>;
+    fix: z.ZodOptional<z.ZodObject<{
+        field: z.ZodString;
+        was: z.ZodUnknown;
+        shouldBe: z.ZodUnknown;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Zod schema for validating a `CompilationResult` at runtime.
+ *
+ * @see Design Choice T7
+ */
+declare const CompilationResultSchema: z.ZodObject<{
+    componentName: z.ZodString;
+    props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    status: z.ZodEnum<{
+        pass: "pass";
+        fail: "fail";
+        corrected: "corrected";
+    }>;
+    provenance: z.ZodObject<{
+        agent: z.ZodString;
+        registry: z.ZodString;
+        compiledAt: z.ZodString;
+        compilerVersion: z.ZodString;
+        forgeMode: z.ZodOptional<z.ZodEnum<{
+            cloud: "cloud";
+            local: "local";
+        }>>;
+        contractOrigin: z.ZodOptional<z.ZodObject<{
+            registryUrl: z.ZodString;
+            publisher: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    errors: z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        path: z.ZodString;
+        message: z.ZodString;
+        received: z.ZodOptional<z.ZodUnknown>;
+        expected: z.ZodOptional<z.ZodUnknown>;
+        fix: z.ZodOptional<z.ZodObject<{
+            field: z.ZodString;
+            was: z.ZodUnknown;
+            shouldBe: z.ZodUnknown;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    selfCorrectionAttempts: z.ZodNumber;
+    diff: z.ZodOptional<z.ZodObject<{
+        raw: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        compiled: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>;
+    correctionTrace: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        tier: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>;
+        errorCode: z.ZodString;
+        field: z.ZodString;
+        was: z.ZodUnknown;
+        correctedTo: z.ZodUnknown;
+        strategy: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+
+/**
+ * @module @enterstellar-ai/types/trace
+ * @description AgentTrace — the observability record for every Enterstellar pipeline execution.
+ *
+ * Every intent processed by Enterstellar produces an `AgentTrace` capturing intent,
+ * resolution, compilation, determinism, and performance metrics. Traces power
+ * the DevTools timeline, validation log, and performance profiler.
+ *
+ * @see Bible §3.4
+ * @see Design Choices T5, T11
+ * @see Appendix E P2 (correlationId), consent fields
+ */
+
+/**
+ * Intent data captured in the trace.
+ * Records what the agent requested.
+ */
+type TraceIntent = {
+    /** Raw intent string or component name from the agent. */
+    readonly raw: string;
+    /** Parsed component name after normalization. */
+    readonly component: string;
+    /** Confidence score from the agent (0.0–1.0). */
+    readonly confidence: number;
+    /** Display mode, if provided. */
+    readonly mode?: string;
+    /** Interaction type, if provided. */
+    readonly interaction?: string;
+};
+/**
+ * Resolution data captured in the trace.
+ * Records how the intent was resolved to a component.
+ */
+type TraceResolution = {
+    /** How the component was resolved. */
+    readonly strategy: 'exact' | 'semantic' | 'forge' | 'fallback';
+    /** Name of the resolved component. */
+    readonly resolvedComponent: string;
+    /** Semantic similarity score, if semantic search was used. */
+    readonly similarityScore?: number;
+    /** Number of candidate components considered before selection. */
+    readonly candidatesConsidered: number;
+};
+/**
+ * Compilation data captured in the trace.
+ * Records the compiler's validation outcome.
+ */
+type TraceCompilation = {
+    /** Final compilation status. */
+    readonly status: 'pass' | 'fail' | 'corrected';
+    /** Number of validation errors encountered (including self-corrected ones). */
+    readonly errorCount: number;
+    /** Number of self-correction attempts made. */
+    readonly selfCorrectionAttempts: number;
+    /** Whether design token enforcement was applied. */
+    readonly tokensValidated: boolean;
+    /** Whether accessibility attributes were auto-injected. */
+    readonly accessibilityInjected: boolean;
+};
+/**
+ * Determinism data captured in the trace.
+ * Records the zone's determinism configuration at render time.
+ */
+type TraceDeterminism = {
+    /** Zone determinism level (0.0–1.0). */
+    readonly level: number;
+    /** Whether a cached result was used. */
+    readonly cacheHit: boolean;
+    /** The zone name this trace belongs to. */
+    readonly zone: string;
+};
+/**
+ * Performance metrics captured in the trace.
+ * Powers the DevTools performance profiler.
+ */
+type TraceMetrics = {
+    /** Total pipeline latency in milliseconds (intent → rendered). */
+    readonly totalMs: number;
+    /** Time from intent reception to resolution in milliseconds. */
+    readonly resolutionMs: number;
+    /** Time from resolution to compilation completion in milliseconds. */
+    readonly compilationMs: number;
+    /** Time from compilation to rendered output in milliseconds. */
+    readonly renderMs: number;
+};
+/**
+ * User consent state for trace aggregation.
+ * Required for Enterstellar Cloud's trace aggregation API (opt-in).
+ *
+ * @see Appendix E — TL10 (ForgeSignal vs AgentTrace consent distinction)
+ */
+type TraceConsent = {
+    /** Whether this trace can be aggregated anonymously for analytics. */
+    readonly anonymizedAggregation: boolean;
+};
+/**
+ * Partial trace produced by `Zone` during compilation.
+ *
+ * `ZoneTrace` captures what the zone actually has at compile time:
+ * intent, compilation status/errors, provenance, and zone-level metrics.
+ * It does NOT include `resolution`, `determinism`, or `consent` fields —
+ * those require the full compiler/lifecycle pipeline to produce.
+ *
+ * The fully resolved `AgentTrace` is assembled downstream by
+ * `@enterstellar-ai/lifecycle` when all pipeline stages are complete.
+ *
+ * @see {@link AgentTrace} — the fully resolved trace with all pipeline stages.
+ * @see Bible §5.3 — Zone specification.
+ * @see Design Choice RE18 — `onError` callback receives this trace type.
+ */
+type ZoneTrace = {
+    /** Unique zone-trace identifier (format: `{zoneName}-{compilationId}-{timestamp}`). */
+    readonly id: string;
+    /** The raw `ComponentIntent` that triggered compilation. */
+    readonly intent: ComponentIntent;
+    /**
+     * Compilation outcome data — status, errors, and self-correction attempts.
+     * This is a subset of the full `TraceCompilation` shape.
+     */
+    readonly compilation: {
+        /** Final compilation status (`pass`, `fail`, or `corrected`). */
+        readonly status: CompilationStatus;
+        /** Validation errors encountered during compilation. */
+        readonly errors: readonly CompilationError[];
+        /** Number of self-correction attempts made before final result. */
+        readonly selfCorrectionAttempts: number;
+    };
+    /** Provenance metadata from the `CompilationResult`. */
+    readonly provenance: CompilationProvenance;
+    /**
+     * Zone-level performance metrics.
+     *
+     * Unlike `TraceMetrics` (which breaks down resolution/compilation/render),
+     * this only captures total latency and retry attempt count.
+     */
+    readonly metrics: {
+        /** Total time from intent reception to render in milliseconds. */
+        readonly totalMs: number;
+        /** Current retry attempt number (0-indexed). */
+        readonly retryAttempt: number;
+    };
+    /** ISO 8601 timestamp when this trace was created. */
+    readonly timestamp: string;
+};
+/**
+ * Zod schema for validating a `ZoneTrace` at runtime.
+ *
+ * This is the **canonical single-source-of-truth** for `ZoneTrace` validation.
+ * Used by:
+ * - `Provider` to register the `'traces'` store extension (S2).
+ * - DevTools for trace data integrity validation.
+ * - Tests for fixture construction.
+ *
+ * The schema reuses `ComponentIntentSchema` and `CompilationErrorSchema`
+ * from their respective modules (T7: co-located schemas, no duplication).
+ *
+ * @see Design Choice T7 — every type has a co-located Zod schema.
+ * @see Design Choice S2 — typed `store.extend()` requires a Zod schema.
+ * @see {@link ZoneTrace} — the TypeScript type this schema validates.
+ */
+declare const ZoneTraceSchema: z.ZodObject<{
+    id: z.ZodString;
+    intent: z.ZodObject<{
+        component: z.ZodString;
+        props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        confidence: z.ZodNumber;
+        layout: z.ZodOptional<z.ZodEnum<{
+            split: "split";
+            single: "single";
+            grid: "grid";
+            stack: "stack";
+            tabs: "tabs";
+        }>>;
+        mode: z.ZodOptional<z.ZodString>;
+        interaction: z.ZodOptional<z.ZodEnum<{
+            "read-only": "read-only";
+            editable: "editable";
+            actionable: "actionable";
+        }>>;
+        _source: z.ZodOptional<z.ZodObject<{
+            protocol: z.ZodEnum<{
+                custom: "custom";
+                "ag-ui": "ag-ui";
+                a2ui: "a2ui";
+                mcp: "mcp";
+                websocket: "websocket";
+                sse: "sse";
+            }>;
+            rawEventId: z.ZodOptional<z.ZodString>;
+            correlationId: z.ZodOptional<z.ZodString>;
+            raw: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    compilation: z.ZodObject<{
+        status: z.ZodEnum<{
+            pass: "pass";
+            fail: "fail";
+            corrected: "corrected";
+        }>;
+        errors: z.ZodArray<z.ZodObject<{
+            code: z.ZodString;
+            path: z.ZodString;
+            message: z.ZodString;
+            received: z.ZodOptional<z.ZodUnknown>;
+            expected: z.ZodOptional<z.ZodUnknown>;
+            fix: z.ZodOptional<z.ZodObject<{
+                field: z.ZodString;
+                was: z.ZodUnknown;
+                shouldBe: z.ZodUnknown;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        selfCorrectionAttempts: z.ZodNumber;
+    }, z.core.$strip>;
+    provenance: z.ZodObject<{
+        agent: z.ZodString;
+        registry: z.ZodString;
+        compiledAt: z.ZodString;
+        compilerVersion: z.ZodString;
+        forgeMode: z.ZodOptional<z.ZodEnum<{
+            cloud: "cloud";
+            local: "local";
+        }>>;
+        contractOrigin: z.ZodOptional<z.ZodObject<{
+            registryUrl: z.ZodString;
+            publisher: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    metrics: z.ZodObject<{
+        totalMs: z.ZodNumber;
+        retryAttempt: z.ZodNumber;
+    }, z.core.$strip>;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+/**
+ * The complete observability record for a single Enterstellar pipeline execution.
+ *
+ * Produced on every `compile()` call. Stored in `EnterstellarStore.traces[]`.
+ * Consumed by DevTools (timeline, inspector, profiler, replay) and
+ * optionally by Enterstellar Cloud for aggregated analytics.
+ *
+ * @see Bible §3.4
+ * @see {@link ZoneTrace} — the zone-level precursor trace produced by `Zone`.
+ */
+type AgentTrace = {
+    /** Unique trace identifier. */
+    readonly id: TraceId;
+    /** ISO 8601 timestamp when the trace was created. */
+    readonly timestamp: string;
+    /**
+     * Correlation ID tying related events across a multi-step interaction chain.
+     * Enables DevTools Trace Timeline to group related events.
+     *
+     * @see Appendix E P2
+     */
+    readonly correlationId?: string;
+    /** Intent data: what the agent requested. */
+    readonly intent: TraceIntent;
+    /** Resolution data: how the component was found. */
+    readonly resolution: TraceResolution;
+    /** Compilation data: the compiler's validation outcome. */
+    readonly compilation: TraceCompilation;
+    /** Determinism data: the zone's configuration at render time. */
+    readonly determinism: TraceDeterminism;
+    /** Performance metrics: latency breakdown. */
+    readonly metrics: TraceMetrics;
+    /** User consent state for trace aggregation. */
+    readonly consent: TraceConsent;
+};
+/**
+ * Zod schema for validating an `AgentTrace` at runtime.
+ *
+ * @see Design Choice T7
+ */
+declare const AgentTraceSchema: z.ZodObject<{
+    id: z.ZodString;
+    timestamp: z.ZodString;
+    correlationId: z.ZodOptional<z.ZodString>;
+    intent: z.ZodObject<{
+        raw: z.ZodString;
+        component: z.ZodString;
+        confidence: z.ZodNumber;
+        mode: z.ZodOptional<z.ZodString>;
+        interaction: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    resolution: z.ZodObject<{
+        strategy: z.ZodEnum<{
+            forge: "forge";
+            exact: "exact";
+            semantic: "semantic";
+            fallback: "fallback";
+        }>;
+        resolvedComponent: z.ZodString;
+        similarityScore: z.ZodOptional<z.ZodNumber>;
+        candidatesConsidered: z.ZodNumber;
+    }, z.core.$strip>;
+    compilation: z.ZodObject<{
+        status: z.ZodEnum<{
+            pass: "pass";
+            fail: "fail";
+            corrected: "corrected";
+        }>;
+        errorCount: z.ZodNumber;
+        selfCorrectionAttempts: z.ZodNumber;
+        tokensValidated: z.ZodBoolean;
+        accessibilityInjected: z.ZodBoolean;
+    }, z.core.$strip>;
+    determinism: z.ZodObject<{
+        level: z.ZodNumber;
+        cacheHit: z.ZodBoolean;
+        zone: z.ZodString;
+    }, z.core.$strip>;
+    metrics: z.ZodObject<{
+        totalMs: z.ZodNumber;
+        resolutionMs: z.ZodNumber;
+        compilationMs: z.ZodNumber;
+        renderMs: z.ZodNumber;
+    }, z.core.$strip>;
+    consent: z.ZodObject<{
+        anonymizedAggregation: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+
+/**
+ * @module @enterstellar-ai/types/config
+ * @description ZoneConfig — configuration for an Zone instance.
+ *
+ * A `ZoneConfig` defines the behavior, constraints, and rendering rules
+ * for a specific Zone. The `determinism` dial (0.0–1.0) controls
+ * how much AI influence the zone allows.
+ *
+ * @see Bible §3.5
+ * @see Design Choices T13 (determinism as raw number), RE5–RE8
+ */
+
+/**
+ * Cache configuration for a zone.
+ * Controls whether and how the zone caches compiled results.
+ */
+type ZoneCacheConfig = {
+    /** Whether caching is enabled for this zone. */
+    readonly enabled: boolean;
+    /** Time-to-live for cached entries in seconds. Default: 3600. */
+    readonly ttl: number;
+};
+/**
+ * Configuration for an Zone instance.
+ *
+ * The `determinism` value is the primary control:
+ * - `0.0` → fully static, agent never called (compliance zones)
+ * - `0.0–1.0` → hybrid: fixed layout with agent-selected components in slots
+ * - `1.0` → fully dynamic, agent controls everything in the zone
+ *
+ * @see Bible §3.5
+ * @see Design Choice T13 — raw number with Zod validation, not branded type.
+ */
+type ZoneConfig = {
+    /** Branded zone identifier. */
+    readonly id: ZoneId;
+    /** Human-readable zone name (e.g., `'patient-sidebar'`). */
+    readonly name: string;
+    /**
+     * Determinism level (0.0–1.0).
+     * Controls AI influence over the zone's content.
+     *
+     * @see Design Choice T13 — validated via `z.number().min(0).max(1)`.
+     */
+    readonly determinism: number;
+    /** Whitelist of component names allowed in this zone. Empty = all allowed. */
+    readonly allowedComponents: readonly string[];
+    /** Fallback component name to render when the agent fails or times out. */
+    readonly fallbackComponent: string;
+    /** Maximum time in milliseconds to wait for the agent before rendering fallback. */
+    readonly agentTimeoutMs: number;
+    /** Cache configuration for this zone. */
+    readonly cache: ZoneCacheConfig;
+    /**
+     * Zone activation strategy.
+     * - `'mount'` — call agent on component mount (default).
+     * - `'visible'` — call agent when zone enters viewport (IntersectionObserver).
+     * - `'manual'` — consumer calls `zone.activate()` programmatically.
+     *
+     * @see Design Choice RE6
+     */
+    readonly activateOn: 'mount' | 'visible' | 'manual';
+};
+/**
+ * Zod schema for validating `ZoneConfig` data at runtime.
+ *
+ * @see Design Choice T7, T13
+ */
+declare const ZoneConfigSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    determinism: z.ZodNumber;
+    allowedComponents: z.ZodArray<z.ZodString>;
+    fallbackComponent: z.ZodString;
+    agentTimeoutMs: z.ZodNumber;
+    cache: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        ttl: z.ZodNumber;
+    }, z.core.$strip>;
+    activateOn: z.ZodEnum<{
+        mount: "mount";
+        visible: "visible";
+        manual: "manual";
+    }>;
+}, z.core.$strip>;
+
+/**
+ * @module @enterstellar-ai/types/adapters
+ * @description Adapter interfaces for infrastructure integration.
+ *
+ * Adapters provide the bridge between Enterstellar components and external services
+ * (auth, data, errors, analytics). Each adapter follows a strict interface
+ * defined here — implementations live in `@enterstellar-ai/adapter-*` packages.
+ *
+ * @see Bible §3.6
+ * @see Design Choice T1 — interfaces for objects with methods.
+ */
+/**
+ * Authentication adapter interface.
+ *
+ * Implementations gate component visibility based on auth state.
+ * Three methods: `getSession()` for current state, `hasRole()` for
+ * RBAC (clinical vs admin zones), and `onAuthChange()` for reactive
+ * auth gating — zones re-evaluate visibility when sessions expire
+ * or roles change.
+ *
+ * `signIn()`/`signOut()` are NOT adapter concerns — they belong to
+ * the auth provider (Supabase, Clerk, Firebase, etc.).
+ *
+ * @see Bible §3.6
+ * @see Design Choice AD1
+ */
+interface AuthAdapter {
+    /**
+     * Gets the current authentication session, if any.
+     *
+     * @returns Session object with user ID and roles, or `null` if unauthenticated.
+     */
+    getSession(): Promise<{
+        userId: string;
+        roles: string[];
+    } | null>;
+    /**
+     * Checks whether the current user has a specific role.
+     * Essential for RBAC — determines clinical vs admin zone visibility.
+     *
+     * @param role - The role to check for (e.g., `'clinician'`, `'admin'`).
+     * @returns `true` if the user has the role.
+     */
+    hasRole(role: string): Promise<boolean>;
+    /**
+     * Subscribes to authentication state changes.
+     *
+     * Essential for reactive auth gating — zones re-evaluate visibility
+     * when sessions expire or roles change. Every major auth provider
+     * supports this: Supabase `onAuthStateChange()`, Firebase
+     * `onAuthStateChanged()`, Clerk `addListener()`.
+     *
+     * @param callback - Called when auth state changes. Receives the new
+     *   session object, or `null` if the user became unauthenticated.
+     * @returns An unsubscribe function (synchronous).
+     *
+     * @example
+     * ```ts
+     * const unsubscribe = auth.onAuthChange((session) => {
+     *   if (!session) console.log('User signed out');
+     * });
+     * // Later: unsubscribe();
+     * ```
+     */
+    onAuthChange(callback: (session: {
+        userId: string;
+        roles: string[];
+    } | null) => void): () => void;
+}
+/**
+ * Data access adapter interface.
+ * Implementations resolve component `dataSource` fields to actual data.
+ *
+ * @see Bible §3.6
+ */
+interface DataAdapter {
+    /**
+     * Queries a resource by name with optional parameters.
+     *
+     * @param resource - The resource/table/collection to query.
+     * @param params - Optional query parameters (filters, pagination, sorting).
+     * @returns The query result as an array of records.
+     */
+    query(resource: string, params?: Readonly<Record<string, unknown>>): Promise<readonly Record<string, unknown>[]>;
+    /**
+     * Performs a mutation (create, update, delete) on a resource.
+     *
+     * @param resource - The resource to mutate.
+     * @param action - The mutation type (`'create'`, `'update'`, `'delete'`).
+     * @param data - The mutation payload.
+     * @returns The mutated record, or `null` for deletes.
+     */
+    mutate(resource: string, action: 'create' | 'update' | 'delete', data: Readonly<Record<string, unknown>>): Promise<Record<string, unknown> | null>;
+    /**
+     * Subscribes to real-time changes on a resource.
+     *
+     * @param resource - The resource to subscribe to.
+     * @param callback - Called when the resource changes.
+     * @returns An unsubscribe function.
+     */
+    subscribe(resource: string, callback: (data: readonly Record<string, unknown>[]) => void): () => void;
+}
+/**
+ * Error handling adapter interface.
+ *
+ * Implementations provide error reporting, retry logic, and PII sanitization.
+ * All methods are async per AD2 — even `shouldRetry` and `sanitize` which
+ * may seem synchronous in simple implementations, but production adapters
+ * may require remote circuit breaker checks or external PII detection
+ * services (Google DLP, AWS Comprehend, Microsoft Presidio).
+ *
+ * @see Bible §3.6
+ * @see Design Choice AD2
+ */
+interface ErrorAdapter {
+    /**
+     * Reports an error to the external error tracking service.
+     *
+     * @param error - The error to report (may be an `EnterstellarError`).
+     * @param context - Optional contextual metadata for the error report.
+     */
+    report(error: Error, context?: Readonly<Record<string, unknown>>): Promise<void>;
+    /**
+     * Determines whether a failed operation should be retried.
+     *
+     * Async to support production implementations that consult remote
+     * circuit breakers (LaunchDarkly, Unleash) or rate-limit services
+     * before deciding whether to retry.
+     *
+     * @param error - The error that caused the failure.
+     * @param attemptNumber - The current retry attempt (1-based).
+     * @returns `true` if the operation should be retried.
+     */
+    shouldRetry(error: Error, attemptNumber: number): Promise<boolean>;
+    /**
+     * Sanitizes an error before it is logged or displayed.
+     * Strips any PII or sensitive data from the error message and stack.
+     *
+     * Async to support production implementations that call external
+     * PII detection services (Google DLP, AWS Comprehend Medical)
+     * for HIPAA-compliant sanitization.
+     *
+     * @param error - The error to sanitize.
+     * @returns A sanitized copy of the error.
+     */
+    sanitize(error: Error): Promise<Error>;
+}
+/**
+ * Analytics adapter interface.
+ * Implementations forward user interaction events to analytics services.
+ *
+ * @see Bible §3.6
+ */
+interface AnalyticsAdapter {
+    /**
+     * Tracks a named event with optional properties.
+     *
+     * @param event - The event name (e.g., `'zone_rendered'`, `'intent_resolved'`).
+     * @param properties - Optional event properties for segmentation.
+     */
+    track(event: string, properties?: Readonly<Record<string, unknown>>): void;
+    /**
+     * Identifies the current user for analytics attribution.
+     *
+     * @param userId - Unique user identifier.
+     * @param traits - Optional user traits (role, plan, etc.).
+     */
+    identify(userId: string, traits?: Readonly<Record<string, unknown>>): void;
+}
+
+/**
+ * @module @enterstellar-ai/types/telemetry
+ * @description ForgeSignal — the mandatory telemetry payload for every compilation.
+ *
+ * ForgeSignals are the atomic unit of the ForgeSignal Corpus (M2 moat).
+ * They contain ZERO PII — only hashed intents, component names, and metrics.
+ * Every render emits a ForgeSignal; this is non-negotiable (L12).
+ *
+ * @see Bible §3.7
+ * @see Design Choices TL1–TL12, T12
+ * @see Principle L12
+ */
+
+/**
+ * Classification of the intent that produced this signal.
+ * Fixed set — not consumer-extensible. Updated only in `@enterstellar-ai/types` releases.
+ *
+ * @see Design Choice T12
+ */
+type IntentCategory = 'clinical' | 'admin' | 'navigation' | 'data-display' | 'form' | 'feedback' | 'utility';
+/**
+ * Forge mode that generated the component (if forged).
+ * `'none'` indicates the component came from the registry (no forge).
+ */
+type ForgeMode = 'none' | 'local' | 'cloud';
+/**
+ * Platform that produced this signal.
+ * Auto-set by the renderer package — never consumer-configured (P9).
+ */
+type SignalPlatform = 'web' | 'native' | 'desktop' | 'cli' | 'unknown';
+/**
+ * The mandatory telemetry payload emitted after every Enterstellar compilation.
+ *
+ * ForgeSignals are the training data for the Intent Router (M4) and
+ * Forge Model (M5). They power the self-reinforcing data flywheel.
+ *
+ * **PII policy:** Zero PII. The `intentHash` is a SHA-256 of the raw intent —
+ * the raw string never leaves the device.
+ *
+ * @see Bible §3.7
+ * @see Design Choice TL3 — hashing happens in `record()`, not caller.
+ */
+type ForgeSignal = {
+    /** SHA-256 hash of the raw intent string. No PII. */
+    readonly intentHash: string;
+    /** PascalCase name of the resolved component. */
+    readonly componentName: string;
+    /** Classification of the intent. */
+    readonly intentCategory: IntentCategory;
+    /** Whether compilation passed, failed, or was corrected. */
+    readonly compilationStatus: 'pass' | 'fail' | 'corrected';
+    /** Whether the Forge was used, and which mode. */
+    readonly forgeMode: ForgeMode;
+    /** Whether the Forge was invoked at all. */
+    readonly forgeUsed: boolean;
+    /** Total pipeline latency from intent to rendered output, in milliseconds. */
+    readonly latencyMs: number;
+    /** Number of self-correction attempts before final result. */
+    readonly selfCorrectionAttempts: number;
+    /**
+     * Token usage for self-correction calls, if any.
+     * Tracked for cost observability, not enforced with a hard budget (C7).
+     */
+    readonly correctionTokensUsed: number;
+    /** ISO 8601 timestamp when the signal was recorded. */
+    readonly timestamp: string;
+    /** Semantic version of the Enterstellar SDK that produced this signal. */
+    readonly sdkVersion: string;
+    /** Number of components in the registry at the time of this signal. */
+    readonly registrySize: number;
+    /** Platform that produced this signal. */
+    readonly platform: SignalPlatform;
+};
+/**
+ * Zod schema for validating a `ForgeSignal` at runtime.
+ *
+ * @see Design Choice T7
+ */
+declare const ForgeSignalSchema: z.ZodObject<{
+    intentHash: z.ZodString;
+    componentName: z.ZodString;
+    intentCategory: z.ZodEnum<{
+        clinical: "clinical";
+        admin: "admin";
+        navigation: "navigation";
+        "data-display": "data-display";
+        form: "form";
+        feedback: "feedback";
+        utility: "utility";
+    }>;
+    compilationStatus: z.ZodEnum<{
+        pass: "pass";
+        fail: "fail";
+        corrected: "corrected";
+    }>;
+    forgeMode: z.ZodEnum<{
+        cloud: "cloud";
+        local: "local";
+        none: "none";
+    }>;
+    forgeUsed: z.ZodBoolean;
+    latencyMs: z.ZodNumber;
+    selfCorrectionAttempts: z.ZodNumber;
+    correctionTokensUsed: z.ZodNumber;
+    timestamp: z.ZodString;
+    sdkVersion: z.ZodString;
+    registrySize: z.ZodNumber;
+    platform: z.ZodEnum<{
+        cli: "cli";
+        unknown: "unknown";
+        web: "web";
+        native: "native";
+        desktop: "desktop";
+    }>;
+}, z.core.$strip>;
+
+/**
+ * @module @enterstellar-ai/types/state
+ * @description EnterstellarStore — the framework-agnostic persistent state container.
+ *
+ * The EnterstellarStore is the "OS's memory." It holds zone state, trace history,
+ * and session metadata. It is a pure TypeScript interface with zero
+ * framework dependencies (L15).
+ *
+ * @see Bible §3.8
+ * @see Design Choices S1–S15, T1, T5
+ * @see Appendix E P3 (threadId)
+ * @see Appendix D Ruling 3
+ */
+
+/**
+ * State of a single zone within the store.
+ * Auto-populated when an `Zone` mounts (S15).
+ */
+type ZoneState = {
+    /** Zone name. */
+    readonly name: string;
+    /** Current lifecycle state. */
+    readonly lifecycleState: 'loading' | 'ready' | 'streaming' | 'error' | 'empty';
+    /** Determinism level at mount time. */
+    readonly determinism: number;
+    /** Last compiled component name, if any. */
+    readonly lastComponent?: string;
+    /** ISO 8601 timestamp of the last update. */
+    readonly lastUpdated: string;
+};
+/**
+ * Session metadata within the store.
+ * Ephemeral session data + optional persistent `threadId`.
+ */
+type SessionState = {
+    /** Ephemeral session ID generated on app mount. Lost on refresh. */
+    readonly id: string;
+    /**
+     * Persistent conversation thread ID that survives across sessions.
+     * Passed via `<Provider threadId="...">`.
+     * When `undefined`, Enterstellar operates in stateless mode (no conversation resumption).
+     *
+     * @see Appendix E P3
+     */
+    readonly threadId?: string;
+    /** ISO 8601 timestamp when the session started. */
+    readonly startedAt: string;
+};
+/**
+ * Serializable representation of the full store state.
+ * Produced by `snapshot()`, consumed by `restore()`.
+ */
+type SerializedState = {
+    /** Semver string for schema versioning (e.g., `"1.0.0"`). */
+    readonly schemaVersion: string;
+    /** Zone state map, keyed by zone name. */
+    readonly zones: Readonly<Record<string, ZoneState>>;
+    /** Trace ID history (most recent first). */
+    readonly traceIds: readonly string[];
+    /** Session metadata. */
+    readonly session: SessionState;
+    /** Extension data from `store.extend()`. Keyed by extension name. */
+    readonly extensions: Readonly<Record<string, unknown>>;
+};
+/**
+ * Configuration for a store state migration.
+ * Migrations chain sequentially from older versions to current.
+ *
+ * @see Design Choice S5 (amended v2)
+ */
+type MigrationConfig = {
+    /** Source schema version (semver). */
+    readonly from: string;
+    /** Target schema version (semver). */
+    readonly to: string;
+    /** Migration function that transforms the state. */
+    readonly migrate: (state: SerializedState) => SerializedState;
+};
+/**
+ * Persistence strategy for the store.
+ * Determines where state is stored between sessions.
+ *
+ * @see Design Choices S5–S7
+ */
+type PersistenceStrategy = 'memory' | 'local-storage' | 'indexed-db' | 'custom';
+/**
+ * Configuration for cross-device state sync.
+ *
+ * @see Design Choices S9–S12
+ */
+type SyncConfig = {
+    /** Whether sync is enabled. */
+    readonly enabled: boolean;
+    /** Endpoint URL for state synchronization. */
+    readonly endpoint: string;
+    /** Sync debounce interval in milliseconds. Default: 100ms. */
+    readonly debounceMs: number;
+};
+/**
+ * Framework-agnostic persistent state container — the OS's memory.
+ *
+ * This is an **interface** (not a type) because it has methods.
+ * Implementations are provided by `@enterstellar-ai/state` (`createEnterstellarStore()`).
+ * React binding is provided by `@enterstellar-ai/react` (`useEnterstellarStore()` hook via
+ * `useSyncExternalStore`).
+ *
+ * @see Bible §3.8
+ * @see Design Choice T1 — interfaces for objects with methods.
+ * @see Design Choice S1 — single global store per app.
+ */
+interface EnterstellarStore {
+    /**
+     * Gets a value from the store by key.
+     * In development mode, validates against the registered Zod schema.
+     *
+     * @param key - The store key to read.
+     * @returns The stored value, or `undefined` if not found.
+     *
+     * @see Design Choice S3
+     */
+    get<T = unknown>(key: string): T | undefined;
+    /**
+     * Sets a value in the store.
+     * Updates memory immediately; persistence is write-behind (debounced, S8).
+     * Fires subscriptions only on actual value change (shallow equality, S4).
+     *
+     * @param key - The store key to write.
+     * @param value - The value to store.
+     */
+    set(key: string, value: unknown): void;
+    /**
+     * Subscribes to store changes.
+     * Callback fires only on actual value change (shallow equality check, S4).
+     *
+     * @param callback - Called when any store value changes.
+     * @returns An unsubscribe function.
+     */
+    subscribe(callback: () => void): () => void;
+    /**
+     * Extends the store with a named, schema-validated section.
+     * Prevents untyped global state.
+     *
+     * The `schema` parameter is intentionally `z.ZodType` (unparameterized)
+     * to allow consumers to register any valid Zod schema shape.
+     *
+     * @param name - Extension name (e.g., `'preferences'`).
+     * @param schema - Zod schema for the extension's value shape.
+     *
+     * @see Design Choice S2
+     */
+    extend(name: string, schema: z.ZodType): void;
+    /**
+     * Checks whether a named extension has been registered via `extend()`.
+     *
+     * Use this to guard idempotent extension registration in components that
+     * may mount multiple times (e.g., `Provider` re-renders). This method
+     * returns `true` only for extension keys — fixed schema keys (`zones`,
+     * `traceIds`, `session`) are NOT considered extensions and always return
+     * `false`.
+     *
+     * @param name - Extension name to check (e.g., `'traces'`, `'preferences'`).
+     * @returns `true` if `extend(name, schema)` was previously called for this name.
+     *
+     * @example
+     * ```ts
+     * if (!store.hasExtension('traces')) {
+     *   store.extend('traces', z.array(ZoneTraceSchema));
+     * }
+     * ```
+     *
+     * @see Design Choice S2 — typed extension point.
+     */
+    hasExtension(name: string): boolean;
+    /**
+     * Serializes the entire store state for cross-device transfer.
+     * Zone configs only — NOT render trees (S9, max 1MB).
+     *
+     * @returns A `SerializedState` snapshot with `schemaVersion`.
+     * @throws {EnterstellarError} If state exceeds 1MB (ENS-4006).
+     */
+    snapshot(): SerializedState;
+    /**
+     * Restores state from a snapshot. Full overwrite, not merge (S10).
+     * Applies chained migrations if snapshot version is older.
+     * Hard-rejects major version forward jumps (ENS-4007).
+     *
+     * @param state - The serialized state to restore.
+     * @throws {EnterstellarError} If major version is ahead (ENS-4007).
+     *
+     * @see Design Choice S5 (amended v2)
+     */
+    restore(state: SerializedState): void;
+    /**
+     * Registers a migration for handling older state snapshots.
+     *
+     * @param config - Migration config with `from`, `to`, and `migrate` function.
+     */
+    registerMigration(config: MigrationConfig): void;
+    /**
+     * Returns the full store snapshot for `useSyncExternalStore` compatibility.
+     * React's `useSyncExternalStore` requires a `getSnapshot` function.
+     */
+    getSnapshot(): SerializedState;
+    /**
+     * Destroys the store, clearing all state and subscriptions.
+     * Called when `Provider` unmounts.
+     */
+    destroy(): void;
+}
+/**
+ * Zod schema for validating `ZoneState` at runtime.
+ *
+ * @see Design Choice T7
+ */
+declare const ZoneStateSchema: z.ZodObject<{
+    name: z.ZodString;
+    lifecycleState: z.ZodEnum<{
+        error: "error";
+        loading: "loading";
+        empty: "empty";
+        ready: "ready";
+        streaming: "streaming";
+    }>;
+    determinism: z.ZodNumber;
+    lastComponent: z.ZodOptional<z.ZodString>;
+    lastUpdated: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Zod schema for validating `SessionState` at runtime.
+ *
+ * @see Design Choice T7
+ */
+declare const SessionStateSchema: z.ZodObject<{
+    id: z.ZodString;
+    threadId: z.ZodOptional<z.ZodString>;
+    startedAt: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Zod schema for validating `SerializedState` at runtime.
+ * Used by `restore()` to validate snapshots before applying.
+ *
+ * @see Design Choice T7, S5
+ */
+declare const SerializedStateSchema: z.ZodObject<{
+    schemaVersion: z.ZodString;
+    zones: z.ZodRecord<z.ZodString, z.ZodObject<{
+        name: z.ZodString;
+        lifecycleState: z.ZodEnum<{
+            error: "error";
+            loading: "loading";
+            empty: "empty";
+            ready: "ready";
+            streaming: "streaming";
+        }>;
+        determinism: z.ZodNumber;
+        lastComponent: z.ZodOptional<z.ZodString>;
+        lastUpdated: z.ZodString;
+    }, z.core.$strip>>;
+    traceIds: z.ZodArray<z.ZodString>;
+    session: z.ZodObject<{
+        id: z.ZodString;
+        threadId: z.ZodOptional<z.ZodString>;
+        startedAt: z.ZodString;
+    }, z.core.$strip>;
+    extensions: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+
+/**
+ * @module @enterstellar-ai/types/connection
+ * @description UserSignal and EnterstellarAgentConnection — the contract between
+ * the UI layer and AI agents.
+ *
+ * `UserSignal` is the fire-and-forget message from a user interaction
+ * (click, submit, input) back to the agent. `EnterstellarAgentConnection` is the
+ * transport-agnostic interface for bidirectional agent communication.
+ *
+ * @see Bible §3.9, §3.10
+ * @see Appendix E P1 (UserSignal), P7 (event whitelist), P11 (connection factory)
+ */
+
+/**
+ * Type of user interaction signal dispatched to the agent.
+ *
+ * @see Appendix E P1
+ */
+type UserSignalType = 'click' | 'submit' | 'input' | 'custom';
+/**
+ * Agent-to-UI event types that trigger zone re-renders.
+ * Internal agent events (graph node transitions, reducer internals)
+ * are NOT surfaced.
+ *
+ * @see Appendix E P7
+ */
+type AgentEventType = 'intent' | 'lifecycle' | 'data' | 'message' | 'reconnect';
+/**
+ * A user interaction signal dispatched from an Zone to the agent.
+ *
+ * Dispatched via `EnterstellarAgentConnection.dispatch()`. Fire-and-forget with
+ * enqueue guarantee — the promise resolves when the signal is queued,
+ * NOT when the agent processes it.
+ *
+ * @see Bible §3.9
+ * @see Appendix E P1
+ */
+type UserSignal = {
+    /** Type of user interaction. */
+    readonly type: UserSignalType;
+    /** Name of the zone that originated this signal. */
+    readonly zone: string;
+    /** Name of the component that originated this signal. */
+    readonly component: string;
+    /** Arbitrary payload from the interaction (form data, click target, etc.). */
+    readonly payload: Readonly<Record<string, unknown>>;
+    /** ISO 8601 timestamp of when the interaction occurred. */
+    readonly timestamp: string;
+    /**
+     * Optional correlation ID for tying this signal to an ongoing interaction chain.
+     *
+     * @see Appendix E P2
+     */
+    readonly correlationId?: string;
+};
+/**
+ * Transport-agnostic interface for bidirectional agent communication.
+ *
+ * Implementations are provided by `@enterstellar-ai/connection` (`createAgentConnection()`)
+ * or custom consumer implementations. The connection is created and owned by
+ * the consumer, not by Enterstellar (RE3).
+ *
+ * This is an **interface** (not a type) because it has methods.
+ *
+ * @see Bible §3.10
+ * @see Design Choices RE3, P1, P5, P7, P11, P12
+ * @see Design Choice T1 — interfaces for objects with methods.
+ */
+interface EnterstellarAgentConnection {
+    /**
+     * Dispatches a user interaction signal to the agent.
+     * Fire-and-forget: resolves when enqueued in the outbound queue,
+     * NOT when the agent processes it.
+     *
+     * @param signal - The user signal to dispatch.
+     * @param options - Optional dispatch options.
+     * @returns Resolves when the signal is enqueued.
+     *
+     * @see Appendix E P1, P6 (debounce)
+     */
+    dispatch(signal: UserSignal, options?: {
+        readonly immediate?: boolean;
+    }): Promise<void>;
+    /**
+     * Subscribes to agent-to-UI events.
+     * Only whitelisted event types are surfaced (P7).
+     *
+     * @param event - The event type to listen for.
+     * @param callback - Called when the event fires.
+     * @returns An unsubscribe function.
+     *
+     * @see Appendix E P7
+     */
+    on(event: AgentEventType, callback: (data: unknown) => void): () => void;
+    /**
+     * Subscribes to ALL raw agent events, including internal ones.
+     * Escape hatch for custom DevTools panels and advanced use cases.
+     *
+     * @param callback - Called for every raw event.
+     * @returns An unsubscribe function.
+     *
+     * @see Appendix E P7
+     */
+    onRawEvent(callback: (event: unknown) => void): () => void;
+    /** Whether the connection is currently active. */
+    readonly connected: boolean;
+    /**
+     * Disconnects the agent connection.
+     * Queued signals are flushed before disconnecting.
+     */
+    disconnect(): Promise<void>;
+}
+/**
+ * Zod schema for validating a `UserSignal` at runtime.
+ *
+ * @see Design Choice T7
+ */
+declare const UserSignalSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        custom: "custom";
+        input: "input";
+        click: "click";
+        submit: "submit";
+    }>;
+    zone: z.ZodString;
+    component: z.ZodString;
+    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    timestamp: z.ZodString;
+    correlationId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+
+/**
+ * @module @enterstellar-ai/types/spatial
+ * @description SpatialContext — DOM-awareness data for AI-informed layout decisions.
+ *
+ * The `SpatialContext` is the return type of the `useSpatialContext()` hook
+ * in `@enterstellar-ai/react`. It provides zone dimensions, visibility state, and an
+ * optional `captureContext()` method for explicit context capture.
+ *
+ * **Two modes:**
+ * - Passive (default): returns `{ zone, width, height, isVisible, focusedElement? }`
+ *   from `ResizeObserver` / `IntersectionObserver`. Never sent to agent automatically.
+ * - Active: consumer calls `captureContext()` explicitly (e.g., on Cmd+K, "Ask AI" click).
+ *
+ * @see Appendix E P13
+ * @see Design Choice RE12
+ */
+/**
+ * DOM-awareness data returned by `useSpatialContext()`.
+ *
+ * Provides zone dimensions and visibility state for AI-informed layout
+ * decisions. No DOM tree walking, no ancestor traversal — naturally
+ * bounded by structure.
+ *
+ * @see Design Choice RE12
+ * @see Appendix E P13
+ */
+type SpatialContext = {
+    /** Zone name this context belongs to. */
+    readonly zone: string;
+    /** Current width of the zone element in pixels. Updated via `ResizeObserver`. */
+    readonly width: number;
+    /** Current height of the zone element in pixels. Updated via `ResizeObserver`. */
+    readonly height: number;
+    /** Whether the zone is currently visible in the viewport. Updated via `IntersectionObserver`. */
+    readonly isVisible: boolean;
+    /** ID or selector of the currently focused element within the zone, if any. */
+    readonly focusedElement?: string;
+    /**
+     * Explicitly captures the current spatial context for sending to the agent.
+     * Consumer decides when to trigger (e.g., Cmd+K, "Ask AI" button).
+     * Returns the captured context snapshot.
+     *
+     * @returns A snapshot of the current spatial context data.
+     */
+    readonly captureContext: () => SpatialContextSnapshot;
+};
+/**
+ * A frozen snapshot of spatial context at a point in time.
+ * Produced by `SpatialContext.captureContext()`.
+ */
+type SpatialContextSnapshot = {
+    /** Zone name. */
+    readonly zone: string;
+    /** Zone width at capture time. */
+    readonly width: number;
+    /** Zone height at capture time. */
+    readonly height: number;
+    /** Visibility at capture time. */
+    readonly isVisible: boolean;
+    /** Focused element at capture time. */
+    readonly focusedElement?: string;
+    /** ISO 8601 timestamp of when the capture occurred. */
+    readonly capturedAt: string;
+};
+
+/**
+ * @module @enterstellar-ai/types/manifest
+ * @description Compact Manifest types — the token-efficient component
+ * descriptions sent to the LLM's system prompt.
+ *
+ * The compact manifest reduces context window consumption from ~50K tokens
+ * to ~200 by including only the essential component metadata for selection.
+ *
+ * @see Bible §4.1 — Registry manifest generation
+ * @see Design Choices R8, R9, R10
+ */
+/**
+ * A single entry in the compact manifest — the minimal representation of a
+ * component sent to the LLM for component selection.
+ *
+ * Format per Design Choice R8: custom compact JSON with name, description,
+ * prop summaries, and category. NOT full JSON Schema (too verbose).
+ *
+ * @see Design Choice R8 — compact JSON format
+ * @see Design Choice R9 — descriptions max 120 chars (enforced by `defineComponent`)
+ * @see Design Choice SI8 — similarity scores included when available
+ */
+type CompactManifestEntry = {
+    /** PascalCase component name. Max 30 characters. */
+    readonly name: string;
+    /** Concise component description. Max 120 characters. */
+    readonly description: string;
+    /** Component category for classification. */
+    readonly category: string;
+    /** Summary of key props: `{ "patientId": "string (UUID)", "riskLevel": "enum: low|medium|high|critical" }`. */
+    readonly props: Readonly<Record<string, string>>;
+    /**
+     * Display mode, if specified in the contract.
+     *
+     * @see Appendix E P8
+     */
+    readonly mode?: string;
+    /**
+     * Interaction type, if specified in the contract.
+     *
+     * @see Appendix E P8
+     */
+    readonly interaction?: string;
+    /**
+     * Semantic similarity score (0.0–1.0).
+     * Only present when the manifest entry comes from a semantic search result.
+     * Helps the LLM prioritize high-confidence matches.
+     *
+     * @see Design Choice SI8
+     */
+    readonly score?: number;
+};
+
+/**
+ * @module @enterstellar-ai/types/semantic-index
+ * @description Semantic Index types — search results and related data shapes
+ * for the embedding-based component retrieval engine.
+ *
+ * The Semantic Index reduces the LLM context window from ~50K tokens to ~200
+ * by selecting only the most relevant components for a given intent.
+ *
+ * **Naming:** Types for data shapes (`SemanticSearchResult`), not interfaces —
+ * per Design Choice T1 (interfaces for objects with methods).
+ *
+ * **L15 compliance:** Zero framework imports. Pure data types only.
+ *
+ * @see Implementation Bible §4.7
+ * @see Design Choices SI1–SI12
+ */
+
+/**
+ * A single result from a semantic index search.
+ *
+ * Returned by `SemanticIndex.search()` — each result pairs a component
+ * with its cosine similarity score to the queried intent.
+ *
+ * @see Design Choice SI8 — similarity scores included in manifest entries.
+ * @see Design Choice SI5 — default `topK: 5`, max 20.
+ * @see Design Choice SI6 — below `noMatchThreshold` (0.4) → Forge activates.
+ */
+type SemanticSearchResult = {
+    /** PascalCase name of the matched component. */
+    readonly componentName: string;
+    /**
+     * Cosine similarity score between the intent embedding and
+     * the component's embedding vector. Range: 0.0–1.0.
+     *
+     * Scores above `noMatchThreshold` (default 0.4) indicate viable matches.
+     * Scores below trigger Forge activation (caller's responsibility).
+     */
+    readonly similarity: number;
+    /**
+     * The full `ComponentContract` of the matched component.
+     * Provides immediate access to props schema, tokens, and metadata
+     * without a second registry lookup.
+     */
+    readonly contract: ComponentContract;
+};
+/**
+ * Zod schema for `SemanticSearchResult`.
+ *
+ * Enables runtime validation of search results — useful for
+ * cross-boundary data validation (e.g., results received from
+ * a cloud semantic index endpoint).
+ *
+ * @see Design Choice T7 — export both TS type and Zod schema.
+ */
+declare const SemanticSearchResultSchema: z.ZodObject<{
+    componentName: z.ZodString;
+    similarity: z.ZodNumber;
+    contract: z.ZodObject<{
+        name: z.ZodString;
+        id: z.ZodString;
+        description: z.ZodString;
+        category: z.ZodString;
+        tags: z.ZodArray<z.ZodString>;
+        props: z.ZodUnknown;
+        tokens: z.ZodRecord<z.ZodString, z.ZodString>;
+        accessibility: z.ZodObject<{
+            role: z.ZodString;
+            ariaLabel: z.ZodString;
+            announceOnUpdate: z.ZodBoolean;
+        }, z.core.$strip>;
+        states: z.ZodObject<{
+            loading: z.ZodString;
+            error: z.ZodString;
+            empty: z.ZodString;
+            ready: z.ZodString;
+        }, z.core.$strip>;
+        examples: z.ZodArray<z.ZodObject<{
+            intent: z.ZodString;
+            props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strip>>;
+        dataSource: z.ZodOptional<z.ZodObject<{
+            adapter: z.ZodString;
+            resource: z.ZodString;
+            params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>>;
+        auth: z.ZodOptional<z.ZodObject<{
+            required: z.ZodBoolean;
+            roles: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+        origin: z.ZodOptional<z.ZodObject<{
+            registryUrl: z.ZodURL;
+            publisher: z.ZodString;
+            verifiedAt: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        _meta: z.ZodObject<{
+            forged: z.ZodBoolean;
+            version: z.ZodString;
+            createdAt: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+
+/**
+ * @module @enterstellar-ai/types/forge
+ * @description Forge types — runtime component generation and Cold Path pipeline.
+ *
+ * The Forge generates temporary ComponentContracts when the registry has
+ * no match. LocalForge uses templates (free), CloudForge uses LLM (metered).
+ *
+ * @see Bible §4.10 — Forge
+ * @see Design Choices F1–F14
+ * @see Appendix D Ruling 7
+ */
+
+/**
+ * The output of a Forge invocation.
+ * Contains the generated contract (if successful), compilation status,
+ * and which forge mode was used.
+ *
+ * @see Bible §4.10
+ * @see Design Choice F8 (auto-routing)
+ */
+type ForgeResult = {
+    /** Whether the forge successfully generated a valid contract. */
+    readonly success: boolean;
+    /**
+     * The generated ComponentContract, or `null` on failure.
+     * Marked with `_meta.forged = true`.
+     * Named with prefix `__forged_{name}_{8-char-hash}` (F13).
+     */
+    readonly contract: ComponentContract | null;
+    /** Compilation result — forged contracts MUST pass the compiler (L3, L13). */
+    readonly compilationResult: CompilationResult | null;
+    /** Whether the fallback component was used instead. */
+    readonly fallbackUsed: boolean;
+    /**
+     * Which forge mode generated this contract.
+     *
+     * @see Appendix D Ruling 7
+     */
+    readonly forgeMode: 'local' | 'cloud';
+};
+/**
+ * Trace record for Cold Path intent clustering.
+ * Every forge invocation is logged for clustering analysis.
+ *
+ * @see Bible §4.10 — Cold Path Rules
+ */
+type ForgeTraceRecord = {
+    /** Slugified intent name. */
+    readonly intentSlug: string;
+    /** Raw intent string hash (SHA-256). */
+    readonly intentHash: string;
+    /** Which forge mode was used. */
+    readonly forgeMode: 'local' | 'cloud';
+    /** Whether the forge succeeded. */
+    readonly success: boolean;
+    /** ISO 8601 timestamp. */
+    readonly timestamp: string;
+    /** Optional context provided during forge invocation. */
+    readonly context?: Readonly<Record<string, unknown>>;
+};
+/**
+ * Configuration for the Forge's Cold Path pipeline.
+ *
+ * @see Design Choices F10–F12
+ */
+type ColdPathConfig = {
+    /** Whether the Cold Path is enabled. */
+    readonly enabled: boolean;
+    /** Minimum occurrences of a similar intent before clustering. Default: 5 (F11). */
+    readonly clusterThreshold: number;
+    /** Whether to auto-queue clustered contracts for HITL review. */
+    readonly autoPromote: boolean;
+};
+/**
+ * Zod schema for validating a `ForgeResult` at runtime.
+ *
+ * @see Design Choice T7
+ */
+declare const ForgeResultSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    contract: z.ZodNullable<z.ZodUnknown>;
+    compilationResult: z.ZodNullable<z.ZodUnknown>;
+    fallbackUsed: z.ZodBoolean;
+    forgeMode: z.ZodEnum<{
+        cloud: "cloud";
+        local: "local";
+    }>;
+}, z.core.$strip>;
+/**
+ * Zod schema for validating a `ForgeTraceRecord` at runtime.
+ */
+declare const ForgeTraceRecordSchema: z.ZodObject<{
+    intentSlug: z.ZodString;
+    intentHash: z.ZodString;
+    forgeMode: z.ZodEnum<{
+        cloud: "cloud";
+        local: "local";
+    }>;
+    success: z.ZodBoolean;
+    timestamp: z.ZodString;
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+
+/**
+ * @module @enterstellar-ai/types/guards
+ * @description Type guard functions for runtime type narrowing.
+ *
+ * Type guards are lightweight checks (one `typeof` + field existence)
+ * for branded types and discriminated unions. Full Zod-based validation
+ * remains in consumer modules (e.g., `@enterstellar-ai/registry`).
+ *
+ * @see Design Choice T17
+ */
+
+/**
+ * Checks whether a value is a valid `ComponentId`.
+ * Validates that the value is a non-empty string.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is a valid `ComponentId`.
+ */
+declare function isComponentId(value: unknown): value is ComponentId;
+/**
+ * Checks whether a value is a valid `ZoneId`.
+ * Validates that the value is a non-empty string.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is a valid `ZoneId`.
+ */
+declare function isZoneId(value: unknown): value is ZoneId;
+/**
+ * Checks whether a value is a valid `TraceId`.
+ * Validates that the value is a non-empty string.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is a valid `TraceId`.
+ */
+declare function isTraceId(value: unknown): value is TraceId;
+/**
+ * Checks whether a value is a valid `ForgeSignal` shape.
+ * Lightweight structural check — NOT full Zod validation.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value has the shape of a `ForgeSignal`.
+ */
+declare function isForgeSignal(value: unknown): value is ForgeSignal;
+/**
+ * Checks whether a value is a valid `CompilationResult` shape.
+ * Lightweight structural check — NOT full Zod validation.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value has the shape of a `CompilationResult`.
+ */
+declare function isCompilationResult(value: unknown): value is CompilationResult;
+/**
+ * Checks whether a value is a valid `ComponentIntent` shape.
+ * Lightweight structural check — NOT full Zod validation.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value has the shape of a `ComponentIntent`.
+ */
+declare function isComponentIntent(value: unknown): value is ComponentIntent;
+/**
+ * Checks whether a value is a valid `AgentTrace` shape.
+ * Lightweight structural check — NOT full Zod validation.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value has the shape of an `AgentTrace`.
+ */
+declare function isAgentTrace(value: unknown): value is AgentTrace;
+/**
+ * Checks whether a value is a valid `UserSignal` shape.
+ * Lightweight structural check — NOT full Zod validation.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value has the shape of a `UserSignal`.
+ */
+declare function isUserSignal(value: unknown): value is UserSignal;
+
+export { type AgentEventType, type AgentTrace, AgentTraceSchema, type AnalyticsAdapter, type AuthAdapter, type ColdPathConfig, type CompactManifestEntry, type CompilationError, CompilationErrorSchema, type CompilationFix, type CompilationProvenance, type CompilationResult, CompilationResultSchema, type CompilationStatus, type ComponentAccessibility, type ComponentAuth, type ComponentCategory, type ComponentContract, ComponentContractSchema, type ComponentDataSource, type ComponentExample, type ComponentId, type ComponentIntent, ComponentIntentSchema, type ComponentStates, type ContractMeta, type ContractOrigin, type DataAdapter, type DesignTokenSet, DesignTokenSetSchema, ENTERSTELLAR_TYPES_VERSION, type EnterstellarAgentConnection, EnterstellarError, type EnterstellarErrorCode, type EnterstellarErrorModule, type EnterstellarStore, type ErrorAdapter, type ForgeMode, type ForgeResult, ForgeResultSchema, type ForgeSignal, ForgeSignalSchema, type ForgeTraceRecord, ForgeTraceRecordSchema, type IntentCategory, type IntentInteraction, type IntentLayout, type IntentProtocol, type IntentSource, type MigrationConfig, type PersistenceStrategy, type SemanticSearchResult, SemanticSearchResultSchema, type SerializedState, SerializedStateSchema, type SessionState, SessionStateSchema, type SignalPlatform, type SpatialContext, type SpatialContextSnapshot, type SyncConfig, type TokenResolver, type TokenResolverContext, type TraceCompilation, type TraceConsent, type TraceDeterminism, type TraceId, type TraceIntent, type TraceMetrics, type TraceResolution, type UserSignal, UserSignalSchema, type UserSignalType, type ZoneCacheConfig, type ZoneConfig, ZoneConfigSchema, type ZoneId, type ZoneState, ZoneStateSchema, type ZoneTrace, ZoneTraceSchema, createComponentId, createTraceId, createZoneId, isAgentTrace, isCompilationResult, isComponentId, isComponentIntent, isForgeSignal, isTraceId, isUserSignal, isZoneId };