@ggui-ai/mcp-server-handlers 0.25.0 → 0.26.0

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

@@ -4,7 +4,7 @@
  *
  * Sibling of `ggui_ops_generate_blueprint`. Same persistence seams +
  * dual-write (BlueprintStore + cache vectorStore via registerBlueprint),
- * same variance + default-pin semantics. The only difference is the
+ * same variance + operator-default mark semantics. The only difference is the
  * code body: instead of dispatching through `generator.generate(...)`
  * to produce componentCode, the operator supplies the bytes directly
  * and the handler persists them verbatim.
@@ -36,7 +36,7 @@
  *     ops_generate — schema-compat + hygiene-3 lint live elsewhere.
  */
 import type { AppMetadataStore, BlueprintStore, TelemetrySink } from "@ggui-ai/mcp-server-core";
-import { type Blueprint, type DataContract, type LlmBlueprintSource, type UserBlueprintSource } from "@ggui-ai/protocol";
+import { type Blueprint, type DataContract, type GeneratorBuild, type LlmBlueprintSource, type UserBlueprintSource } from "@ggui-ai/protocol";
 import { z } from "zod";
 import { type BlueprintRegistryDeps } from "../renders/index.js";
 import { type HandlerContext } from "../types.js";
@@ -132,6 +132,7 @@ export declare function createGguiOpsRegisterBlueprintHandler(deps: GguiOpsRegis
         request: "request";
     }>>;
     setAsOperatorDefault: z.ZodOptional<z.ZodBoolean>;
