@ggui-ai/protocol 0.8.0 → 0.10.0

package/dist/version.js

@@ -6,6 +6,131 @@
  * schema change; the most recent change anchors {@link PROTOCOL_VERSION}.
  *
  * --------------------------------------------------------------------
+ * Authored source rides blueprint reuse (2026-08-14, additive,
+ * pre-launch). Cache-reuse renders (a repeated prompt semantic-matches
+ * a cached blueprint) previously committed without authored
+ * `sourceCode` — structurally, not incidentally: the reuse-commit path
+ * never carried it, and blueprint registry rows never persisted it, so
+ * `ggui_get_render_source` always returned `render_source_unavailable`
+ * for every reuse render.
+ *
+ *   sc1. **`Blueprint.sourceCodeHash?: string`** added to
+ *      `@ggui-ai/protocol` — content hash (`CodeStore.hashOf`) of the
+ *      AUTHORED, pre-compile source body, distinct from the existing
+ *      `codeHash` (compiled `componentCode`). The body itself is never
+ *      stored on the row — persistent adapters keep vector/metadata
+ *      rows small and content-address the body through the same
+ *      `CodeStore` seam `codeHash` already implies. Absent on legacy
+ *      rows and on blueprints with no authored form distinct from
+ *      their compiled output.
+ *
+ *   sc2. **Registration threads it through.** `registerBlueprint`
+ *      (`@ggui-ai/mcp-server-handlers`) gains an optional
+ *      `sourceCode` input; when present, distinct from the compiled
+ *      `componentCode` (fallback-collapse symmetry — a byte-identical
+ *      pair is never worth persisting, since the read-side envelope
+ *      guard would reject it anyway), and a `CodeStore` is bound, the
+ *      registry computes + persists `sourceCodeHash` on the row and
+ *      writes the body through the durability `CodeStore` (body-
+ *      before-row ordering, same orphan-body-beats-dangling-pointer
+ *      posture as the existing compiled-code write). New durability
+ *      event `blueprint_source_write_failed` (additive, sibling to
+ *      `blueprint_code_write_failed`) on a failed body write — the row
+ *      still commits with the hash; a reuse read against a missing
+ *      body degrades gracefully to `render_source_unavailable`, never
+ *      an error.
+ *
+ *   sc3. **Reuse commit threads it back.** The cache-hit reuse branch
+ *      resolves the body from `CodeStore` by the stored hash and
+ *      stamps it onto `GenerationCacheHit.sourceCode`, which
+ *      `commitCachedGguiSession` sidecars onto the render exactly like
+ *      the cold-gen commit path already does — reuse renders now serve
+ *      `ggui_get_render_source` identically to cold-gen renders.
+ *
+ * Conformance-kit verdict: no kit entry required — additive optional
+ * fields + a new durability event, no existing wire shape changed, no
+ * MCP tool name/shape touched.
+ *
+ * Package version — classification MADE here: PATCH for
+ * `@ggui-ai/protocol` (additive optional field, no new export),
+ * MINOR for `@ggui-ai/mcp-server-handlers` (new optional input field +
+ * new event), pre-1.0 and pre-launch. PROTOCOL_VERSION unchanged.
+ * --------------------------------------------------------------------
+ * ops-blueprint appId input + app-access seam (2026-08-14, additive,
+ * pre-launch, ggui#501). Cross-app curation seam for the operator-
+ * class blueprint family — the prerequisite for the family mounting
+ * beyond the OSS default server.
+ *
+ *   ob1. **Optional `appId` input** on all five `ggui_ops_*_blueprint`
+ *      tools (`generate`, `register`, `list`, `update`, `delete`).
+ *      Omitted ⇒ resolves to the caller's bound `ctx.appId` (unchanged
+ *      default behavior). Present ⇒ the tool curates the NAMED app
+ *      instead, subject to the authorizer below.
+ *
+ *   ob2. **`authorizeAppAccess` dep seam**
+ *      (`OpsBlueprintAppAuthorizer`, exported from
+ *      `@ggui-ai/mcp-server-handlers`'s ops-blueprint barrel):
+ *      consulted via `resolveEffectiveAppId` on every resolution,
+ *      bound or unbound `appId` input alike. Seam unbound ⇒ legacy
+ *      bound-only posture — a cross-app `appId` input (different from
+ *      `ctx.appId`) rejects with the new `cross_app_curation_unavailable`
+ *      named code, mirroring the `app_scoped_keys_unavailable` idiom
+ *      from the 2026-07-29 ops slice. Seam bound and denying ⇒
+ *      `app_curation_denied` with a `not_found` / `not_owner` reason.
+ *      `@ggui-ai/mcp-server`'s default server binds an allow-all
+ *      authorizer when the operator supplies none — the
+ *      single-operator trust model: whoever runs the server operates
+ *      every app on it.
+ *
+ *   ob3. **Deployment boundary retired.** The restriction that pinned
+ *      this family to the OSS default server only (2026-08-13 ruling,
+ *      ggui#496) is retired: the family now mounts on any control
+ *      plane whose deployment supplies the store/search/authorizer
+ *      deps. Single-operator deployments bind an allow-all
+ *      authorizer; multi-user deployments supply one that enforces
+ *      their ownership model.
+ *
+ * Conformance-kit verdict: ops tools are not conformance-kit surface —
+ * NO protocol stamp roll.
+ *
+ * Package version — classification MADE here: MINOR for
+ * `@ggui-ai/protocol`, `@ggui-ai/mcp-server-handlers`,
+ * `@ggui-ai/mcp-server` (additive), pre-1.0 and pre-launch.
+ * PROTOCOL_VERSION unchanged.
+ * --------------------------------------------------------------------
+ * `ggui_get_render_source` data-plane tool (2026-08-14, additive,
+ * pre-launch, ggui#282). New bare-wire-name MCP tool, `agent`
+ * audience — the calling app reads the generated source of its OWN
+ * render as `{sessionId, blueprint: {source, contract?,
+ * fixtureProps?}}`. New input shape `getRenderSourceInputShape`
+ * (mirrors `getSessionInputShape`) and output type
+ * `GguiGetRenderSourceOutput` added to `@ggui-ai/protocol`; new
+ * factory `createGguiGetRenderSourceHandler` (modeled on
+ * `createGguiGetSessionHandler` — same tenancy posture via
+ * `ctx.appId`, no heartbeat) plus the shared
+ * `buildRenderSourceEnvelope` helper added to
+ * `@ggui-ai/mcp-server-handlers`. The pre-existing control-plane
+ * `ggui_ops_get_render_source` (cloud-only, connector-key tenancy —
+ * a different caller, unchanged contract) now imports the SAME
+ * shared helper so the two tools' envelope shape cannot drift apart;
+ * a behavior-neutral refactor pinned by an envelope-equivalence test.
+ * No existing wire shape changed.
+ *
+ * Conformance-kit verdict: no kit entry required. The kit's WS
+ * live-channel conformance surface (`@ggui-ai/protocol-conformance`)
+ * has zero enumeration of MCP tool names anywhere in its source —
+ * verified by grepping the package for `ggui_` tool-name references
+ * outside its fixtures/tests, which returns nothing; it grades
+ * `GguiSessionChannelServer` wire-frame behavior (ack/error/data,
+ * echoed requestId, session-state read-back), a surface this
+ * addition never touches.
+ *
+ * Package version — the classification is MADE here, not deferred:
+ * MINOR for `@ggui-ai/protocol` (new exports, additive) and
+ * `@ggui-ai/mcp-server-handlers` (new factory + shared helper,
+ * additive), pre-1.0 and pre-launch. PROTOCOL_VERSION is unchanged —
+ * no WS envelope moved.
+ * --------------------------------------------------------------------
  * MCP tool bindings & discovery (2026-08-10, additive, pre-launch,
  * ggui#259). Artifacts gain an optional MCP tool-binding list and
  * registry search gains a tool dimension, connecting the two
@@ -236,6 +361,173 @@
  * posture), so the additive field breaks nothing. PROTOCOL_VERSION
  * unchanged — no wire frame changed shape.
  *
+ * SSE middle rung (2026-08-11): the failover-ladder stream surface — a
+ * MINOR for the `@ggui-ai/protocol` wave, deferred to the next cut
+ * (≥ 0.9.0) under the same one-wave-version rule as above. Two
+ * additive pieces, one motivation (hosts whose CSP blocks WebSocket
+ * but permits `EventSource`, giving the ladder a live middle rung
+ * between WS and cursor polling):
+ *
+ *   sm1. **`McpAppAiGguiRenderMeta.sseUrl`** — optional server-stamped
+ *      `/api/sessions/<sessionId>/stream?wsToken=<token>` URL beside
+ *      `pollingUrl`. Every envelope that parsed before parses
+ *      identically (tolerant scalar posture, no pairing invariant —
+ *      the URL is self-authorizing via its embedded token). Absent ⇒
+ *      no SSE rung; the ladder is WS → polling. The stream contract
+ *      the URL points at (ChannelFrame-per-`data:`-line byte-same as
+ *      the WS push, `id:` = ledger seq on replay frames only,
+ *      `: hb` comment heartbeat ≤ ~25s, `retry: 3000` first write,
+ *      `Last-Event-ID` over `?sinceSequence=`, 401/404/410 mirroring
+ *      `/events`) is pinned on the interface docstring.
+ *
+ *   sm2. **`composeSessionApiUrls` + `SessionApiUrls`** — the ONE
+ *      pure composer every stamping surface (render/update resultMeta,
+ *      self-contained shell, `/state` bootstrap) routes both URLs
+ *      through — the `deriveRenderMeta` move applied to channel URLs.
+ *      New exports only. This REPAIRS a confirmed drift: `/state` used
+ *      to stamp an unconditional token-less `/state`-shaped
+ *      pollingUrl that could only 401 through the events composer;
+ *      both URLs now stamp ONLY when the live trio is minted, and
+ *      omission is the honest no-HTTP-fallback signal.
+ *
+ * Conformance-kit verdict: same posture as if1 — no fixture pins the
+ * render slice's closed field set (verbatim-carry by design), so the
+ * additive field breaks nothing. Full SSE endpoint conformance cases
+ * are a FLAGGED follow-up (unit tests ride this slice; conformance
+ * ticket after launch — No Silent Block). PROTOCOL_VERSION unchanged —
+ * no WS envelope moved; the SSE `data:` line reuses the ChannelFrame
+ * shape byte for byte.
+ *
+ * --------------------------------------------------------------------
+ * Bridge-pull terminal rung (2026-08-11): `ggui_runtime_pull` — a
+ * MINOR for the `@ggui-ai/protocol` wave, riding the same next cut
+ * (≥ 0.9.0) as the SSE entry above. One motivation: hosts whose CSP
+ * blocks EVERY network API from the iframe (claude.ai's srcdoc
+ * sandbox) can still pull the event ledger over the host's
+ * `tools/call` postMessage bridge — the fourth and terminal rung of
+ * the failover ladder (WS → SSE → HTTP polling → bridge-pull).
+ *
+ *   bp1. **`runtimePullInput/OutputSchema` + `GguiRuntimePullInput/
+ *      Output`** — new tool contract, output byte-parity with the
+ *      `/events` route (`EventsResponse` page arm |
+ *      `REPLAY_HORIZON_PASSED` arm as a NORMAL result) so ONE client
+ *      parse core serves both carriers. `_meta.ui.visibility: ['app']`
+ *      restricts callers to MCP Apps views per spec §401.
+ *
+ *   bp2. **`wait` + `RUNTIME_PULL_MAX_WAIT_SECONDS`** — the
+ *      subscription-mode hold: an empty cursor page holds the call
+ *      server-side (≤ 20s, under `ggui_consume`'s proven 25s host
+ *      tolerance) until an event lands. Back-to-back held single-shots
+ *      emulate push through a request/response-only bridge; clients
+ *      demote to sparse un-held pulls after consecutive empty holds.
+ *
+ * Conformance-kit verdict: additive tool, no existing fixture touches
+ * it; bridge-carrier conformance cases join the SSE follow-up ticket
+ * (No Silent Block). PROTOCOL_VERSION unchanged — no WS envelope
+ * moved; the ledger event vocabulary gained active use of the
+ * existing `'ui.updated'` taxonomy member (`ggui_update` now appends
+ * it), not a new member.
+ *
+ * --------------------------------------------------------------------
+ * Render outcome facet (2026-08-13, ggui#495; rides the next cut
+ * after 0.9.0 — additive MINOR): `ComponentGguiSession` gains
+ * `errorCode?: RenderErrorCode` — the SAME closed enum the §7.1
+ * failure envelope carries, persisted on the committed error render
+ * beside the existing `error` message (invariant: `errorCode` ⇒
+ * `error`; one writer, the failure commit). Deliberately NOT a new
+ * `GguiSessionStatus` member: outcome ⊥ lifecycle — errored rows
+ * still TTL-expire. New exported predicate `isErroredGguiSession` +
+ * accessor `erroredGguiSessionCode` are the single normative
+ * definition of "errored" (message-only legacy rows count); store
+ * `erroredOnly` filters (GguiSessionFilter, all three stores) and
+ * `ggui_ops_list_recent_renders`' new `erroredOnly` arg + per-row
+ * `errorCode` derive from them. The canonical `RenderErrorCode` type
+ * declaration moved from `types/mcp.ts` beside its schema in
+ * `schemas/mcp.ts` (types/mcp re-exports — import paths unchanged).
+ *
+ * --------------------------------------------------------------------
+ * React/RN SDK-surface retirement (2026-08-13, owner ruling; rides
+ * the same next cut ≥ 0.9.0): `@ggui-ai/react` + `@ggui-ai/react-
+ * native` are MCP Apps HOST-HELPER libraries, not SDKs — embeds mount
+ * views via the spec path (`AppRenderer` / RN `McpAppIframe`) and get
+ * runtime semantics (freeze latch, crash card, epochs) from the
+ * mounted iframe itself. Deleted from `@ggui-ai/react`: `GguiRender`
+ * + its WS stack (`useWebSocket`, `WebSocketManager`, `EventBuffer`,
+ * reserved-validators), local `ThemeProvider`, `SelfRepairBoundary`
+ * family, `AgentBrowsePanel`, the dead wire-type re-exports, the
+ * public `useGguiContext`/`useAdapter`/`AdapterRegistry` barrel
+ * entries (impls stay internal), and `chat-thread/**` (both
+ * packages — third-party chat framework, zero consumers; guuey built
+ * `@guuey/threads` instead). RN's direct-render family was already
+ * deleted pre-ruling (#425, 7d5c6955b). Zero-consumer adversarially
+ * traced per export before deletion; guuey pins both packages at
+ * 0.6.3 (npm-immutable — installs unaffected; handoff note per the
+ * deletion discipline). Breaking TS-API shrink, 0.x MINOR carries it.
+ * SAME-DAY RENAME RULING: the packages republish at this cut as
+ * `@ggui-ai/mcp-apps-react` / `@ggui-ai/mcp-apps-react-native` —
+ * the names must say "MCP Apps bindings," not "SDK." Old names get
+ * `npm deprecate` + pointer at cut time (owner click, OTP; new names
+ * need Trusted Publishing setup — see release:cut).
+ *
+ * --------------------------------------------------------------------
+ * Mutation tool split + epoch history (2026-08-13, ggui#481→#483,
+ * SUPERSEDES the same-night renderAsNew param design, which never
+ * reached a cut): a MINOR for the `@ggui-ai/protocol` wave, riding
+ * the same next cut (≥ 0.9.0). One motivation arc: hosts mint
+ * per-result views from result shape, so mutation results must be
+ * either complete mount packages or carry nothing — and once every
+ * update result is a durable record, the records ARE a history.
+ *
+ *   ts1. **`ggui_amend`** — new tool: in-place mutation of the
+ *      mounted card. Same replace/merge grammar as update
+ *      (`amendInputSchema`/`amendOutputSchema` + inferred types); NOT
+ *      UI-bound, results carry NO `_meta` under any outcome; the
+ *      history epoch is untouched by construction. Additive.
+ *
+ *   ts2. **`ggui_update` semantics change, stated plainly:** every
+ *      real update now mints a NEW history record — output gains
+ *      mandatory `epoch` and its `resourceUri` is the epoch-PINNED
+ *      URI (`…#N`); the result `_meta` is unconditionally the full
+ *      bootable mount package (#481). `renderAsNew` is deleted from
+ *      both arms. A consumer that treated update results as in-place
+ *      acknowledgements sees new cards; the in-place path moved to
+ *      ggui_amend. Pre-launch no-compat; the kit is the arbiter and
+ *      update-family conformance cases ship IN THIS SLICE (epoch
+ *      immutability, head aliasing, amend-mints-nothing), closing the
+ *      previously flagged gap.
+ *
+ *   ts3. **Epoch surfaces:** `GguiSessionBase.epoch` +
+ *      `McpAppsGguiSession.epoch` (optional, absent ⇒ 0 — the row is
+ *      the authority; the ledger is horizon-bounded); `'ui.reminted'`
+ *      joins the ledger taxonomy with `UiRemintedEventData`;
+ *      `UiUpdatedEventData` types the props event (now epoch-stamped);
+ *      `composeEpochUri`/`parseEpochUri` (the ONE encoding seam —
+ *      fragment today, flippable post-host-probe);
+ *      `deriveEpochFromEvents` (in-horizon reconstruction only).
+ *      SPEC §7.1.2/§7.1.2.1/§7.1.2.2 are the normative text.
+ *
+ *   ts4. **Live-fan epoch obligation (2026-08-13 follow-up, same
+ *      wave):** `PropsUpdatePayload.epoch` (`@ggui-ai/protocol`
+ *      live-channel, optional on the wire) is the freeze-latch signal,
+ *      and servers MUST stamp live `props_update` frames with the
+ *      COMMIT-TIME epoch (SPEC §7.1.2.2). TS API surfaces moved with
+ *      it: `PropsUpdateNotifier.sendPropsUpdate` gains a required
+ *      `epoch` third param (`@ggui-ai/mcp-server-handlers`), as does
+ *      `GguiSessionChannelServer.sendPropsUpdate`
+ *      (`@ggui-ai/mcp-server`) — 2-arg callers break at compile time
+ *      (pre-launch no-compat; 0.x MINOR carries it). Motivating
+ *      incident: a second notifier impl (cloud pod) omitted the then-
+ *      optional field and shipped epoch-less frames — the latch
+ *      degraded to legacy-apply exactly as designed for skew, which
+ *      is also the compat story: old runtime × new server ignores the
+ *      extra field; new runtime × old server sees no epoch and
+ *      applies as before. Graceful both directions.
+ *
+ * PROTOCOL_VERSION unchanged — no WS frame changed shape; the
+ * `ai.ggui/render` slice's field set was never closed, and the
+ * `ui.updated` / `props_update` payloads gained an optional field on
+ * open payload surfaces.
+ *
  * --------------------------------------------------------------------
  * Credential-broker surface retired (2026-08-08, BREAKING, pre-launch,
  * ggui#436). The `system` frame's auth vocabulary and the
@@ -2755,8 +3047,33 @@
  *      and the WS frame discriminators `'render'` / `'render_event'`.
  *      OSS-first; the cloud pod follows at its next image build. See
  *      `docs/protocol/migrations/2026-06-05-gguisession-reintroduction.md`.
+ *
+ * draft-2026-08-19 — SCHEMA-PRECISE RENDER (additive minor; frozen
+ *      shape per the 2026-08-19 consumer review, design record
+ *      `docs/plans/2026-08-19-schema-precise-render.md`):
+ *
+ *   c1. **Enforced props schema on the handshake output** (SPEC
+ *      §2.3.2 + §7.1.1). `GguiHandshakeOutput` gains `propsSchema?`
+ *      (the exact schema the paired render enforces, emission form,
+ *      RFC 8785-canonical construction), `propsSchemaHash?` (sha256
+ *      over the canonical bytes; on EVERY non-declined handshake) and
+ *      `propsSchemaProfile?` ('grammar-safe' | 'full'; unknown values
+ *      degrade to 'full'). The record persists the artifact and
+ *      `ggui_render` validates against the PERSISTED value — the
+ *      AUTHORITY obligation is structural under version skew.
+ *   c2. **`ContractViolation.keyword`** (additive) + **`propsSchemaHash`
+ *      on `contract_violation` error data** — the failure-class
+ *      segmentation and breach-classifier surfaces (SPEC §7.9).
+ *   c3. **`JsonSchema.type` admits draft-07 type arrays**
+ *      (`['string','null']` — the canonical nullability form the
+ *      emission rewrites OpenAPI `nullable: true` into). Acceptance
+ *      widening only; the schema-subset checker compares type SETS.
+ *   c4. **Conformance:** the `props-schema-conformance` catalog
+ *      (drift / hash / profile / authority obligations; pins the
+ *      2026-08-19 out-of-vocabulary enum incident as a permanent
+ *      sample).
  */
-export const PROTOCOL_VERSION = "draft-2026-06-12";
+export const PROTOCOL_VERSION = "draft-2026-08-19";
 /**
  * Schema version stamped onto wire envelopes that opt into the
  * `schemaVersion` forward-compat field (see {@link ActionEnvelope},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/protocol",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "ggui protocol types — events, renders, WebSocket, MCP, LLM models",
   "license": "Apache-2.0",
   "keywords": [
@@ -50,6 +50,12 @@
       "require": "./dist/registry/blueprint-key.js",
       "default": "./dist/registry/blueprint-key.js"
     },
+    "./props-schema-hash": {
+      "types": "./dist/registry/props-schema-hash.d.ts",
+      "import": "./dist/registry/props-schema-hash.js",
+      "require": "./dist/registry/props-schema-hash.js",
+      "default": "./dist/registry/props-schema-hash.js"
+    },
     "./transport/websocket": {
       "types": "./dist/transport/websocket.d.ts",
       "import": "./dist/transport/websocket.js",