isphere-ai-bridge/docs/superpowers/plans/2026-07-12-in-process-adapter-research.md

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:

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 -NoProfile -ExecutionPolicy Bypass -File scripts\extract-inprocess-adapter-map.ps1

Expected output contains:

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

• Step 3: Verify report content

Run:

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:

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:

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:

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

Expected: PASS.

• Step 5: Run the targeted test again

Run:

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:

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

For send-message, state:

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:

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:

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 -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

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

Expected: PASS.

• Step 3: Run full tests

go test ./...

Expected: PASS.

• Step 4: Run diff hygiene

git diff --check
git diff --cached --check

Expected: no output and exit code 0 after staging.

• Step 5: Commit and push

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.