@ggui-ai/negotiator 0.2.0-alpha.3 → 0.3.0-rc.0

package/README.md

@@ -1,11 +1,19 @@
 # @ggui-ai/negotiator
 
-UI decision engine for [ggui](https://github.com/ggui-ai/ggui).
+Contract-synthesis + match-judge engine for
+[ggui](https://github.com/ggui-ai/ggui)'s handshake.
 
-Given an agent's signal (data, prompt, context, agent tools) and the current
-render state, the negotiator decides **which UI to render** — create a new
-interface, update an existing one, or replace it — and, on the cold path,
-synthesizes the data contract that drives it.
+Given an agent's draft contract + intent, this package synthesizes (or
+repairs) a conforming `DataContract`, judges blueprint-match candidates for
+reuse, and validates contract structure + novelty — the primitives the
+handshake composes to always return a valid contract.
+
+> The handshake **decision** itself (find-similar → reuse vs synth-create)
+> lives in the shared `decideHandshake` core in
+> [`@ggui-ai/mcp-server-handlers`](../mcp-server-handlers), which composes
+> the primitives below. The former in-package `negotiate()` RAG+decision
+> pipeline was retired in favor of that unified, adapter-injected core —
+> one decision spine; LLM and storage bindings plug in per deployment.
 
 The package is deployment-agnostic. It composes the storage interfaces
 defined in `@ggui-ai/mcp-server-core` (`EmbeddingProvider`, `VectorStore`),
@@ -20,28 +28,26 @@ pnpm add @ggui-ai/negotiator
 
 ## What's in the box
 
-- **`negotiate(deps, input)`** — top-level orchestrator. Runs RAG search over
-  registered blueprints, reads render state, fast-paths exact blueprint
-  hits, and otherwise calls the decision LLM.
-- **`makeDecision(...)`** — the decision step in isolation: pick an action
-  (`create` / `update` / `replace`) and a blueprint from the
-  candidate set.
 - **`synthesizeContract(...)`** — cold-path contract synthesizer. Turns an
   agent intent into a `DataContract` (props / context / action / stream
   specs, plus gadget references), with a repair loop and a schema-validation
   gate.
-- **`ragSearch(...)`** — embedding + vector-store retrieval over the
-  blueprint corpus, composing the `@ggui-ai/mcp-server-core` interfaces.
-- **`rerankCandidates(...)`** — LLM re-rank of retrieval candidates.
-- **`validateContractStructure` / `validateContractNovelty`** — advisory
+- **`ensureConformingContract(...)`** — the create-path guarantee: validates
+  an untrusted draft and, on errors, deterministically normalizes or
+  LLM-repairs it so the handshake always returns a contract that passes the
+  backstop. Never throws.
+- **`rerankCandidates(...)`** — LLM judge that re-ranks blueprint-match
+  retrieval candidates (the semantic-match decision used by
+  `decideHandshake`).
+- **`validateContractRedundancy` / `validateContractNovelty`** — advisory
   validators for the actions-vs-context placement rule.
 
 ```ts
-import { negotiate } from "@ggui-ai/negotiator";
+import { ensureConformingContract } from "@ggui-ai/negotiator";
 
-const result = await negotiate(deps, input);
-// result.action — "create" | "update" | "replace"
-// result.blueprint — the picked blueprint, if any
+const result = await ensureConformingContract({ llm }, { intent, draft });
+// result.origin — "agent" (clean) | "synth" (repaired)
+// result.contract — a DataContract guaranteed to pass the handshake backstop
 ```
 
 ## License

package/dist/contract-validators.d.ts

@@ -3,9 +3,12 @@
  *
  * Two detectors live here:
  *
- *   - {@link validateContractStructure} — pure structural heuristics that
- *     flag over-specified contracts without any runtime dependency. The
- *     load-bearing finding is `redundant-action`: an empty-payload
+ *   - {@link validateContractRedundancy} — pure redundancy heuristics that
+ *     flag over-specified contracts without any runtime dependency.
+ *     (Deliberately NOT named `validateContractStructure` — that name is
+ *     owned by `@ggui-ai/protocol`'s normative structural validator,
+ *     which returns `ContractViolation`s; this one returns advisory
+ *     findings.) The load-bearing finding is `redundant-action`: an empty-payload
  *     `actionSpec` entry whose name parses as a mutator of an existing
  *     `contextSpec` slot. Real example that motivated this module: a
  *     synthesizer emitted both `actionSpec.increment` (empty payload)
@@ -59,39 +62,40 @@ export interface ContractValidationResult {
 }
 /**
  * Dependencies the novelty detector needs. Embedding provider + vector
- * store are the same seams the negotiator's RAG path uses, so the
- * novelty check operates over the production index without any extra
- * infrastructure.
+ * store are the same seams the handshake's find-similar retrieval uses,
+ * so the novelty check operates over the production index without any
+ * extra infrastructure.
  */
 export interface ContractValidationNoveltyDeps {
     readonly embedding: EmbeddingProvider;
     readonly vectorStore: VectorStore;
     /** Tenant / partition the nearest-neighbor query runs against. Same
-     * semantics as `RagSearchInput.scope`. */
+     * semantics as the `scope` argument on `VectorStore.query` — the
+     * tenant / index partition, typically `appId`. */
     readonly scope: string;
 }
 export interface ContractValidationNoveltyOptions {
     /**
      * Cosine distance threshold above which the contract is flagged as
-     * novel. Distance is `1 - cosine_similarity`. Default `0.8` —
-     * matches the negotiator's `RETRIEVAL_MIN_SCORE = 0.15` (=cosine
-     * similarity 0.15, distance 0.85) one-tail boundary, with a small
-     * buffer so contracts that hover near retrieval but slightly above
-     * still flag for review.
+     * novel. Distance is `1 - cosine_similarity`. Default `0.8`: a
+     * contract whose nearest stored neighbor sits beyond distance 0.8
+     * is effectively outside retrieval range, with a small buffer below
+     * the hard one-tail boundary (distance 0.85) so contracts that
+     * hover near retrieval but slightly above still flag for review.
      */
     readonly thresholdCosine?: number;
 }
 /**
- * Run the synchronous structural detectors against `contract`.
+ * Run the synchronous redundancy detector against `contract`.
  *
- * Currently:
+ * One finding kind:
  *   - `redundant-action`: empty-payload action whose name parses as a
  *     mutator of an existing context slot.
  *
- * Returns an empty findings array for contracts that don't trip any
+ * Returns an empty findings array for contracts that don't trip the
  * heuristic.
  */
-export declare function validateContractStructure(contract: DataContract): ContractValidationResult;
+export declare function validateContractRedundancy(contract: DataContract): ContractValidationResult;
 /**
  * Validate the actions-vs-context placement rule: actions drive agent
  * turns, context observes state. Findings 1-3 are advisory `warn`;

package/dist/contract-validators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract-validators.d.ts","sourceRoot":"","sources":["../src/contract-validators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,mBAAmB,CAAC;AAElE,OAAO,KAAK,EACV,iBAAiB,EACjB,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAMlC;;;;;;;;;GASG;AACH,MAAM,MAAM,6BAA6B,GACrC,kBAAkB,GAClB,aAAa,GACb,mCAAmC,GACnC,2BAA2B,GAC3B,6BAA6B,GAC7B,4BAA4B,GAC5B,8BAA8B,GAC9B,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,6BAA6B,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,SAAS,yBAAyB,EAAE,CAAC;CACzD;AAED;;;;;GAKG;AACH,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC;8CAC0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gCAAgC;IAC/C;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAwJD;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,YAAY,GACrB,wBAAwB,CAkC1B;AAsCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,YAAY,GACrB,wBAAwB,CA8D1B;AAiCD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,MAAM,GACb,wBAAwB,CAoC1B;AAQD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,6BAA6B,EACnC,OAAO,GAAE,gCAAqC,GAC7C,OAAO,CAAC,wBAAwB,CAAC,CAkCnC;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,wBAAwB,GAC/B,MAAM,CAKR"}
+{"version":3,"file":"contract-validators.d.ts","sourceRoot":"","sources":["../src/contract-validators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,mBAAmB,CAAC;AAElE,OAAO,KAAK,EACV,iBAAiB,EACjB,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAMlC;;;;;;;;;GASG;AACH,MAAM,MAAM,6BAA6B,GACrC,kBAAkB,GAClB,aAAa,GACb,mCAAmC,GACnC,2BAA2B,GAC3B,6BAA6B,GAC7B,4BAA4B,GAC5B,8BAA8B,GAC9B,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,6BAA6B,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,SAAS,yBAAyB,EAAE,CAAC;CACzD;AAED;;;;;GAKG;AACH,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC;;sDAEkD;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gCAAgC;IAC/C;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAwJD;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,YAAY,GACrB,wBAAwB,CAkC1B;AAsCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,YAAY,GACrB,wBAAwB,CA8D1B;AAiCD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,MAAM,GACb,wBAAwB,CAoC1B;AAQD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,6BAA6B,EACnC,OAAO,GAAE,gCAAqC,GAC7C,OAAO,CAAC,wBAAwB,CAAC,CAkCnC;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,wBAAwB,GAC/B,MAAM,CAKR"}

package/dist/contract-validators.js

@@ -3,9 +3,12 @@
  *
  * Two detectors live here:
  *
- *   - {@link validateContractStructure} — pure structural heuristics that
- *     flag over-specified contracts without any runtime dependency. The
- *     load-bearing finding is `redundant-action`: an empty-payload
+ *   - {@link validateContractRedundancy} — pure redundancy heuristics that
+ *     flag over-specified contracts without any runtime dependency.
+ *     (Deliberately NOT named `validateContractStructure` — that name is
+ *     owned by `@ggui-ai/protocol`'s normative structural validator,
+ *     which returns `ContractViolation`s; this one returns advisory
+ *     findings.) The load-bearing finding is `redundant-action`: an empty-payload
  *     `actionSpec` entry whose name parses as a mutator of an existing
  *     `contextSpec` slot. Real example that motivated this module: a
  *     synthesizer emitted both `actionSpec.increment` (empty payload)
@@ -167,19 +170,19 @@ function isEmptyPayloadSchema(schema) {
     return Object.keys(schema.properties).length === 0;
 }
 // =============================================================================
-// Structural validator (synchronous, dependency-free)
+// Redundancy validator (synchronous, dependency-free)
 // =============================================================================
 /**
- * Run the synchronous structural detectors against `contract`.
+ * Run the synchronous redundancy detector against `contract`.
  *
- * Currently:
+ * One finding kind:
  *   - `redundant-action`: empty-payload action whose name parses as a
  *     mutator of an existing context slot.
  *
- * Returns an empty findings array for contracts that don't trip any
+ * Returns an empty findings array for contracts that don't trip the
  * heuristic.
  */
-export function validateContractStructure(contract) {
+export function validateContractRedundancy(contract) {
     const findings = [];
     const actionSpec = contract.actionSpec;
     const contextSpec = contract.contextSpec;

package/dist/ensure-conforming-contract.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `ensureConformingContract` — the negotiator's create-path guarantee.
+ *
+ * Given the agent's PROPOSED draft, return a contract that is
+ * GUARANTEED to pass the deterministic gate (`lintContract` with zero
+ * errors), so the handshake backstop (`validateContract`) never throws
+ * on it. This is the "Propose vs Commit" forgiving-handshake core
+ * shared by every negotiator implementation (OSS llm-backed + cloud
+ * bedrock) so the behavior cannot drift between deployments:
+ *
+ *   - draft already conforms → return it verbatim          (origin: 'agent')
+ *   - draft has errors       → repair-in-place via the bounded LLM loop,
+ *                              seeded with the draft + the deterministic
+ *                              findings, looping until the gate is green
+ *                              (origin: 'synth')
+ *   - repair impossible      → minimal conforming contract (`{}`) + loud
+ *     (LLM down / provider      error findings; STILL origin 'synth';
+ *      can't synth / budget     NEVER throws.
+ *      exhausted)
+ *
+ * Determinism lives in the GATE (`lintContract`), never in the repair.
+ * The repair LLM is non-deterministic, but the loop only exits when the
+ * deterministic gate is green — the same shape ui-gen uses to tolerate
+ * non-deterministic code generation behind a deterministic self_check.
+ *
+ * Cache/blueprint matching is NOT this function's job — the caller
+ * (negotiator `decide()`) runs its deployment-specific cache match
+ * FIRST and only falls through to here on a miss. That preserves the
+ * "cache-first, repair-second" ordering the negotiator contract
+ * mandates.
+ */
+import { type DataContract, type GadgetDescriptor, type SuggestionFinding } from '@ggui-ai/protocol';
+import type { LLMCaller } from './llm-caller.js';
+export interface EnsureConformingResult {
+    /** A contract guaranteed to pass `lintContract` with zero errors. */
+    readonly contract: DataContract;
+    /**
+     * - `'agent'` — the draft was already conforming; returned verbatim.
+     * - `'synth'` — the draft had errors; this is the repaired result
+     *   (or the minimal-conforming fallback when repair was impossible).
+     */
+    readonly origin: 'agent' | 'synth';
+    /**
+     * How the conforming contract was produced — finer-grained than
+     * `origin`, for telemetry (the efficiency tiers):
+     *   - `verbatim`      — draft was clean; returned as-is (origin agent).
+     *   - `normalized`    — deterministic fix only, NO LLM (origin synth).
+     *   - `llm-repair`    — the bounded LLM repair loop ran (origin synth).
+     *   - `fallback-empty`— unrepairable; minimal `{}` contract (origin synth).
+     */
+    readonly method: 'verbatim' | 'normalized' | 'llm-repair' | 'fallback-empty';
+    /**
+     * Findings surfaced to the agent. On `origin: 'agent'`, any hygiene
+     * warnings on the (valid) draft. On `origin: 'synth'`, the ERROR
+     * findings that rejected the agent's draft — so the agent-side model
+     * learns what it got wrong, even though we repaired it.
+     */
+    readonly findings: readonly SuggestionFinding[];
+    /** Operator- + LLM-readable explanation. */
+    readonly reasoning: string;
+}
+export declare function ensureConformingContract(deps: {
+    readonly llm: LLMCaller;
+}, args: {
+    /** Untrusted: the agent's draft may not be a valid DataContract. */
+    readonly draft: unknown;
+    readonly intent: string;
+    readonly appGadgets?: readonly GadgetDescriptor[];
+}): Promise<EnsureConformingResult>;
+//# sourceMappingURL=ensure-conforming-contract.d.ts.map

package/dist/ensure-conforming-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-conforming-contract.d.ts","sourceRoot":"","sources":["../src/ensure-conforming-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,MAAM,WAAW,sBAAsB;IACrC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC;IACnC;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,YAAY,GAAG,YAAY,GAAG,gBAAgB,CAAC;IAC7E;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAChD,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAKD,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAA;CAAE,EACjC,IAAI,EAAE;IACJ,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACnD,GACA,OAAO,CAAC,sBAAsB,CAAC,CA4FjC"}

package/dist/ensure-conforming-contract.js

@@ -0,0 +1,115 @@
+/**
+ * `ensureConformingContract` — the negotiator's create-path guarantee.
+ *
+ * Given the agent's PROPOSED draft, return a contract that is
+ * GUARANTEED to pass the deterministic gate (`lintContract` with zero
+ * errors), so the handshake backstop (`validateContract`) never throws
+ * on it. This is the "Propose vs Commit" forgiving-handshake core
+ * shared by every negotiator implementation (OSS llm-backed + cloud
+ * bedrock) so the behavior cannot drift between deployments:
+ *
+ *   - draft already conforms → return it verbatim          (origin: 'agent')
+ *   - draft has errors       → repair-in-place via the bounded LLM loop,
+ *                              seeded with the draft + the deterministic
+ *                              findings, looping until the gate is green
+ *                              (origin: 'synth')
+ *   - repair impossible      → minimal conforming contract (`{}`) + loud
+ *     (LLM down / provider      error findings; STILL origin 'synth';
+ *      can't synth / budget     NEVER throws.
+ *      exhausted)
+ *
+ * Determinism lives in the GATE (`lintContract`), never in the repair.
+ * The repair LLM is non-deterministic, but the loop only exits when the
+ * deterministic gate is green — the same shape ui-gen uses to tolerate
+ * non-deterministic code generation behind a deterministic self_check.
+ *
+ * Cache/blueprint matching is NOT this function's job — the caller
+ * (negotiator `decide()`) runs its deployment-specific cache match
+ * FIRST and only falls through to here on a miss. That preserves the
+ * "cache-first, repair-second" ordering the negotiator contract
+ * mandates.
+ */
+import { lintContract, dataContractSchema, } from '@ggui-ai/protocol';
+import { synthesizeContract } from './synthesize-contract.js';
+import { normalizeDraft } from './normalize-draft.js';
+/** Trivially-valid last-resort contract — all four specs omitted. */
+const EMPTY_CONTRACT = {};
+export async function ensureConformingContract(deps, args) {
+    const lint = lintContract(args.draft);
+    const warnFindings = lint.warnings.map((w) => ({
+        code: w.code,
+        severity: 'warn',
+        path: w.path,
+        message: w.message,
+    }));
+    // Fast path — draft already conforms. Deterministic, no LLM call.
+    // `lint.errors.length === 0` implies the shape phase passed, so the
+    // strict parse cannot throw — it just re-derives the typed DataContract
+    // from the untrusted input (validator returns the typed shape; no cast).
+    if (lint.errors.length === 0) {
+        return {
+            contract: dataContractSchema.parse(args.draft),
+            origin: 'agent',
+            method: 'verbatim',
+            findings: warnFindings,
+            reasoning: 'agent draft passed validateContract; accepted verbatim (origin: agent)',
+        };
+    }
+    const errorFindings = lint.errors.map((e) => ({
+        code: e.code,
+        severity: 'error',
+        path: e.path,
+        message: e.message,
+    }));
+    // L3 — deterministic normalization tier. Most agent malformations are
+    // mechanical (stray illegal wrapper keys, non-canonical schema types).
+    // Fix them WITHOUT an LLM: strip + canonicalize, re-lint, and if the
+    // draft now conforms, return it verbatim-but-cleaned. Faithful (no
+    // reshape risk — the agent's specs are preserved exactly) and free (no
+    // LLM call). Semantic deficiencies fall through to the repair loop.
+    const normalized = normalizeDraft(args.draft);
+    const normLint = lintContract(normalized);
+    if (normLint.errors.length === 0) {
+        return {
+            contract: dataContractSchema.parse(normalized),
+            origin: 'synth',
+            method: 'normalized',
+            findings: errorFindings,
+            reasoning: 'normalized the agent draft deterministically (stripped invalid keys / canonicalized schema types, no LLM) to pass validateContract',
+        };
+    }
+    // Repair loop on the NORMALIZED draft (mechanical errors already
+    // fixed) with only the REMAINING (semantic) findings — so the LLM
+    // patches what reasoning is genuinely needed for, from a clean start.
+    const synth = await synthesizeContract(deps, args.intent, {
+        ...(args.appGadgets ? { appGadgets: args.appGadgets } : {}),
+        draft: normalized,
+        draftFindings: normLint.errors.map((e) => ({
+            code: e.code,
+            path: e.path,
+            message: e.message,
+        })),
+    });
+    if (synth.contract !== null &&
+        lintContract(synth.contract).errors.length === 0) {
+        return {
+            contract: synth.contract,
+            origin: 'synth',
+            method: 'llm-repair',
+            findings: errorFindings,
+            reasoning: `repaired the agent draft to pass validateContract — ${synth.reason}`,
+        };
+    }
+    // Repair impossible (LLM down, provider can't synthesize, or the
+    // repair budget exhausted). We still MUST return a conforming
+    // contract — the handshake never hard-fails. Minimal conforming
+    // contract + loud findings so the agent can re-issue a corrected
+    // contract via ggui_render override if it needs the declared specs.
+    return {
+        contract: EMPTY_CONTRACT,
+        origin: 'synth',
+        method: 'fallback-empty',
+        findings: errorFindings,
+        reasoning: `could not repair the agent draft within budget (${synth.reason}); returning a minimal conforming contract — re-issue a corrected contract via ggui_render override if you need the declared specs`,
+    };
+}

package/dist/index.d.ts

@@ -1,36 +1,38 @@
 /**
- * @ggui-ai/negotiator — open-source UI decision engine for ggui.
+ * @ggui-ai/negotiator — open-source contract-synthesis + match-judge
+ * engine for ggui's handshake.
  *
- * Decides which UI to render (create/update/replace) given agent
- * signal (data/prompt/context/agentTools) and current render state.
+ * Given an agent's draft contract + intent, this package:
+ *   - synthesizes / repairs a conforming `DataContract`
+ *     (`synthesizeContract`, `ensureConformingContract`) so the
+ *     handshake always returns a valid contract;
+ *   - judges blueprint-match candidates for reuse (`rerankCandidates`);
+ *   - validates contract structure + novelty (`contract-validators`);
+ *   - hashes contracts into identity + variant keys (`hashContract`,
+ *     `buildVariant`) and normalizes untrusted drafts (`normalizeDraft`).
+ *
+ * The HANDSHAKE DECISION itself (find-similar → reuse vs synth-create)
+ * lives in the shared `decideHandshake` core in
+ * `@ggui-ai/mcp-server-handlers`, which composes these primitives; the
+ * former in-package `negotiate()` RAG+decision pipeline was retired in
+ * favor of that unified, adapter-injected core.
  *
  * Composes the storage seams defined in `@ggui-ai/mcp-server-core`
- * (`EmbeddingProvider`, `VectorStore`, `Negotiator`). The decision
- * semantics are open here; concrete cloud-vendor bindings (e.g. a
- * managed embedding service or vector store) live behind those seams
- * so this package stays deployment-agnostic.
+ * (`EmbeddingProvider`, `VectorStore`) so this package stays
+ * deployment-agnostic.
  *
  * This barrel stays narrow — it exports only the minimum surface
  * consumers need. Each additive export carries semver weight.
  */
 export { hashContract, buildVariant } from './contract-hash.js';
-export { computeIntentId, shouldSuppressSuggestion } from './intent.js';
-export { detectDataPatterns, buildSuggestion } from './suggestion.js';
-export type { NegotiatorSuggestion } from './suggestion.js';
-export { inferInteractionMode, inferJsonSchemaType } from './pure.js';
-export { ragSearch } from './rag-search.js';
-export type { RagSearchDeps, RagSearchInput, RagSearchResult, } from './rag-search.js';
-export type { NegotiatorOption } from './types.js';
 export type { LLMCaller, LLMCallerConfig, ToolSchema } from './llm-caller.js';
-export type { RenderState, RenderEntry } from './render.js';
-export type { NegotiatorDecisionInput } from './decision-input.js';
-export { DECISION_SYSTEM_PROMPT, buildDecisionUserMessage, makeDecision, } from './decision.js';
-export { negotiate } from './negotiate.js';
-export type { NegotiateDeps, NegotiateInput, NegotiateConfig, NegotiateResult, } from './negotiate.js';
 export { rerankCandidates } from './llm-rerank.js';
 export type { RerankCandidate, RerankDecision, RerankQuery, } from './llm-rerank.js';
 export { synthesizeContract } from './synthesize-contract.js';
 export type { SynthesizeContractResult } from './synthesize-contract.js';
-export { validateContractStructure, validateContractNovelty, formatValidationFindings, } from './contract-validators.js';
+export { ensureConformingContract } from './ensure-conforming-contract.js';
+export type { EnsureConformingResult } from './ensure-conforming-contract.js';
+export { normalizeDraft } from './normalize-draft.js';
+export { validateContractRedundancy, validateContractNovelty, formatValidationFindings, } from './contract-validators.js';
 export type { ContractValidationFinding, ContractValidationFindingKind, ContractValidationResult, ContractValidationNoveltyDeps, ContractValidationNoveltyOptions, } from './contract-validators.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACtE,YAAY,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACtE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EACV,aAAa,EACb,cAAc,EACd,eAAe,GAChB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC9E,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC5D,YAAY,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,YAAY,GACb,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EACV,aAAa,EACb,cAAc,EACd,eAAe,EACf,eAAe,GAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,YAAY,EACV,eAAe,EACf,cAAc,EACd,WAAW,GACZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,YAAY,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,yBAAyB,EACzB,6BAA6B,EAC7B,wBAAwB,EACxB,6BAA6B,EAC7B,gCAAgC,GACjC,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAChE,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC9E,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,YAAY,EACV,eAAe,EACf,cAAc,EACd,WAAW,GACZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,YAAY,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAC3E,YAAY,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EACL,0BAA0B,EAC1B,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,yBAAyB,EACzB,6BAA6B,EAC7B,wBAAwB,EACxB,6BAA6B,EAC7B,gCAAgC,GACjC,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -1,25 +1,32 @@
 /**
- * @ggui-ai/negotiator — open-source UI decision engine for ggui.
+ * @ggui-ai/negotiator — open-source contract-synthesis + match-judge
+ * engine for ggui's handshake.
  *
- * Decides which UI to render (create/update/replace) given agent
- * signal (data/prompt/context/agentTools) and current render state.
+ * Given an agent's draft contract + intent, this package:
+ *   - synthesizes / repairs a conforming `DataContract`
+ *     (`synthesizeContract`, `ensureConformingContract`) so the
+ *     handshake always returns a valid contract;
+ *   - judges blueprint-match candidates for reuse (`rerankCandidates`);
+ *   - validates contract structure + novelty (`contract-validators`);
+ *   - hashes contracts into identity + variant keys (`hashContract`,
+ *     `buildVariant`) and normalizes untrusted drafts (`normalizeDraft`).
+ *
+ * The HANDSHAKE DECISION itself (find-similar → reuse vs synth-create)
+ * lives in the shared `decideHandshake` core in
+ * `@ggui-ai/mcp-server-handlers`, which composes these primitives; the
+ * former in-package `negotiate()` RAG+decision pipeline was retired in
+ * favor of that unified, adapter-injected core.
  *
  * Composes the storage seams defined in `@ggui-ai/mcp-server-core`
- * (`EmbeddingProvider`, `VectorStore`, `Negotiator`). The decision
- * semantics are open here; concrete cloud-vendor bindings (e.g. a
- * managed embedding service or vector store) live behind those seams
- * so this package stays deployment-agnostic.
+ * (`EmbeddingProvider`, `VectorStore`) so this package stays
+ * deployment-agnostic.
  *
  * This barrel stays narrow — it exports only the minimum surface
  * consumers need. Each additive export carries semver weight.
  */
 export { hashContract, buildVariant } from './contract-hash.js';
-export { computeIntentId, shouldSuppressSuggestion } from './intent.js';
-export { detectDataPatterns, buildSuggestion } from './suggestion.js';
-export { inferInteractionMode, inferJsonSchemaType } from './pure.js';
-export { ragSearch } from './rag-search.js';
-export { DECISION_SYSTEM_PROMPT, buildDecisionUserMessage, makeDecision, } from './decision.js';
-export { negotiate } from './negotiate.js';
 export { rerankCandidates } from './llm-rerank.js';
 export { synthesizeContract } from './synthesize-contract.js';
-export { validateContractStructure, validateContractNovelty, formatValidationFindings, } from './contract-validators.js';
+export { ensureConformingContract } from './ensure-conforming-contract.js';
+export { normalizeDraft } from './normalize-draft.js';
+export { validateContractRedundancy, validateContractNovelty, formatValidationFindings, } from './contract-validators.js';

package/dist/llm-caller.d.ts

@@ -1,23 +1,23 @@
 /**
- * `LLMCaller` — the decision engine's LLM dispatcher.
+ * `LLMCaller` — the negotiator's LLM dispatcher.
  *
  * Narrow abstraction over "call a chat model, optionally with a forced
  * tool-use schema for guaranteed-JSON structured output." Kept public
  * so OSS consumers of `@ggui-ai/negotiator` can bring their own LLM
  * provider (Anthropic direct, OpenAI, Google, a local model, a
- * community LiteLLM wrapper) without touching the decision-engine
+ * community LiteLLM wrapper) without touching the synthesis / judge
  * source.
  *
  * **Why this lives in `@ggui-ai/negotiator`, not
  * `@ggui-ai/mcp-server-core`.** `mcp-server-core` contains the
  * storage + runtime seams an MCP server implementer binds against
  * (`VectorStore`, `EmbeddingProvider`, `KeyValueStore`,
- * `BlueprintProvider`, `Negotiator`). `LLMCaller` is an
- * engine-internal dispatcher — one level below `Negotiator` — so
- * lifting it to `mcp-server-core` would grow the public seam count
- * speculatively. If a second consumer outside the negotiator
- * surfaces later, the "where does `LLMCaller` live?" question can be
- * re-opened at that point.
+ * `BlueprintProvider`). `LLMCaller` is an engine-internal
+ * dispatcher — one level below the synthesis + judge primitives this
+ * package exports — so lifting it to `mcp-server-core` would grow the
+ * public seam count speculatively. If a second consumer outside the
+ * negotiator surfaces later, the "where does `LLMCaller` live?"
+ * question can be re-opened at that point.
  *
  * Normative semantics:
  * - `call(systemPrompt, userMessage, maxTokens?)` returns the raw
@@ -41,7 +41,7 @@ export interface ToolSchema {
     description: string;
     input_schema: Record<string, unknown>;
 }
-/** Chat-model dispatcher consumed by the negotiator decision engine. */
+/** Chat-model dispatcher consumed by the negotiator's synthesis + judge primitives. */
 export interface LLMCaller {
     /**
      * Call the model in plain-text mode. `maxTokens` defaults to

package/dist/llm-caller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"llm-caller.d.ts","sourceRoot":"","sources":["../src/llm-caller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,wEAAwE;AACxE,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,IAAI,CACF,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAAC;IAEnB;;;;;OAKG;IACH,cAAc,CAAC,CAAC,CAAC,EACf,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,UAAU,EAChB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,CAAC,CAAC,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,CAAC;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}
+{"version":3,"file":"llm-caller.d.ts","sourceRoot":"","sources":["../src/llm-caller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,uFAAuF;AACvF,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,IAAI,CACF,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAAC;IAEnB;;;;;OAKG;IACH,cAAc,CAAC,CAAC,CAAC,EACf,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,UAAU,EAChB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,CAAC,CAAC,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,CAAC;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/llm-caller.js

@@ -1,23 +1,23 @@
 /**
- * `LLMCaller` — the decision engine's LLM dispatcher.
+ * `LLMCaller` — the negotiator's LLM dispatcher.
  *
  * Narrow abstraction over "call a chat model, optionally with a forced
  * tool-use schema for guaranteed-JSON structured output." Kept public
  * so OSS consumers of `@ggui-ai/negotiator` can bring their own LLM
  * provider (Anthropic direct, OpenAI, Google, a local model, a
- * community LiteLLM wrapper) without touching the decision-engine
+ * community LiteLLM wrapper) without touching the synthesis / judge
  * source.
  *
  * **Why this lives in `@ggui-ai/negotiator`, not
  * `@ggui-ai/mcp-server-core`.** `mcp-server-core` contains the
  * storage + runtime seams an MCP server implementer binds against
  * (`VectorStore`, `EmbeddingProvider`, `KeyValueStore`,
- * `BlueprintProvider`, `Negotiator`). `LLMCaller` is an
- * engine-internal dispatcher — one level below `Negotiator` — so
- * lifting it to `mcp-server-core` would grow the public seam count
- * speculatively. If a second consumer outside the negotiator
- * surfaces later, the "where does `LLMCaller` live?" question can be
- * re-opened at that point.
+ * `BlueprintProvider`). `LLMCaller` is an engine-internal
+ * dispatcher — one level below the synthesis + judge primitives this
+ * package exports — so lifting it to `mcp-server-core` would grow the
+ * public seam count speculatively. If a second consumer outside the
+ * negotiator surfaces later, the "where does `LLMCaller` live?"
+ * question can be re-opened at that point.
  *
  * Normative semantics:
  * - `call(systemPrompt, userMessage, maxTokens?)` returns the raw

package/dist/llm-rerank.d.ts

@@ -12,7 +12,6 @@
  * judge restores precision. Combined break-even hit rate is ~10%;
  * realistic workloads observe 30-70%.
  */
-import { summarizeContract } from '@ggui-ai/protocol';
 import type { LLMCaller, ToolSchema } from './llm-caller.js';
 /**
  * One candidate blueprint for the LLM judge to consider.
@@ -28,7 +27,7 @@ export interface RerankCandidate {
     readonly cachedIntent: string;
     /**
      * One-line summary of the blueprint's contract surface. Format
-     * matches `summarizeContract()` below — `slots=...; actions=...;
+     * matches `@ggui-ai/protocol`'s `summarizeContract()` — `slots=...; actions=...;
      * streams=...; props=...` so the judge sees the structural shape
      * without the JSON noise.
      */
@@ -49,10 +48,13 @@ export interface RerankDecision {
      */
     readonly matchId: string | null;
     /**
-     * Confidence on `[0, 1]`. Caller compares against a threshold (e.g.
-     * 0.6) before treating the decision as a hit. Returned even when
-     * matchId is null so callers can log "judge declined with
-     * confidence X."
+     * Confidence on `[0, 1]` — how strongly the matched candidate is in
+     * the same task-and-shape family as the request, NOT how completely
+     * its fields cover the request. Field/slot/action deltas are
+     * reconciled and reported to the agent separately; they never lower
+     * this score. Caller compares against a threshold (e.g. 0.6) before
+     * treating the decision as a hit. Returned even when matchId is null
+     * so callers can log "judge declined with confidence X."
      */
     readonly confidence: number;
     /**
@@ -79,9 +81,8 @@ export interface RerankQuery {
     readonly intent: string;
     readonly contractSummary: string;
 }
-declare const RERANK_SYSTEM_PROMPT = "You match user UI requests against previously-generated UI blueprints. Each blueprint was produced for a past request and stored. Decide whether any candidate produces the SAME USEFUL UI for the current request.\n\nMATCH means the candidate would correctly satisfy the user's current request \u2014 same UI shape (component types, layout pattern), same wire surface (slot names, action names), same intended user task, and same load-bearing parameters (dates, months, ranges, enum values).\n\nNO-MATCH means the candidate would NOT satisfy the user's current request \u2014 different task (haiku composer vs tweet draft, login vs signup), different UI shape (form vs list vs dashboard), or load-bearing parameters differ (calendar-Jan vs calendar-Mar \u2014 same contract, different value).\n\nVisual style differences alone (minimal vs ornate, dense vs spacious) DO NOT block a match \u2014 the user can refine those after they get a working UI.\n\nOutput exactly ONE tool call with your decision. confidence is a number in [0, 1]. matchId is a string from the candidate ids, or null when no candidate matches. reason is a short sentence the operator can use to debug.";
+declare const RERANK_SYSTEM_PROMPT = "You match user UI requests against previously-generated UI blueprints. Each blueprint was produced for a past request and stored. Decide whether any candidate belongs to the SAME FAMILY as the current request \u2014 i.e. it would serve as a reasonable starting point that the requester can refine, not a pixel-exact replica.\n\nMATCH means the candidate is the same intended user task AND the same broad UI shape (component types, layout pattern). A candidate still MATCHES when the current request adds or omits fields, slots, or actions relative to the cached blueprint \u2014 a superset, a subset, or an overlapping wire surface all still match. Added or omitted fields/slots/actions DO NOT block a match and are NOT yours to judge: those wire-surface deltas are reconciled and reported to the agent separately, after you decide. Judge similarity of task and shape, never coverage of fields.\n\nNO-MATCH means the candidate is a fundamentally different thing \u2014 a different intended task (haiku composer vs tweet draft, login vs signup), a different UI shape (form vs list vs dashboard), OR a conflicting load-bearing fixed VALUE baked into the blueprint (calendar pinned to Jan vs a request for Mar \u2014 same contract shape, but the fixed value conflicts). Reserve NO-MATCH for these; do not decline a candidate merely because its fields, slots, or actions differ from the request.\n\nVisual style differences alone (minimal vs ornate, dense vs spacious) DO NOT block a match \u2014 the user can refine those after they get a working UI.\n\nOutput exactly ONE tool call with your decision. confidence is a number in [0, 1] measuring how strongly the candidate is in the same task-and-shape family as the request (not how completely its fields cover the request). matchId is a string from the candidate ids, or null when no candidate matches. reason is a short sentence the operator can use to debug.";
 declare const RERANK_TOOL: ToolSchema;
-export { summarizeContract };
 /**
  * Run the rerank judge against a query + candidate list.
  *