@ggui-ai/protocol 0.14.0 → 0.16.0

package/dist/schemas/mcp.js

@@ -7,7 +7,7 @@
  * Two consumption patterns, both anchored here:
  *
  *   - **Wired raw shapes** (`*InputShape`): handlers in
- *     `@ggui-ai/mcp-server-handlers` (and the hosted pod's discover
+ *     `@ggui-ai/mcp-server-handlers` (and a hosted deployment's discover
  *     tool) import the SHAPE directly as their `inputSchema` and
  *     validate with `z.object(shape)` — unknown keys are STRIPPED.
  *     The shape is the one authored copy of the validation rules AND
@@ -25,25 +25,10 @@
  */
 import { z } from 'zod';
 import { blueprintDraftSchema, handshakeSuggestionSchema, } from './handshake-suggestion.js';
-import { dataContractSchema, jsonObjectSchema } from './data-contract.js';
+import { dataContractSchema, jsonObjectSchema, jsonValueSchema } from './data-contract.js';
 import { blueprintVarianceSchema, blueprintSourceSchema } from './blueprint.js';
-import { REFUSAL_RETRIES, RENDER_GATE_REFUSAL_CODES, } from '../types/refusal-codes.js';
-// ── Shared Sub-Schemas ──
-export const viewportSchema = z.object({
-    width: z.number(),
-    height: z.number(),
-});
-export const interfaceContextSchema = z.object({
-    viewport: viewportSchema,
-    platform: z.enum(['web', 'mobile', 'desktop']),
-    deviceType: z.enum(['phone', 'tablet', 'desktop']),
-    orientation: z.enum(['portrait', 'landscape']),
-    devicePixelRatio: z.number().optional(),
-    touchPrimary: z.boolean().optional(),
-    shellType: z.enum(['chat', 'fullscreen', 'spatial']).optional(),
-    colorScheme: z.enum(['light', 'dark']).optional(),
-    reducedMotion: z.boolean().optional(),
-}).passthrough();
+import { MCP_ENDPOINT_REFUSAL_CODES, REFUSAL_RETRIES, RENDER_GATE_REFUSAL_CODES, } from '../types/refusal-codes.js';
+import { RUNTIME_TELEMETRY_MAX_EVENTS } from './runtime-telemetry-limits.js';
 // ── Wired Tool Input Shapes ──
 //
 // Raw zod shapes for the non-lifecycle tools. The SHAPE is the canonical
@@ -63,14 +48,14 @@ export const consumeInputShape = {
     sessionId: z
         .string()
         .min(1)
-        .describe('Globally-unique sessionId to consume events from. Cross-tenant access surfaces uniformly as session_not_found.'),
+        .describe('Globally-unique sessionId to consume events from. Cross-app access surfaces uniformly as session_not_found.'),
     timeout: z
         .number()
         .int()
         .min(0)
         .max(25)
         .optional()
-        .describe('Inline long-poll seconds, integer in [0, 25]. 0 = immediate. Values outside the bound reject INVALID_PARAMS. Returns on first event OR timeout; re-call on empty to keep waiting — longer waits are your loop, not a bigger timeout.'),
+        .describe('Inline long-poll seconds, integer in [0, 25]. 0 = immediate. Values outside the bound reject INVALID_PARAMS. Returns on first event OR timeout; on empty you may re-call once, then end your turn — a later gesture arrives as a new user message carrying its own consume directive.'),
 };
 export const consumeInputSchema = z.object(consumeInputShape);
 /**
@@ -235,7 +220,7 @@ export const handshakeInputSchema = z.object({
  * `'declined'` cover every legal outcome.
  */
 export const handshakeOutputSchema = z.object({
-    handshakeId: z.string().describe('Stable id — pass to ggui_render / ggui_update'),
+    handshakeId: z.string().describe('Stable id — pass to ggui_render'),
     action: z.enum(['create', 'reuse', 'update', 'replace', 'declined']),
     /**
      * The handshake suggestion — see `handshakeSuggestionSchema`. The
@@ -345,7 +330,7 @@ export const renderInputShape = {
             .string()
             .min(1)
             .optional()
-            .describe('Model route in either wire form — canonical `anthropic:claude-haiku-4-5-20251001` or LiteLLM `anthropic/claude-haiku-4-5` (aliases resolve in both); generator-specific prefixes (e.g. `bedrock/...`) route to that transport. A value that parses in neither form fails the handler input parse at `infra.model`, before any pre-generation gate; `model_not_in_tier` is only ever a well-formed route with no rate row on the effective tier.'),
+            .describe('Model route in either wire form — canonical `anthropic:claude-haiku-4-5-20251001` or LiteLLM `anthropic/claude-haiku-4-5` (aliases resolve in both); generator-specific prefixes (e.g. `bedrock/...`) route to that transport. A value that parses in neither form fails the handler input parse at `infra.model`, before any pre-generation gate; `model_not_allowed` is only ever a well-formed route with no rate row on the effective tier.'),
     })
         .strict()
         .optional(),
@@ -489,10 +474,16 @@ export const renderOutcomeSchema = z.enum(['rendered', 'failed', 'refused']);
  * row names a `fixBy` other than `caller`: the fix belongs to the app's
  * owner, the tenant, or the operator, and retrying does not perform it.
  */
-export const renderRefusalSchema = z.object({
-    code: z
-        .enum(RENDER_GATE_REFUSAL_CODES)
-        .describe("Registered refusal state. Look the code up in the protocol's refusal registry for its retry class and which party can act; the accompanying `fix` names the one recovery step."),
+/**
+ * The refusal projection every surface shares — what a client acts on:
+ * the diagnostic, the one recovery step, and how the call becomes
+ * possible again. Defined ONCE and spread into each surface's envelope
+ * (the render gate's {@link renderRefusalSchema}, the per-app endpoint's
+ * {@link transportRefusalSchema}); the `code` enum is per surface,
+ * derived from the registry. `fixBy` never travels — it is a registry
+ * attribute a client reads by `code`.
+ */
+const refusalProjectionFields = {
     message: z
         .string()
         .describe('Precise diagnostic — what was checked, and against what. Surface it to the operator; do not parse it.'),
@@ -502,6 +493,12 @@ export const renderRefusalSchema = z.object({
     retry: z
         .enum(REFUSAL_RETRIES)
         .describe("How the call becomes possible again. 'after-fix': a named party acts and the same call then succeeds. 'next-period': time restores it at the next period boundary. 'later': transient — retry after a short delay. 'never': no caller action restores it under this identity."),
+};
+export const renderRefusalSchema = z.object({
+    code: z
+        .enum(RENDER_GATE_REFUSAL_CODES)
+        .describe("Registered refusal state. Look the code up in the protocol's refusal registry for its retry class and which party can act; the accompanying `fix` names the one recovery step."),
+    ...refusalProjectionFields,
     handshake: z
         .literal('intact')
         .describe('The handshake was NOT consumed — nothing was read. The same handshakeId is valid on a retry.'),
@@ -511,6 +508,51 @@ export const renderRefusalSchema = z.object({
         .optional()
         .describe('Present only when the refusing check read a balance: its value at the moment of the check.'),
 });
+/**
+ * A refusal typed on the per-app MCP endpoint's authorization
+ * (ggui#825) — the registry projection WITHOUT the render-only fields:
+ * no `handshake` (nothing was handed), no `balanceCentsAtCheck`. Strict:
+ * a render-only field here is a bug, never a wire state. `code` draws
+ * from {@link MCP_ENDPOINT_REFUSAL_CODES} — today exactly
+ * `app_deprovisioned`, the one refusal with a tenant-side fix and
+ * therefore the one that MUST be legible where a deleted app and a bad
+ * credential would otherwise look alike. `appId` (ggui#870) is the app
+ * the refused endpoint serves, as DATA — equal to the path's `{appId}`
+ * — so a tenant's repair loop keys on it and never parses prose; it is
+ * the ggui id the bound caller already holds, never the tenant's own
+ * `ownerRef`. The typed refusal answers a correctly bound federated
+ * identity only (identity first): an anonymous request is refused by the
+ * auth adapter before this arm, and learns nothing about the app.
+ */
+export const transportRefusalSchema = z.strictObject({
+    code: z
+        .enum(MCP_ENDPOINT_REFUSAL_CODES)
+        .describe("Registered refusal state on the per-app endpoint. Look the code up in the protocol's refusal registry for its retry class and which party can act."),
+    ...refusalProjectionFields,
+    appId: z
+        .string()
+        .min(1)
+        .describe('The app id the refused endpoint serves — equals the {appId} of the endpoint path. Structured here so a repair loop keys on it instead of parsing the message.'),
+});
+/**
+ * The JSON-RPC error object a per-app MCP endpoint answers with when it
+ * refuses a request for a typed reason (ggui#825, codes ruled in
+ * ggui#836): HTTP 403, `code` `-32003` (`APP_NOT_FOUND` — the endpoint
+ * no longer serves this app, the same reading ggui's embed host gives a
+ * proxy 403) and `message` `App not found`, plus `data.refusal`, which
+ * makes it legible. `data` is strict: it carries the refusal and nothing
+ * else. An authorization failure that is not a registry state answers
+ * HTTP 403 with `-32007` (`UNAUTHORIZED`) and NO `data` — the three
+ * untyped arms stay indistinguishable among themselves by contract:
+ * naming any of them would say which is true. A first-party server
+ * never chooses `-32000`: it is the SDK client's `ConnectionClosed`, so
+ * a bare 403 and a dropped socket would share a number.
+ */
+export const transportRefusalErrorSchema = z.strictObject({
+    code: z.literal(-32003),
+    message: z.literal('App not found'),
+    data: z.strictObject({ refusal: transportRefusalSchema }),
+});
 /**
  * The COMPLETE structuredContent of a refused tool result — the whole
  * payload, not a slice of it. Strict on purpose: a refusal commits
@@ -819,7 +861,7 @@ export const renderOutputSchema = z.object({
  *     wise). Use when most props stay the same and the agent only
  *     needs to send a small delta — common after a single domain-tool
  *     mutation. RFC 7396 chosen because it has a published spec and
- *     wide library support (GitHub API, Kubernetes strategic-merge).
+ *     wide library support (GitHub API's merge semantics, strategic-merge-patch).
  *
  * Anti-patterns (the discriminated union rejects these structurally,
  * but they're a common author mistake when copy-pasting):
@@ -832,7 +874,7 @@ export const renderOutputSchema = z.object({
  * partial patches that would break required fields, type-mismatch
  * values, etc. all reject pre-persist.
  *
- * `sessionId` is globally unique; the server tenancy-checks via
+ * `sessionId` is globally unique; the server checks the app scope via
  * `ctx.appId`.
  */
 export const updateInputSchema = z.discriminatedUnion('kind', [
@@ -1106,15 +1148,15 @@ export const gguiSessionEventSchema = z.object({
  * OPTIONAL here (the bridge rung owns its cursor and seeds from 0; the
  * route requires it because a bare browser GET has no cursor owner),
  * and `limit` is clamped to {@link RUNTIME_PULL_MAX_LIMIT} instead of
- * rejecting above it. Tenancy violations and unknown sessionIds
+ * rejecting above it. Cross-app access and unknown sessionIds
  * surface uniformly as the `session_not_found` error — existence of
- * other tenants' renders is never leaked.
+ * other apps' renders is never leaked.
  */
 export const runtimePullInputShape = {
     sessionId: z
         .string()
         .min(1)
-        .describe('Active render id — sourced from `_meta["ai.ggui/render"].sessionId` on the iframe boot envelope. Unknown and cross-tenant ids surface uniformly as session_not_found.'),
+        .describe('Active render id — sourced from `_meta["ai.ggui/render"].sessionId` on the iframe boot envelope. Unknown and cross-app ids surface uniformly as session_not_found.'),
     sinceSequence: z
         .number()
         .int()
@@ -1174,11 +1216,6 @@ export const runtimePullOutputSchema = z.union([
     runtimePullEventsPageSchema,
     runtimePullHorizonSchema,
 ]);
-/**
- * Per-batch event cap on `ggui_runtime_telemetry` — a bounded
- * fire-and-forget diagnostic channel, never a data plane.
- */
-export const RUNTIME_TELEMETRY_MAX_EVENTS = 40;
 /**
  * `ggui_runtime_telemetry` input — the iframe runtime's transport
  * self-report (`_meta.ui.visibility: ['app']`, view-callable only).
@@ -1255,10 +1292,6 @@ export function isRefusedRenderOutput(output) {
 // mutable JSON; readonly is applied at the seam (`DeepReadonly` on the
 // derived types). Every shape is closed: the transport strip-parses against
 // `.shape`, so the shape IS the wire.
-// Honest exception, pre-existing: three `.readonly()` calls in
-// `schemas/data-contract.ts` (gadget requires/connect, app public env) reach
-// the registered render + handshake inputs through `dataContractSchema` and
-// advertise `readOnly` on tools/list today — ggui#824 removes them.
 // ============================================================================
 /** Display modes an MCP Apps host can render a view in (ext-apps vocabulary). */
 export const mcpUiDisplayModeSchema = z.enum(['inline', 'fullscreen', 'pip']);
@@ -1300,6 +1333,77 @@ export const gguiSessionSummaryWireSchema = z.object({
     wsToken: z.string().optional(),
     wsTokenExpiresAt: z.string().optional(),
 });
+/**
+ * The two states a GguiSession is in on the wire — the pair the consume
+ * loop exits on (`expired`). Owned here (ggui#817 part C2); the type is
+ * derived, never a second list.
+ */
+export const gguiSessionStatusSchema = z.enum(['active', 'expired']);
+/**
+ * One drained row of `ggui_consume` — a user action that reached the
+ * pipe (ggui#817 part C2). Closed on the wire: an unknown key is
+ * stripped at the transport, a missing key refuses the row at the store
+ * boundary (`pendingEventSchema`, ggui#839), so a malformed pipe entry
+ * never ships to an agent typed as a good one.
+ */
+export const consumeEventEntrySchema = z.object({
+    type: z.literal('action'),
+    sessionId: z.string().min(1),
+    intent: z.string(),
+    actionData: jsonValueSchema.nullable(),
+    uiContext: jsonObjectSchema,
+    actionId: z.string(),
+    firedAt: z.string(),
+});
+/**
+ * One stored row of the consume pipe — what a producer appends and
+ * `consumeAndClear` drains, the same shape on every store (ggui#839; a
+ * store-boundary contract, never wire — `ggui_consume` returns the
+ * entries, never the wrapper). `id` is the drain_ack key and the
+ * idempotency key per `(sessionId, id)`; `envelope` is the
+ * {@link consumeEventEntrySchema} entry, always the object (every writer
+ * passes one; a store that serializes the row serializes the whole row);
+ * `createdAt` is when the row was appended — a string, never `.datetime()`:
+ * the relay copies the client's `firedAt`, which the ingress accepts as a
+ * diagnostic. `PendingEventConsumer` adapters validate every row through
+ * this schema on append and, when rows come back from a serialization, on
+ * drain — a malformed row never reaches an agent typed as a good entry.
+ */
+export const pendingEventSchema = z.object({
+    id: z.string().min(1),
+    envelope: consumeEventEntrySchema,
+    createdAt: z.string(),
+});
+/**
+ * `ggui_consume`'s output — the drained rows, the session's state, and the
+ * client's observations when the host sent any (ggui#817 part C2). The
+ * handler registers `.shape`; `tools/list` therefore advertises the entry
+ * vocabulary and the status enum instead of a free-form record and a free
+ * string.
+ */
+export const gguiConsumeOutputSchema = z.object({
+    events: z.array(consumeEventEntrySchema),
+    status: gguiSessionStatusSchema,
+    client: clientObservationsSchema.optional(),
+});
+/** `ggui_list_sessions`' output — the closed summary rows (ggui#817 part C2). */
+export const gguiListSessionsOutputSchema = z.object({
+    sessions: z.array(gguiSessionSummaryWireSchema),
+});
+/**
+ * `ggui_emit`'s output (ggui#817 part C2): `accepted` at the boundary, and
+ * `seq` when the server keeps a stream buffer — seq-aware implementations
+ * stamp and return it so replay cursors can be built from the ack.
+ */
+export const gguiEmitOutputSchema = z.object({
+    accepted: z.boolean(),
+    seq: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe('Session-scoped monotonic outbound sequence assigned to this delivery. Present when the server keeps a stream buffer.'),
+});
 /**
  * `ggui_get_session`'s wire: the store row's six base fields plus the mount
  * variant — for EVERY session. An MCP-Apps mount is locator-only on the
@@ -1307,6 +1411,8 @@ export const gguiSessionSummaryWireSchema = z.object({
  * projection reads them from the row and the wire never fails on that
  * variant. The locator itself is not on this wire (MCP-Apps resources have
  * their own paths).
+ * `contextSnapshot` rides when a component (`render`) mount's row has one —
+ * never on an mcpApps mount.
  */
 export const gguiGetSessionOutputSchema = z.object({
     variant: z.enum(['render', 'mcpApps']),
@@ -1320,7 +1426,8 @@ export const gguiGetSessionOutputSchema = z.object({
      * The last-known value of every declared contextSpec slot, as
      * `ggui_runtime_sync_context` wrote it onto the row — the read path a
      * raw MCP client (no widget-context mirror) has for contextSpec values.
-     * Present iff the row carries one; never an empty placeholder.
+     * Present iff the row carries one — component (`render`) mounts only; an
+     * mcpApps mount never carries one; never an empty placeholder.
      */
     contextSnapshot: jsonObjectSchema.optional(),
 });

package/dist/schemas/ops-blueprint.d.ts

@@ -7,7 +7,7 @@
  *     persisting the result. Optionally pins as the operator default
  *     for its `(appId, contractHash)` group.
  *   - `ggui_ops_list_blueprints` — enumerate blueprint metadata
- *     (no code body) under tenancy + optional filters. Sorted by
+ *     (no code body) under the caller's app scope + optional filters. Sorted by
  *     `createdAt desc`.
  *   - `ggui_ops_update_blueprint` — toggle the operator-default flag
  *     and/or patch variance tags. Immutable fields (contractHash,
@@ -19,7 +19,7 @@
  * The schemas live in `@ggui-ai/protocol` (not the handler package)
  * for the same reason all wire-shape schemas do: the protocol package
  * is the source of truth for every MCP wire surface, and consumers
- * (cloud pod handlers, console UI, fixture authors) can import from
+ * (a hosted deployment's handlers, console UI, fixture authors) can import from
  * one place. Handler package wraps these into `SharedHandler`
  * factories.
  */
@@ -69,11 +69,11 @@ export declare const opsGenerateBlueprintOutputSchema: z.ZodObject<{
  *   - Seeding pre-vetted blueprints at deploy time (fixture corpus,
  *     migration imports).
  *   - Round-tripping export+reimport — operator exports a blueprint
- *     from one tenant and re-registers it in another.
+ *     from one app (or one deployment) and re-registers it in another.
  *   - Reapplying a fixed version of a blueprint after live edits
  *     (manual recovery from a bad generate run).
  *
- * Same tenancy + variance + default-pin semantics as
+ * Same app-scoping + variance + default-pin semantics as
  * `*_generate_*`; the only difference is the LLM/generator dispatch
  * is replaced with a verbatim accept of the operator's
  * `componentCode` string.

package/dist/schemas/ops-blueprint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ops-blueprint.d.ts","sourceRoot":"","sources":["../../src/schemas/ops-blueprint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAYxB;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,+BAA+B;;;;;;;;;kBAgDjC,CAAC;AAEZ;;;;GAIG;AACH,eAAO,MAAM,gCAAgC;;;;;kBAqBlC,CAAC;AAEZ;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,+BAA+B;;;;;;;;;kBA+CjC,CAAC;AAEZ;;;;GAIG;AACH,eAAO,MAAM,gCAAgC;;;;kBAalC,CAAC;AAEZ;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,4BAA4B;;;;;;kBAoC9B,CAAC;AAEZ,eAAO,MAAM,6BAA6B;;kBAI/B,CAAC;AAEZ;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B;;;;;kBAsB/B,CAAC;AAEZ,eAAO,MAAM,8BAA8B;;;kBAKhC,CAAC;AAEZ;;;;GAIG;AACH,eAAO,MAAM,6BAA6B;;;kBAW/B,CAAC;AAEZ,eAAO,MAAM,8BAA8B;;kBAIhC,CAAC;AAEZ;;;;GAIG;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAC7C,OAAO,+BAA+B,CACvC,CAAC;AACF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAC9C,OAAO,gCAAgC,CACxC,CAAC;AACF,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAC7C,OAAO,+BAA+B,CACvC,CAAC;AACF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAC9C,OAAO,gCAAgC,CACxC,CAAC;AACF,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAC1C,OAAO,4BAA4B,CACpC,CAAC;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAC3C,OAAO,6BAA6B,CACrC,CAAC;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAC3C,OAAO,6BAA6B,CACrC,CAAC;AACF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAC5C,OAAO,8BAA8B,CACtC,CAAC;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAC3C,OAAO,6BAA6B,CACrC,CAAC;AACF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAC5C,OAAO,8BAA8B,CACtC,CAAC"}
+{"version":3,"file":"ops-blueprint.d.ts","sourceRoot":"","sources":["../../src/schemas/ops-blueprint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAaxB;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,+BAA+B;;;;;;;;;kBAkDjC,CAAC;AAEZ;;;;GAIG;AACH,eAAO,MAAM,gCAAgC;;;;;kBAqBlC,CAAC;AAEZ;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,+BAA+B;;;;;;;;;kBA+CjC,CAAC;AAEZ;;;;GAIG;AACH,eAAO,MAAM,gCAAgC;;;;kBAalC,CAAC;AAEZ;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,4BAA4B;;;;;;kBAsC9B,CAAC;AAEZ,eAAO,MAAM,6BAA6B;;kBAI/B,CAAC;AAEZ;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B;;;;;kBAsB/B,CAAC;AAEZ,eAAO,MAAM,8BAA8B;;;kBAKhC,CAAC;AAEZ;;;;GAIG;AACH,eAAO,MAAM,6BAA6B;;;kBAW/B,CAAC;AAEZ,eAAO,MAAM,8BAA8B;;kBAIhC,CAAC;AAEZ;;;;GAIG;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAC7C,OAAO,+BAA+B,CACvC,CAAC;AACF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAC9C,OAAO,gCAAgC,CACxC,CAAC;AACF,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAC7C,OAAO,+BAA+B,CACvC,CAAC;AACF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAC9C,OAAO,gCAAgC,CACxC,CAAC;AACF,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAC1C,OAAO,4BAA4B,CACpC,CAAC;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAC3C,OAAO,6BAA6B,CACrC,CAAC;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAC3C,OAAO,6BAA6B,CACrC,CAAC;AACF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAC5C,OAAO,8BAA8B,CACtC,CAAC;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAC3C,OAAO,6BAA6B,CACrC,CAAC;AACF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAC5C,OAAO,8BAA8B,CACtC,CAAC"}

package/dist/schemas/ops-blueprint.js

@@ -7,7 +7,7 @@
  *     persisting the result. Optionally pins as the operator default
  *     for its `(appId, contractHash)` group.
  *   - `ggui_ops_list_blueprints` — enumerate blueprint metadata
- *     (no code body) under tenancy + optional filters. Sorted by
+ *     (no code body) under the caller's app scope + optional filters. Sorted by
  *     `createdAt desc`.
  *   - `ggui_ops_update_blueprint` — toggle the operator-default flag
  *     and/or patch variance tags. Immutable fields (contractHash,
@@ -19,11 +19,12 @@
  * The schemas live in `@ggui-ai/protocol` (not the handler package)
  * for the same reason all wire-shape schemas do: the protocol package
  * is the source of truth for every MCP wire surface, and consumers
- * (cloud pod handlers, console UI, fixture authors) can import from
+ * (a hosted deployment's handlers, console UI, fixture authors) can import from
  * one place. Handler package wraps these into `SharedHandler`
  * factories.
  */
 import { z } from 'zod';
+import { GENERATOR_ID_PATTERN } from '../types/blueprint-source.js';
 import { dataContractSchema, jsonValueSchema, } from './data-contract.js';
 import { blueprintSchema, blueprintVarianceSchema, llmBlueprintSourceSchema, userBlueprintSourceSchema, } from './blueprint.js';
 /**
@@ -51,9 +52,11 @@ export const opsGenerateBlueprintInputSchema = z
     contract: dataContractSchema,
     generator: z
         .string()
-        .min(1)
+        .regex(GENERATOR_ID_PATTERN, {
+        error: 'generator is an identity `ui-gen-<tier>` — one tier token, no model segment (ggui#924)',
+    })
         .optional()
-        .describe('Generator slug (e.g. `ui-gen-default-haiku-4-5`). When omitted, dispatches through `GeneratorRegistry.defaultGenerator()`.'),
+        .describe('Generator identity (e.g. `ui-gen-default`; the model is chosen by the deployment and reported on `source.model`). When omitted, dispatches through `GeneratorRegistry.defaultGenerator()`.'),
     persona: z
         .string()
         .optional()
@@ -106,11 +109,11 @@ export const opsGenerateBlueprintOutputSchema = z
  *   - Seeding pre-vetted blueprints at deploy time (fixture corpus,
  *     migration imports).
  *   - Round-tripping export+reimport — operator exports a blueprint
- *     from one tenant and re-registers it in another.
+ *     from one app (or one deployment) and re-registers it in another.
  *   - Reapplying a fixed version of a blueprint after live edits
  *     (manual recovery from a bad generate run).
  *
- * Same tenancy + variance + default-pin semantics as
+ * Same app-scoping + variance + default-pin semantics as
  * `*_generate_*`; the only difference is the LLM/generator dispatch
  * is replaced with a verbatim accept of the operator's
  * `componentCode` string.
@@ -206,9 +209,11 @@ export const opsListBlueprintsInputSchema = z
         .describe('Filter to a single `(appId, contractHash)` group. Combine with `generator` / `persona` to narrow within the group.'),
     generator: z
         .string()
-        .min(1)
+        .regex(GENERATOR_ID_PATTERN, {
+        error: 'generator is an identity `ui-gen-<tier>` — one tier token, no model segment (ggui#924)',
+    })
         .optional()
-        .describe('Filter to engine-generated blueprints (`source.kind === "llm"`) whose `source.generator` equals this slug. `user`-sourced rows never match (they carry no engine provenance).'),
+        .describe('Filter to engine-generated blueprints (`source.kind === "llm"`) whose `source.generator` equals this identity (`ui-gen-<tier>`, e.g. `ui-gen-advanced`). `user`-sourced rows never match (they carry no engine provenance).'),
     persona: z
         .string()
         .optional()

package/dist/schemas/public-env-key.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The `GGUI_PUBLIC_APP_*` key grammar — its own module (ggui#819) so the
+ * browser entry can carry the regex without the contract schema that
+ * embeds it.
+ */
+/**
+ * `App.publicEnv` key regex.
+ *
+ * Each key in `App.publicEnv` MUST match this pattern. The prefix is
+ * the **security boundary** — operators can't accidentally stash
+ * sensitive credentials under arbitrary names, and downstream consumers
+ * (render gate, bootstrap projection, iframe shim) can rely on the
+ * naming convention to mean "public-by-design".
+ *
+ * Rule: `GGUI_PUBLIC_APP_` prefix, then uppercase letters / digits /
+ * underscores, at least one char after the prefix.
+ *
+ * `GGUI_PUBLIC_USER_*` keys are RESERVED for a future per-user
+ * channel. The current regex rejects them so App-side config can't
+ * pre-emptively use the namespace.
+ *
+ * Hoisted above `gadgetDescriptorSchema` so the wrapper's `requires`
+ * array can reference it at schema-construction time (TDZ-safe).
+ */
+export declare const PUBLIC_ENV_APP_KEY_RE: RegExp;
+//# sourceMappingURL=public-env-key.d.ts.map

package/dist/schemas/public-env-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-env-key.d.ts","sourceRoot":"","sources":["../../src/schemas/public-env-key.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,qBAAqB,QAAiC,CAAC"}

package/dist/schemas/public-env-key.js

@@ -0,0 +1,25 @@
+/**
+ * The `GGUI_PUBLIC_APP_*` key grammar — its own module (ggui#819) so the
+ * browser entry can carry the regex without the contract schema that
+ * embeds it.
+ */
+/**
+ * `App.publicEnv` key regex.
+ *
+ * Each key in `App.publicEnv` MUST match this pattern. The prefix is
+ * the **security boundary** — operators can't accidentally stash
+ * sensitive credentials under arbitrary names, and downstream consumers
+ * (render gate, bootstrap projection, iframe shim) can rely on the
+ * naming convention to mean "public-by-design".
+ *
+ * Rule: `GGUI_PUBLIC_APP_` prefix, then uppercase letters / digits /
+ * underscores, at least one char after the prefix.
+ *
+ * `GGUI_PUBLIC_USER_*` keys are RESERVED for a future per-user
+ * channel. The current regex rejects them so App-side config can't
+ * pre-emptively use the namespace.
+ *
+ * Hoisted above `gadgetDescriptorSchema` so the wrapper's `requires`
+ * array can reference it at schema-construction time (TDZ-safe).
+ */
+export const PUBLIC_ENV_APP_KEY_RE = /^GGUI_PUBLIC_APP_[A-Z0-9_]+$/;

package/dist/schemas/render-input-envelope.d.ts

@@ -7,8 +7,8 @@ export declare const renderInputEnvelopeSchema: z.ZodObject<{
         model: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
     override: z.ZodOptional<z.ZodObject<{
-        contract: z.ZodOptional<z.ZodType<import("..").DataContract, unknown, z.core.$ZodTypeInternals<import("..").DataContract, unknown>>>;
-        variance: z.ZodOptional<z.ZodType<import("..").BlueprintVariance, unknown, z.core.$ZodTypeInternals<import("..").BlueprintVariance, unknown>>>;
+        contract: z.ZodOptional<z.ZodType<import("../index.js").DataContract, unknown, z.core.$ZodTypeInternals<import("../index.js").DataContract, unknown>>>;
+        variance: z.ZodOptional<z.ZodType<import("../index.js").BlueprintVariance, unknown, z.core.$ZodTypeInternals<import("../index.js").BlueprintVariance, unknown>>>;
     }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const renderInputRouteGuardSchema: z.ZodObject<{

package/dist/schemas/render-input-envelope.js

@@ -7,7 +7,7 @@ import { renderInputShape } from './mcp.js';
  * either wire form (canonical `provider:model` or LiteLLM `provider/model`;
  * aliases resolve in both). The render handler parses this BEFORE its
  * pre-generation gate, so a malformed route is a contract error at zod path
- * `infra.model` — never a policy refusal (`model_not_in_tier` is reserved
+ * `infra.model` — never a policy refusal (`model_not_allowed` is reserved
  * for a well-formed route with no rate row on the effective tier).
  *
  * Kept OUT of the registered shape on purpose: `@ggui-ai/iframe-runtime`

package/dist/schemas/runtime-telemetry-limits.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Bounds the browser runtime shares with the server — its own module
+ * (ggui#819) so `@ggui-ai/protocol/wire` carries the number, not the tool
+ * schemas that enforce it.
+ */
+/**
+ * Per-batch event cap on `ggui_runtime_telemetry` — a bounded
+ * fire-and-forget diagnostic channel, never a data plane.
+ */
+export declare const RUNTIME_TELEMETRY_MAX_EVENTS = 40;
+//# sourceMappingURL=runtime-telemetry-limits.d.ts.map

package/dist/schemas/runtime-telemetry-limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-telemetry-limits.d.ts","sourceRoot":"","sources":["../../src/schemas/runtime-telemetry-limits.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;GAGG;AACH,eAAO,MAAM,4BAA4B,KAAK,CAAC"}

package/dist/schemas/runtime-telemetry-limits.js

@@ -0,0 +1,10 @@
+/**
+ * Bounds the browser runtime shares with the server — its own module
+ * (ggui#819) so `@ggui-ai/protocol/wire` carries the number, not the tool
+ * schemas that enforce it.
+ */
+/**
+ * Per-batch event cap on `ggui_runtime_telemetry` — a bounded
+ * fire-and-forget diagnostic channel, never a data plane.
+ */
+export const RUNTIME_TELEMETRY_MAX_EVENTS = 40;

package/dist/transport/websocket.d.ts

@@ -20,11 +20,11 @@
  * pay its type/build cost. Consumers that only need contract payloads
  * stay on the root import.
  */
-import type { ActionEnvelope } from '../types/events';
-import type { JsonObject } from '../types/data-contract';
-import type { SubscribePayload, AckPayload, ErrorPayload, RenderPayload, StreamEnvelope, PropsUpdatePayload, ChannelSubscribePayload, ChannelUnsubscribePayload, ChannelPayloadFrame, ChannelErrorPayload, DrainAckPayload } from '../types/live-channel';
-import type { HostContextObservedPayload } from '../types/host-context';
-import type { GguiSessionEvent } from '../types/ggui-session-event';
+import type { ActionEnvelope } from '../types/events.js';
+import type { JsonObject } from '../types/data-contract.js';
+import type { SubscribePayload, AckPayload, ErrorPayload, RenderPayload, StreamEnvelope, PropsUpdatePayload, ChannelSubscribePayload, ChannelUnsubscribePayload, ChannelPayloadFrame, ChannelErrorPayload, DrainAckPayload } from '../types/live-channel.js';
+import type { HostContextObservedPayload } from '../types/host-context.js';
+import type { GguiSessionEvent } from '../types/ggui-session-event.js';
 /**
  * WebSocket message types for client-server communication.
  * Each type maps to a specific payload shape in the {@link WebSocketMessage} discriminated union.

package/dist/types/auth.d.ts

@@ -1,4 +1,4 @@
-import type { JsonObject } from './data-contract';
+import type { JsonObject } from './data-contract.js';
 /**
  * Authenticated end-user identity.
  * Attached to renders and included in events consumed by agents.

package/dist/types/blueprint-source.d.ts

@@ -11,7 +11,7 @@
  *
  *   - `llm` — engine-generated. `generator` is the slug of the
  *     {@link UiGenerator} that produced the component code; `model` is
- *     the LLM model id the engine called. Both REQUIRED: every
+ *     the route the engine called, as a `ModelRef`. Both REQUIRED: every
  *     generation mint site has them in scope, and an engine-generated
  *     artifact without them is not a real state.
  *   - `user` — developer-registered / hand-authored. Covers
@@ -30,21 +30,41 @@
  * cache (invalidation = regeneration, never data loss), so unlabeled
  * rows are dropped at the trust boundary, never coerced.
  */
+import { type ModelRef } from "./llm-route.js";
 /** Closed list of `BlueprintSource` discriminants. */
 export declare const BLUEPRINT_SOURCE_KINDS: readonly ["llm", "user", "curated"];
 /** Discriminant of {@link BlueprintSource}. */
 export type BlueprintSourceKind = (typeof BLUEPRINT_SOURCE_KINDS)[number];
+/**
+ * The de-modeled generator identity (ggui#924): `ui-gen-` + ONE tier token
+ * — `ui-gen-default`, `ui-gen-advanced`, or an operator-defined tier. No
+ * model segment: the model is its own field, so a model retirement never
+ * renames an identity or re-keys a stored record. The template admits any
+ * `ui-gen-*` at the type level; {@link isGeneratorId} is the grammar.
+ */
+export declare const GENERATOR_ID_PATTERN: RegExp;
+/** A generator identity — see {@link GENERATOR_ID_PATTERN}. */
+export type GeneratorId = `ui-gen-${string}`;
+/** Whether `value` is a generator identity: one tier token, no model segment. */
+export declare function isGeneratorId(value: string): value is GeneratorId;
 /** Engine-generated — full engine provenance is mandatory. */
 export interface LlmBlueprintSource {
     readonly kind: "llm";
     /**
-     * Slug of the generator that produced the component code (e.g.
-     * `'ui-gen-default-haiku-4-5'`). The server's `GeneratorRegistry` is
-     * the authority for which slugs exist on a given deployment.
+     * The generator identity that produced the component code (e.g.
+     * `'ui-gen-default'`), de-modeled — see {@link GENERATOR_ID_PATTERN}.
+     * The server's `GeneratorRegistry` is the authority for which
+     * identities exist on a given deployment.
+     */
+    readonly generator: GeneratorId;
+    /**
+     * The route the generator's LLM call used, rendered in the registry's
+     * spelling (`<prefix>/<model>`; {@link ModelRef}, composed only by
+     * `modelRefOfRoute`). Registry ids (`'anthropic/claude-haiku-4-5'`) are
+     * the subset the registry lists; a self-hoster's bedrock or OpenRouter
+     * route is a ref too. One spelling per route: a dated wire id is refused.
      */
-    readonly generator: string;
-    /** Model id of the LLM call the generator made. */
-    readonly model: string;
+    readonly model: ModelRef;
 }
 /** Developer-registered / hand-authored — no engine provenance exists. */
 export interface UserBlueprintSource {

package/dist/types/blueprint-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blueprint-source.d.ts","sourceRoot":"","sources":["../../src/types/blueprint-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAIH,sDAAsD;AACtD,eAAO,MAAM,sBAAsB,qCAAsC,CAAC;AAE1E,+CAA+C;AAC/C,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E,8DAA8D;AAC9D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;CAC1B;AAED,MAAM,MAAM,eAAe,GACvB,kBAAkB,GAClB,mBAAmB,GACnB,sBAAsB,CAAC;AAE3B;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CAoB3E;AAED,uDAAuD;AACvD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,0BAA0B;;;;CAI7B,CAAC;AAEX;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAC;IACzC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,qEAAqE;AACrE,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,eAAe,GACtB,mBAAmB,CAQrB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE;IACzC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC,GAAG,eAAe,GAAG,IAAI,CAMzB"}
+{"version":3,"file":"blueprint-source.d.ts","sourceRoot":"","sources":["../../src/types/blueprint-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAGH,OAAO,EAAc,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAExD,sDAAsD;AACtD,eAAO,MAAM,sBAAsB,qCAAsC,CAAC;AAE1E,+CAA+C;AAC/C,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,QAAuB,CAAC;AAEzD,+DAA+D;AAC/D,MAAM,MAAM,WAAW,GAAG,UAAU,MAAM,EAAE,CAAC;AAE7C,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,WAAW,CAEjE;AAED,8DAA8D;AAC9D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;CAC1B;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;CAC1B;AAED,MAAM,MAAM,eAAe,GACvB,kBAAkB,GAClB,mBAAmB,GACnB,sBAAsB,CAAC;AAE3B;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CAuB3E;AAED,uDAAuD;AACvD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,0BAA0B;;;;CAI7B,CAAC;AAEX;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAC;IACzC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,qEAAqE;AACrE,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,eAAe,GACtB,mBAAmB,CAQrB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE;IACzC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC,GAAG,eAAe,GAAG,IAAI,CAMzB"}