@ggui-ai/negotiator 0.24.0 → 0.26.0

package/dist/preserve-declared-members.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 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 { type DataContract, type SuggestionFinding } from '@ggui-ai/protocol';
+/** A declared member the repair could not keep; path `<spec>.<name>.<member>`. */
+export declare const REPAIR_MEMBER_DROPPED: "REPAIR_MEMBER_DROPPED";
+/** A draft entry the proposal no longer carries under its key; path `<spec>.<name>`. */
+export declare const REPAIR_ENTRY_DROPPED: "REPAIR_ENTRY_DROPPED";
+/** A draft tool the repair dropped and the overlay restored; path `agentCapabilities.tools.<name>`. */
+export declare const REPAIR_ENTRY_RESTORED: "REPAIR_ENTRY_RESTORED";
+/**
+ * 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 declare function restoreDraftDeclaredMembers(draft: unknown, candidate: DataContract, underRepair: ReadonlySet<string>): {
+    readonly contract: DataContract;
+    readonly dropped: readonly SuggestionFinding[];
+};
+/**
+ * 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 declare function isOnSurvivingEntry(finding: SuggestionFinding, contract: DataContract): boolean;
+/**
+ * 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 declare function findDroppedEntries(draft: unknown, candidate: DataContract, underRepair: ReadonlySet<string>): readonly SuggestionFinding[];
+//# sourceMappingURL=preserve-declared-members.d.ts.map

package/dist/preserve-declared-members.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preserve-declared-members.d.ts","sourceRoot":"","sources":["../src/preserve-declared-members.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,EAWL,KAAK,YAAY,EAGjB,KAAK,iBAAiB,EACvB,MAAM,mBAAmB,CAAC;AAE3B,kFAAkF;AAClF,eAAO,MAAM,qBAAqB,EAAG,uBAAgC,CAAC;AACtE,wFAAwF;AACxF,eAAO,MAAM,oBAAoB,EAAG,sBAA+B,CAAC;AACpE,uGAAuG;AACvG,eAAO,MAAM,qBAAqB,EAAG,uBAAgC,CAAC;AA4VtE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,YAAY,EACvB,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,GAC/B;IAAE,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAA;CAAE,CA+CrF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,YAAY,GAAG,OAAO,CAE9F;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,YAAY,EACvB,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,GAC/B,SAAS,iBAAiB,EAAE,CAa9B"}

package/dist/preserve-declared-members.js

@@ -0,0 +1,427 @@
+/**
+ * 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, } from '@ggui-ai/protocol';
+/** A declared member the repair could not keep; path `<spec>.<name>.<member>`. */
+export const REPAIR_MEMBER_DROPPED = 'REPAIR_MEMBER_DROPPED';
+/** A draft entry the proposal no longer carries under its key; path `<spec>.<name>`. */
+export const REPAIR_ENTRY_DROPPED = 'REPAIR_ENTRY_DROPPED';
+/** A draft tool the repair dropped and the overlay restored; path `agentCapabilities.tools.<name>`. */
+export const REPAIR_ENTRY_RESTORED = 'REPAIR_ENTRY_RESTORED';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function recordAt(value, key) {
+    if (value === undefined)
+        return undefined;
+    const at = value[key];
+    return isRecord(at) ? at : undefined;
+}
+function memberDropped(prefix, name, member, reason) {
+    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) {
+    return `refused by the gate as ${issue.code} at ${issue.path}: ${issue.message}`;
+}
+function specRunner(d) {
+    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) => `${d.prefix}.${name}`;
+    /** `entry` without the member at `member` (`a` or `parent.a`), re-derived by the strict schema. */
+    const withoutMember = (entry, member) => {
+        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 = { ...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, name) => {
+        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, underRepair) => {
+        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, b) => a.code === b.code && a.path === b.path;
+    return {
+        prefix: d.prefix,
+        noun: d.noun,
+        overlay(draft, contract, underRepair) {
+            const state = { members: new Map(), entries: new Set() };
+            const dropped = [];
+            const draftEntries = d.draftEntries(draft);
+            if (draftEntries === undefined)
+                return { contract, state, dropped };
+            const current = d.entries(contract) ?? {};
+            const merged = { ...current };
+            for (const [name, entry] of Object.entries(current)) {
+                const draftEntry = recordAt(draftEntries, name);
+                if (draftEntry === undefined)
+                    continue;
+                const next = { ...d.asRecord(entry) };
+                const put = new Set();
+                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 = { ...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 = [];
+            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) => ({
+                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 = [
+    specRunner({
+        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({
+        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({
+        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({
+        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({
+        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, candidate, underRepair) {
+    if (!isRecord(draft))
+        return { contract: candidate, dropped: [] };
+    let contract = candidate;
+    const dropped = [];
+    const states = [];
+    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 = () => 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, contract) {
+    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, candidate, underRepair) {
+    if (!isRecord(draft))
+        return [];
+    return RUNNERS.flatMap((runner) => runner.droppedKeys(draft, candidate).map((name) => {
+        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/dist/rerank-eval/run-probe.js

@@ -106,7 +106,7 @@ export function formatReport(report) {
         lines.push('Failed predictions:');
         for (const o of failed) {
             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)'}`);
         }
     }
     return lines.join('\n');

package/dist/synthesize-contract.d.ts

@@ -37,6 +37,7 @@
  * contract-aware agents skip synthesis entirely.
  */
 import { type DataContract, type GadgetDescriptor } from '@ggui-ai/protocol';
+import { type SuggestionFinding } from '@ggui-ai/protocol';
 import type { LLMCaller, ToolSchema } from './llm-caller.js';
 import { type ContractValidationFinding } from './contract-validators.js';
 /** Result of one synthesis attempt. */
@@ -62,6 +63,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[];
 }
 /**
  * Tool schema the synthesizer's structured-output call uses. The

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

@@ -1 +1 @@
-{"version":3,"file":"synthesize-contract.d.ts","sourceRoot":"","sources":["../src/synthesize-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAEtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAM7D,OAAO,EAKL,KAAK,yBAAyB,EAC/B,MAAM,0BAA0B,CAAC;AAsBlC,uCAAuC;AACvC,MAAM,WAAW,wBAAwB;IACvC,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IACvC,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,yBAAyB,EAAE,CAAC;CACzD;AAuOD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,UA+I7B,CAAC;AAwRF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAA;CAAE,EACjC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;IACR;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAClD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS;QAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,EAAE,CAAC;CACL,GACA,OAAO,CAAC,wBAAwB,CAAC,CAyMnC;AAmUD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,SAAS,gBAAgB,EAAE,GAAG,SAAS,GAC/C,MAAM,GAAG,SAAS,CA+CpB"}
+{"version":3,"file":"synthesize-contract.d.ts","sourceRoot":"","sources":["../src/synthesize-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAEtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAoC,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC7F,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAO7D,OAAO,EAKL,KAAK,yBAAyB,EAC/B,MAAM,0BAA0B,CAAC;AAsBlC,uCAAuC;AACvC,MAAM,WAAW,wBAAwB;IACvC,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IACvC,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,yBAAyB,EAAE,CAAC;IACxD;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAChD;AAuOD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,UA+I7B,CAAC;AAyRF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAA;CAAE,EACjC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;IACR;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAClD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS;QAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,EAAE,CAAC;CACL,GACA,OAAO,CAAC,wBAAwB,CAAC,CAuNnC;AA2VD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,SAAS,gBAAgB,EAAE,GAAG,SAAS,GAC/C,MAAM,GAAG,SAAS,CA+CpB"}