@danceiny/gotry 0.0.1-rc.19 → 0.0.1-rc.21

package/dist/scripts/benchmark-environment-bridge-tests.js

@@ -4,9 +4,9 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { Context } from '@deepseek-ai/cordis';
 import { apply } from '../src/index.js';
-import { registerBenchmarkEnvironmentBridge } from '../src/benchmark-environment-bridge.js';
+import { BRIDGE_ERROR_CONTRACT, BENCHMARK_TOOL_RESULT_SCHEMA_VERSION, registerBenchmarkEnvironmentBridge } from '../src/benchmark-environment-bridge.js';
 import { installBenchmarkToolIsolation } from '../src/benchmark-tool-isolation.js';
-import { BENCHMARK_BRIDGE_CALL_FAILED, BENCHMARK_BRIDGE_CALL_REQUIRED, BENCHMARK_BRIDGE_RETRY_CALL_NOT_ALLOWED, BENCHMARK_BRIDGE_OUTPUT_TRUNCATED, BENCHMARK_BRIDGE_RUNNER_FAILED, BENCHMARK_BRIDGE_SPAWN_FAILED, BENCHMARK_BRIDGE_TIMED_OUT, BENCHMARK_CONFORMANCE_STATE_UNAVAILABLE, BENCHMARK_TERMINAL_INVALID, MAX_CONFORMANCE_RETRIES, benchmarkChildFailureForConformanceCode, createBenchmarkAgentConformance, installBenchmarkAgentConformance, parseBenchmarkTerminal, validateTerminalOutputConfig } from '../src/benchmark-agent-conformance.js';
+import { BENCHMARK_BRIDGE_CALL_FAILED, BENCHMARK_BRIDGE_CALL_REQUIRED, BENCHMARK_BRIDGE_RETRY_CALL_NOT_ALLOWED, BENCHMARK_BRIDGE_OUTPUT_TRUNCATED, BENCHMARK_BRIDGE_RUNNER_FAILED, BENCHMARK_BRIDGE_SPAWN_FAILED, BENCHMARK_BRIDGE_TIMED_OUT, BENCHMARK_CONFORMANCE_STATE_UNAVAILABLE, BENCHMARK_TERMINAL_INVALID, MAX_CONFORMANCE_RETRIES, benchmarkChildFailureForConformanceCode, createBenchmarkAgentConformance, installBenchmarkAgentConformance, parseBenchmarkTerminal, terminalSchemaOutline, validateTerminalBodySchema, validateTerminalBodyValue, validateTerminalOutputConfig } from '../src/benchmark-agent-conformance.js';
 import { BENCHMARK_CHILD_DIAGNOSTIC_MAX_BYTES, BENCHMARK_CHILD_DIAGNOSTIC_SCHEMA, appendBoundedChildDiagnostic, classifyBenchmarkChildFailure, classifyBenchmarkTurnEnd, createBenchmarkDiagnosticArbiter, parseBenchmarkChildDiagnostic } from '../src/benchmark-headless-child-diagnostics.js';
 {
     const exactFamilies = [
@@ -262,6 +262,22 @@ import { BENCHMARK_CHILD_DIAGNOSTIC_MAX_BYTES, BENCHMARK_CHILD_DIAGNOSTIC_SCHEMA
         'child_model_server'
     ]);
 }assert.equal(MAX_CONFORMANCE_RETRIES, 1);
