<!-- task=m-iop-hot-path-one-shot-execution/08+02,04,06_workspace_binding plan=1 tag=API milestone-task=artifact-pair -->

# Declarative Workspace Tool Binding

## For the Implementing Agent

Start only after predecessors 02, 04, and 06 have `complete.log`. Implement, run every command, and fill `CODE_REVIEW-cloud-G06.md` with actual evidence. Keep active files for official review; finalization is review-agent-only.

## Background

IOP must map canonical workspace operations through compatible tools already supplied by the caller, using deterministic schema matching and safe fixed-data transforms without executing tools or inspecting the workspace.

## Dependencies and Execution Order

- Required predecessors: `02+01_preset_generation`, `04+02,03_preset_model_authorization`, and `06+04,05_request_identity_ingress`.

## Analysis

### Files Read

- `agent-roadmap/sdd/knowledge-tool-optimization-extension/iop-hot-path-one-shot-execution/SDD.md`
- `apps/edge/internal/openai/chat_types.go`
- `apps/edge/internal/openai/chat_decode.go`
- `apps/edge/internal/openai/anthropic_types.go`
- `apps/edge/internal/openai/tool_schema.go`
- `apps/edge/internal/openai/anthropic_surface_test.go`
- `apps/edge/internal/openai/stream_gate_ingress_test.go`
- `agent-contract/outer/openai-compatible-api.md`
- `agent-contract/outer/anthropic-compatible-api.md`

### SDD Criteria

SDD scenario S06 requires canonical-to-actual mapping, parent-capable write or prepare alternatives, exact receipt matching, safe path/command synthesis, and containment rejection before local dispatch.

### Verification Context

Unit fixtures model Chat and Anthropic schemas; no workspace or tool is actually executed. Fresh tests are sufficient. Confidence: high.

### Test Coverage Gaps

Existing validation does not cover request-local workspace roles, argument synthesis, lexical no-escape paths, deterministic guard receipts, or public/provider id mapping.

### Symbol References

New binding code consumes decoded endpoint tools without changing their wire structs.

### Split Judgment

This is the first refined child of the former artifact pair. The immutable binding compiler and codec form an independently verifiable safety boundary; child 09 consumes the selected binding for cross-call frontiers.

### Scope Rationale

Exclude prepare/pair state transitions, filesystem execution, local/review model dispatch, cleanup, generic shell evaluation, manifests, revisions, and server-side artifact fallback.

### Final Routing

`evaluation_mode=isolated-reassessment`; finalizer pair. Build closures are true; scores `(2,0,2,1,1)` yield G06/local-fit, matched risks `boundary_contract,structured_interpretation,variant_product` (3), no large context/rework/evidence failure/gap; `PLAN-local-G06.md`. Review uses the same scores and official cloud G06 in `CODE_REVIEW-cloud-G06.md`.

## Implementation Checklist

- [ ] Select and pin a declarative workspace binding from actual Chat/Anthropic tool schemas.
- [ ] Encode safe deterministic operations, ids, paths, guards, and exact result receipts without executing tools or inspecting a workspace.
- [ ] Run dependency, focused mapping, vet, and diff verification exactly as written.
- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual notes and output.

### [API-1] Compile request-local workspace operation bindings

#### Problem

Endpoint tools are opaque request data. No code matches configured role alternatives or guarantees deterministic workspace-relative paths, shell-safe payloads, and exact receipts.

#### Solution

Compile ordered alternatives against actual JSON Schema into an immutable binding. Provide canonical prepare/read/write/delete encoders and result matchers. Structured bindings use named fields; command bindings synthesize fixed path/content commands with shell-safe encoding and a caller-executed containment guard. Edge performs no workspace inspection or command execution.

#### Modified Files and Checklist

- [ ] `apps/edge/internal/openai/workspace_tool_binding.go` — matcher/compiler/immutable selected binding.
- [ ] `apps/edge/internal/openai/workspace_tool_codec.go` — safe encoding, id mapping, lexical checks, guard synthesis, and exact result matching.
- [ ] `apps/edge/internal/openai/workspace_tool_binding_test.go` — structured/command alternatives, fingerprint, unsafe paths, and receipts.

#### Test Strategy

Write `TestWorkspaceToolBindingMatrix` and `TestWorkspaceCommandBindingSafetyGuard`. Cover parent-capable write, separate prepare, missing roles, reordered properties, schema replacement, exact/opaque receipts, quoting/newlines, traversal/absolute/sibling paths, and failed guard receipts.

#### Verification

Run `go test -count=1 ./apps/edge/internal/openai -run 'TestWorkspace(Tool|Command)'`; expect PASS.

## Modified Files Summary

| File | Items |
|------|-------|
| `apps/edge/internal/openai/workspace_tool_binding.go` | API-1 |
| `apps/edge/internal/openai/workspace_tool_codec.go` | API-1 |
| `apps/edge/internal/openai/workspace_tool_binding_test.go` | API-1 |
| `agent-task/m-iop-hot-path-one-shot-execution/08+02,04,06_workspace_binding/CODE_REVIEW-cloud-G06.md` | API-1 |

## Final Verification

```bash
test -f agent-task/m-iop-hot-path-one-shot-execution/02+01_preset_generation/complete.log
test -f agent-task/m-iop-hot-path-one-shot-execution/04+02,03_preset_model_authorization/complete.log
test -f agent-task/m-iop-hot-path-one-shot-execution/06+04,05_request_identity_ingress/complete.log
go test -count=1 ./apps/edge/internal/openai -run 'TestWorkspace(Tool|Command)'
go vet ./apps/edge/internal/openai
git diff --check
```

Expected: all commands exit 0; unsafe bindings fail before dispatch and no test executes a real workspace operation.
