# In-Process Adapter Research Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Convert the offline B-route decision into a reproducible in-process adapter research slice that identifies reachable runtime objects, defines the minimum helper contract, and keeps production send blocked until logged-in evidence exists.

**Architecture:** This branch does not mutate the iSphere client and does not claim production send. It adds deterministic IL/static analysis for in-process anchors, then updates the Go connector with an explicit `in_process_contract` mode that validates the future bridge request/response shape while returning a blocked/no-side-effect result. Later online work can replace the contract stub with a logged-in managed adapter.

**Tech Stack:** PowerShell static analyzers over IL/text evidence, Markdown reports under `docs/source-discovery`, Go MCP tool connector code under `internal/tools`, and `go test ./...` for regression verification.

## Global Constraints

- Do not use ripgrep (`rg`); use `git ls-files`, `ag`, `grep -R`, PowerShell, or `Select-String`.
- Do not stage or commit `.codex-remote-attachments/`.
- Do not copy, patch, or modify original iSphere binaries.
- Do not enable real text send, file upload, or file send in this offline branch.
- A-route/RPA remains backup-only; do not promote it as the product path.
- B-route primary path for this branch is `in_process_adapter_research`.
- Every claimed completion must be backed by fresh command output.

---

## File Structure

- Create `scripts/extract-inprocess-adapter-map.ps1`: deterministic static analyzer for in-process anchors, object ownership, method accessibility, required runtime state, and stop conditions.
- Create `docs/source-discovery/2026-07-12-inprocess-adapter-static-map.md`: human-readable report generated by the script.
- Create ignored runtime JSON at `runs/inprocess-adapter-research/inprocess-adapter-map.json`: machine-readable evidence generated by the script; not committed unless the repo already tracks runs output.
- Modify `internal/tools/send_message_broute_adapter.go`: add `in_process_contract` mode that validates request shape and returns blocked/no-side-effect contract metadata.
- Modify `internal/tools/send_message_broute_adapter_test.go`: add tests for `in_process_contract` mode, including no accepted send and no side effects.
- Modify `internal/tools/send_message_uia_adapter.go`: extend the existing send connector env factory to route `ISPHERE_SEND_CONNECTOR_MODE=in_process_contract` to the B-route contract connector.
- Modify `internal/tools/send_message_uia_adapter_test.go`: prove the env factory builds the in-process contract connector.
- Modify `docs/source-discovery/capability-source-matrix.md`: point send-message/send-file next slices to the generated static map and keep production blocked.

---

### Task 1: Static In-Process Anchor Map

**Files:**
- Create: `scripts/extract-inprocess-adapter-map.ps1`
- Create: `docs/source-discovery/2026-07-12-inprocess-adapter-static-map.md`

**Interfaces:**
- Consumes: IL files under `runs/offline-evidence-intake/zyl-qqfile-20260709/metadata/c28-il/` and offline B-route reports.
- Produces: Markdown report and JSON with these top-level keys: `ok`, `decision`, `anchors`, `commands`, `required_runtime_state`, `stop_conditions`, `originals_modified`.

- [ ] **Step 1: Create the analyzer script**

Create `scripts/extract-inprocess-adapter-map.ps1` with these behaviors:

```powershell
param(
  [string]$OutDir = "runs/inprocess-adapter-research",
  [string]$ReportPath = "docs/source-discovery/2026-07-12-inprocess-adapter-static-map.md"
)

$ErrorActionPreference = 'Stop'
# Resolve repository root from the script location, not caller cwd.
# Read IL files only; never write into the sample directories.
# Extract anchors for AppContextManager, MessageScheduling, Chat, XMPPConnection,
# OffLineFileSend, FileUploadPara, FileUploadResult, FileTransfer, frmMain, and logged-in user/auth state.
# Emit JSON to $OutDir and Markdown to $ReportPath.
```

- [ ] **Step 2: Run the analyzer**

