106 lines
4.2 KiB
Markdown
106 lines
4.2 KiB
Markdown
# 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.
|
|
|
|
## Round 2 remediation
|
|
|
|
The final review found two remaining contract gaps. The binding resolver already treated
|
|
`auth: none` as credential-free, but the runtime renderer and diagnostic connector still required
|
|
the API-key file. Rendering and connector construction now make that requirement conditional on
|
|
the declared REST authentication mode, so a DWH/vector `auth: none` workspace passes resolver,
|
|
runtime rendering, and diagnostics with no API-key file.
|
|
|
|
SSH forwarding previously changed the PostgreSQL connection host to `127.0.0.1` without retaining
|
|
the original target for TLS hostname validation. Forwarded probes now carry `SSH_TARGET_HOST` as
|
|
`tlsServername` into the PostgreSQL TLS options; private CA and verified system trust behavior are
|
|
unchanged.
|
|
|
|
TDD RED: the new end-to-end no-key test failed at the unconditional runtime
|
|
`API_KEY_FILE` requirement, while the SSH test showed no `tlsServername` on the loopback probe or
|
|
database-client request. TDD GREEN: the focused backend workspace tests passed `40/40`.
|
|
|
|
Round 2 final verification:
|
|
|
|
```text
|
|
backend: npx vitest run
|
|
31 test files passed; 332 tests passed
|
|
|
|
backend: npx tsc --noEmit -p .
|
|
exit 0
|
|
|
|
repository: git diff --check
|
|
exit 0
|
|
```
|