Internal protocols · 0.1.0
Internal service boundaries
Scanner, updater and Advisor connector protocols are documented separately from the control API.
These service protocols connect components inside the workbench. They are implementation interfaces, not supported third-party integration endpoints. Use the control API through its supported client authority for application workflows.
Give each service a narrow responsibility
Coordinator
- Job worker
Owns the durable control-side operation and exact service bindings.
Separate protocols
- Scanner protocol
Bounded runs, paged findings and explicit result acknowledgement.
- Updater protocol
Reviewed component preparation and reconciliation, with no project-source access.
- Advisor connector protocol
Provider work bound to exact grants, destinations and cancellation state.
Connections
Job worker to Scanner protocol
Collect and persist the exact run result before acknowledging cleanup.
Job worker to Updater protocol
Track the operation identity and request digest through preparation and recovery.
Job worker to Advisor connector protocol
Issue only the provider authority required for the intended Advisor request.
| Service | Caller and resources | Protocol responsibility |
|---|---|---|
| Scanner | Worker; authorized source, snapshots and validated cache read-only | Run admission, state, bounded findings, exact-result acknowledgement and cancellation. |
| Scanner-data updater | Control API/worker; writable cache and reviewed download egress | Durable preparation operations and complete cache-generation publication, without project-source access. |
| Advisor connector | Worker; dedicated provider authorization and approved network routes | Narrowly granted provider testing, generation, observation and cancellation. |
The core publishes only its loopback ingress relay. These services are not public website endpoints. The scanner’s internal network, updater egress and Advisor egress are distinct in Compose. Mount/network declarations need verification in the deployed images and containers before being treated as observed isolation.
Runtime scanner
The worker starts a stable run with POST /runs, observes its state and reads its result through bounded finding pages. The run identity and request digest prevent a different command from being substituted under an existing run. The sealed manifest adds the result digest, counts, stream identity, summary and artifact declarations.
Finding-page cursors bind the exact run, request, result and continuation position. The worker validates the entire stream before database publication. POST /runs/{run_id}/result/ack releases the exact temporary result after durable persistence. Cancellation and cleanup through DELETE /runs/{run_id} must preserve the appropriate request/result binding; they are not arbitrary file-deletion commands.
The scanner’s run registry and recovery spool are process-local and time-bounded. A scanner restart does not preserve that spool as durable evidence. Its health response also does not establish that selected binaries, rules and databases are ready. Read the scanner routes, run control and commit-before-ACK.
Source-blind updater
The updater receives durable operations bound to an operation UUID and request digest. Its executor recovers operation state and manages bounded active/pending work. Handlers resolve reviewed components, stage private candidate data, validate and seal it, and publish a complete generation. They do not accept arbitrary source-repository paths, download URLs or shell commands as a substitute for the reviewed catalog.
The private HTTP boundary requires an allowed Host and rejects forwarded-host/protocol headers. This is an additional request boundary, not a reason to expose the updater publicly. The updater has no project-source mount; the scanner consumes its validated cache read-only.
Activation and cancellation have distinct outcomes. Once publication enters its protected commit stage, cancellation cannot be used to interrupt it or roll the selection back. Rollback is a separate validated operation and still requires compatible, fresh previous data. See updater startup and request boundary, operation routes and preparation architecture.
Advisor connector
Both local and remote Advisor work go through the connector. The worker reserves or admits a bounded operation, presents the required execution grant and requests generation. The connector checks the authorized provider route and model, then validates the response. It has dedicated authorization material and no mounted project source; the worker supplies the admitted finding packet.
Remote generation requires the separately confirmed single-finding path. Confirmation binds provider configuration, authorization, transport, destination, model identity, finding revision and prompt hash. Automatic and scan-wide provider selection remains local-only. Remote transport supports the reviewed direct or SSH Ollama routes, not arbitrary model providers.
Operation admission, observation and cancellation are explicit endpoints. Cancellation may stop further work but cannot recall content already sent to the provider. Returned advice is validated again by the worker and discarded if the finding changed while generation was running. It does not automatically change finding lifecycle or gate policy.
See connector operation and generation handlers, worker integration and disclosure binding.
Read the protocol with its implementation
The internal reference describes declarations at its explicitly identified API snapshot. Some handlers read and validate request JSON directly, so an automatically generated broad schema does not express every permitted key, operation binding or authorization condition. Read the handler and its caller together when changing a protocol.
Schema declarations alone do not prove startup, reachability, provider authorization, recovery behavior or integration support. Protocol changes need coordinated caller/service validation and tests of rejection and recovery paths. Public integrations should not depend on these internal endpoints being stable.