@ggui-ai/negotiator 0.24.0 → 0.26.0

package/src/preserve-declared-members.ts

@@ -0,0 +1,521 @@
+/**
+ * Declared-member preservation: the deterministic backstop that keeps a
+ * repair FAITHFUL to what the agent DECLARED (ggui#1421 for actions,
+ * ggui#1430 for every spec).
+ *
+ * The repair tool authors only a few members per entry:
+ *   - `label` / `schema` on an action;
+ *   - `schema` / `required` on a prop;
+ *   - `schema` / `default` on a context slot;
+ *   - `schema` / `source` on a stream channel;
+ *   - `toolInfo.inputSchema` / `toolInfo.outputSchema` / `usage` on a tool.
+ * Every other member is the agent's declaration: an action's `oneShot` (the
+ * one-shot line keys on it being ON THE SERVED CONTRACT, ggui#1108 →
+ * ggui#1223), a stream's `mode` / `replay` / `complete`, a prop's
+ * `default`, a tool's `toolInfo.description`. A repair that re-emits an entry
+ * from the tool's answer alone drops them silently. So the overlay below puts
+ * the draft's declarations back on the repaired candidate, under the SAME
+ * KEY, and names whatever it cannot keep.
+ *
+ * The toolbox is the agent's too. A repair that drops a tool entry the draft
+ * declared leaves every `nextStep` naming it dangling, so a draft tool the
+ * candidate lacks is restored WHOLE. Only tools: a repair may legitimately
+ * move or remove an action, prop, context or stream entry.
+ *
+ * Findings, each at its own path:
+ *   - `REPAIR_MEMBER_DROPPED` at `<spec>.<name>.<member>`: a declared
+ *     member the merged contract cannot carry (it fails its own schema, or
+ *     the gate refuses it there or, for `nextStep`, as `CTR_SCHEMA_INCOMPAT`
+ *     at the sibling `.schema`);
+ *   - `REPAIR_ENTRY_DROPPED` at `<spec>.<name>`: a draft action, prop,
+ *     context, stream or tool entry the proposal no longer carries under that
+ *     key (renamed, moved or removed), named ONCE; its members are not owed
+ *     one by one. A restored tool the gate refuses is named so, with the
+ *     gate's reason;
+ *   - `REPAIR_ENTRY_RESTORED` at `agentCapabilities.tools.<name>`
+ *     (severity `warn`): a draft tool the repair dropped and the overlay put
+ *     back, so a tool coming back is never silent.
+ *
+ * A member whose path a DRAFT finding already names is under repair: it is
+ * not restored, and its absence is named by that finding. A draft tool with a
+ * finding at or under its path is not restored. Paths follow the gate's
+ * convention (`propsSpec.<name>`, not `propsSpec.properties.<name>`).
+ * Model-independent: the overlay works whatever the repair LLM returns, and
+ * it never makes the proposal fail the gate BECAUSE of what it put back.
+ */
+
+import {
+  actionEntrySchema,
+  agentToolEntrySchema,
+  contextEntrySchema,
+  CTR_SCHEMA_INCOMPAT,
+  lintContract,
+  propEntrySchema,
+  streamChannelEntrySchema,
+  type ActionEntry,
+  type AgentToolEntry,
+  type ContextEntry,
+  type DataContract,
+  type PropEntry,
+  type StreamChannelEntry,
+  type SuggestionFinding,
+} from '@ggui-ai/protocol';
+
+/** A declared member the repair could not keep; path `<spec>.<name>.<member>`. */
+export const REPAIR_MEMBER_DROPPED = 'REPAIR_MEMBER_DROPPED' as const;
+/** A draft entry the proposal no longer carries under its key; path `<spec>.<name>`. */
+export const REPAIR_ENTRY_DROPPED = 'REPAIR_ENTRY_DROPPED' as const;
+/** A draft tool the repair dropped and the overlay restored; path `agentCapabilities.tools.<name>`. */
+export const REPAIR_ENTRY_RESTORED = 'REPAIR_ENTRY_RESTORED' as const;
+
+/** One gate error, as `lintContract` reports it. */
+type GateIssue = ReturnType<typeof lintContract>['errors'][number];
+
+/**
+ * What the overlay needs of an entry schema, structurally: the protocol's zod
+ * schemas satisfy it, and this package takes no zod dependency of its own.
+ */
+interface Parser<T> {
+  safeParse(
+    value: unknown,
+  ):
+    | { readonly success: true; readonly data: T }
+    | { readonly success: false; readonly error: { readonly issues: readonly { readonly message: string }[] } };
+  parse(value: unknown): T;
+}
+interface ObjectParser<T> extends Parser<T> {
+  readonly shape: Readonly<Record<string, Parser<unknown>>>;
+}
+
+/** One spec the overlay covers. `E` is the protocol's entry type. */
+interface SpecDescriptor<E> {
+  /** The gate's path prefix for this spec's entries. */
+  readonly prefix: string;
+  /** What an entry is called in a message. */
+  readonly noun: string;
+  readonly schema: ObjectParser<E>;
+  /** Top-level members the repair authors: never restored. */
+  readonly authored: ReadonlySet<string>;
+  /** A nested object whose members are declared too, minus the ones the repair authors in it. */
+  readonly nested?: { readonly member: string; readonly schema: ObjectParser<unknown>; readonly authored: ReadonlySet<string> };
+  /** Whether a draft entry the candidate lacks is restored whole (the toolbox only). */
+  readonly restoresEntries: boolean;
+  /** For a member the gate reports at a SIBLING path: that path's last segment and the code it reports. */
+  readonly sibling?: (member: string) => { readonly segment: string; readonly code: string } | undefined;
+  draftEntries(draft: Readonly<Record<string, unknown>>): Readonly<Record<string, unknown>> | undefined;
+  /** The entry's members as a plain record (a spread at the concrete type). */
+  asRecord(entry: E): Readonly<Record<string, unknown>>;
+  entries(contract: DataContract): Readonly<Record<string, E>> | undefined;
+  withEntries(contract: DataContract, entries: Readonly<Record<string, E>>): DataContract;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function recordAt(value: Readonly<Record<string, unknown>> | undefined, key: string): Readonly<Record<string, unknown>> | undefined {
+  if (value === undefined) return undefined;
+  const at = value[key];
+  return isRecord(at) ? at : undefined;
+}
+
+function memberDropped(prefix: string, name: string, member: string, reason: string): SuggestionFinding {
+  return {
+    code: REPAIR_MEMBER_DROPPED,
+    severity: 'error',
+    path: `${prefix}.${name}.${member}`,
+    message: `the repair could not keep the declared \`${member}\` on '${name}' (${prefix}): ${reason}`,
+  };
+}
+
+function gateReason(issue: GateIssue): string {
+  return `refused by the gate as ${issue.code} at ${issue.path}: ${issue.message}`;
+}
+
+/** Per spec, what the overlay put back: members per entry key, and whole entries. */
+interface RestoreState {
+  readonly members: Map<string, Set<string>>;
+  readonly entries: Set<string>;
+}
+
+/** The descriptor's behaviour behind one non-generic face, so the five specs sit in one list. */
+interface SpecRunner {
+  readonly prefix: string;
+  overlay(
+    draft: Readonly<Record<string, unknown>>,
+    contract: DataContract,
+    underRepair: ReadonlySet<string>,
+  ): { readonly contract: DataContract; readonly state: RestoreState; readonly dropped: readonly SuggestionFinding[] };
+  /** Un-restore the restored members the gate refuses at their own (or sibling) path. */
+  unrestoreMembers(
+    contract: DataContract,
+    state: RestoreState,
+    errors: readonly GateIssue[],
+  ): { readonly contract: DataContract; readonly dropped: readonly SuggestionFinding[] };
+  /** Un-restore ONE restored entry whose presence adds a gate error the tree does not have without it. */
+  unrestoreOneEntry(
+    contract: DataContract,
+    state: RestoreState,
+  ): { readonly contract: DataContract; readonly dropped: readonly SuggestionFinding[] } | undefined;
+  /** The `REPAIR_ENTRY_RESTORED` findings for the entries still restored. */
+  restoredFindings(state: RestoreState): readonly SuggestionFinding[];
+  /** The draft's entry keys the contract no longer carries. */
+  droppedKeys(draft: Readonly<Record<string, unknown>>, contract: DataContract): readonly string[];
+  readonly noun: string;
+  /** Whether `path` is this spec's entry path, or one of its member paths, for an entry `contract` carries. */
+  onSurvivingEntry(path: string, contract: DataContract): boolean;
+}
+
+function specRunner<E>(d: SpecDescriptor<E>): SpecRunner {
+  const topMembers = Object.keys(d.schema.shape).filter((k) => !d.authored.has(k) && k !== d.nested?.member);
+  const nestedMembers = d.nested === undefined ? [] : Object.keys(d.nested.schema.shape).filter((k) => !(d.nested?.authored.has(k) ?? false));
+  const nestedPrefix = d.nested?.member;
+  /** Every member path a finding can carry on an entry, exactly. */
+  const memberPaths = [
+    ...Object.keys(d.schema.shape),
+    ...(d.nested === undefined ? [] : Object.keys(d.nested.schema.shape).map((k) => `${d.nested?.member}.${k}`)),
+  ];
+  const entryPath = (name: string): string => `${d.prefix}.${name}`;
+
+  /** `entry` without the member at `member` (`a` or `parent.a`), re-derived by the strict schema. */
+  const withoutMember = (entry: E, member: string): E => {
+    const dot = member.indexOf('.');
+    if (dot === -1) return d.schema.parse(Object.fromEntries(Object.entries(d.asRecord(entry)).filter(([k]) => k !== member)));
+    const parent = member.slice(0, dot);
+    const leaf = member.slice(dot + 1);
+    const copy: Record<string, unknown> = { ...d.asRecord(entry) };
+    const inner = recordAt(copy, parent);
+    if (inner !== undefined) copy[parent] = Object.fromEntries(Object.entries(inner).filter(([k]) => k !== leaf));
+    return d.schema.parse(copy);
+  };
+
+  const withoutEntry = (contract: DataContract, name: string): DataContract => {
+    const current = d.entries(contract) ?? {};
+    return d.withEntries(contract, Object.fromEntries(Object.entries(current).filter(([k]) => k !== name)));
+  };
+
+  /** Under repair at or under an entry: the entry path, a member path, or a path inside a member. */
+  const entryUnderRepair = (name: string, underRepair: ReadonlySet<string>): boolean => {
+    const base = entryPath(name);
+    if (underRepair.has(base)) return true;
+    for (const p of underRepair) {
+      for (const m of memberPaths) if (p === `${base}.${m}` || p.startsWith(`${base}.${m}.`)) return true;
+    }
+    return false;
+  };
+
+  const sameIssue = (a: GateIssue, b: GateIssue): boolean => a.code === b.code && a.path === b.path;
+
+  return {
+    prefix: d.prefix,
+    noun: d.noun,
+
+    overlay(draft, contract, underRepair) {
+      const state: RestoreState = { members: new Map(), entries: new Set() };
+      const dropped: SuggestionFinding[] = [];
+      const draftEntries = d.draftEntries(draft);
+      if (draftEntries === undefined) return { contract, state, dropped };
+      const current = d.entries(contract) ?? {};
+      const merged: Record<string, E> = { ...current };
+
+      for (const [name, entry] of Object.entries(current)) {
+        const draftEntry = recordAt(draftEntries, name);
+        if (draftEntry === undefined) continue;
+        const next: Record<string, unknown> = { ...d.asRecord(entry) };
+        const put = new Set<string>();
+        for (const member of topMembers) {
+          const value = draftEntry[member];
+          if (value === undefined || next[member] !== undefined || underRepair.has(`${entryPath(name)}.${member}`)) continue;
+          const parsed = d.schema.shape[member]?.safeParse(value);
+          if (parsed === undefined) continue;
+          if (!parsed.success) {
+            dropped.push(memberDropped(d.prefix, name, member, parsed.error.issues[0]?.message ?? 'invalid'));
+            continue;
+          }
+          next[member] = parsed.data;
+          put.add(member);
+        }
+        if (d.nested !== undefined && nestedPrefix !== undefined) {
+          const draftInner = recordAt(draftEntry, nestedPrefix);
+          const inner = recordAt(next, nestedPrefix);
+          if (draftInner !== undefined && inner !== undefined) {
+            const nextInner: Record<string, unknown> = { ...inner };
+            for (const member of nestedMembers) {
+              const path = `${nestedPrefix}.${member}`;
+              const value = draftInner[member];
+              if (value === undefined || nextInner[member] !== undefined || underRepair.has(`${entryPath(name)}.${path}`)) continue;
+              const parsed = d.nested.schema.shape[member]?.safeParse(value);
+              if (parsed === undefined) continue;
+              if (!parsed.success) {
+                dropped.push(memberDropped(d.prefix, name, path, parsed.error.issues[0]?.message ?? 'invalid'));
+                continue;
+              }
+              nextInner[member] = parsed.data;
+              put.add(path);
+            }
+            next[nestedPrefix] = nextInner;
+          }
+        }
+        if (put.size === 0) continue;
+        const reparsed = d.schema.safeParse(next);
+        // The CANDIDATE's own authored members are not an entry yet: the loop's gate retries that.
+        if (!reparsed.success) continue;
+        merged[name] = reparsed.data;
+        state.members.set(name, put);
+      }
+
+      if (d.restoresEntries) {
+        // Sorted, so the outcome depends on the draft's content, never on its key order.
+        for (const name of Object.keys(draftEntries).sort()) {
+          if (Object.hasOwn(current, name) || entryUnderRepair(name, underRepair)) continue;
+          const parsed = d.schema.safeParse(draftEntries[name]);
+          if (!parsed.success) continue;
+          merged[name] = parsed.data;
+          state.entries.add(name);
+        }
+      }
+
+      if (state.members.size === 0 && state.entries.size === 0) return { contract, state, dropped };
+      return { contract: d.withEntries(contract, merged), state, dropped };
+    },
+
+    unrestoreMembers(contract, state, errors) {
+      const dropped: SuggestionFinding[] = [];
+      let next = contract;
+      for (const [name, members] of state.members) {
+        for (const member of [...members]) {
+          const sib = d.sibling?.(member);
+          const refusal =
+            errors.find((issue) => issue.path === `${entryPath(name)}.${member}`) ??
+            (sib !== undefined ? errors.find((issue) => issue.code === sib.code && issue.path === `${entryPath(name)}.${sib.segment}`) : undefined);
+          if (refusal === undefined) continue;
+          const entry = d.entries(next)?.[name];
+          if (entry === undefined) continue;
+          next = d.withEntries(next, { ...(d.entries(next) ?? {}), [name]: withoutMember(entry, member) });
+          members.delete(member);
+          dropped.push(memberDropped(d.prefix, name, member, gateReason(refusal)));
+        }
+        if (members.size === 0) state.members.delete(name);
+      }
+      return { contract: next, dropped };
+    },
+
+    unrestoreOneEntry(contract, state) {
+      if (state.entries.size === 0) return undefined;
+      const withAll = lintContract(contract).errors;
+      // Sorted: when two restored tools fail only together, which one comes back out
+      // depends on their names, never on the draft's key order.
+      for (const name of [...state.entries].sort()) {
+        const without = withoutEntry(contract, name);
+        const base = lintContract(without).errors;
+        const added = withAll.find((issue) => !base.some((b) => sameIssue(b, issue)));
+        if (added === undefined) continue;
+        state.entries.delete(name);
+        return {
+          contract: without,
+          dropped: [
+            {
+              code: REPAIR_ENTRY_DROPPED,
+              severity: 'error',
+              path: entryPath(name),
+              message: `the repair dropped the ${d.noun} '${name}' you declared, and restoring it from your draft would fail the gate (${gateReason(added)}); declare it again in a form the gate accepts, via ggui_render override or a corrected re-handshake`,
+            },
+          ],
+        };
+      }
+      return undefined;
+    },
+
+    restoredFindings(state) {
+      return [...state.entries].sort().map((name): SuggestionFinding => ({
+        code: REPAIR_ENTRY_RESTORED,
+        severity: 'warn',
+        path: entryPath(name),
+        message: `the repair dropped the ${d.noun} '${name}' you declared; it is restored from your draft, because the toolbox is yours to declare`,
+      }));
+    },
+
+    droppedKeys(draft, contract) {
+      const draftEntries = d.draftEntries(draft);
+      if (draftEntries === undefined) return [];
+      const kept = d.entries(contract) ?? {};
+      return Object.keys(draftEntries).filter((name) => !Object.hasOwn(kept, name));
+    },
+
+    onSurvivingEntry(path, contract) {
+      const kept = d.entries(contract);
+      if (kept === undefined) return false;
+      return Object.keys(kept).some((name) => {
+        const base = entryPath(name);
+        return path === base || memberPaths.some((m) => path === `${base}.${m}`);
+      });
+    },
+  };
+}
+
+/** The five specs, in the order a finding list names them. */
+const RUNNERS: readonly SpecRunner[] = [
+  specRunner<ActionEntry>({
+    prefix: 'actionSpec',
+    noun: 'action',
+    schema: actionEntrySchema,
+    authored: new Set(['label', 'schema']),
+    restoresEntries: false,
+    sibling: (member) => (member === 'nextStep' ? { segment: 'schema', code: CTR_SCHEMA_INCOMPAT } : undefined),
+    draftEntries: (draft) => recordAt(draft, 'actionSpec'),
+    asRecord: (entry) => ({ ...entry }),
+    entries: (contract) => contract.actionSpec,
+    withEntries: (contract, entries) => ({ ...contract, actionSpec: entries }),
+  }),
+  specRunner<PropEntry>({
+    prefix: 'propsSpec',
+    noun: 'prop',
+    schema: propEntrySchema,
+    authored: new Set(['schema', 'required']),
+    restoresEntries: false,
+    draftEntries: (draft) => recordAt(recordAt(draft, 'propsSpec'), 'properties'),
+    asRecord: (entry) => ({ ...entry }),
+    entries: (contract) => contract.propsSpec?.properties,
+    withEntries: (contract, entries) => ({ ...contract, propsSpec: { ...contract.propsSpec, properties: entries } }),
+  }),
+  specRunner<ContextEntry>({
+    prefix: 'contextSpec',
+    noun: 'context slot',
+    schema: contextEntrySchema,
+    authored: new Set(['schema', 'default']),
+    restoresEntries: false,
+    draftEntries: (draft) => recordAt(draft, 'contextSpec'),
+    asRecord: (entry) => ({ ...entry }),
+    entries: (contract) => contract.contextSpec,
+    withEntries: (contract, entries) => ({ ...contract, contextSpec: entries }),
+  }),
+  specRunner<StreamChannelEntry>({
+    prefix: 'streamSpec',
+    noun: 'stream channel',
+    schema: streamChannelEntrySchema,
+    authored: new Set(['schema', 'source']),
+    restoresEntries: false,
+    draftEntries: (draft) => recordAt(draft, 'streamSpec'),
+    asRecord: (entry) => ({ ...entry }),
+    entries: (contract) => contract.streamSpec,
+    withEntries: (contract, entries) => ({ ...contract, streamSpec: entries }),
+  }),
+  specRunner<AgentToolEntry>({
+    prefix: 'agentCapabilities.tools',
+    noun: 'tool',
+    schema: agentToolEntrySchema,
+    authored: new Set(['toolInfo', 'usage']),
+    nested: { member: 'toolInfo', schema: agentToolEntrySchema.shape.toolInfo, authored: new Set(['inputSchema', 'outputSchema']) },
+    restoresEntries: true,
+    draftEntries: (draft) => recordAt(recordAt(draft, 'agentCapabilities'), 'tools'),
+    asRecord: (entry) => ({ ...entry }),
+    entries: (contract) => contract.agentCapabilities?.tools,
+    withEntries: (contract, entries) => ({ ...contract, agentCapabilities: { ...contract.agentCapabilities, tools: entries } }),
+  }),
+];
+
+/**
+ * Overlay the draft's declarations onto the candidate: every declared member
+ * of every entry the candidate carries under the same key (keeping what the
+ * repair authors), and every draft tool the candidate dropped, whole. A
+ * member or tool whose path a draft finding names is under repair and stays
+ * out. Then lint the merged contract and un-restore, until the tree is
+ * stable, every restored member the gate refuses (at its own path, or for
+ * `nextStep` as `CTR_SCHEMA_INCOMPAT` at the sibling `.schema`) and every
+ * restored tool whose presence adds a gate error, naming each one, so the
+ * returned contract never fails the gate BECAUSE of the overlay. A malformed
+ * candidate entry is left un-overlaid for the loop's own gate to retry;
+ * nothing here throws on the model's answer. Entries the candidate moved or
+ * removed (other than tools) get nothing back here: see
+ * {@link findDroppedEntries}.
+ */
+export function restoreDraftDeclaredMembers(
+  draft: unknown,
+  candidate: DataContract,
+  underRepair: ReadonlySet<string>,
+): { readonly contract: DataContract; readonly dropped: readonly SuggestionFinding[] } {
+  if (!isRecord(draft)) return { contract: candidate, dropped: [] };
+  let contract = candidate;
+  const dropped: SuggestionFinding[] = [];
+  const states: RestoreState[] = [];
+  for (const runner of RUNNERS) {
+    const result = runner.overlay(draft, contract, underRepair);
+    contract = result.contract;
+    dropped.push(...result.dropped);
+    states.push(result.state);
+  }
+  const restoredCount = (): number => states.reduce((n, s) => n + s.entries.size + [...s.members.values()].reduce((m, set) => m + set.size, 0), 0);
+  if (restoredCount() === 0) return { contract, dropped };
+
+  // Cross-reference and compatibility errors exist only on the MERGED tree.
+  // Each pass un-restores at least one member or entry, or stops, so the
+  // loop is bounded by what was restored.
+  for (let pass = 0, budget = restoredCount() + 1; pass < budget; pass += 1) {
+    const errors = lintContract(contract).errors;
+    let changed = false;
+    RUNNERS.forEach((runner, i) => {
+      const state = states[i];
+      if (state === undefined) return;
+      const result = runner.unrestoreMembers(contract, state, errors);
+      if (result.dropped.length > 0) changed = true;
+      contract = result.contract;
+      dropped.push(...result.dropped);
+    });
+    if (!changed) {
+      for (const [i, runner] of RUNNERS.entries()) {
+        const state = states[i];
+        if (state === undefined) continue;
+        const result = runner.unrestoreOneEntry(contract, state);
+        if (result === undefined) continue;
+        contract = result.contract;
+        dropped.push(...result.dropped);
+        changed = true;
+        break;
+      }
+    }
+    if (!changed || restoredCount() === 0) break;
+  }
+  RUNNERS.forEach((runner, i) => {
+    const state = states[i];
+    if (state !== undefined) dropped.push(...runner.restoredFindings(state));
+  });
+  return { contract, dropped };
+}
+
+/**
+ * Whether `finding` sits on an entry `contract` still carries: at its exact
+ * entry path or one of its member paths, never by dotted prefix (an action
+ * named `a` is not a prefix of `a.b`). Used to keep a repair's member and
+ * restore findings only for entries the final proposal carries.
+ */
+export function isOnSurvivingEntry(finding: SuggestionFinding, contract: DataContract): boolean {
+  return RUNNERS.some((runner) => runner.onSurvivingEntry(finding.path, contract));
+}
+
+/**
+ * One `REPAIR_ENTRY_DROPPED` per draft entry, on every spec, that the
+ * candidate no longer carries under its key: renamed, moved or removed by the
+ * repair, or pruned by the loop's own placement pass. Its members are not
+ * owed one by one. When the gate refused the NAME itself (`CTR_DUP_NAME` /
+ * `CTR_RESERVED_NAME` at `<spec>.<name>`, so the path is under repair) the
+ * message says so and does not send the agent back to a name the gate will
+ * refuse again. Empty when every draft entry survived.
+ */
+export function findDroppedEntries(
+  draft: unknown,
+  candidate: DataContract,
+  underRepair: ReadonlySet<string>,
+): readonly SuggestionFinding[] {
+  if (!isRecord(draft)) return [];
+  return RUNNERS.flatMap((runner) =>
+    runner.droppedKeys(draft, candidate).map((name): SuggestionFinding => {
+      const path = `${runner.prefix}.${name}`;
+      const message = underRepair.has(path)
+        ? `the gate refused the ${runner.noun} name '${name}' (see the finding at this path) and the repair removed or renamed it; every member it carried went with it — declare those members again under a name the gate accepts, via ggui_render override or a corrected re-handshake`
+        : runner.prefix === 'actionSpec'
+          ? `the repair no longer carries the action '${name}' you declared (renamed or removed); every member it carried, oneShot included, went with it — re-declare it via ggui_render override or a corrected re-handshake`
+          : `the repair no longer carries the ${runner.noun} '${name}' you declared under that key (renamed, moved or removed); every member it carried went with it — re-declare it via ggui_render override or a corrected re-handshake`;
+      return { code: REPAIR_ENTRY_DROPPED, severity: 'error', path, message };
+    }),
+  );
+}

package/src/rerank-eval/run-probe.ts

@@ -190,7 +190,7 @@ export function formatReport(report: ProbeReport): string {
       lines.push(
         `  [${o.pair.kind}] ${o.pair.id}: predicted=${o.predictedMatchId ?? 'null'}, gold=${o.pair.goldMatchId ?? 'null'}, conf=${o.decision.confidence.toFixed(2)}`,
       );
-      lines.push(`    reason: ${o.decision.reason}`);
+      lines.push(`    reason: ${o.decision.reason ?? '(none)'}`);
     }
   }
 

