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

package/dist/ops-blueprint/list.js

@@ -42,8 +42,7 @@ const opsOutputSchema = {
 };
 /**
  * Sort blueprints by `createdAt desc`, then `blueprintId asc` as
- * stable tiebreaker. Mirrors the `BlueprintSelector` deterministic
- * ladder ordering (see `@ggui-ai/mcp-server-core/blueprint-selector`).
+ * stable tiebreaker.
  */
 function sortBlueprintsByCreatedAtDesc(rows) {
     return [...rows].sort((a, b) => {

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,16 +36,19 @@
  *     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 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";
 import { type OpsBlueprintAppAuthorizer } from "./app-access.js";
 import type { PutCodeHook } from "./generate.js";
 /**
- * Deps for `ggui_ops_register_blueprint`. Mirrors `*_generate_*`'s
- * deps minus `resolveLlm`, `blueprints`, and `registry` (no generator
- * dispatch — provenance is structurally `{kind: 'user'}`, so there is
- * no slug to resolve).
+ * Deps shared by `ggui_ops_register_blueprint` and the in-process
+ * {@link createRegisterGeneratedBlueprint}. Mirrors `*_generate_*`'s deps
+ * minus `resolveLlm`, `blueprints` and `registry`: neither entry dispatches
+ * a generator, so there is no slug to resolve. The operator door stamps
+ * `{kind: 'user'}`; the generated entry takes the generation's own `llm`
+ * record.
  */
 export interface GguiOpsRegisterBlueprintDeps {
     /**
@@ -117,7 +120,19 @@ export declare function createGguiOpsRegisterBlueprintHandler(deps: GguiOpsRegis
     aesthetic: z.ZodOptional<z.ZodString>;
     context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<import("@ggui-ai/protocol").JsonValue, unknown, z.core.$ZodTypeInternals<import("@ggui-ai/protocol").JsonValue, unknown>>>>;
     seedPrompt: z.ZodOptional<z.ZodString>;
+    intent: z.ZodOptional<z.ZodString>;
+    judgedCanvases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    aestheticPreset: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    directionDigest: z.ZodOptional<z.ZodString>;
+    directionScope: z.ZodOptional<z.ZodEnum<{
+        app: "app";
+        request: "request";
+    }>>;
     setAsOperatorDefault: z.ZodOptional<z.ZodBoolean>;
+    clonedFrom: z.ZodOptional<z.ZodString>;
 }, {
     blueprintId: z.ZodString;
     codeHash: z.ZodString;
@@ -129,4 +144,66 @@ export declare function createGguiOpsRegisterBlueprintHandler(deps: GguiOpsRegis
     codeHash: string;
     source: UserBlueprintSource;
 }>;
+/**
+ * Engine-generated bytes and the authored source they were compiled
+ * from — what {@link createRegisterGeneratedBlueprint} registers.
+ */
+export interface GeneratedBlueprintBytes {
+    /**
+     * The authored (pre-compile) source that `componentCode` was compiled
+     * from. **Caller obligation:** it MUST be that exact pair, produced by
+     * one generation (for example, the authored `.tsx` a generation wrote
+     * and the module compiled from it). Nothing here recompiles it to check — that is why
+     * this entry is in-process only and the public operator door takes no
+     * source. A pair that is byte-identical records no source (the
+     * registry's collapse rule), which is the honest answer for a
+     * generation that produced no distinct authored form.
+     */
+    readonly sourceCode: string;
+    /**
+     * The generation's own provenance, read from what the generation itself
+     * reported — never a placeholder or a configured default. An `llm` record with a guessed model is a provenance
+     * 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 {
+    readonly blueprintId: string;
+    readonly codeHash: string;
+    readonly source: LlmBlueprintSource;
+}
+/**
+ * The in-process generated-bytes registration entry. `input` is the same
+ * RAW input `ggui_ops_register_blueprint` takes — parsed with its schema
+ * on entry, so a value the schema refuses throws, exactly as it would
+ * through the operator door.
+ */
+export type RegisterGeneratedBlueprint = (input: Record<string, unknown>, generated: GeneratedBlueprintBytes, ctx: HandlerContext) => Promise<RegisterGeneratedBlueprintOutput>;
+/**
+ * ggui#1493 (ggui#1477's source half) — register ENGINE-GENERATED bytes
+ * 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 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.
+ *
+ * Refuses, before anything is persisted, provenance the protocol's
+ * `llmBlueprintSourceSchema` rejects and an empty `sourceCode`.
+ */
+export declare function createRegisterGeneratedBlueprint(deps: GguiOpsRegisterBlueprintDeps): RegisterGeneratedBlueprint;
 //# sourceMappingURL=register.d.ts.map

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,EAEL,KAAK,SAAS,EACd,KAAK,YAAY,EAGjB,KAAK,mBAAmB,EACzB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAqB,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEpF,OAAO,EAAyB,KAAK,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AACxF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAiBjD;;;;;GAKG;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;AAED,wBAAgB,qCAAqC,CACnD,IAAI,EAAE,4BAA4B;;;;;;;;;;;;;;;;;;;GAsMnC"}
+{"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.
@@ -35,15 +35,17 @@
  *   - Validate the contract beyond Zod parsing. Same posture as
  *     ops_generate — schema-compat + hygiene-3 lint live elsewhere.
  */
-import { opsRegisterBlueprintInputSchema, } from "@ggui-ai/protocol";
+import { llmBlueprintSourceSchema, opsRegisterBlueprintInputSchema, } from "@ggui-ai/protocol";
 import { blueprintKey } from "@ggui-ai/protocol/blueprint-key";
 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 { ClonedFromRefusedError, DirectionScopeWithoutDigestError } from "./errors.js";
 import { findNearDuplicatePersona, normalizePersona } from "./persona-normalization.js";
 const opsInputSchema = opsRegisterBlueprintInputSchema.shape;
 const opsOutputSchema = z.object({
@@ -57,153 +59,58 @@ const opsOutputSchema = z.object({
  * no engine claim because none exists to record.
  */
 const USER_SOURCE = { kind: "user" };
-export function createGguiOpsRegisterBlueprintHandler(deps) {
+/**
+ * The registration body both entries share: app resolution, the
+ * 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) {
     const now = deps.now ?? (() => new Date().toISOString());
     const mintBlueprintId = deps.mintBlueprintId ?? (() => `bp_${randomUUID()}`);
-    return defineHandler({
-        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).",
-        inputSchema: opsInputSchema,
-        outputSchema: opsOutputSchema,
-        async handler(rawInput, ctx) {
-            const parsed = opsRegisterBlueprintInputSchema.parse(rawInput);
-            const appId = await resolveEffectiveAppId({
-                toolName: "ggui_ops_register_blueprint",
-                inputAppId: parsed.appId,
-                ctx,
-                ...(deps.authorizeAppAccess ? { authorize: deps.authorizeAppAccess } : {}),
-            });
-            // Reject retired top-level contract fields BEFORE any
-            // persistence so an operator-supplied row can't smuggle
-            // deprecated vocabulary (`terminal`, `consumeSpec`,
-            // `interaction`, `commandSpec`, `behaviorSpec`) into the
-            // registry. The same gate fires on the render + handshake seams
-            // in `renders/`.
-            assertContractNoRetiredFields(parsed.contract);
-            // Every `contract.clientCapabilities.gadgets[*]` MUST resolve
-            // in `App.gadgets` by `(package, export name)` — the wire
-            // carries no version; the operator's catalog is the version
-            // pin. Fails fast with a precise reject before any state
-            // mutation. No-op when no `appMetadataStore` is bound.
-            if (deps.appMetadataStore) {
-                const appRecord = await deps.appMetadataStore.get(appId);
-                assertGadgetsRegistered(parsed.contract, appRecord?.gadgets);
-            }
-            // 1. Normalize the persona + run near-dup detection. Same
-            // posture as ops_generate.
-            const normalizedPersona = normalizePersona(parsed.persona);
-            if (normalizedPersona !== undefined && deps.listAllForApp) {
-                try {
-                    const allForApp = await deps.listAllForApp(appId);
-                    const existingPersonas = allForApp
-                        .map((bp) => bp.variance.persona)
-                        .filter((p) => typeof p === "string");
-                    const dup = findNearDuplicatePersona(normalizedPersona, existingPersonas);
-                    if (dup && dup.nearestExisting !== null) {
-                        try {
-                            deps.telemetry?.emit({
-                                name: "near-duplicate-persona",
-                                at: Date.now(),
-                                attributes: {
-                                    appId,
-                                    requestId: ctx.requestId,
-                                    candidate: normalizedPersona,
-                                    existing: dup.nearestExisting,
-                                    distance: dup.nearestDistance,
-                                },
-                            });
-                        }
-                        catch {
-                            // Swallow telemetry-side throws.
-                        }
-                    }
-                }
-                catch {
-                    // Swallow enumeration failures — the near-dup warning is
-                    // an early-detection signal, not a gate.
-                }
-            }
-            // 2. Compute canonical hashes.
-            const contract = parsed.contract;
-            const contractHash = blueprintKey(contract);
-            const componentCode = parsed.componentCode;
-            const codeHash = createHash("sha256").update(componentCode).digest("hex");
-            const blueprintId = mintBlueprintId();
-            // 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
-            // of the same contract already sat — the mirror then returned THAT row
-            // and the new variant was never bound (the durable row said one thing,
-            // the served index another). Same rule as ops_generate.
-            const variance = {
-                ...(normalizedPersona !== undefined ? { persona: normalizedPersona } : {}),
-                ...(parsed.aesthetic !== undefined ? { aesthetic: parsed.aesthetic } : {}),
-                ...(parsed.context !== undefined ? { context: parsed.context } : {}),
-                ...(parsed.seedPrompt !== undefined ? { seedPrompt: parsed.seedPrompt } : {}),
-            };
-            const blueprint = {
-                blueprintId,
-                contractHash,
-                appId,
-                codeHash,
-                // Operator-supplied bytes, no LLM dispatch — provenance is the
-                // user arm on BOTH stores this handler writes (MVB row here,
-                // cache mirror below). No engine claim exists to record.
-                source: USER_SOURCE,
-                variance,
-                createdAt: now(),
-                createdBy: "operator",
-                contract,
-            };
-            // 3. Persist the blueprint + code body.
-            await deps.blueprintStore.put(blueprint);
-            if (deps.putCode) {
-                await deps.putCode(codeHash, componentCode);
-            }
-            // 3.5 Mirror into the cache vectorStore so the agent-facing
-            // matchBlueprint exact-key probe (handshake + render) finds this
-            // operator-registered blueprint. Symmetric with ops_generate's
-            // dual-write — see #358.
-            if (deps.cacheRegistry) {
-                try {
-                    const intentForCache = parsed.seedPrompt ??
-                        normalizedPersona ??
-                        `operator-registered blueprint (${blueprintId})`;
-                    await registerBlueprint(deps.cacheRegistry, appId, {
-                        kind: "template",
-                        contract,
-                        intent: intentForCache,
-                        // ggui#1275 — only 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.seedPrompt !== undefined ? "authored" : "fallback",
-                        componentCode,
-                        // Same user-arm provenance as the MVB row above — one
-                        // handler call, one provenance claim across both stores.
-                        source: USER_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",
-                    });
-                }
-                catch (err) {
+    return async function registerVariant(parsed, ctx, provenance) {
+        const appId = await resolveEffectiveAppId({
+            toolName: "ggui_ops_register_blueprint",
+            inputAppId: parsed.appId,
+            ctx,
+            ...(deps.authorizeAppAccess ? { authorize: deps.authorizeAppAccess } : {}),
+        });
+        // Reject retired top-level contract fields BEFORE any
+        // persistence so an operator-supplied row can't smuggle
+        // deprecated vocabulary (`terminal`, `consumeSpec`,
+        // `interaction`, `commandSpec`, `behaviorSpec`) into the
+        // registry. The same gate fires on the render + handshake seams
+        // in `renders/`.
+        assertContractNoRetiredFields(parsed.contract);
+        // Every `contract.clientCapabilities.gadgets[*]` MUST resolve
+        // in `App.gadgets` by `(package, export name)` — the wire
+        // carries no version; the operator's catalog is the version
+        // pin. Fails fast with a precise reject before any state
+        // mutation. No-op when no `appMetadataStore` is bound.
+        if (deps.appMetadataStore) {
+            const appRecord = await deps.appMetadataStore.get(appId);
+            assertGadgetsRegistered(parsed.contract, appRecord?.gadgets);
+        }
+        // 1. Normalize the persona + run near-dup detection. Same
+        // posture as ops_generate.
+        const normalizedPersona = normalizePersona(parsed.persona);
+        if (normalizedPersona !== undefined && deps.listAllForApp) {
+            try {
+                const allForApp = await deps.listAllForApp(appId);
+                const existingPersonas = allForApp
+                    .map((bp) => bp.variance.persona)
+                    .filter((p) => typeof p === "string");
+                const dup = findNearDuplicatePersona(normalizedPersona, existingPersonas);
+                if (dup && dup.nearestExisting !== null) {
                     try {
                         deps.telemetry?.emit({
-                            name: "blueprint.cache_mirror_failed",
+                            name: "near-duplicate-persona",
                             at: Date.now(),
                             attributes: {
                                 appId,
                                 requestId: ctx.requestId,
-                                blueprintId,
-                                contractHash,
-                                errorClass: err instanceof Error ? err.name : "unknown",
-                                errorMessage: err instanceof Error ? err.message : String(err),
+                                candidate: normalizedPersona,
+                                existing: dup.nearestExisting,
+                                distance: dup.nearestDistance,
                             },
                         });
                     }
@@ -212,29 +119,191 @@ export function createGguiOpsRegisterBlueprintHandler(deps) {
                     }
                 }
             }
-            // 4. Pin as operator default when requested.
-            if (parsed.setAsOperatorDefault === true) {
-                await deps.blueprintStore.setOperatorDefault(blueprintId);
+            catch {
+                // Swallow enumeration failures — the near-dup warning is
+                // an early-detection signal, not a gate.
             }
+        }
+        // 2. Compute canonical hashes.
+        const contract = parsed.contract;
+        const contractHash = blueprintKey(contract);
+        const componentCode = parsed.componentCode;
+        const codeHash = createHash("sha256").update(componentCode).digest("hex");
+        // ggui#1427 — a scope without a digest is a scope for nothing: refused
+        // before anything is persisted (see DirectionScopeWithoutDigestError).
+        if (parsed.directionScope !== undefined && parsed.directionDigest === undefined) {
+            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
+        // of the same contract already sat — the mirror then returned THAT row
+        // and the new variant was never bound (the durable row said one thing,
+        // the served index another). Same rule as ops_generate.
+        const variance = {
+            ...(normalizedPersona !== undefined ? { persona: normalizedPersona } : {}),
+            ...(parsed.aesthetic !== undefined ? { aesthetic: parsed.aesthetic } : {}),
+            ...(parsed.context !== undefined ? { context: parsed.context } : {}),
+            ...(parsed.seedPrompt !== undefined ? { seedPrompt: parsed.seedPrompt } : {}),
+        };
+        const blueprint = {
+            blueprintId,
+            contractHash,
+            appId,
+            codeHash,
+            // The caller's provenance, on BOTH stores this call writes (MVB
+            // 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",
+            contract,
+        };
+        // 3. Persist the blueprint + code body.
+        await deps.blueprintStore.put(blueprint);
+        if (deps.putCode) {
+            await deps.putCode(codeHash, componentCode);
+        }
+        // 3.5 Mirror into the cache vectorStore so the agent-facing
+        // matchBlueprint exact-key probe (handshake + render) finds this
+        // operator-registered blueprint. Symmetric with ops_generate's
+        // dual-write — see #358.
+        if (deps.cacheRegistry) {
             try {
-                deps.telemetry?.emit({
-                    name: "blueprint.registered",
-                    at: Date.now(),
-                    attributes: {
-                        appId,
-                        requestId: ctx.requestId,
-                        blueprintId,
-                        contractHash,
-                        // Flat-codec provenance key — always 'user' on this path.
-                        sourceKind: USER_SOURCE.kind,
+                // ggui#1427 — the request's own sentence, when the caller has it
+                // (symmetric with `*_generate_*`'s `intent`): prompt-only, never
+                // part of the cache identity.
+                const intentForCache = parsed.intent ??
+                    parsed.seedPrompt ??
+                    normalizedPersona ??
+                    `operator-registered blueprint (${blueprintId})`;
+                // 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",
-                        setAsOperatorDefault: parsed.setAsOperatorDefault === true,
                     },
                 });
             }
-            catch {
-                // Swallow telemetry-side throws.
+            catch (err) {
+                try {
+                    deps.telemetry?.emit({
+                        name: "blueprint.cache_mirror_failed",
+                        at: Date.now(),
+                        attributes: {
+                            appId,
+                            requestId: ctx.requestId,
+                            blueprintId,
+                            contractHash,
+                            errorClass: err instanceof Error ? err.name : "unknown",
+                            errorMessage: err instanceof Error ? err.message : String(err),
+                        },
+                    });
+                }
+                catch {
+                    // Swallow telemetry-side throws.
+                }
             }
+        }
+        // 4. Mark as operator default when requested.
+        if (parsed.setAsOperatorDefault === true) {
+            await deps.blueprintStore.setOperatorDefault(blueprintId);
+        }
+        try {
+            deps.telemetry?.emit({
+                name: "blueprint.registered",
+                at: Date.now(),
+                attributes: {
+                    appId,
+                    requestId: ctx.requestId,
+                    blueprintId,
+                    contractHash,
+                    // Flat-codec provenance key — 'user' on the operator door,
+                    // 'llm' on the generated-bytes path.
+                    sourceKind: provenance.source.kind,
+                    createdBy: "operator",
+                    setAsOperatorDefault: parsed.setAsOperatorDefault === true,
+                },
+            });
+        }
+        catch {
+            // Swallow telemetry-side throws.
+        }
+        return { blueprintId, codeHash };
+    };
+}
+export function createGguiOpsRegisterBlueprintHandler(deps) {
+    const registerVariant = makeRegisterCore(deps);
+    return defineHandler({
+        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 + 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) {
+            const parsed = opsRegisterBlueprintInputSchema.parse(rawInput);
+            // Operator-supplied bytes, no LLM dispatch: the user arm, and no
+            // authored source (this door never carries one — ggui#1477).
+            const { blueprintId, codeHash } = await registerVariant(parsed, ctx, { source: USER_SOURCE });
             return {
                 blueprintId,
                 codeHash,
@@ -243,3 +312,37 @@ export function createGguiOpsRegisterBlueprintHandler(deps) {
         },
     });
 }
+/**
+ * ggui#1493 (ggui#1477's source half) — register ENGINE-GENERATED bytes
+ * 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 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.
+ *
+ * Refuses, before anything is persisted, provenance the protocol's
+ * `llmBlueprintSourceSchema` rejects and an empty `sourceCode`.
+ */
+export function createRegisterGeneratedBlueprint(deps) {
+    const registerVariant = makeRegisterCore(deps);
+    return async (input, generated, ctx) => {
+        const parsed = opsRegisterBlueprintInputSchema.parse(input);
+        const source = llmBlueprintSourceSchema.parse(generated.source);
+        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"}