feat: add in-process adapter research contract
This commit is contained in:
zhaoyilun
285
docs/superpowers/plans/2026-07-12-in-process-adapter-research.md
Normal file
285
docs/superpowers/plans/2026-07-12-in-process-adapter-research.md
Normal file
@@ -0,0 +1,285 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user