package/src/synthesize-contract.ts

@@ -44,9 +44,10 @@ import {
   type GadgetDescriptor,
   type JsonSchema,
 } from '@ggui-ai/protocol';
-import { lintContract, type ContractIssue } from '@ggui-ai/protocol';
+import { lintContract, type ContractIssue, type SuggestionFinding } from '@ggui-ai/protocol';
 import type { LLMCaller, ToolSchema } from './llm-caller.js';
 import { normalizeSchema } from './normalize-schema.js';
+import { findDroppedEntries, isOnSurvivingEntry, REPAIR_ENTRY_DROPPED, restoreDraftDeclaredMembers } from './preserve-declared-members.js';
 import {
   draftSeedPropKeys,
   findDroppedSeedSurfaces,
@@ -102,6 +103,16 @@ export interface SynthesizeContractResult {
    * findings without re-running the detector.
    */
   readonly findings: readonly ContractValidationFinding[];
+  /**
+   * What a repair-in-place could NOT keep of the agent's draft
+   * (ggui#1421): one `REPAIR_MEMBER_DROPPED` per declared action-entry
+   * member the merged contract cannot carry, one `REPAIR_ENTRY_DROPPED`
+   * per draft action the contract no longer carries under its name.
+   * Empty on the cold path (no draft) and whenever every declaration
+   * survived. The caller surfaces these to the agent beside the gate's
+   * own findings, so a drop is never silent.
+   */
+  readonly dropped: readonly SuggestionFinding[];
 }
 
 /**
@@ -200,7 +211,7 @@ CONCRETE PATTERNS
     (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_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"} }
+        actionSpec:  { toggleTodo: {label: "Toggle todo", schema: {type: "object", properties: {id: {type: "string"}}, required: ["id"]}}, addTodo: {label: "Add todo", schema: {type: "object", properties: {text: {type: "string"}}, required: ["text"]}} }
 
     (b) User-built local — "a todo list where I can add and remove items", "a shopping list", "a checklist I tick off"
         No agent-owned source: the USER assembles the list in the UI and the agent merely observes it. The items are client-originated state → a CONTEXTSPEC slot; OMIT actionSpec (the slot mirror IS the wire — the agent already sees every change). Only when the intent says the agent must persist / sync each change does it become the agent-owned case (a) above.
@@ -565,6 +576,7 @@ const REPAIR_PREAMBLE = `PATCH MODE — you are REPAIRING a contract the agent a
 - PRESERVE every spec the agent declared — ESPECIALLY every propsSpec property (agent-owned render-time seed data the UI needs). Never drop it.
 - Do NOT move data between specs (e.g. propsSpec → contextSpec) unless a finding explicitly requires it. A collection the agent supplies on propsSpec STAYS on propsSpec.
 - Keep the agent's names, shapes, and structure intact wherever the findings do not force a change.
+- KEEP the agent's TOOLBOX: every agentCapabilities.tools entry the draft declares, and every actionSpec[X].nextStep that names one of them. The rules below about tools (declare them only behind a streamSpec source; emit no nextStep) govern only what YOU synthesize from scratch — they never remove a tool or a nextStep the agent declared.
 The four-spec model and placement rules below still hold — but in PATCH MODE they are guardrails for the fix, not a license to re-author.`;
 
 /**
@@ -837,6 +849,7 @@ export async function synthesizeContract(
       latencyMs: Date.now() - startedAt,
       attempts: 0,
       findings: [],
+      dropped: [],
     };
   }
 
@@ -878,6 +891,10 @@ export async function synthesizeContract(
   const draftSeedKeys =
     options?.draft !== undefined ? draftSeedPropKeys(options.draft) : [];
   let lastValidContract: DataContract | null = null;
+  /** The paths the draft's own findings name — members under repair are not restored. */
+  const underRepair: ReadonlySet<string> = new Set((options?.draftFindings ?? []).map((f) => f.path));
+  /** The member drops of the attempt that produced `lastValidContract`. */
+  let lastValidDropped: readonly SuggestionFinding[] = [];
 
   for (let attempt = 1; attempt <= MAX_SYNTH_ATTEMPTS; attempt++) {
     const userPrompt =
@@ -916,8 +933,14 @@ export async function synthesizeContract(
     }
 
     // `buildContract` normalizes every emitted schema (invalid `type`
-    // spellings → canonical JSON Schema) before the gate sees it.
-    const contract = buildContract(parsed);
+    // spellings → canonical JSON Schema) before the gate sees it. On a
+    // repair-in-place it authors only a few members per entry; the agent's
+    // DECLARED members (`oneShot` above all) are put back from the draft
+    // deterministically, on every spec, and so is any tool the repair
+    // dropped. Anything the merged tree cannot carry is named rather than
+    // lost (ggui#1421, ggui#1430).
+    const restored = restoreDraftDeclaredMembers(options?.draft, buildContract(parsed), underRepair);
+    const contract = restored.contract;
 
     // Defensive gate: re-validate the assembled contract against the
     // canonical schema. Catches LLM outputs that pass the loose tool
@@ -991,6 +1014,7 @@ export async function synthesizeContract(
         // Remember the best VALID candidate so an exhausted budget never
         // returns WORSE than the validity-only gate did (a valid contract).
         lastValidContract = validatedContract;
+        lastValidDropped = restored.dropped;
         lastReason = `synthesize-preservation: candidate dropped agent-owned propsSpec seed surface(s) [${dropped.join(', ')}]`;
         lastFindings = allFindings;
         repairNote = buildPreservationRepairNote(validatedContract, dropped);
@@ -1011,6 +1035,7 @@ export async function synthesizeContract(
       latencyMs: Date.now() - startedAt,
       attempts: attempt,
       findings: allFindings,
+      dropped: droppedFor(restored.dropped, options?.draft, validatedContract, underRepair),
     };
   }
 
@@ -1027,9 +1052,34 @@ export async function synthesizeContract(
     latencyMs: Date.now() - startedAt,
     attempts: MAX_SYNTH_ATTEMPTS,
     findings: lastFindings,
+    dropped: lastValidContract !== null ? droppedFor(lastValidDropped, options?.draft, lastValidContract, underRepair) : [],
   };
 }
 
+/**
+ * What a repair could not keep, or put back, against the contract it finally
+ * returns: the accepted attempt's member drops and restored tools, minus
+ * those on an entry the final contract no longer carries (the entry finding
+ * names that loss once), plus one entry finding per draft entry, on every
+ * spec, that the final contract no longer carries under its key. Where the
+ * overlay itself named an entry it had to un-restore, its finding (which
+ * carries the gate's reason) stands for that entry.
+ */
+function droppedFor(
+  overlayFindings: readonly SuggestionFinding[],
+  draft: unknown,
+  finalContract: DataContract,
+  underRepair: ReadonlySet<string>,
+): readonly SuggestionFinding[] {
+  const overlayEntryDrops = new Map(
+    overlayFindings.filter((f) => f.code === REPAIR_ENTRY_DROPPED).map((f) => [f.path, f] as const),
+  );
+  return [
+    ...overlayFindings.filter((f) => f.code !== REPAIR_ENTRY_DROPPED && isOnSurvivingEntry(f, finalContract)),
+    ...findDroppedEntries(draft, finalContract, underRepair).map((f) => overlayEntryDrops.get(f.path) ?? f),
+  ];
+}
+
 function parseToolInput(raw: unknown): SynthesizeToolInput | null {
   if (typeof raw !== 'object' || raw === null) return null;
   const obj = raw as Record<string, unknown>;