fix: align workspace diagnostic contracts

2026-08-04 00:37:57 +02:00
parent f6494fd8ef
commit 565e93a456
12 changed files with 346 additions and 42 deletions
@@ -0,0 +1,75 @@
+# Task 3 — Diagnostic contract remediation report
+
+Date: 2026-08-04
+
+## Scope
+
+This remediation is limited to the four approved review findings for the workspace diagnostic
+extension. It does not add registry routes, change workspace publication, alter session startup,
+or expand transport support.
+
+## Changes
+
+1. `RuntimeBindings` now has an explicit `vectorWriter` binding. The new
+   `resolveRuntimeBindings()` resolves DWH, vector reader, vector writer, and embedding bindings
+   together. The diagnoser takes the writer credential only from `bindings.vectorWriter`, never
+   from vector-reader values.
+2. Direct PostgreSQL and SSH-tunnelled direct probes accept an absent CA binding while retaining
+   certificate verification through the runtime system trust store. A supplied CA still uses
+   verified private-CA trust. REST private-CA refusal is unchanged.
+3. A reversible vector probe now requires an authenticated POST declaration with a response map
+   containing `operation`. The adapter requires the successful JSON response to echo `create` or
+   `remove` respectively, so an arbitrary 2xx or an upsert-only response cannot activate the
+   write probe.
+4. For DWH and vector REST diagnostics declared with `auth: none`, the resolver no longer
+   requires an API-key file and the adapter sends no credential. Credential-backed diagnostics
+   continue to require their local secret file.
+
+## TDD evidence
+
+The first focused RED run failed for the intended missing behavior:
+
+- `resolveRuntimeBindings is not a function` for unauthenticated resolver bindings;
+- schema accepted a reversible probe without a response contract; and
+- existing diagnostic fixtures rejected the new `response` declaration until schema support was
+  implemented.
+
+The focused GREEN run passed `43/43` tests across:
+
+- `test/workspaces-bindings.test.ts`
+- `test/workspaces-schema.test.ts`
+- `test/workspaces-diagnostics.test.ts`
+
+The regression coverage includes resolver-to-diagnoser writer propagation without manually
+inserting the writer key into vector-reader bindings, no-CA direct/SSH system-trust requests,
+operation-echo validation for create/remove, and `auth: none` bindings without secret files.
+
+## Documentation and design
+
+- `docs/workspace-diagnostic-protocol.md` now documents the verified system-trust fallback,
+  no-secret `auth: none` behavior, and required reversible response contract.
+- `docs/superpowers/specs/2026-08-03-git-workspace-registry-design.md` now records the same
+  response, CA, SSH, and authentication rules.
+
+## Final verification
+
+The initial sandboxed full suite could not bind its local SSE listener (`listen EPERM:
+operation not permitted 127.0.0.1`). It was rerun unchanged with local-listener permission.
+
+```text
+backend: npx vitest run
+31 test files passed; 329 tests passed
+
+backend: npx tsc --noEmit -p .
+exit 0
+
+repository: git diff --check
+exit 0
+```
+
+Expected test harness stderr from existing Pi/process failure-path tests remained present; no test
+failed and no diagnostic secret was emitted.
+
+## Blockers
+
+None.