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

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,CA+Cf"}
+{"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 } : {}),
     };
 }
 /**
@@ -68,12 +73,42 @@ export function projectDurableBlueprint(blueprint, appId, codeHash, createdBy =
  */
 export async function writeBlueprintDurably(deps, appId, blueprint, createdBy = 'agent') {
     const blueprintStore = deps?.blueprintStore;
+    const codeStore = deps?.codeStore;
+    // Authored source body, own try/catch — a distinct
+    // failure mode from the compiled-code write below. `sourceCodeHash`
+    // is already decided (computed at registration, already on the
+    // vector-store row); this write just persists the body it points at.
+    // ggui#1493 — it is written whenever that hash was stamped, WITH OR
+    // WITHOUT a durable blueprint store: the cache row's `sourceCodeHash`
+    // references it when it is written, so it is not written as an orphan (a
+    // later eviction of that capped cache row can still leave it
+    // unreferenced in a code-store-only deployment), and gating it on
+    // the durable store left a cache row pointing at nothing wherever a
+    // code store was bound alone. A failure here does NOT withhold
+    // `sourceCodeHash` from the durable row below (contrast `codeHash`,
+    // which IS withheld on failure) — see `projectDurableBlueprint`'s
+    // comment. The degradation is honest and non-fatal: a reuse read that
+    // resolves the hash but finds `codeStore.get(hash) === null`
+    // gracefully skips, surfacing as the typed `render_source_unavailable`
+    // at the tool layer, never an error.
+    if (codeStore &&
+        blueprint.sourceCode !== undefined &&
+        blueprint.sourceCodeHash !== undefined) {
+        try {
+            await codeStore.put(blueprint.sourceCodeHash, blueprint.sourceCode);
+        }
+        catch (err) {
+            logDurabilityFailure(SOURCE_WRITE_FAILED, blueprint, appId, err);
+        }
+    }
+    // The compiled body and the durable row need a durable store: without
+    // one, nothing references the compiled body (the cache row carries the
+    // code inline), so writing it would be pure orphan.
     if (!blueprintStore)
         return;
     // Body first — see the module docstring on why an orphan body beats a
     // row that points at nothing.
     let codeHash;
-    const codeStore = deps?.codeStore;
     if (codeStore && blueprint.componentCode.length > 0) {
         try {
             const hash = codeStore.hashOf(blueprint.componentCode);
@@ -84,26 +119,6 @@ export async function writeBlueprintDurably(deps, appId, blueprint, createdBy =
             logDurabilityFailure(CODE_WRITE_FAILED, blueprint, appId, err);
         }
     }
-    // Authored source body, own try/catch — a distinct
-    // failure mode from the compiled-code write above. `sourceCodeHash`
-    // is already decided (computed at registration, already on the
-    // vector-store row); this write just persists the body it points at.
-    // A failure here does NOT withhold `sourceCodeHash` from the durable
-    // row below (contrast `codeHash`, which IS withheld on failure) — see
-    // `projectDurableBlueprint`'s comment. The degradation is honest and
-    // non-fatal: a reuse read that resolves the hash but finds
-    // `codeStore.get(hash) === null` gracefully skips, surfacing as the
-    // typed `render_source_unavailable` at the tool layer, never an error.
-    if (codeStore &&
-        blueprint.sourceCode !== undefined &&
-        blueprint.sourceCodeHash !== undefined) {
-        try {
-            await codeStore.put(blueprint.sourceCodeHash, blueprint.sourceCode);
-        }
-        catch (err) {
-            logDurabilityFailure(SOURCE_WRITE_FAILED, blueprint, appId, err);
-        }
-    }
     try {
         await blueprintStore.put(projectDurableBlueprint(blueprint, appId, codeHash, createdBy));
     }

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

@@ -46,6 +46,7 @@
  */
 import type { LLMCaller } from '@ggui-ai/negotiator';
 import { type RerankJudge } from '@ggui-ai/negotiator';
+import { type FitDeclined, type FitVerdict, type RequestFitFacts } from './fits.js';
 import { type DataContract, type BlueprintVariance } from '@ggui-ai/protocol';
 import { type CacheTraceStrategy } from './cache-trace-sink.js';
 import { type Blueprint, type BlueprintCandidate, type BlueprintKind, type BlueprintRegistryDeps } from './blueprint-registry.js';
@@ -63,6 +64,15 @@ export interface BlueprintMatchHit {
     readonly cosine: number;
     /** Free-text reason for trace logs / handshake reason field. */
     readonly reason: string;
+    /**
+     * ggui#1427 — the served candidate's fit verdict. A semantic hit fits by
+     * construction (the judge ranked only fitting candidates). An exact-key
+     * hit is OBSERVED, never declined: `fits: false` here is a would-miss,
+     * named by kind, for the deployment to count.
+     */
+    readonly fit?: FitVerdict;
+    /** ggui#1427 — candidates the pre-filter dropped before the judge (semantic path only). */
+    readonly fitDeclined?: readonly FitDeclined[];
     /** When strategy='semantic', the LLM judge's confidence; undefined for exact-key. */
     readonly judgeConfidence?: number;
     /**
@@ -92,9 +102,16 @@ export interface BlueprintMatchMiss {
      * when LLM was unavailable or rerank short-circuited.
      */
     readonly judgeReason?: string;
+    /** ggui#1427 — candidates the pre-filter dropped before the judge, named by miss kind (semantic path only). */
+    readonly fitDeclined?: readonly FitDeclined[];
 }
 export type BlueprintMatchResult = BlueprintMatchHit | BlueprintMatchMiss;
 /** Compose deps for the matcher. */
+/** A judge with the confidence threshold it was measured on (ggui#1235). */
+export interface RerankPair {
+    readonly judge: RerankJudge;
+    readonly threshold: number;
+}
 export interface MatchBlueprintDeps {
     readonly registry: BlueprintRegistryDeps;
     /**
@@ -116,10 +133,7 @@ export interface MatchBlueprintDeps {
      * chain) passes `threshold: 0` and declines only with `matchId: null`.
      * Wins over a bare `llm` when both are given.
      */
-    readonly rerank?: {
-        readonly judge: RerankJudge;
-        readonly threshold: number;
-    };
+    readonly rerank?: RerankPair;
     /**
      * Optional marketplace-install bridge. When set, the matcher STARTS
      * `ensureCached(scope)` and reads the exact key while it runs: a hit
@@ -143,9 +157,11 @@ export interface MatchBlueprintOptions {
     /** RAG top-K. Default 20 — balance between recall and prompt cost. */
     readonly topK?: number;
     /**
-     * Minimum cosine a candidate needs to reach the LLM judge. Default 0.2
-     * (see the DEFAULT_MIN_COSINE note for why it is not
-     * `ggui_search_blueprints`' 0.3). Applied PER CANDIDATE (ggui#1275): a
+     * Minimum cosine a candidate needs to reach the LLM judge. Default: one
+     * floor per query kind — 0.50 when the request carries a contract (its
+     * query is composed like the stored vectors), 0.2 when it does not (its
+     * query embeds the intent alone, on a lower scale); see the
+     * DEFAULT_MIN_COSINE_* note. A value here overrides both. Applied PER CANDIDATE (ggui#1275): a
      * candidate under the floor is never offered to the judge, so it can
      * never become a reuse; when even top-1 is under it, the judge is skipped
      * entirely and the rerank cost is saved.
@@ -164,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.
  *
@@ -177,5 +221,11 @@ export declare function matchBlueprint(deps: MatchBlueprintDeps, scope: string,
     readonly intent: string;
     readonly contract?: DataContract;
     readonly variance?: BlueprintVariance;
+    /**
+     * ggui#1427 — the request's declared fit facts (canvas, aesthetic
+     * preset, direction digest). Absent facts evaluate nothing; data-shape
+     * runs from `contract` alone.
+     */
+    readonly fit?: RequestFitFacts;
 }, options?: MatchBlueprintOptions): Promise<BlueprintMatchResult>;
 //# sourceMappingURL=blueprint-matcher.d.ts.map

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,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,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;CAC/B;AAED,MAAM,MAAM,oBAAoB,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;AAE1E,oCAAoC;AACpC,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;QAChB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;QAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF;;;;;;;;;;;;;;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;;;;;;;OAOG;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;AA8BD;;;;;;;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;CACvC,EACD,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,oBAAoB,CAAC,CA4W/B"}
+{"version":3,"file":"blueprint-matcher.d.ts","sourceRoot":"","sources":["../../src/renders/blueprint-matcher.ts"],"names":[],"mappings":"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"}