@ggui-ai/negotiator 0.8.0 → 0.10.0

package/dist/synth-bench/run-repair-bench.js

@@ -24,7 +24,7 @@
  * Live LLM probe — opt-in CLI (run-repair-bench-cli.ts), NOT in CI. The
  * deterministic scorer pinning lives in round-trip-score.test.ts.
  */
-import { ensureConformingContract } from '../ensure-conforming-contract.js';
+import { ensureConformingContract, } from '../ensure-conforming-contract.js';
 import { scoreSynthesizedContract } from './run-bench.js';
 import { scoreContractRoundTrip, } from './round-trip-score.js';
 import { REPAIR_CORPUS } from './corpus.js';
@@ -48,7 +48,8 @@ export async function evaluateRepairCorpus(deps, options = {}, corpus = REPAIR_C
         const startedAt = Date.now();
         // The real production create-path: lint the draft → verbatim if clean
         // (origin agent), repair-in-place otherwise (origin synth). NEVER
-        // throws; an unrepairable draft yields the empty `{}` contract.
+        // throws; an unrepairable draft yields its conforming subset, or a
+        // decline (`contract: null`) when nothing survives.
         const result = await ensureConformingContract({ llm: deps.llm }, {
             draft: entry.draft,
             intent: entry.intent,
@@ -57,9 +58,13 @@ export async function evaluateRepairCorpus(deps, options = {}, corpus = REPAIR_C
                 : {}),
         });
         const latencyMs = Date.now() - startedAt;
-        const shape = scoreSynthesizedContract(result.contract, entry.expected);
+        // A decline carries no contract; score it as the empty contract —
+        // exactly what the retired fallback returned — so pass rates before
+        // and after the posture change measure the same thing.
+        const scored = result.contract ?? {};
+        const shape = scoreSynthesizedContract(scored, entry.expected);
         const roundTrip = entry.roundTrip !== undefined
-            ? scoreContractRoundTrip(result.contract, entry.roundTrip)
+            ? scoreContractRoundTrip(scored, entry.roundTrip)
             : null;
         const outcome = {
             entry,
@@ -134,7 +139,7 @@ export function formatRepairBenchReport(report) {
     for (const o of report.outcomes) {
         byMethod.set(o.method, (byMethod.get(o.method) ?? 0) + 1);
     }
-    const methodStr = ['verbatim', 'normalized', 'llm-repair', 'fallback-empty']
+    const methodStr = ['verbatim', 'normalized', 'llm-repair', 'salvaged-subset', 'declined']
         .filter((m) => byMethod.has(m))
         .map((m) => `${m}×${byMethod.get(m)}`)
         .join(' ');

package/dist/synthesize-contract.js

@@ -77,7 +77,7 @@ A contract has FOUR specs that describe distinct directions on the wire between
 THE FOUR-SPEC MODEL
 
   propsSpec    (agent → UI, render-time + agent-pushed refreshes)
-    Data the AGENT owns and supplies — the initial values at mount, AND every later refresh via ggui_update. NOT "static / never changes": propsSpec is the ONLY channel for agent-owned data, mutable or not. A weather card's city+temp (fixed) AND the items of the todo list the agent fetched and keeps in sync (mutable) BOTH live here — the agent seeds them at render and pushes each change with ggui_update. Use whenever the agent is the SOURCE of what the UI shows: the intent names data the agent provides / fetches / owns ("my todos", "the cart", "this user's profile", "the directory contents") OR data the component cannot render without (city, temp). Omit only when the UI originates its own state with no agent-supplied contents (a counter starting at zero, a blank notepad, a list the USER builds locally).
+    Data the AGENT owns and supplies — the initial values at mount, AND every later refresh via ggui_amend (in-place repaint of the mounted card; ggui_update instead mints a NEW history card for milestones). NOT "static / never changes": propsSpec is the ONLY channel for agent-owned data, mutable or not. A weather card's city+temp (fixed) AND the items of the todo list the agent fetched and keeps in sync (mutable) BOTH live here — the agent seeds them at render and pushes each change with ggui_amend. Use whenever the agent is the SOURCE of what the UI shows: the intent names data the agent provides / fetches / owns ("my todos", "the cart", "this user's profile", "the directory contents") OR data the component cannot render without (city, temp). Omit only when the UI originates its own state with no agent-supplied contents (a counter starting at zero, a blank notepad, a list the USER builds locally).
 
   streamSpec   (agent → UI, live, append-only)
     Channels where the agent pushes live data the UI displays as it arrives. Use ONLY when the intent describes ongoing agent-originated updates (a chat with messages, a live dashboard, a clock, a stock ticker, a notifications feed). Wrong instinct: do NOT use streamSpec for user-driven state, nor for a multi-step wizard / tutorial — its steps are a local stepper plus component-authored copy, not an agent-pushed feed.
@@ -152,7 +152,7 @@ CONCRETE PATTERNS
   Todo list / collection — split on OWNERSHIP, not on mutability. Both kinds mutate; what differs is WHO supplies the items.
 
     (a) Agent-owned — "show my todos", "an agent-backed todo list that persists across sessions", "render my cart", "the messages in this thread", "the directory contents"
-        The AGENT owns the items: it fetched / persists / keeps them in sync. The collection is the agent's data → it goes on PROPSSPEC, seeded at render and refreshed via ggui_update after each change. This is the ONLY shape that round-trips — contextSpec has no agent-push channel, so an agent-owned list placed there can never be seeded or updated (the UI renders empty). add / delete / toggle are discrete events the agent must witness to persist → declare them on actionSpec (with a matching agentCapabilities tool for each nextStep). Mutability is fine: ggui_update is exactly how the agent pushes the change.
+        The AGENT owns the items: it fetched / persists / keeps them in sync. The collection is the agent's data → it goes on PROPSSPEC, seeded at render and refreshed via ggui_amend after each change. This is the ONLY shape that round-trips — contextSpec has no agent-push channel, so an agent-owned list placed there can never be seeded or updated (the UI renders empty). add / delete / toggle are discrete events the agent must witness to persist → declare them on actionSpec (with a matching agentCapabilities tool for each nextStep). Mutability is fine: ggui_amend is exactly how the agent pushes the change.
         propsSpec:   { properties: { todos: {schema: {type: "array", items: {type: "object", properties: {id: {type: "string"}, text: {type: "string"}, done: {type: "boolean"}}, required: ["id", "text", "done"]}}, required: true} } }
         actionSpec:  { toggleTodo: {label: "Toggle todo", schema: {type: "object", properties: {id: {type: "string"}}, required: ["id"]}, nextStep: "todo_toggle"}, addTodo: {label: "Add todo", schema: {type: "object", properties: {text: {type: "string"}}, required: ["text"]}, nextStep: "todo_add"} }
 
@@ -409,7 +409,7 @@ export const SYNTHESIZE_TOOL = {
                         description: 'Per-prop map: name → {schema, required?}. Declares the initial render data the agent passes at push time.',
                     },
                 },
-                description: 'Agent-OWNED data the UI displays — the initial values seeded at render, refreshed any time after via ggui_update. NOT static-only: mutable collections the agent owns / fetched / keeps in sync (my todos, the cart, this thread\'s messages, a directory listing) go here too — propsSpec is the ONLY agent→client data channel. Use whenever the agent is the SOURCE of the displayed data (weather card → city/temp; profile → name/avatar; "my todos" → todos). Omit only when the UI originates its own state with no agent-supplied contents (a counter, a blank notepad, a list the user builds locally).',
+                description: 'Agent-OWNED data the UI displays — the initial values seeded at render, refreshed any time after via ggui_amend. NOT static-only: mutable collections the agent owns / fetched / keeps in sync (my todos, the cart, this thread\'s messages, a directory listing) go here too — propsSpec is the ONLY agent→client data channel. Use whenever the agent is the SOURCE of the displayed data (weather card → city/temp; profile → name/avatar; "my todos" → todos). Omit only when the UI originates its own state with no agent-supplied contents (a counter, a blank notepad, a list the user builds locally).',
             },
             reason: {
                 type: 'string',
@@ -477,7 +477,7 @@ function buildPreservationRepairNote(rejected, dropped) {
         '',
         `The agent's draft declared these on propsSpec (agent-owned seed data the UI renders): ${dropped.join(', ')}. Your contract no longer carries them as propsSpec properties — so the agent can no longer seed them at render. contextSpec has NO agent seed channel, so moving them there leaves the UI empty.`,
         '',
-        `Re-emit the contract with ${dropped.join(', ')} restored as propsSpec properties (agent-owned, seeded at render and refreshed via ggui_update). Keep every other spec unchanged.`,
+        `Re-emit the contract with ${dropped.join(', ')} restored as propsSpec properties (agent-owned, seeded at render and refreshed via ggui_amend). Keep every other spec unchanged.`,
     ].join('\n');
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/negotiator",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Contract-synthesis + match-judge engine for ggui's handshake. Synthesizes or repairs a conforming DataContract from an agent's draft, judges blueprint-match candidates for reuse, and validates contract structure + novelty — the primitives composed by decideHandshake in @ggui-ai/mcp-server-handlers. Deployment-agnostic: concrete embedding and vector-store bindings plug in via the storage interfaces from @ggui-ai/mcp-server-core.",
   "license": "Apache-2.0",
   "keywords": [
@@ -47,8 +47,8 @@
     }
   },
   "dependencies": {
-    "@ggui-ai/mcp-server-core": "0.8.0",
-    "@ggui-ai/protocol": "0.8.0"
+    "@ggui-ai/mcp-server-core": "0.10.0",
+    "@ggui-ai/protocol": "0.10.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/src/contract-validators.ts

@@ -249,7 +249,13 @@ function nameImpliesMutation(args: {
  */
 function isEmptyPayloadSchema(schema: JsonSchema | undefined): boolean {
   if (schema === undefined) return true;
-  if (schema.type !== 'object') return false;
+  // `type` may be a draft-07 type ARRAY (`['object','null']`) since
+  // draft-2026-08-19 — treat a type set containing 'object' like the
+  // single-string form.
+  const declaresObject = Array.isArray(schema.type)
+    ? schema.type.includes('object')
+    : schema.type === 'object';
+  if (!declaresObject) return false;
   if (schema.properties === undefined) return true;
   return Object.keys(schema.properties).length === 0;
 }

package/src/ensure-conforming-contract.ts

@@ -13,10 +13,14 @@
  *                              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)
+ *   - repair impossible      → the conforming SUBSET of the draft (every
+ *     (LLM down / provider      refused entry dropped and reported;
+ *      can't synth / budget     origin 'synth', method 'salvaged-subset')
+ *      exhausted)              — or, when nothing usable survives, a
+ *                              DECLINE (`contract: null`, method
+ *                              'declined') with the findings. NEVER
+ *                              throws; NEVER an empty contract on the
+ *                              agent's behalf (ggui#523 item 3).
  *
  * Determinism lives in the GATE (`lintContract`), never in the repair.
  * The repair LLM is non-deterministic, but the loop only exits when the
@@ -39,38 +43,65 @@ import {
 import type { LLMCaller } from './llm-caller.js';
 import { synthesizeContract } from './synthesize-contract.js';
 import { normalizeDraft } from './normalize-draft.js';
+import { salvageConformingSubset } from './salvage-draft.js';
 
-export interface EnsureConformingResult {
+/**
+ * How a 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).
+ *   - `salvaged-subset` — unrepairable within budget; the conforming
+ *                         SUBSET of the draft, refused entries dropped
+ *                         and reported (origin synth).
+ */
+export type EnsureConformingMethod =
+  | 'verbatim'
+  | 'normalized'
+  | 'llm-repair'
+  | 'salvaged-subset';
+
+/** A conforming contract was produced (the common case). */
+export interface EnsureConformingAccepted {
   /** 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).
+   *   (or the salvaged subset 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';
+  readonly method: EnsureConformingMethod;
   /**
    * 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.
+   * learns what it got wrong, even though we repaired it. On
+   * `salvaged-subset` they include one finding per dropped entry.
    */
   readonly findings: readonly SuggestionFinding[];
   /** Operator- + LLM-readable explanation. */
   readonly reasoning: string;
 }
 
-/** Trivially-valid last-resort contract — all four specs omitted. */
-const EMPTY_CONTRACT: DataContract = {};
+/**
+ * Nothing in the draft could be kept: repair failed AND no entry
+ * survives the gate. There is no contract to propose — the caller
+ * answers `action: 'declined'` with the findings and the agent fixes
+ * and re-handshakes. This is what replaced the empty-contract fallback:
+ * a hollow "success" was indistinguishable from a rejection and the
+ * observed recovery was a field-by-field bisect (ggui#523 item 3).
+ */
+export interface EnsureConformingDeclined {
+  readonly contract: null;
+  readonly origin: 'agent';
+  readonly method: 'declined';
+  /** The ERROR findings that rejected the draft — every one of them. */
+  readonly findings: readonly SuggestionFinding[];
+  readonly reasoning: string;
+}
+
+export type EnsureConformingResult = EnsureConformingAccepted | EnsureConformingDeclined;
 
 export async function ensureConformingContract(
   deps: { readonly llm: LLMCaller },
@@ -161,15 +192,37 @@ export async function ensureConformingContract(
   }
 
   // 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.
+  // repair budget exhausted). Keep what conforms: drop exactly the
+  // entries the gate refuses, report each drop, and propose the rest —
+  // the agent's own draft minus the parts the protocol rejected. Never
+  // an empty contract dressed as a proposal.
+  const salvaged = salvageConformingSubset(normalized);
+  if (salvaged !== null) {
+    const droppedPaths = salvaged.dropped.map((d) => d.path);
+    return {
+      contract: salvaged.contract,
+      origin: 'synth',
+      method: 'salvaged-subset',
+      findings: [...errorFindings, ...salvaged.dropped],
+      reasoning:
+        `could not repair the agent draft within budget (${synth.reason}); ` +
+        `proposing the conforming SUBSET of your draft — dropped ${droppedPaths.length} ` +
+        `entr${droppedPaths.length === 1 ? 'y' : 'ies'} the protocol refused (${droppedPaths.join(', ')}). ` +
+        `Each drop is a finding: fix those entries and re-handshake, or render this subset ` +
+        `and re-declare them via ggui_render override.`,
+    };
+  }
+
+  // Nothing usable survives. Decline: there is no contract to propose,
+  // and the findings say exactly why.
   return {
-    contract: EMPTY_CONTRACT,
-    origin: 'synth',
-    method: 'fallback-empty',
+    contract: null,
+    origin: 'agent',
+    method: 'declined',
     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`,
+    reasoning:
+      `declined: could not repair the agent draft within budget (${synth.reason}) and no entry of it ` +
+      `passes the contract gate — nothing to propose. Fix the findings (every one names its path) ` +
+      `and re-handshake; do not render against this handshake.`,
   };
 }

package/src/index.ts

@@ -36,8 +36,21 @@ export type {
 export { synthesizeContract } from './synthesize-contract.js';
 export type { SynthesizeContractResult } from './synthesize-contract.js';
 export { ensureConformingContract } from './ensure-conforming-contract.js';
-export type { EnsureConformingResult } from './ensure-conforming-contract.js';
+export type {
+  EnsureConformingAccepted,
+  EnsureConformingDeclined,
+  EnsureConformingMethod,
+  EnsureConformingResult,
+} from './ensure-conforming-contract.js';
 export { normalizeDraft } from './normalize-draft.js';
+// The last-resort tier that replaced the empty-contract fallback (ggui#523
+// item 3): keep the conforming subset of a draft, or decline. Shared with
+// the handlers' no-LLM paths so every producer answers the same way.
+export {
+  salvageConformingSubset,
+  declaresAnySurface,
+  type SalvageResult,
+} from './salvage-draft.js';
 export {
   validateContractRedundancy,
   validateContractNovelty,

package/src/normalize-schema.ts

@@ -102,7 +102,7 @@ function inferEnumBaseType(enumSibling: unknown): string {
 function normalizeTypeValue(
   value: unknown,
   enumSibling: unknown,
-): string | undefined {
+): string | string[] | undefined {
   if (typeof value === 'string') {
     const lower = value.toLowerCase();
     if (VALID_TYPES.has(lower)) return lower;
@@ -113,33 +113,51 @@ function normalizeTypeValue(
     if (lower.includes('|')) {
       // Pipe-union string (`"STRING|null"`). Some models emit the union
       // as one pipe-delimited string rather than the JSON Schema array
-      // form; recover the first valid non-null member, mirroring the
-      // array branch below (drops the nullable arm).
-      for (const member of lower.split('|')) {
-        const norm = normalizeTypeValue(member, enumSibling);
-        if (norm !== undefined && norm !== 'null') return norm;
-      }
-      return undefined;
+      // form; recover it AS the draft-07 array form — since
+      // draft-2026-08-19 the protocol's JsonSchema.type admits type
+      // arrays, and the nullable arm is load-bearing (schema-precise
+      // render: dropping it narrows the contract and turns the agent's
+      // legal `null` into a contract_violation).
+      return normalizeTypeMembers(lower.split('|'), enumSibling);
     }
     // Unrecognized garbage — drop the constraint rather than guess.
     return undefined;
   }
   if (Array.isArray(value)) {
-    // Union type (`["string", "null"]`). The protocol contract schema
-    // accepts only a single string; recover the first valid non-null
-    // member, dropping the nullable arm.
-    for (const member of value) {
-      if (typeof member === 'string') {
-        const norm = normalizeTypeValue(member, enumSibling);
-        if (norm !== undefined && norm !== 'null') return norm;
-      }
-    }
-    return 'string';
+    // Draft-07 union type (`["string", "null"]`) — PRESERVED, with
+    // each member normalized individually (invalid members drop). The
+    // pre-draft-2026-08-19 behavior collapsed to the first non-null
+    // member; see the pipe-union note above for why that narrowing is
+    // now a contract-violation factory.
+    return normalizeTypeMembers(value, enumSibling) ?? 'string';
   }
   // `type` was a number / object / boolean — meaningless; drop it.
   return undefined;
 }
 
+/**
+ * Normalize a list of candidate type members: each member runs through
+ * {@link normalizeTypeValue} (case folding, aliases, drop-words),
+ * survivors dedupe in order. Two-plus survivors → the draft-07 array
+ * form; exactly one → the plain string form; none → `undefined`.
+ */
+function normalizeTypeMembers(
+  members: readonly unknown[],
+  enumSibling: unknown,
+): string | string[] | undefined {
+  const survivors: string[] = [];
+  for (const member of members) {
+    if (typeof member !== 'string') continue;
+    const norm = normalizeTypeValue(member, enumSibling);
+    if (typeof norm === 'string' && !survivors.includes(norm)) {
+      survivors.push(norm);
+    }
+  }
+  if (survivors.length === 0) return undefined;
+  if (survivors.length === 1) return survivors[0];
+  return survivors;
+}
+
 /** Normalize a map of name → schema (e.g. `properties`). */
 function normalizeSchemaMap(value: unknown): unknown {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) {

package/src/salvage-draft.ts

@@ -0,0 +1,204 @@
+/**
+ * `salvageConformingSubset` — the last-resort tier that replaces the
+ * empty-contract fallback (ggui#523 item 3, "make `{}` impossible").
+ *
+ * When a draft cannot be made to conform any other way (no LLM bound,
+ * provider down, repair budget exhausted), the negotiator used to hand
+ * back the trivially-conforming `{}` with the findings attached — a
+ * response the agent cannot tell apart from success: `action: create`,
+ * a handshakeId, a `nextStep`, and a contract that declares NOTHING. The
+ * paired render then paints a hollow shell, and the observed recovery
+ * is a field-by-field bisect (No Silent Block, applied to contracts).
+ *
+ * This tier instead keeps what DOES conform. It deletes exactly the
+ * entries the deterministic gate names — one offending property,
+ * action, stream, context slot, or tool at a time (a bad sub-field
+ * first, the whole entry only if that was not enough) — re-lints, and
+ * repeats until the gate is green. The result is the agent's own draft
+ * minus the parts the protocol refused, with every drop reported as a
+ * finding, so the agent sees exactly what to fix in one read.
+ *
+ * It returns `null` — "nothing salvageable" — when what survives
+ * declares no surface at all (no props, actions, streams, context
+ * slots, or tools), or when an error is structural (the root is not an
+ * object). `null` is the DECLINE signal: the caller answers
+ * `action: 'declined'` with the findings, never a proposal. Between the
+ * two, no path produces an empty contract on the agent's behalf.
+ *
+ * Deterministic and pure: no LLM, no mutation of the input, no throw.
+ * Bounded: every iteration removes at least one key or returns.
+ */
+import {
+  dataContractSchema,
+  lintContract,
+  type DataContract,
+  type SuggestionFinding,
+} from '@ggui-ai/protocol';
+
+/** The six top-level spec keys the DataContract declares. */
+const SPEC_KEYS = new Set([
+  'propsSpec',
+  'actionSpec',
+  'streamSpec',
+  'contextSpec',
+  'agentCapabilities',
+  'clientCapabilities',
+]);
+
+/** Spec maps whose direct children are the droppable entries. */
+const ENTRY_MAP_SPECS = new Set(['actionSpec', 'streamSpec', 'contextSpec']);
+
+/** Hard cap on gate iterations — every iteration deletes ≥1 key. */
+const MAX_ROUNDS = 100;
+
+export interface SalvageResult {
+  /** A contract guaranteed to pass `lintContract` with zero errors, and to declare at least one surface. */
+  readonly contract: DataContract;
+  /**
+   * What was removed to get there — one finding per deleted key, in
+   * deletion order, carrying the gate's own code + message for that
+   * path. Surfaced to the agent verbatim.
+   */
+  readonly dropped: readonly SuggestionFinding[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Does the contract declare at least one surface an agent could use? */
+export function declaresAnySurface(contract: DataContract): boolean {
+  const props = contract.propsSpec?.properties;
+  if (props !== undefined && Object.keys(props).length > 0) return true;
+  if (contract.actionSpec !== undefined && Object.keys(contract.actionSpec).length > 0) return true;
+  if (contract.streamSpec !== undefined && Object.keys(contract.streamSpec).length > 0) return true;
+  if (contract.contextSpec !== undefined && Object.keys(contract.contextSpec).length > 0) return true;
+  const tools = contract.agentCapabilities?.tools;
+  if (tools !== undefined && Object.keys(tools).length > 0) return true;
+  return false;
+}
+
+/**
+ * Where to cut for an offending path. Returns the key path to delete
+ * (as segments) or `null` when the error is structural.
+ *
+ *   propsSpec.properties.<k>[.…]  → try the sub-field, then the property
+ *   actionSpec|streamSpec|contextSpec.<k>[.…] → sub-field, then the entry
+ *   agentCapabilities.tools.<k>[.…] → sub-field, then the tool
+ *   <spec>[.other]               → the whole spec
+ *   <unknown-top-level-key>[.…]  → that key (retired fields, typos)
+ *   <root>                       → structural, null
+ *
+ * `leafFirst` picks the deeper cut when one exists; the caller retries
+ * with `false` if that cut did not clear the entry.
+ */
+export function cutFor(path: string, leafFirst: boolean): readonly string[] | null {
+  if (path === '' || path === '<root>') return null;
+  const seg = path.split('.');
+  const head = seg[0]!;
+
+  if (head === 'propsSpec') {
+    if (seg[1] === 'properties' && seg.length >= 3) {
+      const entry = seg.slice(0, 3);
+      return leafFirst && seg.length > 3 ? seg : entry;
+    }
+    return ['propsSpec'];
+  }
+  if (ENTRY_MAP_SPECS.has(head)) {
+    if (seg.length >= 2) {
+      const entry = seg.slice(0, 2);
+      return leafFirst && seg.length > 2 ? seg : entry;
+    }
+    return [head];
+  }
+  if (head === 'agentCapabilities') {
+    if (seg[1] === 'tools' && seg.length >= 3) {
+      const entry = seg.slice(0, 3);
+      return leafFirst && seg.length > 3 ? seg : entry;
+    }
+    return ['agentCapabilities'];
+  }
+  if (SPEC_KEYS.has(head)) return [head];
+  // Unknown / retired top-level field — the whole key goes.
+  return [head];
+}
+
+/** Delete `keyPath` from a structural copy of `root`; false if absent. */
+function deleteAt(root: Record<string, unknown>, keyPath: readonly string[]): boolean {
+  let node: Record<string, unknown> = root;
+  for (let i = 0; i < keyPath.length - 1; i += 1) {
+    const next = node[keyPath[i]!];
+    if (!isRecord(next)) return false;
+    // Copy-on-write down the path so the input is never mutated.
+    const copy: Record<string, unknown> = { ...next };
+    node[keyPath[i]!] = copy;
+    node = copy;
+  }
+  const leaf = keyPath[keyPath.length - 1]!;
+  if (!(leaf in node)) return false;
+  delete node[leaf];
+  // A dropped prop must leave `propsSpec.required` too — a stale name
+  // there is its own gate error and would only cost another round.
+  if (keyPath.length === 3 && keyPath[0] === 'propsSpec' && keyPath[1] === 'properties') {
+    const ps = root['propsSpec'];
+    if (isRecord(ps) && Array.isArray(ps['required'])) {
+      root['propsSpec'] = {
+        ...ps,
+        required: ps['required'].filter((name) => name !== leaf),
+      };
+    }
+  }
+  return true;
+}
+
+/**
+ * Keep the conforming subset of `draft` (already normalized by the
+ * caller, ideally). See the module docstring for the contract.
+ */
+export function salvageConformingSubset(draft: unknown): SalvageResult | null {
+  if (!isRecord(draft)) return null;
+  let working: Record<string, unknown> = { ...draft };
+  const dropped: SuggestionFinding[] = [];
+  /** Cuts already tried at leaf depth for a path — the retry goes to the entry. */
+  const leafTried = new Set<string>();
+
+  for (let round = 0; round < MAX_ROUNDS; round += 1) {
+    const lint = lintContract(working);
+    if (lint.errors.length === 0) {
+      // Shape passed ⇒ the strict parse cannot throw.
+      const contract = dataContractSchema.parse(working);
+      return declaresAnySurface(contract) ? { contract, dropped } : null;
+    }
+    let cutSomething = false;
+    for (const issue of lint.errors) {
+      const leafFirst = !leafTried.has(issue.path);
+      const cut = cutFor(issue.path, leafFirst);
+      if (cut === null) return null; // structural — nothing to keep
+      const cutKey = cut.join('.');
+      if (leafFirst && cutKey === issue.path) leafTried.add(issue.path);
+      const next: Record<string, unknown> = { ...working };
+      if (!deleteAt(next, cut)) {
+        // The path names something that is not there (a reference
+        // target, a computed check) — fall back to the entry cut once,
+        // then give up on this issue for the round.
+        if (leafFirst) {
+          leafTried.add(issue.path);
+          const entryCut = cutFor(issue.path, false);
+          if (entryCut !== null && deleteAt(next, entryCut)) {
+            working = next;
+            dropped.push({ code: issue.code, severity: 'error', path: entryCut.join('.'), message: issue.message });
+            cutSomething = true;
+            break;
+          }
+        }
+        continue;
+      }
+      working = next;
+      dropped.push({ code: issue.code, severity: 'error', path: cutKey, message: issue.message });
+      cutSomething = true;
+      break; // one cut per round — re-lint before the next decision
+    }
+    if (!cutSomething) return null; // no cut could be applied — structural
+  }
+  return null;
+}

package/src/synth-bench/corpus.ts

@@ -451,7 +451,7 @@ export const BENCH_CORPUS: readonly BenchEntry[] = [
         'remove',
       ],
       notes:
-        'agent-backed/persisted = the agent OWNS the items → todos seed on propsSpec (refreshed via ggui_update); add/delete/toggle are discrete events on actionSpec. contextSpec has no agent-push channel, so an agent-owned persisted list there cannot round-trip — this is the round-trip-correct shape, aligned with list-message-thread / list-file-browser (both props-bearing agent-supplied collections).',
+        'agent-backed/persisted = the agent OWNS the items → todos seed on propsSpec (refreshed via ggui_amend); add/delete/toggle are discrete events on actionSpec. contextSpec has no agent-push channel, so an agent-owned persisted list there cannot round-trip — this is the round-trip-correct shape, aligned with list-message-thread / list-file-browser (both props-bearing agent-supplied collections).',
     },
   },
   {

package/src/synth-bench/round-trip-score.ts

@@ -86,9 +86,9 @@ export interface RoundTripScore {
 
 /**
  * True when a contract declares none of the six spec surfaces — the
- * `EMPTY_CONTRACT` (`{}`) that `ensureConformingContract` returns when a
- * draft is unrepairable. Such a contract is structurally valid but
- * carries no wire at all.
+ * empty contract the bench substitutes for a DECLINE (and the `{}` the
+ * retired fallback used to return for an unrepairable draft). Such a
+ * contract is structurally valid but carries no wire at all.
  */
 function isEmptyContract(contract: DataContract): boolean {
   return (