@ggui-ai/mcp-server-handlers 0.6.2 → 0.7.0

package/dist/renders/render.js

@@ -53,6 +53,8 @@ import { handlerFailure, isHandlerFailure, } from '../types.js';
 import { consumeHandshakeRecord, peekHandshakeRecord, HandshakeNotFoundError, } from './handshake.js';
 import { evaluateProvisionalPreviewGate, finalizeProvisionalPreview, kickoffProvisionalPreview, } from './provisional-preview.js';
 import { assertNoDuplicateGadgetHooks } from './assert-no-duplicate-gadget-hooks.js';
+import { reportRenderCodeWriteFailed } from './code-delivery-events.js';
+import { writeRenderIdentity } from './render-identity.js';
 import { findBlueprintExact, readBlueprintById, registerBlueprint, } from './blueprint-registry.js';
 import { assertGadgetsRegistered, filterDescriptorsToContract, } from './assert-gadgets.js';
 import { fetchGadgetTypes } from './fetch-gadget-types.js';
@@ -316,6 +318,24 @@ export function createGguiRenderHandler(deps) {
             // the §6 re-resolution and the cold-gen registration below both
             // key on it, so reuse / registration stay on the same identity.
             const effectiveVariantKey = variantKey(effectiveVariance);
+            // Contract axis of that same reuse key. Pure over the effective
+            // contract, so it is computed ONCE here and read everywhere:
+            // the §6 exact re-resolution, the wire `contractHash` field, the
+            // resource-URI segment, and the durable identity record every
+            // commit site writes. Hoisted to handler scope because the
+            // identity write-through happens at commit time — well before
+            // the wire output is assembled.
+            const effectiveContractKey = blueprintKey(effectiveContract);
+            // Bind the identity slice a commit will record. The blueprint id
+            // is per-path (a reuse knows it up front; a cold gen resolves it
+            // via registration immediately BEFORE its success commit — #460),
+            // which is why it is a parameter and the contract/variant axes
+            // are captured.
+            const identityWriterFor = (blueprintId) => (committed) => writeRenderIdentity(deps.renderIdentityStore, committed, {
+                blueprintId,
+                contractKey: effectiveContractKey,
+                variantKey: effectiveVariantKey,
+            });
             // Resolved gadget catalog, lifted to handler scope. When
             // `appMetadataStore` is bound, the registry-membership block
             // below captures the catalog (App record's `gadgets`, or
@@ -606,16 +626,20 @@ export function createGguiRenderHandler(deps) {
                     contentType: 'application/javascript+react',
                     createdAt: nowEpochMs,
                     lastActivityAt: nowEpochMs,
-                    expiresAt: nowEpochMs + DEFAULT_RENDER_TTL_MS,
+                    expiresAt: nowEpochMs + (deps.renderTtlMs ?? DEFAULT_RENDER_TTL_MS),
                     eventSequence: 0,
                 };
                 try {
-                    await deps.renderStore.commit({
+                    const committed = await deps.renderStore.commit({
                         render: placeholder,
                         appId: ctx.appId,
                         userId: ctx.userId, // per-user isolation (undefined for non-federated single-user)
                     });
                     placeholderCommitted = true;
+                    // The placeholder is a real row a locator can address, so it
+                    // gets a record too — the later in-place replacement
+                    // overwrites it with the settled identity.
+                    await identityWriterFor(null)(committed);
                 }
                 catch {
                     // Defensive — a placeholder-commit failure is not fatal to
@@ -671,18 +695,19 @@ export function createGguiRenderHandler(deps) {
                     kind: 'mcp-apps-probe',
                     createdAt: nowEpochMs,
                     lastActivityAt: nowEpochMs,
-                    expiresAt: nowEpochMs + DEFAULT_RENDER_TTL_MS,
+                    expiresAt: nowEpochMs + (deps.renderTtlMs ?? DEFAULT_RENDER_TTL_MS),
                     eventSequence: 0,
                     props: { intent: story.intent },
                 };
                 try {
-                    await deps.renderStore.commit({
+                    const committed = await deps.renderStore.commit({
                         render: probeRender,
                         appId: ctx.appId,
                         userId: ctx.userId, // per-user isolation (undefined for non-federated single-user)
                     });
                     safelyNotifyGguiSessionCommit(deps.channelNotifier, sessionId, probeRender);
                     generatedCodeReady = true;
+                    await identityWriterFor(null)(committed);
                 }
                 catch {
                     // Commit failure leaves codeReady=false; downstream synth
@@ -796,7 +821,7 @@ export function createGguiRenderHandler(deps) {
                     // `(contractKey, effectiveVariantKey)` and reuse a stored
                     // component for that exact variant if one exists (per-app first,
                     // then seed pools — see fan-out comment above).
-                    const bp = await findExactAcrossPools(blueprintKey(effectiveContract), effectiveVariantKey);
+                    const bp = await findExactAcrossPools(effectiveContractKey, effectiveVariantKey);
                     if (bp) {
                         blueprintHit = {
                             id: bp.id,
@@ -808,11 +833,18 @@ export function createGguiRenderHandler(deps) {
                     }
                 }
                 if (blueprintHit) {
-                    generatedCodeReady = await commitCachedGguiSession(deps.renderStore, deps.provisionalPreview, deps.channelNotifier, deps.checkRenderContracts, {
+                    // Reuse → the stored UUID is the materialised component id.
+                    // `cache.cachedBlueprintId === blueprintId` on a hit (§9.3).
+                    // Resolved BEFORE the commit so the identity record written
+                    // at that commit already carries the id (no backfill needed
+                    // on this path).
+                    resolvedBlueprintId = blueprintHit.id;
+                    generatedCodeReady = await commitCachedGguiSession(deps.renderStore, deps.provisionalPreview, deps.channelNotifier, deps.checkRenderContracts, deps.renderTtlMs, {
                         sessionId,
                         appId: ctx.appId,
                         userId: ctx.userId, // per-user isolation (undefined for non-federated single-user)
                         story,
+                        writeIdentity: identityWriterFor(blueprintHit.id),
                         cacheHit: {
                             cachedBlueprintId: blueprintHit.id,
                             similarity: blueprintHit.cosine,
@@ -874,9 +906,6 @@ export function createGguiRenderHandler(deps) {
                         kind: 'full-template',
                         reason: `full-template: reused stored blueprint ${blueprintHit.id}; 1 generation call avoided`,
                     };
-                    // Reuse → the stored UUID is the materialised component id.
-                    // `cache.cachedBlueprintId === blueprintId` on a hit (§9.3).
-                    resolvedBlueprintId = blueprintHit.id;
                 }
                 else {
                     // The `.d.ts` fetch is deferred to HERE — the cold-gen
@@ -890,10 +919,57 @@ export function createGguiRenderHandler(deps) {
                     const resolvedGadgetTypes = resolvedAppLibraries !== undefined
                         ? await fetchGadgetTypes(resolvedAppLibraries)
                         : undefined;
-                    const outcome = await runGenerationIntoGguiSession(deps.generation, deps.renderStore, deps.provisionalPreview, deps.channelNotifier, deps.checkRenderContracts, deps.generator, {
+                    const generationCache = deps.generation.cache;
+                    const outcome = await runGenerationIntoGguiSession(deps.generation, deps.renderStore, deps.provisionalPreview, deps.channelNotifier, deps.checkRenderContracts, deps.generator, deps.renderTtlMs, {
                         ctx,
                         sessionId,
                         story,
+                        // #460 — the callee binds each commit's id itself:
+                        // failure commits bind null; the success commit binds
+                        // whatever `resolveBlueprintId` returned, resolved
+                        // BEFORE that commit (no backfill exists anymore).
+                        writeIdentityFor: identityWriterFor,
+                        // Registration is the resolve hook, passed only when a
+                        // cache is bound (unbound deployments keep null ids —
+                        // #445). Failures swallow to undefined inside
+                        // `safelyRegisterBlueprint`, incl. fail-closed
+                        // rejections. The cache handle is captured as a const so
+                        // the async closure keeps the narrowing.
+                        ...(generationCache
+                            ? {
+                                resolveBlueprintId: async (produced) => safelyRegisterBlueprint({
+                                    embedding: generationCache.embedding,
+                                    vectorStore: generationCache.vectorStore,
+                                    index: generationCache.index,
+                                    // Forwarded so a fresh mint is written
+                                    // through to durable storage. Undefined on
+                                    // deployments that bound none, which
+                                    // `registerBlueprint` treats as a no-op.
+                                    ...(generationCache.durability !== undefined
+                                        ? { durability: generationCache.durability }
+                                        : {}),
+                                }, ctx.appId, {
+                                    kind: 'template',
+                                    contract: story.contract,
+                                    intent,
+                                    componentCode: produced.componentCode,
+                                    // Engine provenance from the generator's own
+                                    // metadata stamp — a fresh generation mints
+                                    // an `llm`-sourced row.
+                                    source: produced.source,
+                                    // Register under the EFFECTIVE variance
+                                    // (proposed on accept, re-aimed on
+                                    // `override.variance`) so the row's
+                                    // `variantKey` equals `effectiveVariantKey`
+                                    // — the same `(contractKey, variantKey)`
+                                    // identity the §6 re-resolution and the wire
+                                    // output key on.
+                                    ...(effectiveVariance !== undefined
+                                        ? { variance: effectiveVariance }
+                                        : {}),
+                                }),
+                            }
+                            : {}),
                         ...(runtimeProps !== undefined
                             ? { runtimeProps: runtimeProps }
                             : {}),
@@ -925,36 +1001,12 @@ export function createGguiRenderHandler(deps) {
                                 ? 'cold: generated fresh — no stored component was reused for this render'
                                 : 'cold: generation failed — no stored component was produced or reused',
                         };
-                        // Register the produced blueprint into the registry so
-                        // future calls can hit Tier 1 (exact contract match) or
-                        // Tier 2 (semantic neighbour). The minted UUID becomes this
-                        // render's `blueprintId` (a fresh generation mints a new id).
-                        // Register under the EFFECTIVE variance (proposed on accept,
-                        // re-aimed on `override.variance`) so the row's `variantKey`
-                        // equals `effectiveVariantKey` — the same
-                        // `(contractKey, variantKey)` identity the §6 re-resolution
-                        // and the wire output key on. Never the default sentinel when
-                        // an override re-aimed the variant.
-                        if (outcome.ok && outcome.componentCode && outcome.source) {
-                            const registered = await safelyRegisterBlueprint({
-                                embedding: deps.generation.cache.embedding,
-                                vectorStore: deps.generation.cache.vectorStore,
-                                index: deps.generation.cache.index,
-                            }, ctx.appId, {
-                                kind: 'template',
-                                contract: story.contract,
-                                intent,
-                                componentCode: outcome.componentCode,
-                                // Engine provenance travels on the outcome — the
-                                // generator stamped its own slug + the resolved
-                                // model id into metadata, and a fresh generation
-                                // mints an `llm`-sourced row.
-                                source: outcome.source,
-                                ...(effectiveVariance !== undefined
-                                    ? { variance: effectiveVariance }
-                                    : {}),
-                            });
-                            resolvedBlueprintId = registered;
+                        // #460 — registration already ran INSIDE the generation
+                        // call, before the success commit (the resolve hook
+                        // above); the outcome carries the id the committed
+                        // identity record was written with. No backfill exists.
+                        if (outcome.ok) {
+                            resolvedBlueprintId = outcome.blueprintId;
                         }
                     }
                 }
@@ -990,15 +1042,16 @@ export function createGguiRenderHandler(deps) {
                     contentType: 'application/javascript+react',
                     createdAt: nowEpochMs,
                     lastActivityAt: nowEpochMs,
-                    expiresAt: nowEpochMs + DEFAULT_RENDER_TTL_MS,
+                    expiresAt: nowEpochMs + (deps.renderTtlMs ?? DEFAULT_RENDER_TTL_MS),
                     eventSequence: 0,
                 };
                 try {
-                    await deps.renderStore.commit({
+                    const committed = await deps.renderStore.commit({
                         render: placeholder,
                         appId: ctx.appId,
                         userId: ctx.userId, // per-user isolation (undefined for non-federated single-user)
                     });
+                    await identityWriterFor(null)(committed);
                 }
                 catch {
                     // Defensive, matching the provisional-preview placeholder
@@ -1015,10 +1068,30 @@ export function createGguiRenderHandler(deps) {
             // several branches above (cache-hit, fresh generation, MCP Apps
             // inbound) — re-reading is simpler than threading a reference
             // through every branch and matches resultMeta's own pattern.
-            // Failures are silent: on a put error or a missing render we
-            // fall through with no codeUrl. Without codeUrl, the iframe
-            // falls back to live-mode (wsUrl+token) — the render is
-            // delivered via the live-channel WS subscribe.
+            //
+            // A store failure does NOT fail the render: the code is already
+            // generated and the row already committed. But nothing catches
+            // the envelope either — the guard above narrowed this to a
+            // compiled-component render, and `codeUrl` is the only STATIC
+            // delivery surface such a render has (the other static mode,
+            // system-card `kind`, is excluded by that same guard). What
+            // survives is deployment-shaped, and no arm of it is visible on
+            // the wire:
+            //
+            //   - `mintWsToken` wired ⇒ the slice still carries the live
+            //     trio, the iframe subscribes, and the WS delivers the
+            //     render body. Cost: the zero-round-trip first paint.
+            //   - A host that resolves `resourceUri` re-mints `codeUrl`
+            //     against this same store at READ time, so a transient
+            //     fault costs it nothing.
+            //   - Neither ⇒ this envelope's slice keeps `runtimeUrl` and no
+            //     mode discriminator, which hosts read as "not a mountable
+            //     ggui render".
+            //
+            // Hence the named event rather than a swallow — see
+            // `code-delivery-events.ts`. A render with no `componentCode`
+            // (the placeholder / system arms) is not a failure and emits
+            // nothing: there was never a body to deliver.
             let codeUrl;
             let codeHash;
             if (deps.codeStore && deps.codeBaseUrl) {
@@ -1037,8 +1110,17 @@ export function createGguiRenderHandler(deps) {
                         codeUrl = `${base}/code/${hash}.js`;
                     }
                 }
-                catch {
-                    // Silent — codeStore failure falls back to inline-base64 path.
+                catch (err) {
+                    // Named for the OUTCOME, not the call: a throwing
+                    // `renderStore.get` or `hashOf` reaches here too, and the
+                    // consequence is identical — this envelope has no codeUrl.
+                    // `error` carries which one it was.
+                    reportRenderCodeWriteFailed({
+                        sessionId,
+                        appId: ctx.appId,
+                        liveChannelWired: deps.mintWsToken !== undefined,
+                        cause: err,
+                    });
                 }
             }
             // Per-render theme overlay. The commit paths above
@@ -1064,11 +1146,16 @@ export function createGguiRenderHandler(deps) {
                         top.type !== 'mcpApps' &&
                         top.type !== 'system') {
                         const overlaid = { ...top, themeId: parsed.themeId };
-                        await deps.renderStore.commit({
+                        const committed = await deps.renderStore.commit({
                             render: overlaid,
                             appId: ctx.appId,
                             userId: ctx.userId, // per-user isolation (undefined for non-federated single-user)
                         });
+                        // Last commit of the render when a theme override is in
+                        // play, and every reuse / cold-gen path has settled by
+                        // here — so this write carries the final blueprint id
+                        // (already resolved before the success commit, #460).
+                        await identityWriterFor(resolvedBlueprintId ?? null)(committed);
                     }
                 }
                 catch (err) {
@@ -1076,14 +1163,6 @@ export function createGguiRenderHandler(deps) {
                     console.warn('[ggui_render.theme_overlay_failed]', err instanceof Error ? err.message : String(err));
                 }
             }
-            // Canonical-key of the resolved contract. Surface on output so
-            // downstream consumers (resultMeta builder, cache trace,
-            // resource URI minter) read from a single computed value
-            // instead of recomputing against the same canonicalization.
-            // This is the same hash the handshake returned as
-            // `contractHash`. The variant axis pairs with this on the wire
-            // output via `effectiveVariantKey` (computed once up top).
-            const resolvedContractHash = blueprintKey(effectiveContract);
             // ── Failure envelope (SPEC §7.1) ──────────────────────────────
             //
             // A failed/rejected generation returns the in-result failure
@@ -1106,7 +1185,7 @@ export function createGguiRenderHandler(deps) {
                     shortCode,
                     codeReady: false,
                     handshakeId: handshakeRecord.handshakeId,
-                    contractHash: resolvedContractHash,
+                    contractHash: effectiveContractKey,
                     // Present-on-materialisation (§9.1): no component
                     // materialised, so the id is the empty sentinel.
                     blueprintId: '',
@@ -1128,7 +1207,7 @@ export function createGguiRenderHandler(deps) {
                         ctx,
                         sessionId,
                         contract: effectiveContract,
-                        contractHash: resolvedContractHash,
+                        contractHash: effectiveContractKey,
                         intent: story.intent,
                         action,
                         codeReady: false,
@@ -1163,8 +1242,8 @@ export function createGguiRenderHandler(deps) {
             // structuredContent too lets agent SDKs that strip `_meta` from
             // tool_results (OpenAI Agents SDK, Google ADK) still hand a
             // mount handle to their frontend without the side-channel.
-            const blueprintSegmentForOutput = resolvedContractHash
-                ? `/${resolvedContractHash}`
+            const blueprintSegmentForOutput = effectiveContractKey
+                ? `/${effectiveContractKey}`
                 : '';
             const resourceUriForOutput = `${GGUI_RENDER_UI_META.resourceUri}/${sessionId}${blueprintSegmentForOutput}`;
             const result = {
@@ -1174,7 +1253,7 @@ export function createGguiRenderHandler(deps) {
                 shortCode,
                 codeReady: generatedCodeReady,
                 handshakeId: handshakeRecord.handshakeId,
-                contractHash: resolvedContractHash,
+                contractHash: effectiveContractKey,
                 // Reuse → stored UUID (§6 point-read); cold-gen → minted UUID
                 // (`safelyRegisterBlueprint`). Empty only on the
                 // genuinely-no-component branches (probe-card / generation-off),
@@ -1200,7 +1279,7 @@ export function createGguiRenderHandler(deps) {
                     ctx,
                     sessionId,
                     contract: effectiveContract,
-                    contractHash: resolvedContractHash,
+                    contractHash: effectiveContractKey,
                     intent: story.intent,
                     action,
                     codeReady: generatedCodeReady,
@@ -1416,7 +1495,13 @@ export function createGguiRenderHandler(deps) {
  * semantics; anything shorter would close active renders mid-lifecycle.
  */
 const DEFAULT_RENDER_TTL_MS = 60 * 60 * 1000;
-async function runGenerationIntoGguiSession(generation, renderStore, previewDeps, channelNotifier, checkRenderContracts, generatorOverride, args) {
+async function runGenerationIntoGguiSession(generation, renderStore, previewDeps, channelNotifier, checkRenderContracts, generatorOverride, 
+/**
+ * Render-row retention window in ms — forwarded from
+ * `GguiRenderHandlerDeps.renderTtlMs`. `undefined` falls back to
+ * `DEFAULT_RENDER_TTL_MS` at each commit site below.
+ */
+renderTtlMs, args) {
     const { ctx, sessionId, story } = args;
     const nowIso = new Date().toISOString();
     const nowEpochMs = Date.now();
@@ -1449,13 +1534,14 @@ async function runGenerationIntoGguiSession(generation, renderStore, previewDeps
             result = await generatorOverride(generateInputBase, ctx);
         }
         catch (err) {
-            return commitErrorGguiSession(renderStore, previewDeps, channelNotifier, {
+            return commitErrorGguiSession(renderStore, previewDeps, channelNotifier, renderTtlMs, {
                 sessionId,
                 appId: ctx.appId,
                 userId: ctx.userId, // per-user isolation (undefined for non-federated single-user)
                 story,
                 nowIso,
                 nowEpochMs,
+                writeIdentity: args.writeIdentityFor(null),
                 message: err instanceof Error
                     ? `generator threw: ${err.message}`
                     : 'generator threw',
@@ -1472,13 +1558,14 @@ async function runGenerationIntoGguiSession(generation, renderStore, previewDeps
             creds = await generation.resolveLlm(ctx);
         }
         catch (err) {
-            return commitErrorGguiSession(renderStore, previewDeps, channelNotifier, {
+            return commitErrorGguiSession(renderStore, previewDeps, channelNotifier, renderTtlMs, {
                 sessionId,
                 appId: ctx.appId,
                 userId: ctx.userId, // per-user isolation (undefined for non-federated single-user)
                 story,
                 nowIso,
                 nowEpochMs,
+                writeIdentity: args.writeIdentityFor(null),
                 message: err instanceof Error
                     ? `credential resolution failed: ${err.message}`
                     : 'credential resolution failed',
@@ -1508,16 +1595,18 @@ async function runGenerationIntoGguiSession(generation, renderStore, previewDeps
                         userId: ctx.userId, // per-user isolation (undefined for non-federated single-user)
                         nowIso,
                         render: fallback,
+                        writeIdentity: args.writeIdentityFor(null),
                     });
                 }
             }
-            return commitErrorGguiSession(renderStore, previewDeps, channelNotifier, {
+            return commitErrorGguiSession(renderStore, previewDeps, channelNotifier, renderTtlMs, {
                 sessionId,
                 appId: ctx.appId,
                 userId: ctx.userId, // per-user isolation (undefined for non-federated single-user)
                 story,
                 nowIso,
                 nowEpochMs,
+                writeIdentity: args.writeIdentityFor(null),
                 message: 'no credentials available for the configured generation provider (expected env var or ~/.ggui/credentials.json entry)',
                 code: 'NO_CREDENTIALS',
                 reason: 'no-credentials',
@@ -1532,13 +1621,14 @@ async function runGenerationIntoGguiSession(generation, renderStore, previewDeps
             });
         }
         catch (err) {
-            return commitErrorGguiSession(renderStore, previewDeps, channelNotifier, {
+            return commitErrorGguiSession(renderStore, previewDeps, channelNotifier, renderTtlMs, {
                 sessionId,
                 appId: ctx.appId,
                 userId: ctx.userId, // per-user isolation (undefined for non-federated single-user)
                 story,
                 nowIso,
                 nowEpochMs,
+                writeIdentity: args.writeIdentityFor(null),
                 message: err instanceof Error
                     ? `generator threw: ${err.message}`
                     : 'generator threw',
@@ -1549,13 +1639,14 @@ async function runGenerationIntoGguiSession(generation, renderStore, previewDeps
         }
     }
     if (!result.ok) {
-        return commitErrorGguiSession(renderStore, previewDeps, channelNotifier, {
+        return commitErrorGguiSession(renderStore, previewDeps, channelNotifier, renderTtlMs, {
             sessionId,
             appId: ctx.appId,
             userId: ctx.userId, // per-user isolation (undefined for non-federated single-user)
             story,
             nowIso,
             nowEpochMs,
+            writeIdentity: args.writeIdentityFor(null),
             message: result.error.message,
             // Canonical projection — cloud seam codes (VALIDATION_ERROR /
             // NO_PLATFORM_KEY / PRODUCTION_FAILED) map through 1:1;
@@ -1576,7 +1667,7 @@ async function runGenerationIntoGguiSession(generation, renderStore, previewDeps
         contentType: 'application/javascript+react',
         createdAt: nowEpochMs,
         lastActivityAt: nowEpochMs,
-        expiresAt: nowEpochMs + DEFAULT_RENDER_TTL_MS,
+        expiresAt: nowEpochMs + (renderTtlMs ?? DEFAULT_RENDER_TTL_MS),
         eventSequence: 0,
         ...(result.response.warnings && result.response.warnings.length > 0
             ? { description: result.response.warnings[0] }
@@ -1617,12 +1708,30 @@ async function runGenerationIntoGguiSession(generation, renderStore, previewDeps
             throw err;
         }
     }
+    // #460 — resolve the blueprint id BEFORE the commit. Registration
+    // was already awaited on this path (it just ran after the commit),
+    // so the reorder adds no latency and deletes the get+put backfill —
+    // and with it the backfill's stale-write race against the pod's
+    // field-targeted seq advance.
+    const producedSource = {
+        kind: 'llm',
+        generator: result.metadata.generator,
+        model: result.metadata.model,
+    };
+    let resolvedBlueprintId;
+    if (args.resolveBlueprintId) {
+        resolvedBlueprintId = await args.resolveBlueprintId({
+            componentCode: result.response.componentCode,
+            source: producedSource,
+        });
+    }
     try {
-        await renderStore.commit({
+        const committed = await renderStore.commit({
             render: componentRender,
             appId: ctx.appId,
             userId: ctx.userId, // per-user isolation (undefined for non-federated single-user)
         });
+        await args.writeIdentityFor(resolvedBlueprintId ?? null)(committed);
     }
     catch {
         await safelyFinalizePreview(previewDeps, sessionId, 'commit-failed');
@@ -1645,11 +1754,10 @@ async function runGenerationIntoGguiSession(generation, renderStore, previewDeps
         ok: true,
         componentCode: result.response.componentCode,
         createdAt: nowIso,
-        source: {
-            kind: 'llm',
-            generator: result.metadata.generator,
-            model: result.metadata.model,
-        },
+        source: producedSource,
+        ...(resolvedBlueprintId !== undefined
+            ? { blueprintId: resolvedBlueprintId }
+            : {}),
     };
 }
 /**
@@ -1670,12 +1778,13 @@ async function commitNoCredentialsCardGguiSession(renderStore, previewDeps, chan
     const render = { ...args.render, id: args.sessionId };
     let committed = false;
     try {
-        await renderStore.commit({
+        const stored = await renderStore.commit({
             render,
             appId: args.appId,
             userId: args.userId,
         });
         committed = true;
+        await args.writeIdentity(stored);
     }
     catch {
         // Commit rejected — preview teardown is the only honest recovery;
@@ -1709,7 +1818,9 @@ async function commitNoCredentialsCardGguiSession(renderStore, previewDeps, chan
  * `componentCode === ''` by showing a fallback UI; the extra `error`
  * field carries the operator-facing reason.
  */
-async function commitErrorGguiSession(renderStore, previewDeps, channelNotifier, args) {
+async function commitErrorGguiSession(renderStore, previewDeps, channelNotifier, 
+/** Forwarded from `GguiRenderHandlerDeps.renderTtlMs` (see there). */
+renderTtlMs, args) {
     const errorRender = {
         id: args.sessionId,
         appId: args.appId,
@@ -1720,18 +1831,19 @@ async function commitErrorGguiSession(renderStore, previewDeps, channelNotifier,
         contentType: 'application/javascript+react',
         createdAt: args.nowEpochMs,
         lastActivityAt: args.nowEpochMs,
-        expiresAt: args.nowEpochMs + DEFAULT_RENDER_TTL_MS,
+        expiresAt: args.nowEpochMs + (renderTtlMs ?? DEFAULT_RENDER_TTL_MS),
         eventSequence: 0,
         ...(args.appTheme !== undefined ? { theme: args.appTheme } : {}),
     };
     let committed = false;
     try {
-        await renderStore.commit({
+        const stored = await renderStore.commit({
             render: errorRender,
             appId: args.appId,
             userId: args.userId,
         });
         committed = true;
+        await args.writeIdentity(stored);
     }
     catch {
         // Secondary failure — render store rejected the error record.
@@ -1810,7 +1922,9 @@ function isJsonObject(v) {
  * returns `codeReady: false` so the agent observes the degraded
  * state through the channel instead of a synthetic "ready" signal).
  */
-async function commitCachedGguiSession(renderStore, previewDeps, channelNotifier, checkRenderContracts, args) {
+async function commitCachedGguiSession(renderStore, previewDeps, channelNotifier, checkRenderContracts, 
+/** Forwarded from `GguiRenderHandlerDeps.renderTtlMs` (see there). */
+renderTtlMs, args) {
     const nowEpochMs = Date.now();
     // Cached path — project optional contract fields onto the
     // ComponentGguiSession so the bootstrap-meta derivation in `resultMeta`
@@ -1824,7 +1938,7 @@ async function commitCachedGguiSession(renderStore, previewDeps, channelNotifier
         contentType: 'application/javascript+react',
         createdAt: nowEpochMs,
         lastActivityAt: nowEpochMs,
-        expiresAt: nowEpochMs + DEFAULT_RENDER_TTL_MS,
+        expiresAt: nowEpochMs + (renderTtlMs ?? DEFAULT_RENDER_TTL_MS),
         eventSequence: 0,
         ...(args.runtimeProps !== undefined
             ? { props: args.runtimeProps }
@@ -1862,11 +1976,12 @@ async function commitCachedGguiSession(renderStore, previewDeps, channelNotifier
         }
     }
     try {
-        await renderStore.commit({
+        const committed = await renderStore.commit({
             render: componentRender,
             appId: args.appId,
             userId: args.userId,
         });
+        await args.writeIdentity(committed);
     }
     catch {
         await safelyFinalizePreview(previewDeps, args.sessionId, 'commit-failed');

package/dist/renders/sync-context.d.ts

@@ -52,7 +52,7 @@
  * IS the addressable scope.
  */
 import { z } from 'zod';
-import type { GguiSessionStore } from '@ggui-ai/mcp-server-core';
+import type { GguiSessionStore, RenderIdentityStore } from '@ggui-ai/mcp-server-core';
 import type { SharedHandler } from '../types.js';
 declare const inputSchema: {
     readonly sessionId: z.ZodString;
@@ -80,6 +80,18 @@ interface SyncContextRejected {
 type SyncContextOutput = SyncContextAccepted | SyncContextRejected;
 export interface CreateGguiSyncContextHandlerDeps {
     readonly renderStore: GguiSessionStore;
+    /**
+     * Durable render-identity side store. A snapshot sync re-commits the
+     * render row, so when a record exists its freshness stamp is
+     * refreshed off the committed row.
+     *
+     * Note what this does NOT persist: the record carries no
+     * `contextSnapshot`, so the snapshot itself stays on the render row
+     * alone. Identity fields are never recomputed here, and a render
+     * with no record yet is skipped rather than synthesized. Writes are
+     * best-effort and can never fail the sync.
+     */
+    readonly renderIdentityStore?: RenderIdentityStore;
 }
 /**
  * Build the `ggui_runtime_sync_context` handler. Registers as app-visible so

package/dist/renders/sync-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync-context.d.ts","sourceRoot":"","sources":["../../src/renders/sync-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,QAAA,MAAM,WAAW;;;;CAyBP,CAAC;AAEX,QAAA,MAAM,YAAY;;;;;;;;;CAWR,CAAC;AAEX,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;CACnB;AACD,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,IAAI,EACT,mBAAmB,GACnB,iBAAiB,GACjB,0BAA0B,GAC1B,mBAAmB,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AACD,KAAK,iBAAiB,GAAG,mBAAmB,GAAG,mBAAmB,CAAC;AAEnE,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;CACxC;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,gCAAgC,GACrC,aAAa,CAAC,OAAO,WAAW,EAAE,OAAO,YAAY,EAAE,iBAAiB,CAAC,CAmH3E"}
+{"version":3,"file":"sync-context.d.ts","sourceRoot":"","sources":["../../src/renders/sync-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB,OAAO,KAAK,EACV,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,QAAA,MAAM,WAAW;;;;CAyBP,CAAC;AAEX,QAAA,MAAM,YAAY;;;;;;;;;CAWR,CAAC;AAEX,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;CACnB;AACD,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,IAAI,EACT,mBAAmB,GACnB,iBAAiB,GACjB,0BAA0B,GAC1B,mBAAmB,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AACD,KAAK,iBAAiB,GAAG,mBAAmB,GAAG,mBAAmB,CAAC;AAEnE,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;CACpD;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,gCAAgC,GACrC,aAAa,CAAC,OAAO,WAAW,EAAE,OAAO,YAAY,EAAE,iBAAiB,CAAC,CAwH3E"}