M3b: Implement minimal local REST adapter #47

New issue

Closed

opened 2026-09-06 23:52:58 +00:00 by kilo · 0 comments

kilo commented

2026-09-06 23:52:58 +00:00

Member

Goal

Implement the frozen D-028 REST v1 machine interface as a thin,
loopback-only adapter over the existing Scarcity Router application/core.

Why

M2 established trusted CLI selection semantics and M3a froze the machine
contract. M3b must expose those same semantics to local machine clients
without creating transport-specific business logic.

Scope

GET /healthz
GET /v1/status
POST /v1/select
POST /v1/simulate
strict request parsing
frozen REST envelopes/error semantics
loopback-only server lifecycle
typed in-memory application seam shared with CLI/future MCP
deterministic REST contract and integration tests
minimal runtime documentation

Acceptance Criteria

exact D-028 REST surface implemented
REST adapter owns no selection/scarcity/provider logic
CLI and REST share the same typed application/core path
strict duplicate/non-finite JSON rejection implemented
exact missing/null semantics implemented
valid no-solution returns HTTP 200
provider degradation remains domain data
safe 400/500 error envelopes implemented
healthz performs no provider collection
server binds only to 127.0.0.1
request handling is serialized/bounded explicitly
no credentials/provider payloads/tracebacks leak
representative direct-application vs REST parity tests pass
existing CLI behavior remains unchanged
no MCP implementation

Constraints

no model execution
no prompt proxy
no provider changes
no catalog/rating/policy changes
no auth/TLS/non-loopback exposure
no database/cache/history
no Docker/systemd/service manager
no MCP
human merge gate

Links

Frozen contract: docs/machine-interfaces.md, decision D-028 in docs/decisions.md
Predecessor: M3a interface contracts (merged into develop as 2cdff27)

## Goal Implement the frozen D-028 REST v1 machine interface as a thin, loopback-only adapter over the existing Scarcity Router application/core. ## Why M2 established trusted CLI selection semantics and M3a froze the machine contract. M3b must expose those same semantics to local machine clients without creating transport-specific business logic. ## Scope - GET /healthz - GET /v1/status - POST /v1/select - POST /v1/simulate - strict request parsing - frozen REST envelopes/error semantics - loopback-only server lifecycle - typed in-memory application seam shared with CLI/future MCP - deterministic REST contract and integration tests - minimal runtime documentation ## Acceptance Criteria - exact D-028 REST surface implemented - REST adapter owns no selection/scarcity/provider logic - CLI and REST share the same typed application/core path - strict duplicate/non-finite JSON rejection implemented - exact missing/null semantics implemented - valid no-solution returns HTTP 200 - provider degradation remains domain data - safe 400/500 error envelopes implemented - healthz performs no provider collection - server binds only to 127.0.0.1 - request handling is serialized/bounded explicitly - no credentials/provider payloads/tracebacks leak - representative direct-application vs REST parity tests pass - existing CLI behavior remains unchanged - no MCP implementation ## Constraints - no model execution - no prompt proxy - no provider changes - no catalog/rating/policy changes - no auth/TLS/non-loopback exposure - no database/cache/history - no Docker/systemd/service manager - no MCP - human merge gate ## Links - Frozen contract: `docs/machine-interfaces.md`, decision D-028 in `docs/decisions.md` - Predecessor: M3a interface contracts (merged into `develop` as `2cdff27`)

kilo referenced this issue

2026-09-07 10:44:50 +00:00

M3b follow-up: align REST tests and version table with policy v5 #51