Run:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\extract-inprocess-adapter-map.ps1
```

Expected output contains:

```json
{
  "ok": true,
  "decision": "managed_in_process_adapter_contract_first",
  "originals_modified": false
}
```

- [ ] **Step 3: Verify report content**

Run:

```powershell
Get-Content docs\source-discovery\2026-07-12-inprocess-adapter-static-map.md -Raw | Select-String -Pattern 'AppContextManager|MessageScheduling|Chat|FileUploadResult|in_process_contract|Stop conditions'
```

Expected: all listed terms are present.

---

### Task 2: Go Connector In-Process Contract Mode

**Files:**
- Modify: `internal/tools/send_message_broute_adapter.go`
- Modify: `internal/tools/send_message_broute_adapter_test.go`
- Modify: `internal/tools/send_message_uia_adapter.go`
- Modify: `internal/tools/send_message_uia_adapter_test.go`

**Interfaces:**
- Consumes: `SendMessageConnectorRequest` from `internal/tools/send_message_connector.go`.
- Produces: new connector mode string `in_process_contract` with blocked result:
  - `Accepted: false`
  - `Status: "blocked"`
  - `ErrorCode: "broute_in_process_contract_only"`
  - `ConnectorMode: "broute-in-process-contract"`
  - `ProductionEnabled: false`
  - `SideEffects["attached_hook"] == false`
  - `SideEffects["sent_message"] == false`

- [ ] **Step 1: Add a failing test for contract mode**

Add this test to `internal/tools/send_message_broute_adapter_test.go`:

```go
func TestBRouteSendMessageConnectorInProcessContract(t *testing.T) {
	connector := NewBRouteSendMessageConnector(BRouteSendAdapterConfig{Mode: "in_process_contract"})
	result, err := connector.ExecuteSendMessage(context.Background(), SendMessageConnectorRequest{
		TargetType:           "direct",
		TargetID:             "u1",
		TargetRef:            "contact:u1",
		ContentText:          "hello",
		ContentSHA256:        strings.Repeat("a", 64),
		ContentLength:        5,
		IdempotencyKeySHA256: strings.Repeat("b", 64),
		ExecutionMode:        "production",
	})
	if err != nil {
		t.Fatalf("in_process_contract should be a structured blocked result, not process error: %v", err)
	}
	if result.Accepted || result.ProductionEnabled {
		t.Fatalf("contract mode must not accept production send: %+v", result)
	}
	if result.Status != "blocked" || result.ErrorCode != "broute_in_process_contract_only" {
		t.Fatalf("unexpected contract result: %+v", result)
	}
	if result.ConnectorMode != "broute-in-process-contract" {
		t.Fatalf("connector mode = %q", result.ConnectorMode)
	}
	if result.SideEffects["sent_message"] != false || result.SideEffects["attached_hook"] != false {
		t.Fatalf("contract mode must report no side effects: %#v", result.SideEffects)
	}
}
```

- [ ] **Step 2: Run the failing test**

Run:

```powershell
go test ./internal/tools -run TestBRouteSendMessageConnectorInProcessContract -count=1
```

Expected before implementation: FAIL because `in_process_contract` is not handled.

- [ ] **Step 3: Implement minimal mode branch**

In `internal/tools/send_message_broute_adapter.go`, add a `case "in_process_contract"` branch that calls `validateBRouteSendMessageRequest(request)` and returns a structured blocked result with no side effects.

- [ ] **Step 4: Add and run env factory coverage**

Add `TestSendMessageConnectorFromEnvBuildsInProcessContractConnector` to `internal/tools/send_message_uia_adapter_test.go` and update `NewSendMessageConnectorFromEnv()` so `ISPHERE_SEND_CONNECTOR_MODE=in_process_contract` returns `NewBRouteSendMessageConnector(BRouteSendAdapterConfig{Mode: "in_process_contract"})`.

Run:

```powershell
go test ./internal/tools -run 'Test(BRouteSendMessageConnector|SendMessageConnectorFromEnv)' -count=1
```

Expected: PASS.

- [ ] **Step 5: Run the targeted test again**

Run:

```powershell
go test ./internal/tools -run TestBRouteSendMessageConnectorInProcessContract -count=1
```

Expected: PASS.

---

### Task 3: Capability Matrix Correction

**Files:**
- Modify: `docs/source-discovery/capability-source-matrix.md`

**Interfaces:**
- Consumes: `docs/source-discovery/2026-07-12-inprocess-adapter-static-map.md`.
- Produces: updated business-facing capability status showing B-route next step is contract/in-process reachability, not production send.

- [ ] **Step 1: Update send-message and send-file rows**

Add the new report path to the evidence references and update next-slice language:

```markdown
- In-process adapter static map: `docs/source-discovery/2026-07-12-inprocess-adapter-static-map.md`
```

For send-message, state:

```markdown
Next slice: validate `in_process_contract` reachability in a logged-in runtime; production remains blocked until adapter invocation plus sent-record/content-hash/ack evidence exists.
```

For send-file, state:

```markdown
Next slice: validate logged-in access to `IFileTransfer.FileUpload` and returned `FileUploadResult.FileID`; production file upload/send remains blocked until online evidence exists.
```

- [ ] **Step 2: Verify diff contains no RPA promotion**

Run:

```powershell
git diff -- docs\source-discovery\capability-source-matrix.md | Select-String -Pattern 'RPA|in_process|production remains blocked|FileUploadResult'
```

Expected: in-process language appears and RPA remains backup-only.

---

### Task 4: Verification and Branch Closure

**Files:**
- All files from Tasks 1-3.

**Interfaces:**
- Consumes: scripts and tests from previous tasks.
- Produces: committed and pushed branch `codex/in-process-adapter-research`.

- [ ] **Step 1: Run static analyzer**

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\extract-inprocess-adapter-map.ps1
```

Expected: `ok=true`, `decision=managed_in_process_adapter_contract_first`, `originals_modified=false`.

- [ ] **Step 2: Run targeted tests**

```powershell
go test ./internal/tools -run TestBRouteSendMessageConnector -count=1
```

Expected: PASS.

- [ ] **Step 3: Run full tests**

```powershell
go test ./...
```

Expected: PASS.

- [ ] **Step 4: Run diff hygiene**

```powershell
git diff --check
git diff --cached --check
```

Expected: no output and exit code 0 after staging.

- [ ] **Step 5: Commit and push**

```powershell
git add scripts\extract-inprocess-adapter-map.ps1 docs\source-discovery\2026-07-12-inprocess-adapter-static-map.md docs\source-discovery\capability-source-matrix.md internal\tools\send_message_broute_adapter.go internal\tools\send_message_broute_adapter_test.go docs\superpowers\plans\2026-07-12-in-process-adapter-research.md
git commit -m "feat: add in-process adapter research contract"
git push -u gitea codex/in-process-adapter-research
```

Expected: branch pushed to `gitea/codex/in-process-adapter-research`.

---

## Self-Review

- Spec coverage: The plan covers B-route in-process research, static evidence, Go connector contract, capability matrix, verification, commit, and push.
- Placeholder scan: No task uses TBD/TODO/fill-in-later language; every implementation task names exact files and commands.
- Type consistency: `in_process_contract` maps to `broute-in-process-contract`; `SendMessageConnectorResult.SideEffects` reuses the existing `sendMessageNoSideEffects()` shape.