@ggui-ai/protocol 0.1.0-rc.1

package/dist/types/thread.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Persistent-chat wire types for OSS `@ggui-ai/mcp-server` and its
+ * adapters.
+ *
+ * Paired with the Portal-side `FullChatStorageAdapter` contract in
+ * `packages/chat-managed-amplify/src/createAdapter.ts` — this file's
+ * vocabulary (action names, author roles, message kinds, idempotency
+ * semantics) matches that adapter verbatim so both cloud and self-
+ * hosted implementations speak the same shape.
+ *
+ * These types are protocol-level because they cross the wire between
+ * self-hosted clients (Portal) and self-hosted servers (`ggui serve`)
+ * + between SDK adapter packages and server handler implementations.
+ * Internal server state (e.g., per-thread sequencer counters) stays
+ * in `@ggui-ai/mcp-server-core` and is NOT exposed here.
+ *
+ * Out of scope for v1:
+ *   - cross-origin thread federation
+ *   - multi-user / shared threads
+ *   - server-driven push-notification delivery (channel is here, pipe
+ *     isn't)
+ *   - search within threads
+ *
+ * Rule of thumb: these shapes are the public wire contract.
+ * **Additions are additive forever** (consumer adapters dedupe on
+ * fields they know). Breaking changes require a protocol version bump.
+ */
+/**
+ * Opaque identity owning a thread.
+ *
+ * - Hosted-cloud origins → Cognito sub (`cognito_<sub>`) or guest
+ *   install id (`guest_<uuidv4>`). Wire shape identical; ownership is
+ *   derived per-auth-mode on the server.
+ * - Self-hosted origins → the subject the `AuthAdapter` resolves a
+ *   pairing bearer token to (implementation-defined, typically
+ *   `paired_<pairingId>`).
+ *
+ * The server never needs to parse this; it's an opaque string that
+ * partitions thread rows. The SDK adapter likewise treats it as
+ * opaque.
+ */
+export type ThreadOwnerId = string;
+/** Message author roles. Matches the cloud adapter verbatim. */
+export type ThreadMessageAuthor = 'user' | 'agent' | 'system';
+/** Message content kinds. Matches the cloud adapter verbatim. */
+export type ThreadMessageKind = 'text' | 'card' | 'event';
+/** Thread lifecycle states. */
+export type ThreadStatus = 'active' | 'archived' | 'pending_delete';
+/**
+ * The 9-action state machine that mutates per-thread UI state. Identical
+ * vocabulary to `packages/chat-managed-amplify/src/createAdapter.ts#
+ * ThreadStateAction` so both cloud and self-hosted adapters dispatch
+ * through the same call. Every action is idempotent with respect to
+ * its target state — `pin` twice leaves the thread pinned; `unpin` on
+ * an unpinned thread is a no-op; `restore` requires
+ * `status === 'pending_delete'` or is rejected.
+ */
+export declare const THREAD_STATE_ACTIONS: readonly ["pin", "unpin", "mute", "unmute", "archive", "unarchive", "mark_read", "request_delete", "restore"];
+export type ThreadStateAction = (typeof THREAD_STATE_ACTIONS)[number];
+export declare function isThreadStateAction(value: unknown): value is ThreadStateAction;
+/**
+ * A persistent conversation.
+ *
+ * Pinned to its origin at creation; origin-awareness lives on the
+ * client. A thread exists on exactly one origin for its entire
+ * lifetime — there is no migration path.
+ */
+export interface Thread {
+    id: string;
+    /** App this thread belongs to. */
+    appId: string;
+    /** Opaque owner identity — see {@link ThreadOwnerId}. */
+    ownerId: ThreadOwnerId;
+    /** Optional human-readable title. Initially derived from the
+     *  `firstMessageHint` supplied at creation, or the app name if
+     *  absent. Editable later (not part of v1 transport, but the field
+     *  is here so the shape is forward-compatible). */
+    title?: string;
+    /** Monotonic sequence of the latest message. Starts at 0 on create;
+     *  bumps on every `appendMessage`. */
+    lastSeq: number;
+    /** ISO timestamp of the last message append. Absent until the
+     *  first message exists. */
+    lastMessageAt?: string;
+    /** Unread count from the owner's perspective. Incremented by
+     *  `appendMessage`, zeroed by `mark_read`. */
+    unreadCount: number;
+    pinned: boolean;
+    muted: boolean;
+    status: ThreadStatus;
+    createdAt: string;
+    updatedAt: string;
+    /** Opaque per-thread metadata — integrators may attach
+     *  servingRegion, shellType hints, etc. Not interpreted by the
+     *  server; forwarded verbatim on reads. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * One message within a thread. Append-only — messages are never
+ * edited or deleted in place; thread state mutations use
+ * {@link ThreadStateAction} instead.
+ *
+ * `seq` is server-assigned and monotonic per thread, starting at 1.
+ * `key` is the caller-supplied idempotency key — a duplicate `key`
+ * on append returns the existing row (the appended row's `seq` and
+ * `at` stay stable across retries).
+ */
+export interface ThreadMessage {
+    threadId: string;
+    /** Idempotency key. Unique per `(threadId, key)`. */
+    key: string;
+    /** Monotonic within a thread; starts at 1. */
+    seq: number;
+    /** ISO timestamp of server receipt. */
+    at: string;
+    authorRole: ThreadMessageAuthor;
+    kind: ThreadMessageKind;
+    /** Content blocks. The OSS protocol does not constrain block shape
+     *  beyond JSON-serializability; integrators typically put the same
+     *  ContentBlock vocabulary `@ggui-ai/protocol/types/invoke.ts` uses
+     *  (text + tool_use + tool_result + thinking). Kept `unknown[]` here
+     *  so the wire stays forward-compatible when the block vocabulary
+     *  widens. */
+    blocks: unknown[];
+    /** Card snapshot — populated when `kind === 'card'`. Opaque. */
+    cardSnapshot?: unknown;
+    /** Short text preview used in transcript lists + search indexing. */
+    textPreview: string;
+    /** Opaque integrator context (appId, model, shellType, etc.). */
+    aiContext?: unknown;
+}
+/**
+ * Input to `createThread` / `POST /threads`.
+ */
+export interface CreateThreadInput {
+    appId: string;
+    /** A hint the server may use to seed the thread title or be echoed
+     *  to the agent as the conversation opener. Not stored as a message
+     *  by default — a subsequent `appendMessage` with the user's real
+     *  first message is the load-bearing write. */
+    firstMessageHint?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Input to `appendMessage` / `POST /threads/{id}/messages`.
+ */
+export interface AppendThreadMessageInput {
+    threadId: string;
+    key: string;
+    authorRole: ThreadMessageAuthor;
+    kind: ThreadMessageKind;
+    blocks: unknown[];
+    cardSnapshot?: unknown;
+    /** Required — keeps compact transcript views honest. Callers that
+     *  have nothing visual to show should still pass an empty string
+     *  explicitly to make that choice auditable. */
+    textPreview: string;
+    aiContext?: unknown;
+}
+/**
+ * Input to `listMessages` / `GET /threads/{id}/messages`.
+ */
+export interface ListMessagesOptions {
+    /** First `seq` to include. Default: 1. */
+    fromSeq?: number;
+    /** Max messages to return. Default: 100. Hard ceiling enforced
+     *  server-side — implementations MAY cap below this. */
+    limit?: number;
+    /** Opaque cursor for pagination. Format is implementation-local;
+     *  clients pass the previous response's cursor verbatim. */
+    cursor?: string;
+}
+export interface ListMessagesResult {
+    messages: ThreadMessage[];
+    /** Cursor for the next page. Absent when no more pages. */
+    nextCursor?: string;
+}
+/**
+ * Filter shape for `listThreads` / `GET /threads`.
+ */
+export interface ListThreadsFilter {
+    /** Restrict by status. Omit for all statuses. */
+    status?: ThreadStatus;
+    /** Restrict by app. Omit for all apps. */
+    appId?: string;
+    /** Max threads to return. Default: 50. */
+    limit?: number;
+    cursor?: string;
+}
+export interface ListThreadsResult {
+    threads: Thread[];
+    nextCursor?: string;
+}
+/**
+ * SSE stream event emitted by `GET /threads/{id}/stream`.
+ *
+ * Every event carries the message's `seq` so reconnecting clients can
+ * resume with `?fromSeq=<last-seen-seq + 1>`. Delivery is
+ * at-least-once; consumers dedupe by `(threadId, seq)`.
+ */
+export interface ThreadStreamEvent {
+    /** Discriminator — makes future event kinds additive-forward. */
+    type: 'thread-message';
+    message: ThreadMessage;
+}
+export declare function isThreadStreamEvent(value: unknown): value is ThreadStreamEvent;
+//# sourceMappingURL=thread.d.ts.map

package/dist/types/thread.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread.d.ts","sourceRoot":"","sources":["../../src/types/thread.ts"],"names":[],"mappings":"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"}

package/dist/types/thread.js

@@ -0,0 +1,57 @@
+/**
+ * Persistent-chat wire types for OSS `@ggui-ai/mcp-server` and its
+ * adapters.
+ *
+ * Paired with the Portal-side `FullChatStorageAdapter` contract in
+ * `packages/chat-managed-amplify/src/createAdapter.ts` — this file's
+ * vocabulary (action names, author roles, message kinds, idempotency
+ * semantics) matches that adapter verbatim so both cloud and self-
+ * hosted implementations speak the same shape.
+ *
+ * These types are protocol-level because they cross the wire between
+ * self-hosted clients (Portal) and self-hosted servers (`ggui serve`)
+ * + between SDK adapter packages and server handler implementations.
+ * Internal server state (e.g., per-thread sequencer counters) stays
+ * in `@ggui-ai/mcp-server-core` and is NOT exposed here.
+ *
+ * Out of scope for v1:
+ *   - cross-origin thread federation
+ *   - multi-user / shared threads
+ *   - server-driven push-notification delivery (channel is here, pipe
+ *     isn't)
+ *   - search within threads
+ *
+ * Rule of thumb: these shapes are the public wire contract.
+ * **Additions are additive forever** (consumer adapters dedupe on
+ * fields they know). Breaking changes require a protocol version bump.
+ */
+/**
+ * The 9-action state machine that mutates per-thread UI state. Identical
+ * vocabulary to `packages/chat-managed-amplify/src/createAdapter.ts#
+ * ThreadStateAction` so both cloud and self-hosted adapters dispatch
+ * through the same call. Every action is idempotent with respect to
+ * its target state — `pin` twice leaves the thread pinned; `unpin` on
+ * an unpinned thread is a no-op; `restore` requires
+ * `status === 'pending_delete'` or is rejected.
+ */
+export const THREAD_STATE_ACTIONS = [
+    'pin',
+    'unpin',
+    'mute',
+    'unmute',
+    'archive',
+    'unarchive',
+    'mark_read',
+    'request_delete',
+    'restore',
+];
+export function isThreadStateAction(value) {
+    return (typeof value === 'string' &&
+        THREAD_STATE_ACTIONS.includes(value));
+}
+export function isThreadStreamEvent(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    return v['type'] === 'thread-message' && typeof v['message'] === 'object';
+}

package/dist/types/ui-generator.d.ts

@@ -0,0 +1,100 @@
+import type { EventSubscription } from './events';
+import type { DataContract, JsonObject, JsonSchema, JsonValue } from './data-contract';
+/**
+ * Design system version — used as part of the cache fingerprint.
+ * When tokens or primitives change, bump this to invalidate cached blueprints.
+ *
+ * Keep in sync with the `@ggui-ai/design` package.json version.
+ */
+export declare const DESIGN_SYSTEM_VERSION = "0.1.0";
+/**
+ * Inputs for computing a style fingerprint.
+ * The fingerprint determines cache validity for generated blueprints.
+ *
+ * NOTE: themeId is NOT included — theme colors are injected at render time
+ * via cssOverrides, not baked into generated code.
+ */
+export interface StyleFingerprintInput {
+    /** App's styling/generation prompt (affects component structure/layout) */
+    stylingPrompt?: string;
+    /** Design system preset (affects available components/tokens) */
+    designSystemPreset?: string;
+    /** Design system version (covers tokens, primitives, motion, everything compiled) */
+    designSystemVersion: string;
+}
+/**
+ * Compute a style fingerprint for cache invalidation.
+ *
+ * Blueprints generated under the same fingerprint are interchangeable.
+ * A fingerprint change means cached blueprints may use outdated primitives,
+ * tokens, or structural patterns and should be regenerated.
+ *
+ * What invalidates the cache:
+ * - stylingPrompt changed ("make it playful" → different layout)
+ * - designSystemPreset changed (different component set available)
+ * - designSystemVersion bumped (new tokens, primitives, motion, etc.)
+ *
+ * What does NOT invalidate:
+ * - themeId changed (colors are applied at render time via cssOverrides)
+ *
+ * Uses FNV-1a (non-cryptographic) — this is for cache keys, not security.
+ * Works in all JS runtimes (browser, Node.js, React Native).
+ */
+export declare function computeStyleFingerprint(input: StyleFingerprintInput): string;
+/**
+ * Request to generate a UI component.
+ * Generic `TContext` defaults to {@link JsonObject} for generator context hints.
+ */
+export interface UIGenerationRequest<TContext = JsonObject> {
+    sessionId: string;
+    prompt: string;
+    context?: TContext;
+    schema?: JsonSchema;
+    subscription?: EventSubscription;
+}
+/**
+ * Internal response from UI generation. This is the GENERATOR-OUTPUT
+ * shape — `componentCode` is the freshly produced ESM string. Before
+ * the stack item commits to the wire, the bootstrap-meta derivation
+ * uploads the code body and projects `codeUrl` (a fetchable URL) onto
+ * `_meta.ggui.bootstrap` instead of inlining the source. Iframe
+ * runtimes fetch the code from `codeUrl`; they never see this field.
+ */
+export interface UIGenerationResponse {
+    stackItemId: string;
+    componentCode: string;
+    sourceCode?: string;
+    warnings?: string[];
+    /**
+     * Data contract the generated component conforms to.
+     *
+     * Populated by the generator when the component calls wire hooks
+     * (`useAction('name')`, `useStream('channel')`) — the generator
+     * extracts the call sites and emits a matching authoring-side
+     * envelope so downstream consumers (`ggui_push` → StackItem, console
+     * inspectors, session-channel router) have the contract available.
+     *
+     * - When the caller supplied `UiGenerateInput.contract` that
+     *   envelope is passed through as-is (already authoritative).
+     * - When the caller didn't supply a contract but the generated code
+     *   uses wire hooks, the generator synthesizes a MINIMAL envelope:
+     *   `actionSpec[name] = {label: name}` and
+     *   `streamSpec[channel] = {schema: {type: 'object'}}`. Enough for
+     *   the receiver to know the surface exists; callers who need
+     *   richer metadata (labels, schemas, refresh tools) should
+     *   author the contract themselves and pass it on input.
+     * - When no wire hooks are used, this field stays absent.
+     */
+    contract?: DataContract;
+}
+/**
+ * Error during UI generation.
+ * The `details` field is {@link JsonValue} to carry any JSON-safe diagnostic data.
+ */
+export interface GenerationError {
+    code: 'PRODUCTION_FAILED' | 'COMPILATION_ERROR' | 'VALIDATION_ERROR';
+    message: string;
+    /** Additional diagnostic information. Typed as {@link JsonValue} (any JSON-safe value). */
+    details?: JsonValue;
+}
+//# sourceMappingURL=ui-generator.d.ts.map

package/dist/types/ui-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-generator.d.ts","sourceRoot":"","sources":["../../src/types/ui-generator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EACV,UAAU,EACV,SAAS,EACV,MAAM,iBAAiB,CAAC;AAEzB;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,UAAU,CAAC;AAE7C;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,2EAA2E;IAC3E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,qFAAqF;IACrF,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAuBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,qBAAqB,GAAG,MAAM,CAO5E;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB,CAAC,QAAQ,GAAG,UAAU;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,YAAY,CAAC,EAAE,iBAAiB,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,mBAAmB,GAAG,mBAAmB,GAAG,kBAAkB,CAAC;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,2FAA2F;IAC3F,OAAO,CAAC,EAAE,SAAS,CAAC;CACrB"}

package/dist/types/ui-generator.js

@@ -0,0 +1,53 @@
+/**
+ * Design system version — used as part of the cache fingerprint.
+ * When tokens or primitives change, bump this to invalidate cached blueprints.
+ *
+ * Keep in sync with the `@ggui-ai/design` package.json version.
+ */
+export const DESIGN_SYSTEM_VERSION = '0.1.0';
+/**
+ * FNV-1a hash — a fast, non-cryptographic hash with good distribution.
+ * Used for cache key fingerprinting only, not for security purposes.
+ * Works in all JS runtimes (browser, Node.js, React Native).
+ */
+function fnv1aHash(str) {
+    let hash = 0x811c9dc5; // FNV offset basis (32-bit)
+    for (let i = 0; i < str.length; i++) {
+        hash ^= str.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193); // FNV prime (32-bit)
+    }
+    // Convert to unsigned 32-bit, then to base-36 for compact representation.
+    // Produce two 32-bit hashes (second seeded differently) for a longer fingerprint.
+    let hash2 = 0x1a2b3c4d;
+    for (let i = 0; i < str.length; i++) {
+        hash2 ^= str.charCodeAt(i);
+        hash2 = Math.imul(hash2, 0x01000193);
+    }
+    return (hash >>> 0).toString(36) + (hash2 >>> 0).toString(36);
+}
+/**
+ * Compute a style fingerprint for cache invalidation.
+ *
+ * Blueprints generated under the same fingerprint are interchangeable.
+ * A fingerprint change means cached blueprints may use outdated primitives,
+ * tokens, or structural patterns and should be regenerated.
+ *
+ * What invalidates the cache:
+ * - stylingPrompt changed ("make it playful" → different layout)
+ * - designSystemPreset changed (different component set available)
+ * - designSystemVersion bumped (new tokens, primitives, motion, etc.)
+ *
+ * What does NOT invalidate:
+ * - themeId changed (colors are applied at render time via cssOverrides)
+ *
+ * Uses FNV-1a (non-cryptographic) — this is for cache keys, not security.
+ * Works in all JS runtimes (browser, Node.js, React Native).
+ */
+export function computeStyleFingerprint(input) {
+    const raw = [
+        input.stylingPrompt || '',
+        input.designSystemPreset || 'default',
+        input.designSystemVersion,
+    ].join('|');
+    return fnv1aHash(raw);
+}

package/dist/validation/ajv-runtime.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Ajv-backed JSON Schema validation runtime for ggui contracts.
+ *
+ * Owns layers B (inner JSON Schema meta-validation) and C (runtime
+ * data validation across propsSpec / actionSpec / streamSpec /
+ * contextSpec) of the six-layer model. The outer A-layers — protocol
+ * wrappers (DataContract envelope, PropsSpec, PropEntry, ActionEntry,
+ * etc.) — stay on zod where TS inference + structural strict-mode
+ * already do their job.
+ *
+ * Why Ajv:
+ *   - Canonical JSON Schema validator (303M weekly downloads).
+ *   - Single source of truth: same compiled validator powers all four
+ *     runtime spec surfaces, so closed-shape semantics never diverge
+ *     between props vs action vs stream vs context.
+ *   - Compile-time meta-validation: `strict: true` rejects malformed
+ *     JSON Schemas at `compile()` — agents discover bugs at
+ *     handshake/push, not at first data flow.
+ *
+ * Closed-shape (load-bearing):
+ *   JSON Schema's default is `additionalProperties: true` (extras
+ *   allowed). Our "propsSpec IS the contract" promise needs
+ *   closed-shape at EVERY depth. Rather than tax agents with
+ *   `additionalProperties: false` at every object node, we inject it
+ *   recursively via {@link injectClosedShape} before Ajv compiles.
+ *   An author who explicitly sets `additionalProperties` (boolean or
+ *   schema) keeps that intent — escape hatch for the rare case where
+ *   open extension is intentional.
+ *
+ * Tolerated metadata keywords:
+ *   - `example` (singular, OpenAPI-ish; JSON Schema standard is
+ *     `examples` array). Treated as informational.
+ *   - `nullable` (OpenAPI 3.0 shorthand). Tolerated; the canonical
+ *     way to express nullability is `type: [<original>, 'null']`.
+ *
+ * Both are registered as no-op keywords so Ajv strict mode doesn't
+ * reject schemas that carry them.
+ */
+import type { ErrorObject, ValidateFunction } from 'ajv';
+/**
+ * Re-export of Ajv's compiled-validator function type. Consumers
+ * (e.g. the renderer iframe loading precompiled validator modules)
+ * import it from `@ggui-ai/protocol` so they need no direct `ajv`
+ * dependency — TS resolves the type transitively through this package.
+ */
+export type { ValidateFunction } from 'ajv';
+import type { JsonSchema } from '../types/data-contract';
+import type { ContractViolation } from './contract-validator';
+/**
+ * Recursively walk a JSON Schema and inject
+ * `additionalProperties: false` at every object node. Authors who
+ * explicitly set `additionalProperties` keep that intent (boolean
+ * preserved; schema recursed into).
+ *
+ * Walks:
+ *   - `properties` (each entry)
+ *   - `items` (array element schema)
+ *   - `additionalProperties` (when it's a schema)
+ *   - `oneOf` / `anyOf` (each branch)
+ *
+ * Returns a new schema tree; never mutates the input.
+ */
+export declare function injectClosedShape(schema: JsonSchema): JsonSchema;
+/**
+ * Compile a JSON Schema into an Ajv {@link ValidateFunction}, with
+ * closed-shape injected at every object node. Throws if the schema
+ * is malformed under Ajv strict mode — this is layer B meta-
+ * validation as a free side effect. Dedicated meta-validation call
+ * sites (handshake / push) wrap this in a structured error.
+ *
+ * Not cached. Compilation is fast and contracts are small; caching
+ * adds a memory cost without a measured win. Revisit if profiling
+ * shows compile dominating.
+ */
+export declare function compileForValidation(schema: JsonSchema): ValidateFunction;
+/**
+ * Compile a JSON Schema into a standalone, **fully self-contained ESM
+ * validator module** — source text, never a live function. Closed-shape
+ * is injected first, exactly as {@link compileForValidation} does, so
+ * the emitted validator enforces the same semantics.
+ *
+ * Why this exists: the renderer iframe runs under a strict CSP with no
+ * `'unsafe-eval'`, so `ajv.compile()` (which builds the validator via
+ * `new Function`) throws `EvalError` there. Codegen has to happen
+ * where `eval` is legal — the server, at push time, where the contract
+ * schema is already fixed. The iframe then loads this module source
+ * via a `blob:` dynamic import (governed by `script-src`, not
+ * `unsafe-eval`) and only ever *runs* the validator.
+ *
+ * The returned module `export default`s the validator function (and
+ * also names it `validate`). Ajv standalone references its runtime
+ * helpers by bare specifier (`ajv/dist/runtime/*`) — the
+ * CSP-sandboxed iframe has no bundler to resolve those, so this
+ * function **inlines** every helper a closed-contract validator can
+ * reach (in practice only `equal` / fast-deep-equal, for `uniqueItems`
+ * and object-valued `enum`/`const`). The result has zero imports. A
+ * survivor check throws if any un-inlined bare import remains, so a new
+ * Ajv helper surfaces as a loud server-side failure, never as silent
+ * iframe breakage.
+ *
+ * Throws if the schema is malformed under Ajv strict mode — same
+ * layer-B meta-validation side effect as {@link compileForValidation}.
+ */
+export declare function compileValidatorModule(schema: JsonSchema): string;
+/**
+ * Convert Ajv error objects into our {@link ContractViolation} shape.
+ *
+ * Path translation: Ajv `instancePath: '/todos/0/done'` →
+ * `field: 'todos[0].done'`. Numeric segments become bracket indices,
+ * named segments become dot-separated. Empty instancePath collapses
+ * to `''` (root-level error).
+ *
+ * Per-keyword mapping (see {@link mapOne}):
+ *   - `additionalProperties` — extra-key violation; `field` includes
+ *     the offending key, `expected: '<declared key>'`.
+ *   - `required` — missing-key violation; `field` includes the
+ *     missing key, `expected: 'present'`, `received: 'undefined'`.
+ *   - `type` — type mismatch; `expected` is the JSON Schema type,
+ *     `received` reads from the violating value.
+ *   - `enum` / `const` — `expected` is the allowed value(s);
+ *     `received` is the offending value.
+ *   - `pattern` — `expected` is the regex; `received` is the
+ *     offending string.
+ *   - other keywords — fall through to Ajv's message verbatim.
+ */
+export declare function mapAjvErrorsToViolations(errors: ErrorObject[] | null | undefined, data: unknown): ContractViolation[];
+/**
+ * Re-anchor a list of Ajv-mapped violations under a stable field
+ * prefix. Used by the four spec validators to lift Ajv's root-
+ * relative paths into the caller's namespace:
+ *   - propsSpec: no prefix (paths already prop-relative).
+ *   - actionSpec: `<actionName>.data`.
+ *   - streamSpec: `<channelName>.payload`.
+ *   - contextSpec: `<slotName>.value`.
+ *
+ * Empty `field` (root-level violation) collapses to the prefix
+ * itself; sub-fields dot-join.
+ */
+export declare function prefixViolations(violations: ContractViolation[], prefix: string): ContractViolation[];
+//# sourceMappingURL=ajv-runtime.d.ts.map

package/dist/validation/ajv-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ajv-runtime.d.ts","sourceRoot":"","sources":["../../src/validation/ajv-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,KAAK,CAAC;AAGzD;;;;;GAKG;AACH,YAAY,EAAE,gBAAgB,EAAE,MAAM,KAAK,CAAC;AAI5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAmF9D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAqChE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,GAAG,gBAAgB,CAGzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAIjE;AA4DD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,WAAW,EAAE,GAAG,IAAI,GAAG,SAAS,EACxC,IAAI,EAAE,OAAO,GACZ,iBAAiB,EAAE,CAGrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,iBAAiB,EAAE,EAC/B,MAAM,EAAE,MAAM,GACb,iBAAiB,EAAE,CAMrB"}