+const OK_BODY_SCHEMA = {
+    type: 'object',
+    properties: {
+        ok: {
+            type: 'boolean'
+        },
+        status: {
+            type: 'string'
+        },
+        x: {
+            type: 'string'
+        }
+    },
+    required: [],
+    additionalProperties: false
+};
 const projection = {
     toolName: 'gotry_benchmark_environment',
     allowedTools: [
@@ -269,7 +285,8 @@ const projection = {
     ],
     terminal: {
         tag: 'done',
-        max_bytes: 1024
+        max_bytes: 1024,
+        body_schema: OK_BODY_SCHEMA
     }
 };
 assert.equal(validateTerminalOutputConfig(projection.terminal), true);
@@ -294,6 +311,20 @@ for (const invalid of [
         tag: 'done',
         max_bytes: 1024,
         extra: true
+    },
+    {
+        tag: 'done',
+        max_bytes: 1024
+    },
+    {
+        tag: 'done',
+        max_bytes: 1024,
+        body_schema: {
+            type: 'object',
+            properties: {},
+            required: [],
+            additionalProperties: true
+        }
     }
 ])assert.equal(validateTerminalOutputConfig(invalid), false);
 assert.deepEqual(parseBenchmarkTerminal(' \n<done>{"ok":true}</done>\n', projection.terminal), {
@@ -338,7 +369,284 @@ for (const [raw, expectOk] of [
 ]){
     assert.equal(parseBenchmarkTerminal(raw, projection.terminal).ok, expectOk, raw);
 }
-function turnStart(turn = 1) {
+{
+    const travelSchema = {
+        type: 'object',
+        properties: {
+            people_number: {
+                type: 'integer'
+            },
+            start_city: {
+                type: 'string'
+            },
+            target_city: {
+                type: 'string'
+            },
+            itinerary: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        day: {
+                            type: 'integer'
+                        },
+                        activities: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    type: {
+                                        type: 'string'
+                                    },
+                                    start_time: {
+                                        type: 'string'
+                                    },
+                                    cost: {
+                                        type: 'number'
+                                    },
+                                    transports: {
+                                        type: 'array',
+                                        items: {
+                                            type: 'object',
+                                            properties: {
+                                                start: {
+                                                    type: 'string'
+                                                },
+                                                mode: {
+                                                    type: 'string'
+                                                }
+                                            },
+                                            required: [
+                                                'start',
+                                                'mode'
+                                            ],
+                                            additionalProperties: false
+                                        }
+                                    }
+                                },
+                                required: [
+                                    'type',
+                                    'start_time',
+                                    'cost',
+                                    'transports'
+                                ],
+                                additionalProperties: false
+                            }
+                        }
+                    },
+                    required: [
+                        'day',
+                        'activities'
+                    ],
+                    additionalProperties: false
+                }
+            }
+        },
+        required: [
+            'people_number',
+            'start_city',
+            'target_city',
+            'itinerary'
+        ],
+        additionalProperties: false
+    };
+    const travelConfig = {
+        tag: 'done',
+        max_bytes: 65_536,
+        body_schema: travelSchema
+    };
+    assert.equal(validateTerminalOutputConfig(travelConfig), true, 'ChinaTravel-like closed schema is a valid terminal config');
+    const legalBody = {
+        people_number: 2,
+        start_city: 'Dubai',
+        target_city: 'Chengdu',
+        itinerary: [
+            {
+                day: 1,
+                activities: [
+                    {
+                        type: 'attraction',
+                        start_time: '09:00',
+                        cost: 0,
+                        transports: [
+                            {
+                                start: 'hotel',
+                                mode: 'walk'
+                            }
+                        ]
+                    }
+                ]
+            }
+        ]
+    };
+    assert.equal(validateTerminalBodySchema(travelSchema), true);
+    const mutate = (fn)=>{
+        const copy = JSON.parse(JSON.stringify(travelSchema));
+        fn(copy);
+        return copy;
+    };
+    for (const [label, schema] of [
+        [
+            'extra root key',
+            mutate((s)=>{
+                s.description = 'the plan';
+            })
+        ],
+        [
+            'enum on scalar',
+            mutate((s)=>{
+                s.properties.people_number.enum = [
+                    2
+                ];
+            })
+        ],
+        [
+            'const on scalar',
+            mutate((s)=>{
+                s.properties.start_city.const = 'Dubai';
+            })
+        ],
+        [
+            'default on scalar',
+            mutate((s)=>{
+                s.properties.target_city.default = 'Chengdu';
+            })
+        ],
+        [
+            'examples key',
+            mutate((s)=>{
+                s.properties.itinerary.examples = [];
+            })
+        ],
+        [
+            'pattern on scalar',
+            mutate((s)=>{
+                s.properties.start_city.pattern = '^[A-Z]';
+            })
+        ],
+        [
+            'open object',
+            mutate((s)=>{
+                s.additionalProperties = true;
+            })
+        ],
+        [
+            'missing additionalProperties',
+            mutate((s)=>{
+                delete s.additionalProperties;
+            })
+        ],
+        [
+            'array without items',
+            mutate((s)=>{
+                s.properties.itinerary = {
+                    type: 'array'
+                };
+            })
+        ],
+        [
+            'object without required',
+            mutate((s)=>{
+                delete s.required;
+            })
+        ],
+        [
+            'unknown type',
+            mutate((s)=>{
+                s.properties.people_number.type = 'float';
+            })
+        ],
+        [
+            'allOf composition',
+            mutate((s)=>{
+                s.allOf = [];
+            })
+        ]
+    ]){
+        assert.equal(validateTerminalBodySchema(schema), false, `schema dialect rejects: ${label}`);
+    }
+    assert.equal(validateTerminalBodyValue(legalBody, travelSchema), true, 'legal ChinaTravel-like hierarchy passes');
+    assert.equal(parseBenchmarkTerminal(`<done>${JSON.stringify(legalBody)}</done>`, travelConfig).ok, true, 'legal body parses through the terminal gate');
+    for (const [label, body] of [
+        [
+            'extra root key (Round 11 budget/total_cost case)',
+            {
+                ...legalBody,
+                budget: {
+                    total_cost: 1
+                }
+            }
+        ],
+        [
+            'itinerary item written as direct activity (missing day)',
+            {
+                ...legalBody,
+                itinerary: [
+                    {
+                        type: 'attraction',
+                        start_time: '09:00',
+                        cost: 0,
+                        transports: []
+                    }
+                ]
+            }
+        ],
+        [
+            'missing activities array',
+            {
+                ...legalBody,
+                itinerary: [
+                    {
+                        day: 1
+                    }
+                ]
+            }
+        ],
+        [
+            'wrong type (string day)',
+            {
+                ...legalBody,
+                itinerary: [
+                    {
+                        day: '1',
+                        activities: []
+                    }
+                ]
+            }
+        ],
+        [
+            'nested extra field',
+            {
+                ...legalBody,
+                itinerary: [
+                    {
+                        day: 1,
+                        activities: [
+                            {
+                                type: 'attraction',
+                                start_time: '09:00',
+                                cost: 0,
+                                transports: [],
+                                unexpected: 1
+                            }
+                        ]
+                    }
+                ]
+            }
+        ]
+    ]){
+        assert.equal(validateTerminalBodyValue(body, travelSchema), false, `value validation rejects: ${label}`);
+        assert.equal(parseBenchmarkTerminal(`<done>${JSON.stringify(body)}</done>`, travelConfig).ok, false, `terminal gate rejects: ${label}`);
+    }
+    assert.equal(parseBenchmarkTerminal(`<done>${' '.repeat(2000)}${JSON.stringify({
+        ok: true
+    })}</done>`, projection.terminal).ok, false, 'schema-valid body over max_bytes still rejects');
+    const outline = terminalSchemaOutline(travelSchema);
+    assert.equal(outline, terminalSchemaOutline(JSON.parse(JSON.stringify(travelSchema))), 'outline is deterministic');
+    assert.equal(outline, 'object{people_number:integer,start_city:string,target_city:string,itinerary:array<object{day:integer,activities:array<object{type:string,start_time:string,cost:number,transports:array<object{start:string,mode:string}>}>}>}', 'outline renders the exact structural contract');
+    assert.match(outline, /object\{/, 'outline renders object nodes');
+    assert.ok(!outline.includes('optional') && !outline.includes('?'), 'all keys required render without optional markers');
+}function turnStart(turn = 1) {
     return {
         type: 'turn/start',
         data: {
@@ -375,7 +683,7 @@ function toolCall(callId = 'call-1', options = {}) {
     };
 }
 function toolResult(callId = 'call-1', options = {}) {
-    const { turn = 1, step = 1, ok = true, isError = false, error = 'runner_failed' } = options;
+    const { turn = 1, step = 1, ok = true, isError = false, error = 'runner_failed', outcome, payload } = options;
     return {
         type: 'tool/result',
         data: {
@@ -394,13 +702,16 @@ function toolResult(callId = 'call-1', options = {}) {
                         content: [
                             {
                                 type: 'text',
-                                text: JSON.stringify(ok ? {
+                                text: JSON.stringify(payload ?? (outcome ? {
+                                    ok: true,
+                                    outcome
+                                } : ok ? {
                                     ok: true,
                                     result: {}
                                 } : {
                                     ok: false,
                                     error
-                                })
+                                }))
                             }
                         ]
                     }
@@ -409,7 +720,107 @@ function toolResult(callId = 'call-1', options = {}) {
         }
     };
 }
-function assistant(text, options = {}) {
+{
+    const state = createBenchmarkAgentConformance(projection);
+    state.observe(turnStart());
+    state.observe(toolCall());
+    state.observe(toolResult('call-1', {
+        outcome: {
+            schema_version: 'gotry_benchmark_tool_result_v1',
+            status: 'miss',
+            code: 'NOT_FOUND',
+            recovery: 'revise_arguments'
+        }
+    }));
+    assert.deepEqual(state.stopping(1), {
+        kind: 'steer',
+        mode: 'terminal'
+    }, 'domain outcome alone permits tagged terminal');
+    state.observe(assistant('<done>{"status":"miss"}</done>', {
+        step: 2
+    }));
+    assert.deepEqual(state.stopping(1), {
+        kind: 'accept'
+    }, 'domain-only tagged terminal is accepted');
+}{
+    const state = createBenchmarkAgentConformance(projection);
+    state.observe(turnStart());
+    state.observe(toolCall());
+    state.observe(toolResult('call-1', {
+        outcome: {
+            schema_version: 'gotry_benchmark_tool_result_v1',
+            status: 'miss',
+            code: 'NOT_FOUND',
+            recovery: 'revise_arguments'
+        }
+    }));
+    state.observe(toolCall('call-2', {
+        step: 2
+    }));
+    state.observe(toolResult('call-2'));
+    state.observe(assistant('<done>{"status":"succeeded"}</done>', {
+        step: 3
+    }));
+    assert.deepEqual(state.stopping(1), {
+        kind: 'accept'
+    }, 'domain outcome followed by concrete result accepts');
+}{
+    const state = createBenchmarkAgentConformance(projection);
+    state.observe(turnStart());
+    state.observe(toolCall());
+    state.observe(toolResult('call-1', {
+        outcome: {
+            schema_version: 'gotry_benchmark_tool_result_v1',
+            status: 'miss',
+            code: 'NOT_FOUND',
+            recovery: 'revise_arguments'
+        }
+    }));
+    state.observe(toolCall('call-2', {
+        step: 2
+    }));
+    state.observe(toolResult('call-2', {
+        ok: false,
+        error: 'runner_failed'
+    }));
+    assert.deepEqual(state.stopping(1), {
+        kind: 'reject',
+        code: BENCHMARK_BRIDGE_RUNNER_FAILED
+    }, 'infra failure overrides domain-only outcome');
+}{
+    const state = createBenchmarkAgentConformance(projection);
+    state.observe(turnStart());
+    state.observe(toolCall());
+    state.observe(toolResult('call-1', {
+        payload: {
+            ok: true,
+            result: {},
+            outcome: {
+                status: 'miss'
+            }
+        }
+    }));
+    state.observe(assistant('<done>{"status":"succeeded"}</done>'));
+    assert.deepEqual(state.stopping(1), {
+        kind: 'reject',
+        code: BENCHMARK_BRIDGE_CALL_FAILED
+    }, 'ambiguous ok wrapper with result and outcome fails closed');
+}{
+    const state = createBenchmarkAgentConformance(projection);
+    state.observe(turnStart());
+    state.observe(toolCall());
+    state.observe(toolResult('call-1', {
+        payload: {
+            ok: true,
+            outcome: {}
+        }
+    }));
+    state.observe(assistant('<done>{"status":"miss"}</done>'));
+    assert.deepEqual(state.stopping(1), {
+        kind: 'reject',
+        code: BENCHMARK_BRIDGE_CALL_FAILED
+    }, 'malformed inner domain outcome fails closed');
+}function assistant(text, options = {}) {
     const { turn = 1, step = 2, interrupted = false } = options;
     return {
         type: 'assistant/message',
@@ -588,6 +999,69 @@ function assistant(text, options = {}) {
     assert.deepEqual(state.stopping(1), {
         kind: 'accept'
     }, 'a later failed optional call does not erase an already paired successful result');
+}{
+    const state = createBenchmarkAgentConformance(projection);
+    state.observe(turnStart());
+    state.observe(toolCall('successful', {
+        step: 1
+    }));
+    state.observe(toolResult('successful', {
+        step: 1
+    }));
+    state.observe(assistant('<done>{"status":"succeeded"}</done>', {
+        step: 2
+    }));
+    state.observe(toolCall('domain', {
+        step: 3
+    }));
+    state.observe(toolResult('domain', {
+        step: 3,
+        outcome: {
+            schema_version: 'gotry_benchmark_tool_result_v1',
+            status: 'miss',
+            code: 'NOT_FOUND',
+            recovery: 'revise_arguments'
+        }
+    }));
+    assert.deepEqual(state.stopping(1), {
+        kind: 'steer',
+        mode: 'terminal'
+    }, 'a terminal before the latest domain response is stale');
+    state.observe(assistant('<done>{"status":"succeeded"}</done>', {
+        step: 4
+    }));
+    assert.deepEqual(state.stopping(1), {
+        kind: 'accept'
+    }, 'a fresh terminal after the latest domain response may reuse the earlier concrete result');
+}{
+    const state = createBenchmarkAgentConformance(projection);
+    state.observe(turnStart());
+    state.observe(toolCall('successful', {
+        step: 1
+    }));
+    state.observe(toolResult('successful', {
+        step: 1
+    }));
+    state.observe(assistant('<done>{"status":"succeeded"}</done>', {
+        step: 2
+    }));
+    state.observe(toolCall('failed', {
+        step: 3
+    }));
+    state.observe(toolResult('failed', {
+        step: 3,
+        ok: false
+    }));
+    assert.deepEqual(state.stopping(1), {
+        kind: 'steer',
+        mode: 'terminal'
+    }, 'a terminal before a later optional failure is stale');
+    state.observe(assistant('<done>{"status":"succeeded"}</done>', {
+        step: 4
+    }));
+    assert.deepEqual(state.stopping(1), {
+        kind: 'accept'
+    }, 'a fresh terminal may still converge after an optional failure when a concrete result exists');
 }{
     const state = createBenchmarkAgentConformance(projection);
     state.observe(turnStart());
@@ -708,6 +1182,8 @@ function assistant(text, options = {}) {
     assert.match(assembled.sections[0].text, /\"action\":\"call\"/);
     assert.match(assembled.sections[0].text, /<done>/);
     assert.equal(assembled.sections[0].text.includes('/tmp/'), false);
+    const round12Outline = terminalSchemaOutline(OK_BODY_SCHEMA);
+    assert.ok(assembled.sections[0].text.includes(`matching exactly ${round12Outline}`), 'system section projects the terminal body schema outline');
     rootListeners.get('session/event')[0](session, turnEnd());
     assert.deepEqual(runtimeWrites, []);
     rootListeners.get('session/event')[0](session, turnStart(2));
@@ -838,16 +1314,77 @@ function assistant(text, options = {}) {
         waitForExit: async ()=>true
     };
 }
+function okEnvelope(result) {
+    return JSON.stringify({
+        schema_version: BENCHMARK_TOOL_RESULT_SCHEMA_VERSION,
+        status: 'ok',
+        result
+    });
+}
+function lookupInputSchema() {
+    return {
+        type: 'object',
+        properties: {
+            city: {
+                type: 'string',
+                enum: [
+                    'Dubai',
+                    'Abu Dhabi'
+                ],
+                description: 'Declared city name.'
+            },
+            payload: {
+                type: 'string'
+            },
+            notes: {
+                type: 'string'
+            },
+            executable: {
+                type: 'string'
+            },
+            cwd: {
+                type: 'string'
+            },
+            argv: {
+                type: 'array',
+                items: {
+                    type: 'string'
+                }
+            }
+        },
+        required: [
+            'city'
+        ],
+        additionalProperties: false
+    };
+}
+function bridgeCall(tool, argumentsValue) {
+    return {
+        action: 'call',
+        tool,
+        arguments: argumentsValue
+    };
+}
 async function assertRealCordisWaterfallOrdering() {
     const ctx = new Context();
     const bridge = {
         name: 'gotry_benchmark_environment',
         description: 'benchmark bridge',
         parameters: {
-            query: {
-                type: 'json',
-                required: true
-            }
+            oneOf: [
+                {
+                    type: 'object',
+                    properties: {
+                        action: {
+                            const: 'tools'
+                        }
+                    },
+                    required: [
+                        'action'
+                    ],
+                    additionalProperties: false
+                }
+            ]
         }
     };
     const exactSchema = structuredClone(bridge);
@@ -979,7 +1516,7 @@ try {
     assert.equal(parseBenchmarkChildDiagnostic(boundedControl.toString('utf8')), 'child_bridge_timed_out', 'rolling tail preserves a final structured reason after bounded noise');
     const configPath = join(root, 'bridge.json');
     writeFileSync(configPath, JSON.stringify({
-        schema_version: 'gotry_benchmark_environment_bridge_v2',
+        schema_version: 'gotry_benchmark_environment_bridge_v4',
         enabled: true,
         executable: process.execPath,
         cwd: root,
@@ -989,25 +1526,60 @@ try {
             '--lang',
             'en'
         ],
-        allowed_tools: [
-            'lookup',
-            'constructor',
-            'toString'
+        tools: [
+            {
+                name: 'lookup',
+                description: 'Lookup one declared city.',
+                input_schema: lookupInputSchema(),
+                output_keys: [
+                    'city',
+                    'nested'
+                ],
+                domain_outcomes: [
+                    {
+                        status: 'miss',
+                        code: 'NOT_FOUND',
+                        recovery: 'revise_arguments'
+                    },
+                    {
+                        status: 'error',
+                        code: 'AMBIGUOUS',
+                        recovery: 'choose_alternative'
+                    }
+                ]
+            },
+            {
+                name: 'constructor',
+                description: 'Construct one declared city.',
+                input_schema: lookupInputSchema(),
+                output_keys: [
+                    'legacy'
+                ],
+                domain_outcomes: [
+                    {
+                        status: 'error',
+                        code: 'INVALID',
+                        recovery: 'retry_same'
+                    }
+                ]
+            },
+            {
+                name: 'toString',
+                description: 'Stringify one declared city.',
+                input_schema: lookupInputSchema(),
+                output_keys: [
+                    'city',
+                    'nested'
+                ],
+                domain_outcomes: []
+            }
         ],
-        allowed_output_keys: {
-            lookup: [
-                'city',
-                'nested'
-            ],
-            constructor: [
-                'legacy'
-            ]
-        },
         timeout_ms: 20,
         max_output_bytes: 4_096,
         terminal_output: {
             tag: 'done',
-            max_bytes: 4_096
+            max_bytes: 4_096,
+            body_schema: OK_BODY_SCHEMA
         },
         isolation: {
             mode: 'host-enforced',
@@ -1048,7 +1620,11 @@ try {
     let timeoutSignal;
     const outcomes = [
         {
-            stdout: '{"result":[{"city":"Dubai"}]}'
+            stdout: okEnvelope([
+                {
+                    city: 'Dubai'
+                }
+            ])
         }
     ];
     process.env.GOTRY_BENCHMARK_BRIDGE_PARENT_SENTINEL = 'must-not-cross-boundary';
@@ -1108,7 +1684,7 @@ try {
             spawn (spec) {
                 spawnSpecs.push(spec);
                 const outcome = outcomes.shift() ?? {
-                    stdout: '{"result":{}}'
+                    stdout: okEnvelope({})
                 };
                 if (outcome.spawnError) throw new Error('fake spawn failed');
                 if (outcome.waitForAbort) {
@@ -1625,15 +2201,95 @@ try {
     }, 'agent disposal releases its quarantined isolation and conformance effects');
     const bridge = registered.find((tool)=>tool.name === 'gotry_benchmark_environment');
     assert.ok(bridge.execute, 'registered bridge exposes execute');
+    const parameters = bridge.parameters;
+    assert.equal(parameters.type, 'object', 'flat bridge uses an object root for model-facing parameters');
+    assert.equal(parameters.oneOf, undefined, 'model-facing wire has no top-level oneOf');
+    assert.deepEqual(parameters.required, [
+        'action'
+    ], 'action is the only universally required wire field');
+    assert.equal(parameters.additionalProperties, false);
+    assert.deepEqual(parameters.properties?.action?.enum, [
+        'tools',
+        'call',
+        'errors'
+    ]);
+    assert.deepEqual(parameters.properties?.tool?.enum, [
+        'lookup',
+        'constructor',
+        'toString'
+    ], 'tool enum exposes frozen descriptor names');
+    assert.equal(parameters.properties?.arguments?.type, 'object', 'arguments remains a generic object on the open wire');
+    assert.equal(parameters.properties?.arguments?.additionalProperties, true);
+    assert.equal(Object.isFrozen(bridge.parameters), true, 'registered raw parameters are frozen');
+    assert.equal(Object.isFrozen(parameters.properties?.tool?.enum), true, 'descriptor-derived tool enum is frozen');
+    assert.throws(()=>{
+        parameters.properties?.tool?.enum.push('escape');
+    }, TypeError);
+    const beforeProtocolRejected = spawnSpecs.length;
+    await assert.rejects(()=>bridge.execute({
+            query: bridgeCall('lookup', {
+                city: 'Dubai'
+            })
+        }, null), /invalid arguments/, 'legacy nested query envelope is rejected by the flat protocol');
+    await assert.rejects(()=>bridge.execute({}, null), /invalid arguments/, 'empty object is rejected by the flat protocol');
+    await assert.rejects(()=>bridge.execute({
+            action: 'tools',
+            tool: 'lookup'
+        }, null), /invalid arguments/, 'mixed action/tool fields are rejected by the flat protocol');
+    await assert.rejects(()=>bridge.execute({
+            action: 'tools',
+            arguments: {}
+        }, null), /invalid arguments/, 'tools rejects mixed arguments');
+    await assert.rejects(()=>bridge.execute({
+            action: 'errors',
+            tool: 'lookup'
+        }, null), /invalid arguments/, 'errors rejects mixed tool fields');
+    await assert.rejects(()=>bridge.execute({
+            action: 'errors',
+            arguments: {}
+        }, null), /invalid arguments/, 'errors rejects mixed arguments');
+    await assert.rejects(()=>bridge.execute({
+            ...bridgeCall('lookup', {
+                city: 'Dubai'
+            }),
+            extra: true
+        }, null), /invalid arguments/, 'extra top-level fields are rejected by the flat protocol');
+    await assert.rejects(()=>bridge.execute({
+            action: 'call'
+        }, null), /invalid arguments/, 'call without tool or arguments is rejected');
+    await assert.rejects(()=>bridge.execute({
+            action: 'call',
+            tool: 'lookup'
+        }, null), /invalid arguments/, 'call without arguments is rejected');
+    await assert.rejects(()=>bridge.execute({
+            action: 'call',
+            arguments: {
+                city: 'Dubai'
+            }
+        }, null), /invalid arguments/, 'call without tool is rejected');
+    await assert.rejects(()=>bridge.execute(bridgeCall('lookup', {
+            city: 'Sharjah'
+        }), null), /invalid arguments/, 'invalid descriptor argument values are rejected by the flat protocol');
+    await assert.rejects(()=>bridge.execute({
+            action: 'call',
+            tool: 'lookup',
+            arguments: {}
+        }, null), /invalid arguments/, 'missing required descriptor arguments are rejected by the flat protocol');
+    for (const tool of [
+        'lookup',
+        'constructor',
+        'toString'
+    ]){
+        await assert.rejects(()=>bridge.execute(bridgeCall(tool, {
+                city: 'Sharjah'
+            }), null), /invalid arguments/, `${tool} rejects invalid descriptor arguments`);
+    }
+    assert.equal(spawnSpecs.length, beforeProtocolRejected, 'flat protocol rejections happen before spawn');
     const args = {
         city: 'Dubai',
         payload: '$(touch /tmp/nope)'
     };
-    const result = await bridge.execute({
-        action: 'call',
-        tool: 'lookup',
-        arguments: args
-    }, null);
+    const result = await bridge.execute(bridgeCall('lookup', args), null);
     assert.deepEqual(spawnSpecs[0]?.argv, [
         process.execPath,
         '-m',
@@ -1670,15 +2326,13 @@ try {
         ]
     }, 'one-line JSON stdout becomes structured result');
     outcomes.push({
-        stdout: '{"result":{"city":"Dubai"}}'
-    });
-    const unmappedResult = await bridge.execute({
-        action: 'call',
-        tool: 'toString',
-        arguments: {
+        stdout: okEnvelope({
             city: 'Dubai'
-        }
-    }, null);
+        })
+    });
+    const unmappedResult = await bridge.execute(bridgeCall('toString', {
+        city: 'Dubai'
+    }), null);
     assert.deepEqual(unmappedResult, {
         ok: true,
         result: {
@@ -1686,15 +2340,13 @@ try {
         }
     }, 'allowed tool without a positive mapping retains the recursive denylist only');
     outcomes.push({
-        stdout: '{"result":{"legacy":"value"}}'
+        stdout: okEnvelope({
+            legacy: 'value'
+        })
     });
-    const legacyResult = await bridge.execute({
-        action: 'call',
-        tool: 'constructor',
-        arguments: {
-            city: 'Dubai'
-        }
-    }, null);
+    const legacyResult = await bridge.execute(bridgeCall('constructor', {
+        city: 'Dubai'
+    }), null);
     assert.deepEqual(legacyResult, {
         ok: true,
         result: {
@@ -1702,29 +2354,27 @@ try {
         }
     }, 'mapped constructor accepts its declared positive key');
     outcomes.push({
-        stdout: '{"result":{"city":"Dubai"}}'
-    });
-    const constructorUnexpected = await bridge.execute({
-        action: 'call',
-        tool: 'constructor',
-        arguments: {
+        stdout: okEnvelope({
             city: 'Dubai'
-        }
-    }, null);
+        })
+    });
+    const constructorUnexpected = await bridge.execute(bridgeCall('constructor', {
+        city: 'Dubai'
+    }), null);
     assert.deepEqual(constructorUnexpected, {
         ok: false,
         error: 'forbidden_output'
     }, 'mapped constructor rejects undeclared positive keys');
     outcomes.push({
-        stdout: '{"result":{"nested":{"city":"Dubai"}}}'
+        stdout: okEnvelope({
+            nested: {
+                city: 'Dubai'
+            }
+        })
     });
-    const nestedAllowedResult = await bridge.execute({
-        action: 'call',
-        tool: 'lookup',
-        arguments: {
-            city: 'Dubai'
-        }
-    }, null);
+    const nestedAllowedResult = await bridge.execute(bridgeCall('lookup', {
+        city: 'Dubai'
+    }), null);
     assert.deepEqual(nestedAllowedResult, {
         ok: true,
         result: {
@@ -1734,29 +2384,31 @@ try {
         }
     }, 'configured positive output allowlist accepts declared nested keys');
     outcomes.push({
-        stdout: '{"result":{"city":"Dubai","unexpected":"secret"}}'
+        stdout: okEnvelope({
+            city: 'Dubai',
+            unexpected: 'secret'
+        })
     });
-    const unexpectedResult = await bridge.execute({
-        action: 'call',
-        tool: 'lookup',
-        arguments: {
-            city: 'Dubai'
-        }
-    }, null);
+    const unexpectedResult = await bridge.execute(bridgeCall('lookup', {
+        city: 'Dubai'
+    }), null);
     assert.deepEqual(unexpectedResult, {
         ok: false,
         error: 'forbidden_output'
     }, 'configured positive output allowlist rejects unexpected keys without reflecting them');
     outcomes.push({
-        stdout: '{"result":[{"city":"Dubai","nested":{"unexpected":"secret"}}]}'
+        stdout: okEnvelope([
+            {
+                city: 'Dubai',
+                nested: {
+                    unexpected: 'secret'
+                }
+            }
+        ])
     });
-    const nestedUnexpectedResult = await bridge.execute({
-        action: 'call',
-        tool: 'lookup',
-        arguments: {
-            city: 'Dubai'
-        }
-    }, null);
+    const nestedUnexpectedResult = await bridge.execute(bridgeCall('lookup', {
+        city: 'Dubai'
+    }), null);
     assert.deepEqual(nestedUnexpectedResult, {
         ok: false,
         error: 'forbidden_output'
@@ -1781,48 +2433,125 @@ try {
         'gоld'
     ]){
         outcomes.push({
-            stdout: JSON.stringify({
-                result: {
-                    nested: {
-                        [forbidden]: 'secret'
-                    }
+            stdout: okEnvelope({
+                nested: {
+                    [forbidden]: 'secret'
                 }
             })
         });
-        const forbiddenResult = await bridge.execute({
-            action: 'call',
-            tool: 'lookup',
-            arguments: {
-                city: 'Dubai'
-            }
-        }, null);
+        const forbiddenResult = await bridge.execute(bridgeCall('lookup', {
+            city: 'Dubai'
+        }), null);
         assert.deepEqual(forbiddenResult, {
             ok: false,
             error: 'forbidden_output'
         }, `recursive no-oracle key ${forbidden} is rejected without reflecting its name`);
     }
     outcomes.push({
-        stdout: '{"result":"the hidden answer"}'
+        stdout: okEnvelope('the hidden answer')
     });
-    const primitiveOutput = await bridge.execute({
-        action: 'call',
-        tool: 'lookup',
-        arguments: {
-            city: 'Dubai'
-        }
-    }, null);
+    const primitiveOutput = await bridge.execute(bridgeCall('lookup', {
+        city: 'Dubai'
+    }), null);
     assert.deepEqual(primitiveOutput, {
         ok: false,
         error: 'invalid_output'
     }, 'primitive result strings cannot bypass the structured visible-output boundary');
-    const beforeOversized = spawnSpecs.length;
-    const oversized = await bridge.execute({
-        action: 'call',
-        tool: 'lookup',
-        arguments: {
-            blob: 'x'.repeat(65_537)
+    outcomes.push({
+        stdout: okEnvelope([
+            'PRIVATE_ARRAY_VALUE'
+        ])
+    });
+    const primitiveArrayOutput = await bridge.execute(bridgeCall('lookup', {
+        city: 'Dubai'
+    }), null);
+    assert.deepEqual(primitiveArrayOutput, {
+        ok: false,
+        error: 'forbidden_output'
+    }, 'top-level primitive arrays cannot bypass the positive output-key boundary');
+    assert.equal(JSON.stringify(primitiveArrayOutput).includes('PRIVATE_ARRAY_VALUE'), false, 'rejected primitive array values are not reflected');
+    outcomes.push({
+        stdout: okEnvelope([
+            [
+                "PRIVATE_NESTED_ARRAY_VALUE"
+            ]
+        ])
+    });
+    const nestedPrimitiveArrayOutput = await bridge.execute(bridgeCall('lookup', {
+        city: 'Dubai'
+    }), null);
+    assert.deepEqual(nestedPrimitiveArrayOutput, {
+        ok: false,
+        error: 'forbidden_output'
+    }, 'nested primitive arrays without a declared-key ancestor fail closed');
+    assert.equal(JSON.stringify(nestedPrimitiveArrayOutput).includes('PRIVATE_NESTED_ARRAY_VALUE'), false, 'rejected nested primitive array values are not reflected');
+    outcomes.push({
+        stdout: okEnvelope([
+            {
+                city: 'Dubai'
+            },
+            'PRIVATE_MIXED_ARRAY_VALUE'
+        ])
+    });
+    const mixedArrayOutput = await bridge.execute(bridgeCall('lookup', {
+        city: 'Dubai'
+    }), null);
+    assert.deepEqual(mixedArrayOutput, {
+        ok: false,
+        error: 'forbidden_output'
+    }, 'a valid record cannot mask an unkeyed primitive sibling');
+    assert.equal(JSON.stringify(mixedArrayOutput).includes('PRIVATE_MIXED_ARRAY_VALUE'), false, 'rejected mixed-array primitive values are not reflected');
+    outcomes.push({
+        stdout: okEnvelope([])
+    });
+    const emptyArrayOutput = await bridge.execute(bridgeCall('lookup', {
+        city: 'Dubai'
+    }), null);
+    assert.deepEqual(emptyArrayOutput, {
+        ok: true,
+        result: []
+    }, 'an empty top-level result array is an explicit non-reflecting collection');
+    outcomes.push({
+        stdout: okEnvelope([
+            {
+                city: 'Dubai'
+            }
+        ])
+    });
+    const recordArrayOutput = await bridge.execute(bridgeCall('lookup', {
+        city: 'Dubai'
+    }), null);
+    assert.deepEqual(recordArrayOutput, {
+        ok: true,
+        result: [
+            {
+                city: 'Dubai'
+            }
+        ]
+    }, 'top-level arrays of records remain valid when every leaf is covered by a declared key');
+    outcomes.push({
+        stdout: okEnvelope({
+            city: [
+                'Dubai'
+            ]
+        })
+    });
+    const keyedPrimitiveArrayOutput = await bridge.execute(bridgeCall('lookup', {
+        city: 'Dubai'
+    }), null);
+    assert.deepEqual(keyedPrimitiveArrayOutput, {
+        ok: true,
+        result: {
+            city: [
+                'Dubai'
+            ]
         }
-    }, null);
+    }, 'primitive arrays remain valid below a declared output key');
+    const beforeOversized = spawnSpecs.length;
+    const oversized = await bridge.execute(bridgeCall('lookup', {
+        city: 'Dubai',
+        notes: 'x'.repeat(65_537)
+    }), null);
     assert.deepEqual(oversized, {
         ok: false,
         error: 'invalid_arguments',
@@ -1834,30 +2563,20 @@ try {
     for(let index = 0; index < 13; index++)deep = {
         next: deep
     };
-    const deepResult = await bridge.execute({
-        action: 'call',
-        tool: 'lookup',
-        arguments: deep
-    }, null);
-    assert.deepEqual(deepResult, {
-        ok: false,
-        error: 'invalid_arguments',
-        reason: 'serialization_limit'
-    });
-    assert.equal(spawnSpecs.length, beforeDeep, 'over-deep arguments are rejected before spawn');
-    const beforeOverride = spawnSpecs.length;
-    const overrideResult = await bridge.execute({
-        action: 'call',
-        tool: 'lookup',
-        arguments: {
+    await assert.rejects(()=>bridge.execute(bridgeCall('lookup', {
             city: 'Dubai',
-            executable: '/tmp/evil',
-            cwd: '/tmp/evil',
-            argv: [
-                '--unsafe'
-            ]
-        }
-    }, null);
+            ...deep
+        }), null), /invalid arguments/);
+    assert.equal(spawnSpecs.length, beforeDeep, 'schema-invalid deep arguments are rejected before spawn');
+    const beforeOverride = spawnSpecs.length;
+    const overrideResult = await bridge.execute(bridgeCall('lookup', {
+        city: 'Dubai',
+        executable: '/tmp/evil',
+        cwd: '/tmp/evil',
+        argv: [
+            '--unsafe'
+        ]
+    }), null);
     assert.deepEqual(spawnSpecs[beforeOverride]?.argv, [
         process.execPath,
         '-m',
@@ -1877,33 +2596,29 @@ try {
     ], 'model executable/cwd/argv fields remain data and cannot override config');
     assert.equal(overrideResult.ok, true, 'override-shaped arguments still use the configured bridge');
     outcomes.push({
-        stdout: '{"result":{"city":"Dubai"}}',
+        stdout: okEnvelope({
+            city: 'Dubai'
+        }),
         lossy: true
     });
-    const truncated = await bridge.execute({
-        action: 'call',
-        tool: 'lookup',
-        arguments: {
-            city: 'Dubai'
-        }
-    }, null);
+    const truncated = await bridge.execute(bridgeCall('lookup', {
+        city: 'Dubai'
+    }), null);
     assert.deepEqual(truncated, {
         ok: false,
         error: 'output_truncated'
     }, 'lossy stdout is rejected without parsing partial output');
     outcomes.push({
-        stdout: '{"result":{"city":"Dubai"}}',
+        stdout: okEnvelope({
+            city: 'Dubai'
+        }),
         stderr: 'private runner diagnostic',
         exitCode: 17,
         signal: 'SIGTERM'
     });
-    const failed = await bridge.execute({
-        action: 'call',
-        tool: 'lookup',
-        arguments: {
-            city: 'Dubai'
-        }
-    }, null);
+    const failed = await bridge.execute(bridgeCall('lookup', {
+        city: 'Dubai'
+    }), null);
     assert.deepEqual(failed, {
         ok: false,
         error: 'runner_failed',
@@ -1913,7 +2628,7 @@ try {
     const errorsTable = await bridge.execute({
         action: 'errors'
     }, null);
-    assert.ok(errorsTable.ok === true && errorsTable.errors, 'errors 契约表可拉取');
+    assert.ok(errorsTable.ok === true && errorsTable.errors, 'bridge failure contract is discoverable');
     for (const code of [
         'invalid_action',
         'disallowed_tool',
@@ -1927,10 +2642,68 @@ try {
         'forbidden_output'
     ]){
         const row = errorsTable.errors?.[code];
-        assert.ok(row && typeof row.recoverable === 'boolean' && row.remedy.length > 0, `契约表应含 ${code}(recoverable+remedy)`);
+        assert.ok(row && typeof row.recoverable === 'boolean' && row.remedy.length > 0, `failure contract contains ${code} with recovery guidance`);
     }
-    assert.equal(errorsTable.errors?.invalid_arguments?.recoverable, true, '参数形态错=调用方可恢复');
-    assert.equal(errorsTable.errors?.forbidden_output?.recoverable, false, '策略边界=不可恢复');
+    assert.equal(errorsTable.errors?.invalid_arguments?.recoverable, true, 'invalid caller arguments are recoverable');
+    assert.equal(errorsTable.errors?.forbidden_output?.recoverable, false, 'policy-boundary output is not recoverable');
+    assert.deepEqual(errorsTable, {
+        ok: true,
+        errors: BRIDGE_ERROR_CONTRACT
+    }, 'errors action returns the exact closed failure contract');
+    const toolsTable = await bridge.execute({
+        action: 'tools'
+    }, null);
+    assert.deepEqual(toolsTable, {
+        ok: true,
+        tools: [
+            {
+                name: 'lookup',
+                description: 'Lookup one declared city.',
+                input_schema: lookupInputSchema(),
+                output_keys: [
+                    'city',
+                    'nested'
+                ],
+                domain_outcomes: [
+                    {
+                        status: 'miss',
+                        code: 'NOT_FOUND',
+                        recovery: 'revise_arguments'
+                    },
+                    {
+                        status: 'error',
+                        code: 'AMBIGUOUS',
+                        recovery: 'choose_alternative'
+                    }
+                ]
+            },
+            {
+                name: 'constructor',
+                description: 'Construct one declared city.',
+                input_schema: lookupInputSchema(),
+                output_keys: [
+                    'legacy'
+                ],
+                domain_outcomes: [
+                    {
+                        status: 'error',
+                        code: 'INVALID',
+                        recovery: 'retry_same'
+                    }
+                ]
+            },
+            {
+                name: 'toString',
+                description: 'Stringify one declared city.',
+                input_schema: lookupInputSchema(),
+                output_keys: [
+                    'city',
+                    'nested'
+                ],
+                domain_outcomes: []
+            }
+        ]
+    }, 'tools action returns every exact frozen descriptor, including its input schema');
     for (const stdout of [
         'not-json',
         '{"result":1}{"result":2}'
@@ -1938,28 +2711,127 @@ try {
         outcomes.push({
             stdout
         });
-        const malformed = await bridge.execute({
-            action: 'call',
-            tool: 'lookup',
-            arguments: {
-                city: 'Dubai'
-            }
-        }, null);
+        const malformed = await bridge.execute(bridgeCall('lookup', {
+            city: 'Dubai'
+        }), null);
         assert.deepEqual(malformed, {
             ok: false,
             error: 'invalid_json'
         }, 'malformed or multi-value JSON is rejected');
     }
     outcomes.push({
-        spawnError: true
+        stdout: JSON.stringify({
+            schema_version: BENCHMARK_TOOL_RESULT_SCHEMA_VERSION,
+            status: 'miss',
+            code: 'NOT_FOUND',
+            recovery: 'revise_arguments'
+        })
     });
-    const spawnFailed = await bridge.execute({
-        action: 'call',
-        tool: 'lookup',
-        arguments: {
-            city: 'Dubai'
+    const miss = await bridge.execute(bridgeCall('lookup', {
+        city: 'Dubai'
+    }), null);
+    assert.deepEqual(miss, {
+        ok: true,
+        outcome: {
+            schema_version: BENCHMARK_TOOL_RESULT_SCHEMA_VERSION,
+            status: 'miss',
+            code: 'NOT_FOUND',
+            recovery: 'revise_arguments'
         }
-    }, null);
+    }, 'exit-zero domain miss is a successful typed outcome');
+    outcomes.push({
+        stdout: JSON.stringify({
+            schema_version: BENCHMARK_TOOL_RESULT_SCHEMA_VERSION,
+            status: 'error',
+            code: 'AMBIGUOUS',
+            recovery: 'choose_alternative'
+        })
+    });
+    const domainError = await bridge.execute(bridgeCall('lookup', {
+        city: 'Dubai'
+    }), null);
+    assert.deepEqual(domainError, {
+        ok: true,
+        outcome: {
+            schema_version: BENCHMARK_TOOL_RESULT_SCHEMA_VERSION,
+            status: 'error',
+            code: 'AMBIGUOUS',
+            recovery: 'choose_alternative'
+        }
+    }, 'declared exit-zero domain error is transport success');
+    for (const invalidEnvelope of [
+        {
+            schema_version: 'legacy',
+            status: 'miss',
+            code: 'NOT_FOUND',
+            recovery: 'revise_arguments'
+        },
+        {
+            schema_version: BENCHMARK_TOOL_RESULT_SCHEMA_VERSION,
+            status: 'miss',
+            code: 'UNKNOWN',
+            recovery: 'revise_arguments'
+        },
+        {
+            schema_version: BENCHMARK_TOOL_RESULT_SCHEMA_VERSION,
+            status: 'miss',
+            code: 'NOT_FOUND',
+            recovery: 'retry_same'
+        },
+        {
+            schema_version: BENCHMARK_TOOL_RESULT_SCHEMA_VERSION,
+            status: 'error',
+            code: 'AMBIGUOUS',
+            recovery: 'choose_alternative',
+            message: 'private free text'
+        }
+    ]){
+        outcomes.push({
+            stdout: JSON.stringify(invalidEnvelope)
+        });
+        assert.deepEqual(await bridge.execute(bridgeCall('lookup', {
+            city: 'Dubai'
+        }), null), {
+            ok: false,
+            error: 'invalid_output'
+        }, 'undeclared or non-exact domain envelope fails closed');
+    }
+    outcomes.push({
+        stdout: JSON.stringify({
+            result: {
+                city: 'Dubai'
+            }
+        })
+    });
+    assert.deepEqual(await bridge.execute(bridgeCall('lookup', {
+        city: 'Dubai'
+    }), null), {
+        ok: false,
+        error: 'invalid_output'
+    }, 'legacy versionless result envelope is rejected');
+    outcomes.push({
+        stdout: JSON.stringify({
+            schema_version: BENCHMARK_TOOL_RESULT_SCHEMA_VERSION,
+            status: 'miss',
+            code: 'NOT_FOUND',
+            recovery: 'revise_arguments'
+        }),
+        exitCode: 23
+    });
+    assert.deepEqual(await bridge.execute(bridgeCall('lookup', {
+        city: 'Dubai'
+    }), null), {
+        ok: false,
+        error: 'runner_failed',
+        exit_code: 23,
+        signal: null
+    }, 'nonzero exit remains infrastructure failure even when stdout resembles a domain envelope');
+    outcomes.push({
+        spawnError: true
+    });
+    const spawnFailed = await bridge.execute(bridgeCall('lookup', {
+        city: 'Dubai'
+    }), null);
     assert.deepEqual(spawnFailed, {
         ok: false,
         error: 'spawn_failed'
@@ -1967,13 +2839,9 @@ try {
     outcomes.push({
         spawnReject: true
     });
-    const asyncSpawnFailed = await bridge.execute({
-        action: 'call',
-        tool: 'lookup',
-        arguments: {
-            city: 'Dubai'
-        }
-    }, null);
+    const asyncSpawnFailed = await bridge.execute(bridgeCall('lookup', {
+        city: 'Dubai'
+    }), null);
     assert.deepEqual(asyncSpawnFailed, {
         ok: false,
         error: 'spawn_failed'
@@ -1981,53 +2849,47 @@ try {
     outcomes.push({
         waitForAbort: true
     });
-    const timedOut = await bridge.execute({
-        action: 'call',
-        tool: 'lookup',
-        arguments: {
-            city: 'Dubai'
-        }
-    }, null);
+    const timedOut = await bridge.execute(bridgeCall('lookup', {
+        city: 'Dubai'
+    }), null);
     assert.deepEqual(timedOut, {
         ok: false,
         error: 'timed_out'
     }, 'deadline abort is surfaced as timed_out');
     assert.equal(timeoutSignal?.aborted, true, 'timeout abort signal is fired');
     const beforeInvalidArgs = spawnSpecs.length;
-    let argsTypeRejected = '';
-    try {
-        await bridge.execute({
-            action: 'call',
-            tool: 'lookup',
-            arguments: [
-                'not',
-                'plain'
-            ]
-        }, null);
-    } catch (e) {
-        argsTypeRejected = e.name;
-    }
-    assert.equal(argsTypeRejected, 'ToolArgsError', 'arguments 非对象 → 宿主权 schema 结构化拒绝');
+    await assert.rejects(()=>bridge.execute(bridgeCall('lookup', [
+            'not',
+            'plain'
+        ]), null), /invalid arguments/);
     assert.equal(spawnSpecs.length, beforeInvalidArgs, 'non-object arguments are rejected before spawn');
-    let actionRejected = '';
-    try {
-        await bridge.execute({
-            action: 'inspect'
-        }, null);
-    } catch (e) {
-        actionRejected = e.name;
+    for (const [label, argumentsValue] of [
+        [
+            'missing required city',
+            {}
+        ],
+        [
+            'wrong city type',
+            {
+                city: 7
+            }
+        ],
+        [
+            'undeclared country',
+            {
+                city: 'Dubai',
+                country: 'AE'
+            }
+        ]
+    ]){
+        await assert.rejects(()=>bridge.execute(bridgeCall('lookup', argumentsValue), null), /invalid arguments/, `${label} is rejected by the descriptor-derived runtime validator`);
     }
-    assert.equal(actionRejected, 'ToolArgsError', '枚举外 action → 宿主权 schema 结构化拒绝(ToolArgsError)');
+    assert.equal(spawnSpecs.length, beforeInvalidArgs, 'required, type, and closed-object argument failures all happen before spawn');
+    await assert.rejects(()=>bridge.execute({
+            action: 'inspect'
+        }, null), /invalid arguments/);
     const beforeRejected = spawnSpecs.length;
-    const rejected = await bridge.execute({
-        action: 'call',
-        tool: 'delete_all',
-        arguments: {}
-    }, null);
-    assert.deepEqual(rejected, {
-        ok: false,
-        error: 'disallowed_tool'
-    }, 'disallowed tool is rejected structurally');
+    await assert.rejects(()=>bridge.execute(bridgeCall('delete_all', {}), null), /invalid arguments/);
     assert.equal(spawnSpecs.length, beforeRejected, 'disallowed tool is rejected before spawn');
     const spacedConfigPath = join(root, ' benchmark-environment-config.json ');
     writeFileSync(spacedConfigPath, readFileSync(configPath));
@@ -2214,7 +3076,7 @@ try {
         else process.env.GOTRY_LLM_MODEL = originalModelOverride;
     }
     const validConfig = {
-        schema_version: 'gotry_benchmark_environment_bridge_v2',
+        schema_version: 'gotry_benchmark_environment_bridge_v4',
         enabled: true,
         executable: process.execPath,
         cwd: root,
@@ -2224,14 +3086,45 @@ try {
             '--lang',
             'en'
         ],
-        allowed_tools: [
-            'lookup'
+        tools: [
+            {
+                name: 'lookup',
+                description: 'Lookup one declared city.',
+                input_schema: {
+                    type: 'object',
+                    properties: {
+                        city: {
+                            type: 'string',
+                            enum: [
+                                'Dubai',
+                                'Abu Dhabi'
+                            ],
+                            description: 'Declared city name.'
+                        }
+                    },
+                    required: [
+                        'city'
+                    ],
+                    additionalProperties: false
+                },
+                output_keys: [
+                    'city'
+                ],
+                domain_outcomes: [
+                    {
+                        status: 'miss',
+                        code: 'NOT_FOUND',
+                        recovery: 'revise_arguments'
+                    }
+                ]
+            }
         ],
         timeout_ms: 20,
         max_output_bytes: 4_096,
         terminal_output: {
             tag: 'done',
-            max_bytes: 4_096
+            max_bytes: 4_096,
+            body_schema: OK_BODY_SCHEMA
         },
         isolation: {
             mode: 'host-enforced',
@@ -2239,6 +3132,86 @@ try {
             network: 'denied'
         }
     };
+    const clonedConfig = ()=>JSON.parse(JSON.stringify(validConfig));
+    const configWithTool = (mutate)=>{
+        const config = clonedConfig();
+        mutate(config.tools[0]);
+        return config;
+    };
+    const nestedInputSchema = (objectLevels)=>{
+        let child = {
+            type: 'string'
+        };
+        for(let index = 0; index < objectLevels; index += 1){
+            child = {
+                type: 'object',
+                properties: {
+                    next: child
+                },
+                required: [
+                    'next'
+                ],
+                additionalProperties: false
+            };
+        }
+        return child;
+    };
+    const flatInputSchema = (count)=>({
+            type: 'object',
+            properties: Object.fromEntries(Array.from({
+                length: count
+            }, (_, index)=>[
+                    `p${index}`,
+                    {
+                        type: 'string'
+                    }
+                ])),
+            required: [],
+            additionalProperties: false
+        });
+    const totalEnumInputSchema = (groups)=>({
+            type: 'object',
+            properties: Object.fromEntries(Array.from({
+                length: groups
+            }, (_, group)=>[
+                    `e${group}`,
+                    {
+                        type: 'string',
+                        enum: Array.from({
+                            length: 64
+                        }, (_, index)=>`v${group}_${index}`)
+                    }
+                ])),
+            required: [],
+            additionalProperties: false
+        });
+    const byteSizedInputSchema = (targetBytes)=>{
+        const properties = Object.fromEntries(Array.from({
+            length: 64
+        }, (_, index)=>[
+                `b${index}`,
+                {
+                    type: 'string',
+                    description: ''
+                }
+            ]));
+        const schema = {
+            type: 'object',
+            properties,
+            required: [],
+            additionalProperties: false
+        };
+        let remaining = targetBytes - Buffer.byteLength(JSON.stringify(schema), 'utf8');
+        assert.ok(remaining >= 0 && remaining <= 64 * 512, 'byte-boundary fixture has enough bounded description capacity');
+        for (const property of Object.values(properties)){
+            const added = Math.min(512, remaining);
+            property.description = 'x'.repeat(added);
+            remaining -= added;
+        }
+        assert.equal(remaining, 0, 'byte-boundary fixture reaches the requested serialized size');
+        assert.equal(Buffer.byteLength(JSON.stringify(schema), 'utf8'), targetBytes);
+        return schema;
+    };
     const frozenProjection = registerBenchmarkEnvironmentBridge(configPath, ()=>{}, {
         spawn: (_spec)=>fakeHandle({
                 stdout: '{"result":{}}'
@@ -2279,7 +3252,7 @@ try {
                 return ()=>{};
             },
             effect (action) {
-                return action();
+                return runEffect(action);
             },
             agents: {
                 list () {
@@ -2313,62 +3286,300 @@ try {
         }), /benchmark environment bridge configuration unavailable/, 'unknown top-level config key fails hard');
     assert.throws(()=>bridgeRegistrationFor({
             ...validConfig,
-            schema_version: 'gotry_benchmark_environment_bridge_v1'
-        }), /benchmark environment bridge configuration unavailable/, 'v1 config cannot silently omit the Round 3 terminal semantics');
+            tools: [
+                {
+                    ...validConfig.tools[0],
+                    input_schema: {
+                        type: 'object'
+                    }
+                }
+            ]
+        }), /benchmark environment bridge configuration unavailable/, 'v3 rejects an open annotation-only input schema');
     assert.throws(()=>bridgeRegistrationFor({
             ...validConfig,
-            allowed_tools: [
-                'lookup',
-                'lookup'
-            ]
-        }), /benchmark environment bridge configuration unavailable/, 'duplicate allowed tool fails hard');
+            schema_version: 'gotry_benchmark_environment_bridge_v1'
+        }), /benchmark environment bridge configuration unavailable/, 'v1 config cannot silently omit the Round 3 terminal semantics');
     assert.throws(()=>bridgeRegistrationFor({
             ...validConfig,
-            allowed_output_keys: {}
-        }), /benchmark environment bridge configuration unavailable/, 'empty output-key mapping fails hard');
+            schema_version: 'gotry_benchmark_environment_bridge_v3'
+        }), /benchmark environment bridge configuration unavailable/, 'v3 config cannot silently omit the Round 12 terminal body schema (#215)');
     assert.throws(()=>bridgeRegistrationFor({
             ...validConfig,
-            allowed_output_keys: {
-                lookup: []
+            terminal_output: {
+                ...validConfig.terminal_output,
+                body_schema: {
+                    ...validConfig.terminal_output.body_schema,
+                    additionalProperties: true
+                }
             }
-        }), /benchmark environment bridge configuration unavailable/, 'empty output-key allowlist fails hard');
+        }), /benchmark environment bridge configuration unavailable/, 'non-closed terminal body schema fails the config load closed');
     assert.throws(()=>bridgeRegistrationFor({
             ...validConfig,
-            allowed_output_keys: {
-                unknown: [
+            tools: [
+                validConfig.tools[0],
+                validConfig.tools[0]
+            ]
+        }), /benchmark environment bridge configuration unavailable/, 'duplicate tool descriptor fails hard');
+    assert.throws(()=>bridgeRegistrationFor(configWithTool((tool)=>{
+            delete tool.output_keys;
+        })), /benchmark environment bridge configuration unavailable/, 'missing output_keys fails hard');
+    assert.throws(()=>bridgeRegistrationFor(configWithTool((tool)=>{
+            tool.output_keys = [];
+        })), /benchmark environment bridge configuration unavailable/, 'empty output allowlist fails closed at registration');
+    assert.throws(()=>bridgeRegistrationFor(configWithTool((tool)=>{
+            tool.output_keys = [
+                'city',
+                'city'
+            ];
+        })), /benchmark environment bridge configuration unavailable/, 'duplicate output key fails hard');
+    assert.throws(()=>bridgeRegistrationFor(configWithTool((tool)=>{
+            tool.output_keys = [
+                'not a key'
+            ];
+        })), /benchmark environment bridge configuration unavailable/, 'non-identifier output key fails hard');
+    assert.throws(()=>bridgeRegistrationFor(configWithTool((tool)=>{
+            delete tool.domain_outcomes;
+        })), /benchmark environment bridge configuration unavailable/, 'missing domain_outcomes fails hard');
+    assert.throws(()=>bridgeRegistrationFor(configWithTool((tool)=>{
+            tool.domain_outcomes = [
+                {
+                    status: 'unknown',
+                    code: 'NOT_FOUND',
+                    recovery: 'none'
+                }
+            ];
+        })), /benchmark environment bridge configuration unavailable/, 'unknown domain status fails hard');
+    assert.throws(()=>bridgeRegistrationFor(configWithTool((tool)=>{
+            tool.domain_outcomes = [
+                {
+                    status: 'miss',
+                    code: 'NOT_FOUND',
+                    recovery: 'free_text'
+                }
+            ];
+        })), /benchmark environment bridge configuration unavailable/, 'free-text domain recovery fails hard');
+    assert.throws(()=>bridgeRegistrationFor(configWithTool((tool)=>{
+            tool.domain_outcomes = [
+                {
+                    status: 'miss',
+                    code: 'NOT_FOUND',
+                    recovery: 'none'
+                },
+                {
+                    status: 'error',
+                    code: 'NOT_FOUND',
+                    recovery: 'none'
+                }
+            ];
+        })), /benchmark environment bridge configuration unavailable/, 'duplicate domain code fails hard');
+    assert.throws(()=>bridgeRegistrationFor(configWithTool((tool)=>{
+            tool.name = 'lookup;rm';
+        })), /benchmark environment bridge configuration unavailable/, 'shell metacharacter tool identifier fails hard');
+    for (const [label, schema] of [
+        [
+            'reference keyword',
+            {
+                type: 'object',
+                properties: {
+                    city: {
+                        $ref: '#/city'
+                    }
+                },
+                required: [
                     'city'
-                ]
+                ],
+                additionalProperties: false
             }
-        }), /benchmark environment bridge configuration unavailable/, 'output-key mapping for unknown tool fails hard');
-    assert.throws(()=>bridgeRegistrationFor({
-            ...validConfig,
-            allowed_output_keys: {
-                lookup: [
+        ],
+        [
+            'default keyword',
+            {
+                type: 'object',
+                properties: {
+                    city: {
+                        type: 'string',
+                        default: 'Dubai'
+                    }
+                },
+                required: [
+                    'city'
+                ],
+                additionalProperties: false
+            }
+        ],
+        [
+            'examples keyword',
+            {
+                type: 'object',
+                properties: {
+                    city: {
+                        type: 'string',
+                        examples: [
+                            'Dubai'
+                        ]
+                    }
+                },
+                required: [
+                    'city'
+                ],
+                additionalProperties: false
+            }
+        ],
+        [
+            'unknown keyword',
+            {
+                type: 'object',
+                properties: {
+                    city: {
+                        type: 'string',
+                        title: 'City'
+                    }
+                },
+                required: [
+                    'city'
+                ],
+                additionalProperties: false
+            }
+        ],
+        [
+            'open nested object',
+            {
+                type: 'object',
+                properties: {
+                    nested: {
+                        type: 'object',
+                        properties: {},
+                        required: []
+                    }
+                },
+                required: [
+                    'nested'
+                ],
+                additionalProperties: false
+            }
+        ],
+        [
+            'array without items',
+            {
+                type: 'object',
+                properties: {
+                    values: {
+                        type: 'array'
+                    }
+                },
+                required: [
+                    'values'
+                ],
+                additionalProperties: false
+            }
+        ],
+        [
+            'duplicate required',
+            {
+                type: 'object',
+                properties: {
+                    city: {
+                        type: 'string'
+                    }
+                },
+                required: [
                     'city',
                     'city'
-                ]
+                ],
+                additionalProperties: false
             }
-        }), /benchmark environment bridge configuration unavailable/, 'duplicate output key fails hard');
-    assert.throws(()=>bridgeRegistrationFor({
-            ...validConfig,
-            allowed_output_keys: {
-                lookup: [
-                    'not a key'
-                ]
+        ],
+        [
+            'unknown required',
+            {
+                type: 'object',
+                properties: {
+                    city: {
+                        type: 'string'
+                    }
+                },
+                required: [
+                    'country'
+                ],
+                additionalProperties: false
             }
-        }), /benchmark environment bridge configuration unavailable/, 'non-identifier output key fails hard');
+        ],
+        [
+            'type-mismatched enum',
+            {
+                type: 'object',
+                properties: {
+                    city: {
+                        type: 'string',
+                        enum: [
+                            'Dubai',
+                            7
+                        ]
+                    }
+                },
+                required: [
+                    'city'
+                ],
+                additionalProperties: false
+            }
+        ],
+        [
+            'duplicate enum',
+            {
+                type: 'object',
+                properties: {
+                    city: {
+                        type: 'string',
+                        enum: [
+                            'Dubai',
+                            'Dubai'
+                        ]
+                    }
+                },
+                required: [
+                    'city'
+                ],
+                additionalProperties: false
+            }
+        ]
+    ]){
+        assert.throws(()=>bridgeRegistrationFor(configWithTool((tool)=>{
+                tool.input_schema = schema;
+            })), /benchmark environment bridge configuration unavailable/, `${label} fails closed`);
+    }
+    assert.equal(bridgeRegistrationFor(configWithTool((tool)=>{
+        tool.input_schema = nestedInputSchema(8);
+    })), true, 'schema depth eight is accepted');
+    assert.throws(()=>bridgeRegistrationFor(configWithTool((tool)=>{
+            tool.input_schema = nestedInputSchema(9);
+        })), /benchmark environment bridge configuration unavailable/, 'schema depth nine is rejected');
+    assert.equal(bridgeRegistrationFor(configWithTool((tool)=>{
+        tool.input_schema = flatInputSchema(255);
+    })), true, 'the 256-node total boundary is accepted');
+    assert.throws(()=>bridgeRegistrationFor(configWithTool((tool)=>{
+            tool.input_schema = flatInputSchema(256);
+        })), /benchmark environment bridge configuration unavailable/, 'the 256-node total boundary plus one is rejected');
+    assert.throws(()=>bridgeRegistrationFor(configWithTool((tool)=>{
+            tool.input_schema = flatInputSchema(257);
+        })), /benchmark environment bridge configuration unavailable/, 'the property total bound rejects 257 properties');
+    assert.equal(bridgeRegistrationFor(configWithTool((tool)=>{
+        tool.input_schema = totalEnumInputSchema(4);
+    })), true, 'the 256-enum-value total boundary is accepted');
+    assert.throws(()=>bridgeRegistrationFor(configWithTool((tool)=>{
+            tool.input_schema = totalEnumInputSchema(5);
+        })), /benchmark environment bridge configuration unavailable/, 'the enum-value total bound rejects values above 256');
+    assert.equal(bridgeRegistrationFor(configWithTool((tool)=>{
+        tool.input_schema = byteSizedInputSchema(16 * 1024);
+    })), true, 'the 16 KiB schema boundary is accepted');
+    assert.throws(()=>bridgeRegistrationFor(configWithTool((tool)=>{
+            tool.input_schema = byteSizedInputSchema(16 * 1024 + 1);
+        })), /benchmark environment bridge configuration unavailable/, 'the schema byte boundary plus one is rejected');
     assert.throws(()=>bridgeRegistrationFor({
             ...validConfig,
             argv_prefix: [
                 'agent\n--unsafe'
             ]
         }), /benchmark environment bridge configuration unavailable/, 'argv control separator fails hard');
-    assert.throws(()=>bridgeRegistrationFor({
-            ...validConfig,
-            allowed_tools: [
-                'lookup;rm'
-            ]
-        }), /benchmark environment bridge configuration unavailable/, 'shell metacharacter tool identifier fails hard');
     assert.throws(()=>bridgeRegistrationFor({
             ...validConfig,
             isolation: {
@@ -2418,20 +3629,20 @@ try {
     writeFileSync(widePath, JSON.stringify(validConfig));
     chmodSync(widePath, 0o666);
     assert.throws(()=>loadConfigRegistration(widePath, root), /benchmark environment bridge configuration unavailable/, 'group/world writable config fails hard');
-    const legacyConfigPath = join(root, 'legacy-bridge.json');
-    writeFileSync(legacyConfigPath, JSON.stringify(validConfig));
-    const legacyTools = [];
-    const legacyCtx = {
+    const strictConfigPath = join(root, 'strict-bridge.json');
+    writeFileSync(strictConfigPath, JSON.stringify(validConfig));
+    const strictTools = [];
+    const strictCtx = {
         tools: {
             register (tool) {
-                legacyTools.push(tool);
+                strictTools.push(tool);
                 return ()=>{};
             },
             get (name) {
-                return legacyTools.find((tool)=>tool.name === name);
+                return strictTools.find((tool)=>tool.name === name);
             },
             schemas () {
-                return legacyTools.map((tool)=>({
+                return strictTools.map((tool)=>({
                         name: tool.name
                     }));
             }
@@ -2456,31 +3667,29 @@ try {
         },
         subprocess: {
             spawn: (_spec)=>fakeHandle({
-                    stdout: '{"result":{"city":"Dubai"}}'
+                    stdout: okEnvelope({
+                        city: 'Dubai'
+                    })
                 })
         }
     };
-    apply(legacyCtx, {
+    apply(strictCtx, {
         stateRoot: root,
         timeoutMs: 20,
         hbcliBin: '',
         sessionAccess: 'off',
-        benchmarkEnvironmentConfigPath: legacyConfigPath
+        benchmarkEnvironmentConfigPath: strictConfigPath
     });
-    const legacyBridge = legacyTools.find((tool)=>tool.name === 'gotry_benchmark_environment');
-    assert.ok(legacyBridge?.execute, 'legacy config without allowed_output_keys registers the bridge');
-    assert.deepEqual(await legacyBridge.execute({
-        action: 'call',
-        tool: 'lookup',
-        arguments: {
-            city: 'Dubai'
-        }
-    }, null), {
+    const strictBridge = strictTools.find((tool)=>tool.name === 'gotry_benchmark_environment');
+    assert.ok(strictBridge?.execute, 'strict v3 config registers the bridge');
+    assert.deepEqual(await strictBridge.execute(bridgeCall('lookup', {
+        city: 'Dubai'
+    }), null), {
         ok: true,
         result: {
             city: 'Dubai'
         }
-    }, 'legacy config without allowed_output_keys still executes safe structured output');
+    }, 'strict v3 result envelope executes safe structured output');
     console.log('BENCHMARK ENVIRONMENT BRIDGE TESTS: registration + TDD bridge contract assertions');
 } catch (error) {
     console.error(error);