+    clonedFrom: z.ZodOptional<z.ZodString>;
 }, {
     blueprintId: z.ZodString;
     codeHash: z.ZodString;
@@ -165,6 +166,14 @@ export interface GeneratedBlueprintBytes {
      * claim nobody made. Validated against the protocol's schema.
      */
     readonly source: LlmBlueprintSource;
+    /**
+     * ggui#1280 — the build the generation reported (`metadata.build`),
+     * verbatim. Admitted by the registry's one rule (`admitGeneratorBuild`):
+     * a stamp that fails the protocol's `generatorBuildSchema` is dropped
+     * with a `blueprint_build_stamp_dropped` line and the row registers
+     * unstamped, so a bad stamp never refuses a registration.
+     */
+    readonly build?: GeneratorBuild;
 }
 /** What {@link createRegisterGeneratedBlueprint}'s entry returns. */
 export interface RegisterGeneratedBlueprintOutput {
@@ -184,10 +193,12 @@ export type RegisterGeneratedBlueprint = (input: Record<string, unknown>, genera
  * with the authored source they were compiled from, in-process.
  *
  * Same body as `ggui_ops_register_blueprint` (one durable row, one cache
- * mirror, the same gates and variance), with two differences: provenance
- * is the generation's `llm` arm, and the authored source reaches the
- * cache registry, so a render that reuses the registration serves it
- * (`ggui_get_render_source`, save-to-library). It is NOT an MCP tool and
+ * mirror, the same gates and variance), with three differences: provenance
+ * is the generation's `llm` arm; the authored source reaches the cache
+ * registry, so a render that reuses the registration serves it
+ * (`ggui_get_render_source`, save-to-library); and the generation's build,
+ * when the caller passes one, is stamped on the durable rows (ggui#1280).
+ * It is NOT an MCP tool and
  * is on no wire: the public operator door stays source-free, because it
  * cannot verify that supplied source compiles to the supplied code.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/ops-blueprint/register.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,cAAc,EACd,aAAa,EACd,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAGL,KAAK,SAAS,EAEd,KAAK,YAAY,EACjB,KAAK,kBAAkB,EAGvB,KAAK,mBAAmB,EACzB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAqB,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACpF,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAyB,KAAK,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AACxF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAkBjD;;;;;;;GAOG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CAAC;IAC1E;;;;;;;OAOG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAC7C;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;IAC/B;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,qBAAqB,CAAC;IAC/C;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;IACnC;;OAEG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B;;OAEG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,MAAM,CAAC;IACxC;;;;;;;OAOG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,yBAAyB,CAAC;CACzD;AA0OD,wBAAgB,qCAAqC,CACnD,IAAI,EAAE,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BnC;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;;;;;OASG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;CACrC;AAED,qEAAqE;AACrE,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;CACrC;AAED;;;;;GAKG;AACH,MAAM,MAAM,0BAA0B,GAAG,CACvC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,SAAS,EAAE,uBAAuB,EAClC,GAAG,EAAE,cAAc,KAChB,OAAO,CAAC,gCAAgC,CAAC,CAAC;AAE/C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,4BAA4B,GACjC,0BAA0B,CAgB5B"}
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/ops-blueprint/register.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,cAAc,EACd,aAAa,EACd,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAGL,KAAK,SAAS,EAEd,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EAGvB,KAAK,mBAAmB,EACzB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAuB,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEtF,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAyB,KAAK,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AACxF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAkBjD;;;;;;;GAOG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CAAC;IAC1E;;;;;;;OAOG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAC7C;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;IAC/B;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,qBAAqB,CAAC;IAC/C;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;IACnC;;OAEG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B;;OAEG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,MAAM,CAAC;IACxC;;;;;;;OAOG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,yBAAyB,CAAC;CACzD;AA0QD,wBAAgB,qCAAqC,CACnD,IAAI,EAAE,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BnC;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;;;;;OASG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,qEAAqE;AACrE,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;CACrC;AAED;;;;;GAKG;AACH,MAAM,MAAM,0BAA0B,GAAG,CACvC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,SAAS,EAAE,uBAAuB,EAClC,GAAG,EAAE,cAAc,KAChB,OAAO,CAAC,gCAAgC,CAAC,CAAC;AAE/C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,4BAA4B,GACjC,0BAA0B,CAkB5B"}

package/dist/ops-blueprint/register.js

@@ -4,7 +4,7 @@
  *
  * Sibling of `ggui_ops_generate_blueprint`. Same persistence seams +
  * dual-write (BlueprintStore + cache vectorStore via registerBlueprint),
- * same variance + default-pin semantics. The only difference is the
+ * same variance + operator-default mark semantics. The only difference is the
  * code body: instead of dispatching through `generator.generate(...)`
  * to produce componentCode, the operator supplies the bytes directly
  * and the handler persists them verbatim.
@@ -41,10 +41,11 @@ import { createHash, randomUUID } from "node:crypto";
 import { z } from "zod";
 import { assertContractNoRetiredFields } from "../renders/assert-contract-no-retired-fields.js";
 import { assertGadgetsRegistered } from "../renders/assert-gadgets.js";
-import { registerBlueprint } from "../renders/index.js";
+import { admitGeneratorBuild } from "../renders/index.js";
+import { mirrorIntoCache } from "./cache-mirror.js";
 import { defineHandler } from "../types.js";
 import { resolveEffectiveAppId } from "./app-access.js";
-import { DirectionScopeWithoutDigestError } from "./errors.js";
+import { ClonedFromRefusedError, DirectionScopeWithoutDigestError } from "./errors.js";
 import { findNearDuplicatePersona, normalizePersona } from "./persona-normalization.js";
 const opsInputSchema = opsRegisterBlueprintInputSchema.shape;
 const opsOutputSchema = z.object({
@@ -60,7 +61,7 @@ const opsOutputSchema = z.object({
 const USER_SOURCE = { kind: "user" };
 /**
  * The registration body both entries share: app resolution, the
- * contract gates, the durable row, the cache mirror, the default pin and
+ * contract gates, the durable row, the cache mirror, the operator-default mark and
  * the event. The two entries differ only in the provenance they pass.
  */
 function makeRegisterCore(deps) {
@@ -134,6 +135,18 @@ function makeRegisterCore(deps) {
             throw new DirectionScopeWithoutDigestError();
         }
         const blueprintId = mintBlueprintId();
+        // ggui#1570 — a copy (`clonedFrom`, the door's input member, which the
+        // in-process generated-bytes entry parses too) names another row of this
+        // app that the store holds. Checked after the id is minted (a copy never
+        // names itself) and before anything is persisted. The cache mirror's own
+        // durable write-through, when it writes to a store other than this one,
+        // does not carry it: that copy serves re-mint, which ignores provenance.
+        if (parsed.clonedFrom !== undefined) {
+            const parentId = parsed.clonedFrom;
+            const parent = parentId.length > 0 && parentId !== blueprintId ? await deps.blueprintStore.get(parentId) : null;
+            if (parent === null || parent.appId !== appId)
+                throw new ClonedFromRefusedError(parentId);
+        }
         // ONE variance for BOTH stores. The cache row's exact key is
         // `variantKey(variance)`; omitting it on the cache call filed every
         // variant under the default-variant key, where an earlier registration
@@ -155,6 +168,10 @@ function makeRegisterCore(deps) {
             // row here, cache mirror below): the user arm for operator-
             // supplied bytes, the llm arm for engine-generated ones.
             source: provenance.source,
+            // ggui#1280 — the minting build, on a generation mint's bytes only.
+            ...(provenance.build !== undefined ? { build: provenance.build } : {}),
+            // ggui#1570 — provenance about the row: the row whose bytes it copies.
+            ...(parsed.clonedFrom !== undefined ? { clonedFrom: parsed.clonedFrom } : {}),
             variance,
             createdAt: now(),
             createdBy: "operator",
@@ -178,41 +195,52 @@ function makeRegisterCore(deps) {
                     parsed.seedPrompt ??
                     normalizedPersona ??
                     `operator-registered blueprint (${blueprintId})`;
-                await registerBlueprint(deps.cacheRegistry, appId, {
-                    kind: "template",
-                    contract,
-                    intent: intentForCache,
-                    // ggui#1275 — an explicit intent or a seed prompt states the
-                    // UI's task. A persona describes the agent and the placeholder
-                    // describes nothing: both are stand-ins the matcher's judge
-                    // never sees.
-                    intentSource: parsed.intent !== undefined || parsed.seedPrompt !== undefined
-                        ? "authored"
-                        : "fallback",
-                    // ggui#1427 — the fit facts `fits()` reads before the judge
-                    // ranks this row. Absent inputs write nothing (not-evaluated).
-                    ...(parsed.judgedCanvases !== undefined ? { judgedCanvases: parsed.judgedCanvases } : {}),
-                    ...(parsed.aestheticPreset !== undefined ? { aestheticPreset: parsed.aestheticPreset } : {}),
-                    ...(parsed.directionDigest !== undefined ? { directionDigest: parsed.directionDigest } : {}),
-                    ...(parsed.directionDigest !== undefined && parsed.directionScope !== undefined
-                        ? { directionScope: parsed.directionScope }
-                        : {}),
-                    componentCode,
-                    // ggui#1493 — the authored form of `componentCode`, when the
-                    // caller has one (the in-process generated-bytes path only).
-                    // The registry persists its hash and body only when a code
-                    // store is bound and the pair is not byte-identical.
-                    ...(provenance.sourceCode !== undefined ? { sourceCode: provenance.sourceCode } : {}),
-                    // Same provenance as the MVB row above — one call, one
-                    // provenance claim across both stores.
-                    source: provenance.source,
-                    // The cache row MUST carry the same variance as the MVB row —
-                    // its exact key is `variantKey(variance)`.
-                    variance,
-                    // An operator invoked this tool. Without it the durable
-                    // record would claim the standard agent flow minted a row
-                    // that is retained permanently.
-                    createdBy: "operator",
+                // ggui#1497 — ONE id per registration: the cache row serves the
+                // durable row's id (see `mirrorIntoCache` for what else it writes).
+                await mirrorIntoCache({
+                    cacheRegistry: deps.cacheRegistry,
+                    writerStore: deps.blueprintStore,
+                    appId,
+                    blueprintId,
+                    input: {
+                        kind: "template",
+                        contract,
+                        intent: intentForCache,
+                        // ggui#1275 — an explicit intent or a seed prompt states the
+                        // UI's task. A persona describes the agent and the placeholder
+                        // describes nothing: both are stand-ins the matcher's judge
+                        // never sees.
+                        intentSource: parsed.intent !== undefined || parsed.seedPrompt !== undefined
+                            ? "authored"
+                            : "fallback",
+                        // ggui#1427 — the fit facts `fits()` reads before the judge
+                        // ranks this row. Absent inputs write nothing (not-evaluated).
+                        ...(parsed.judgedCanvases !== undefined ? { judgedCanvases: parsed.judgedCanvases } : {}),
+                        ...(parsed.aestheticPreset !== undefined ? { aestheticPreset: parsed.aestheticPreset } : {}),
+                        ...(parsed.directionDigest !== undefined ? { directionDigest: parsed.directionDigest } : {}),
+                        ...(parsed.directionDigest !== undefined && parsed.directionScope !== undefined
+                            ? { directionScope: parsed.directionScope }
+                            : {}),
+                        componentCode,
+                        // ggui#1493 — the authored form of `componentCode`, when the
+                        // caller has one (the in-process generated-bytes path only).
+                        // The registry persists its hash and body only when a code
+                        // store is bound and the pair is not byte-identical.
+                        ...(provenance.sourceCode !== undefined ? { sourceCode: provenance.sourceCode } : {}),
+                        // Same provenance as the MVB row above — one call, one
+                        // provenance claim across both stores.
+                        source: provenance.source,
+                        // ggui#1280 — the same stamp, onto the durable row a mirror
+                        // writes through to (never onto its vector-store row).
+                        ...(provenance.build !== undefined ? { build: provenance.build } : {}),
+                        // The cache row MUST carry the same variance as the MVB row —
+                        // its exact key is `variantKey(variance)`.
+                        variance,
+                        // An operator invoked this tool. Without it the durable
+                        // record would claim the standard agent flow minted a row
+                        // that is retained permanently.
+                        createdBy: "operator",
+                    },
                 });
             }
             catch (err) {
@@ -235,7 +263,7 @@ function makeRegisterCore(deps) {
                 }
             }
         }
-        // 4. Pin as operator default when requested.
+        // 4. Mark as operator default when requested.
         if (parsed.setAsOperatorDefault === true) {
             await deps.blueprintStore.setOperatorDefault(blueprintId);
         }
@@ -268,7 +296,7 @@ export function createGguiOpsRegisterBlueprintHandler(deps) {
         name: "ggui_ops_register_blueprint",
         title: "Register blueprint",
         audience: ["ops"],
-        description: "Register a pre-built blueprint variant (operator-supplied componentCode bytes, no LLM dispatch). Sibling of `ggui_ops_generate_blueprint` — same persistence + dual-write semantics, same variance + default-pin behavior. Use for fixture seeding, export/reimport round-trips, and manual recovery. Returns `{blueprintId, codeHash, source}` where `source` is always `{kind: 'user'}` — hand-supplied bytes carry no engine claim, so none is recorded. App-scoped variant curation for an app you operate — distinct from the personal saved-blueprint library (the _my_ tools).",
+        description: "Register a pre-built blueprint variant (operator-supplied componentCode bytes, no LLM dispatch). Sibling of `ggui_ops_generate_blueprint` — same persistence + dual-write semantics, same variance + operator-default mark behavior (the mark orders blueprint listings; it does not decide which blueprint serves a render). Use for fixture seeding, export/reimport round-trips, and manual recovery. Returns `{blueprintId, codeHash, source}` where `source` is always `{kind: 'user'}` — hand-supplied bytes carry no engine claim, so none is recorded. App-scoped variant curation for an app you operate — distinct from the personal saved-blueprint library (the _my_ tools).",
         inputSchema: opsInputSchema,
         outputSchema: opsOutputSchema,
         async handler(rawInput, ctx) {
@@ -289,10 +317,12 @@ export function createGguiOpsRegisterBlueprintHandler(deps) {
  * with the authored source they were compiled from, in-process.
  *
  * Same body as `ggui_ops_register_blueprint` (one durable row, one cache
- * mirror, the same gates and variance), with two differences: provenance
- * is the generation's `llm` arm, and the authored source reaches the
- * cache registry, so a render that reuses the registration serves it
- * (`ggui_get_render_source`, save-to-library). It is NOT an MCP tool and
+ * mirror, the same gates and variance), with three differences: provenance
+ * is the generation's `llm` arm; the authored source reaches the cache
+ * registry, so a render that reuses the registration serves it
+ * (`ggui_get_render_source`, save-to-library); and the generation's build,
+ * when the caller passes one, is stamped on the durable rows (ggui#1280).
+ * It is NOT an MCP tool and
  * is on no wire: the public operator door stays source-free, because it
  * cannot verify that supplied source compiles to the supplied code.
  *
@@ -307,9 +337,11 @@ export function createRegisterGeneratedBlueprint(deps) {
         if (generated.sourceCode.length === 0) {
             throw new Error("registerGeneratedBlueprint: sourceCode must be the non-empty authored source componentCode was compiled from");
         }
+        const build = admitGeneratorBuild(source, generated.build);
         const { blueprintId, codeHash } = await registerVariant(parsed, ctx, {
             source,
             sourceCode: generated.sourceCode,
+            ...(build !== undefined ? { build } : {}),
         });
         return { blueprintId, codeHash, source };
     };

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

@@ -3,8 +3,9 @@
  *
  * Patches the two mutable surfaces of a blueprint:
  *
- *   1. `isOperatorDefault` — pin as the operator default for the
- *      blueprint's `(appId, contractHash)` group. The store
+ *   1. `isOperatorDefault` — mark as the operator default for the
+ *      blueprint's `(appId, contractHash)` group (orders listings; no
+ *      render path reads it to choose what serves). The store
  *      automatically clears any prior default in the same group
  *      (see `BlueprintStore.setOperatorDefault`).
  *   2. `variance` — partial merge into the persisted variance. Keys

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

@@ -1 +1 @@
-{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../src/ops-blueprint/update.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAGL,KAAK,iBAAiB,EAGvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACV,cAAc,EACf,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAyB,KAAK,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AASxF;;;;;;;;;GASG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,IAAI,EAAG,wBAAwB,CAAU;gBACtC,WAAW,EAAE,MAAM;CAMhC;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,yBAAyB,CAAC;CACzD;AAuCD,wBAAgB,mCAAmC,CACjD,IAAI,EAAE,0BAA0B;;;;;;;;;;;GAwEjC"}
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../src/ops-blueprint/update.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAGL,KAAK,iBAAiB,EAGvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACV,cAAc,EACf,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAyB,KAAK,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AASxF;;;;;;;;;GASG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,IAAI,EAAG,wBAAwB,CAAU;gBACtC,WAAW,EAAE,MAAM;CAMhC;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,yBAAyB,CAAC;CACzD;AAuCD,wBAAgB,mCAAmC,CACjD,IAAI,EAAE,0BAA0B;;;;;;;;;;;GAwEjC"}

package/dist/ops-blueprint/update.js

@@ -3,8 +3,9 @@
  *
  * Patches the two mutable surfaces of a blueprint:
  *
- *   1. `isOperatorDefault` — pin as the operator default for the
- *      blueprint's `(appId, contractHash)` group. The store
+ *   1. `isOperatorDefault` — mark as the operator default for the
+ *      blueprint's `(appId, contractHash)` group (orders listings; no
+ *      render path reads it to choose what serves). The store
  *      automatically clears any prior default in the same group
  *      (see `BlueprintStore.setOperatorDefault`).
  *   2. `variance` — partial merge into the persisted variance. Keys
@@ -91,7 +92,7 @@ export function createGguiOpsUpdateBlueprintHandler(deps) {
         name: 'ggui_ops_update_blueprint',
         title: 'Update blueprint',
         audience: ['ops'],
-        description: 'Patch the mutable surface of an existing blueprint: pin/unpin operator-default + merge variance tags. Immutable fields (contractHash, appId, codeS3Url, codeHash, source, createdAt, createdBy) are absent from the schema — to "replace" a row, delete + re-generate. Partial-merge semantics: supplied variance keys overwrite, omitted keys preserve. Empty-string persona is removal. App-scoped variant curation for an app you operate — distinct from the personal saved-blueprint library (the _my_ tools).',
+        description: 'Patch the mutable surface of an existing blueprint: set the operator-default mark (it orders blueprint listings and is shown to operators; it does not decide which blueprint serves a render) + merge variance tags. Immutable fields (contractHash, appId, codeS3Url, codeHash, source, createdAt, createdBy) are absent from the schema — to "replace" a row, delete + re-generate. Partial-merge semantics: supplied variance keys overwrite, omitted keys preserve. Empty-string persona is removal. App-scoped variant curation for an app you operate — distinct from the personal saved-blueprint library (the _my_ tools).',
         inputSchema: opsInputSchema,
         outputSchema: opsOutputSchema,
         async handler(rawInput, ctx) {

package/dist/renders/blueprint-coverage.d.ts

@@ -23,10 +23,13 @@
  * proposed contract is the safety valve when a flagged surface is one
  * the user must directly see or act on.
  *
- * Pure — no store, no LLM. Compares only declared key-SETS; differences
- * WITHIN a shared surface (a relabeled action, an `id` vs `id+done`
- * payload schema) are tolerated, because atomic reuse hands the agent
- * the cached contract and it drives that contract, not its own draft.
+ * Pure — no store, no LLM. Compares declared key-SETS, plus ONE thing
+ * inside a shared action: the members that change what the runtime does
+ * with a gesture ({@link LOAD_BEARING_ACTION_MEMBERS}). Every other
+ * difference WITHIN a shared surface (a relabeled action, an `id` vs
+ * `id+done` payload schema) is tolerated, because atomic reuse hands the
+ * agent the cached contract and it drives that contract, not its own
+ * draft.
  */
 import type { DataContract } from '@ggui-ai/protocol';
 /** The request-declared surfaces a candidate fails to cover. Empty
@@ -37,7 +40,23 @@ export interface CoverageGap {
     readonly context: readonly string[];
     readonly streams: readonly string[];
     readonly gadgets: readonly string[];
+    /**
+     * `<action>.<member>` for every load-bearing member the request declares
+     * on an action BOTH contracts carry, where the candidate's entry does not
+     * say the same (ggui#1428). An action the candidate lacks altogether is in
+     * {@link actions}, never here.
+     */
+    readonly actionMembers: readonly string[];
 }
+/**
+ * The action-entry members that change what the runtime DOES with a gesture,
+ * as opposed to how the action reads: `oneShot` arms the single-dispatch
+ * guard, `confirm` asks before firing, `nextStep` names the tool the agent is
+ * routed to. A stored card that lacks one the draft declares serves a card
+ * without that behaviour, so the agent is told. `label`, `description`,
+ * `icon`, `example` and `schema` stay tolerated differences.
+ */
+export declare const LOAD_BEARING_ACTION_MEMBERS: readonly ["oneShot", "confirm", "nextStep"];
 /**
  * Compute the surfaces the request declares that the candidate does NOT.
  * A wholly-empty gap means the candidate covers the request.

package/dist/renders/blueprint-coverage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blueprint-coverage.d.ts","sourceRoot":"","sources":["../../src/renders/blueprint-coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGtD;4DAC4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAmBD;;;GAGG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,YAAY,EACvB,OAAO,EAAE,YAAY,GACpB,WAAW,CAWb;AAED;2DAC2D;AAC3D,wBAAgB,MAAM,CAAC,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAS9E"}
+{"version":3,"file":"blueprint-coverage.d.ts","sourceRoot":"","sources":["../../src/renders/blueprint-coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGtD;4DAC4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,6CAA8C,CAAC;AA6CvF;;;GAGG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,YAAY,EACvB,OAAO,EAAE,YAAY,GACpB,WAAW,CAYb;AAED;2DAC2D;AAC3D,wBAAgB,MAAM,CAAC,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAU9E"}

package/dist/renders/blueprint-coverage.js

@@ -23,12 +23,50 @@
  * proposed contract is the safety valve when a flagged surface is one
  * the user must directly see or act on.
  *
- * Pure — no store, no LLM. Compares only declared key-SETS; differences
- * WITHIN a shared surface (a relabeled action, an `id` vs `id+done`
- * payload schema) are tolerated, because atomic reuse hands the agent
- * the cached contract and it drives that contract, not its own draft.
+ * Pure — no store, no LLM. Compares declared key-SETS, plus ONE thing
+ * inside a shared action: the members that change what the runtime does
+ * with a gesture ({@link LOAD_BEARING_ACTION_MEMBERS}). Every other
+ * difference WITHIN a shared surface (a relabeled action, an `id` vs
+ * `id+done` payload schema) is tolerated, because atomic reuse hands the
+ * agent the cached contract and it drives that contract, not its own
+ * draft.
  */
 import { listContractGadgets } from '@ggui-ai/protocol';
+/**
+ * The action-entry members that change what the runtime DOES with a gesture,
+ * as opposed to how the action reads: `oneShot` arms the single-dispatch
+ * guard, `confirm` asks before firing, `nextStep` names the tool the agent is
+ * routed to. A stored card that lacks one the draft declares serves a card
+ * without that behaviour, so the agent is told. `label`, `description`,
+ * `icon`, `example` and `schema` stay tolerated differences.
+ */
+export const LOAD_BEARING_ACTION_MEMBERS = ['oneShot', 'confirm', 'nextStep'];
+/**
+ * Members the request DECLARES on `name` that the candidate's entry does not
+ * match. One direction, like the rest of coverage: a boolean member counts as
+ * declared only when `true` (`false` and absent both mean "off"), `nextStep`
+ * when present. A candidate that is stricter than the request (it carries a
+ * member the request does not) is not a gap. That holds for `nextStep` too,
+ * because the case that would matter there is already refused elsewhere: a
+ * stored `nextStep` naming a tool the requesting agent does not declare makes
+ * the candidate unfulfillable, and `isFulfillable` declines it before it is
+ * ever proposed (`blueprint-fulfillability.ts`).
+ */
+function mismatchedActionMembers(request, candidate) {
+    const out = [];
+    for (const [name, wanted] of Object.entries(request.actionSpec ?? {})) {
+        const stored = candidate.actionSpec?.[name];
+        if (stored === undefined)
+            continue;
+        if (wanted.oneShot === true && stored.oneShot !== true)
+            out.push(`${name}.oneShot`);
+        if (wanted.confirm === true && stored.confirm !== true)
+            out.push(`${name}.confirm`);
+        if (wanted.nextStep !== undefined && stored.nextStep !== wanted.nextStep)
+            out.push(`${name}.nextStep`);
+    }
+    return out.sort();
+}
 function keySet(map) {
     return new Set(Object.keys(map ?? {}));
 }
@@ -51,6 +89,7 @@ export function coverageGap(candidate, request) {
         context: missing(keySet(request.contextSpec), keySet(candidate.contextSpec)),
         streams: missing(keySet(request.streamSpec), keySet(candidate.streamSpec)),
         gadgets: missing(gadgetIdSet(request), gadgetIdSet(candidate)),
+        actionMembers: mismatchedActionMembers(request, candidate),
     };
 }
 /** True iff `candidate` declares every surface `request` declares —
@@ -61,5 +100,6 @@ export function covers(candidate, request) {
         gap.props.length === 0 &&
         gap.context.length === 0 &&
         gap.streams.length === 0 &&
-        gap.gadgets.length === 0);
+        gap.gadgets.length === 0 &&
+        gap.actionMembers.length === 0);
 }

package/dist/renders/blueprint-durability.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blueprint-durability.d.ts","sourceRoot":"","sources":["../../src/renders/blueprint-durability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC1E,OAAO,KAAK,EAAE,SAAS,IAAI,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,IAAI,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE9E;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,GAChC,gCAAgC,GAChC,6BAA6B,GAC7B,+BAA+B,CAAC;AAEpC;;;GAGG;AACH,eAAO,MAAM,2BAA2B;IACtC,sEAAsE;;IAEtE,gEAAgE;;IAEhE;;;;;;;OAOG;;CAEwD,CAAC;AAW9D;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;CAChC;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,iBAAiB,EAC5B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,SAAS,GAAE,gBAAgB,CAAC,WAAW,CAAW,GACjD,gBAAgB,CA4BlB;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,uBAAuB,GAAG,SAAS,EACzC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,iBAAiB,EAC5B,SAAS,GAAE,gBAAgB,CAAC,WAAW,CAAW,GACjD,OAAO,CAAC,IAAI,CAAC,CA0Df"}
+{"version":3,"file":"blueprint-durability.d.ts","sourceRoot":"","sources":["../../src/renders/blueprint-durability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC1E,OAAO,KAAK,EAAE,SAAS,IAAI,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,IAAI,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE9E;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,GAChC,gCAAgC,GAChC,6BAA6B,GAC7B,+BAA+B,CAAC;AAEpC;;;GAGG;AACH,eAAO,MAAM,2BAA2B;IACtC,sEAAsE;;IAEtE,gEAAgE;;IAEhE;;;;;;;OAOG;;CAEwD,CAAC;AAW9D;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;CAChC;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,iBAAiB,EAC5B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,SAAS,GAAE,gBAAgB,CAAC,WAAW,CAAW,GACjD,gBAAgB,CAiClB;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,uBAAuB,GAAG,SAAS,EACzC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,iBAAiB,EAC5B,SAAS,GAAE,gBAAgB,CAAC,WAAW,CAAW,GACjD,OAAO,CAAC,IAAI,CAAC,CA0Df"}

package/dist/renders/blueprint-durability.js

@@ -56,6 +56,11 @@ export function projectDurableBlueprint(blueprint, appId, codeHash, createdBy =
         ...(blueprint.sourceCodeHash !== undefined
             ? { sourceCodeHash: blueprint.sourceCodeHash }
             : {}),
+        // ggui#1280 — the minting engine's build, admitted at registration.
+        // Written once here at mint (a dedup never reaches this projection) and
+        // never rewritten. The registry's vector-store row carries the same
+        // value (ggui#1476).
+        ...(blueprint.build !== undefined ? { build: blueprint.build } : {}),
     };
 }
 /**

package/dist/renders/blueprint-matcher.d.ts

@@ -180,7 +180,35 @@ export interface MatchBlueprintOptions {
      * stability-sensitive caller cannot afford (ggui#607).
      */
     readonly disableSemantic?: boolean;
+    /**
+     * ggui#1568 — WHY `disableSemantic` is set, so the trace never names a
+     * cause that did not hold. `'exact-only-policy'` (the default) is the
+     * ggui#607 reuse policy. `'exclusion-unavailable'` means the deployment
+     * could not say which rows are reserved from the semantic tier
+     * ({@link excludeFromSemantic}), so it turned the tier off rather than
+     * risk offering one. Read only when `disableSemantic` is true.
+     */
+    readonly disableSemanticCause?: 'exact-only-policy' | 'exclusion-unavailable';
+    /**
+     * ggui#1568 — rows the deployment reserves from the semantic tier, each
+     * named by {@link semanticExclusionKey}. A named row is dropped straight
+     * after retrieval, so it is never offered to the judge, never returned as
+     * a candidate and never reused by similarity. It stays reachable by its
+     * exact key: exclusion governs how a row is FOUND, never whether it can be
+     * served to a request that names it. Retrieval over-fetches by the set's
+     * size, so the pool the judge ranks is still `topK` deep. A vector store
+     * that clamps its `topK` returns fewer rows than asked, and the pool is
+     * then shallower: fewer reuses, never a reserved row.
+     */
+    readonly excludeFromSemantic?: ReadonlySet<string>;
 }
+/**
+ * ggui#1568 — the key {@link MatchBlueprintOptions.excludeFromSemantic}
+ * names a row by: its `(contractKey, variantKey)` pair, the same pair the
+ * exact tier resolves. Unambiguous by construction (JSON array), so no two
+ * different pairs share a key.
+ */
+export declare function semanticExclusionKey(contractKey: string, variantKey: string): string;
 /**
  * Walk the matcher and return the decision.
  *

package/dist/renders/blueprint-matcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blueprint-matcher.d.ts","sourceRoot":"","sources":["../../src/renders/blueprint-matcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,EAAQ,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAC1F,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACvB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAML,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AACtF,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAaxE,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,UAAU,CAAC;IAC1B,2FAA2F;IAC3F,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAC9C,qFAAqF;IACrF,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;CAChC;AAED,0CAA0C;AAC1C,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACnD;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,+GAA+G;IAC/G,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;CAC/C;AAED,MAAM,MAAM,oBAAoB,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;AAE1E,oCAAoC;AACpC,4EAA4E;AAC5E,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IACzC;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC;IACzB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,2BAA2B,CAAC;CAC5D;AAED,MAAM,WAAW,qBAAqB;IACpC,kEAAkE;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC;IAC9B,sEAAsE;IACtE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;OASG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,yFAAyF;IACzF,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAqCD;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,kBAAkB,EACxB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE;IACL,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,eAAe,CAAC;CAChC,EACD,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,oBAAoB,CAAC,CAuc/B"}
+{"version":3,"file":"blueprint-matcher.d.ts","sourceRoot":"","sources":["../../src/renders/blueprint-matcher.ts"],"names":[],"mappings":"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"}

package/dist/renders/blueprint-matcher.js

@@ -14,7 +14,17 @@ const EMPTY_GAP = {
     context: [],
     streams: [],
     gadgets: [],
+    actionMembers: [],
 };
+/**
+ * ggui#1568 — the key {@link MatchBlueprintOptions.excludeFromSemantic}
+ * names a row by: its `(contractKey, variantKey)` pair, the same pair the
+ * exact tier resolves. Unambiguous by construction (JSON array), so no two
+ * different pairs share a key.
+ */
+export function semanticExclusionKey(contractKey, variantKey) {
+    return JSON.stringify([contractKey, variantKey]);
+}
 const DEFAULT_TOP_K = 20;
 // The cosine gate before the judge — ONE FLOOR PER QUERY KIND, because the
 // two kinds of query sit on two scales (ggui#606).
@@ -221,10 +231,13 @@ export async function matchBlueprint(deps, scope, query, options = {}) {
         await ensured;
     }
     if (options.disableSemantic === true) {
-        // Exact-only reuse policy (ggui#607): the semantic tier is
-        // switched off for this request — report the miss without
-        // spending the retrieval or the judge call.
-        const reason = 'exact-only policy: no canonical match — a new interface will be generated';
+        // The semantic tier is switched off for this request: the exact-only
+        // reuse policy (ggui#607), or a deployment that cannot say which rows
+        // are reserved from it (ggui#1568). Report the miss, naming which,
+        // without spending the retrieval or the judge call.
+        const reason = options.disableSemanticCause === 'exclusion-unavailable'
+            ? 'no-match: no canonical match, and similar-interface reuse is unavailable for this request — a new interface will be generated'
+            : 'exact-only policy: no canonical match — a new interface will be generated';
         emit({ decision: 'no-match', strategy: 'semantic', reason, candidates: [] });
         return { strategy: 'no-match', reason, candidates: [] };
     }
@@ -236,6 +249,9 @@ export async function matchBlueprint(deps, scope, query, options = {}) {
     // Miss buckets distinguish cosine-gate, no-LLM, judge-declined,
     // low-confidence, defense.
     let candidates = [];
+    const excluded = options.excludeFromSemantic;
+    const excludedCount = excluded?.size ?? 0;
+    let droppedByExclusion = 0;
     try {
         // ggui#606: compose the query the way stored vectors are composed
         // (`composeEmbeddingInput(contract, intent)`), so a candidate is scored
@@ -244,7 +260,14 @@ export async function matchBlueprint(deps, scope, query, options = {}) {
         const ragArg = query.contract !== undefined
             ? { intent: trimmedIntent, contract: query.contract }
             : { intent: trimmedIntent };
-        candidates = await findBlueprintsByEmbedding(deps.registry, scope, ragArg, { kind, topK });
+        const retrieved = await findBlueprintsByEmbedding(deps.registry, scope, ragArg, { kind, topK: topK + excludedCount });
+        // ggui#1568 — a reserved row leaves here, before the cosine gate, the
+        // judge, the trace and the result: nothing downstream ever sees it.
+        const kept = excluded === undefined || excludedCount === 0
+            ? retrieved
+            : retrieved.filter((c) => !excluded.has(semanticExclusionKey(c.blueprint.contractKey, c.blueprint.variantKey)));
+        droppedByExclusion = retrieved.length - kept.length;
+        candidates = kept.slice(0, topK);
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -258,11 +281,18 @@ export async function matchBlueprint(deps, scope, query, options = {}) {
         return { strategy: 'no-match', reason, candidates: [] };
     }
     if (candidates.length === 0) {
-        const reason = 'no-match: no candidates in scope — first registration of this kind';
+        // ggui#1568 — "first registration" is false when rows were retrieved and
+        // every one was reserved; the reason says which it was.
+        const reason = droppedByExclusion > 0
+            ? 'no-match: no saved interface is available for reuse — a new one will be generated'
+            : 'no-match: no candidates in scope — first registration of this kind';
+        const traceReason = droppedByExclusion > 0
+            ? `no-match: ${droppedByExclusion} candidates retrieved, every one reserved from the semantic tier by the deployment`
+            : reason;
         emit({
             decision: 'no-match',
             strategy: 'semantic',
-            reason,
+            reason: traceReason,
             candidates: [],
         });
         return { strategy: 'no-match', reason, candidates: [] };
@@ -463,6 +493,8 @@ function coverageGapNote(gap) {
         parts.push(`streams: ${gap.streams.join(', ')}`);
     if (gap.gadgets.length > 0)
         parts.push(`gadgets: ${gap.gadgets.join(', ')}`);
+    if (gap.actionMembers.length > 0)
+        parts.push(`action members: ${gap.actionMembers.join(', ')}`);
     if (parts.length === 0)
         return '';
     return ` [coverage gap — the request declares surfaces this cached UI lacks (${parts.join('; ')}); agent override is the safety valve]`;