Interactive operator client contract: Nyxt/Hackmode capability and ingest integration tests #120

New issue

Open

opened 2026-08-25 07:38:46 +00:00 by lost-rob0t · 0 comments

lost-rob0t commented

2026-08-25 07:38:46 +00:00

(Migrated from github.com)

Goal

Prove that non-web interactive Common Lisp clients such as Nyxt/Hackmode can discover and use the supported StarIntel HTTP contract without copying server internals or guessing legacy routes.

This is primarily a contract/integration slice over existing API work, not a request for a Nyxt-specific server subsystem.

Client flows to guarantee

From a clean authenticated client:

GET /api/v1/capabilities
inspect API/document revision, auth mode, features, limits and advertised endpoints
stats/search
document lookup
versioned document ingest/bulk ingest when #59 lands
target list/submit/control when advertised
view discovery/query when #61 lands

Requirements

stable JSON envelope and structured error shape
auth passed in headers/service-client configuration, never embedded in navigable URLs
explicit request deadlines/timeouts
request/correlation ID propagation where supported
capability metadata sufficient for a client to hide/disable unsupported commands rather than probing by 404
compatibility routes clearly marked as such
OpenAPI/contract fixtures consumable by Common Lisp clients without requiring browser-only CORS behavior

Operator/evidence use case

Hackmode's durable outbox and Nyxt evidence workflow need to distinguish:

locally accepted/queued evidence
server accepted
persisted
validation rejected
authorization rejected
retryable transport/server failure
unknown mutation outcome

Do not encourage blind retries of mutations without idempotency guarantees.

Tests

Add hermetic client/server contract tests using canonical v0.9 fixtures and a minimal generic HTTP client shape:

capability discovery
auth success/failure with secret redaction
search + document lookup
ingest acceptance/validation failure
idempotent retry once supported
unavailable feature advertised as unavailable
legacy compatibility path only when capabilities declare it

Dependencies

#58 versioned capability-discovered API
#59 idempotent batch ingest/target lifecycle
#61 versioned view registry
#62 auth/observability hardening

Consumers

lost-rob0t/dotfiles Nyxt StarIntel mode
lost-rob0t/hackmode local-first StarIntel outbox/client integrations

## Goal Prove that non-web interactive Common Lisp clients such as Nyxt/Hackmode can discover and use the supported StarIntel HTTP contract without copying server internals or guessing legacy routes. This is primarily a contract/integration slice over existing API work, not a request for a Nyxt-specific server subsystem. ## Client flows to guarantee From a clean authenticated client: 1. `GET /api/v1/capabilities` 2. inspect API/document revision, auth mode, features, limits and advertised endpoints 3. stats/search 4. document lookup 5. versioned document ingest/bulk ingest when #59 lands 6. target list/submit/control when advertised 7. view discovery/query when #61 lands ## Requirements - stable JSON envelope and structured error shape - auth passed in headers/service-client configuration, never embedded in navigable URLs - explicit request deadlines/timeouts - request/correlation ID propagation where supported - capability metadata sufficient for a client to hide/disable unsupported commands rather than probing by 404 - compatibility routes clearly marked as such - OpenAPI/contract fixtures consumable by Common Lisp clients without requiring browser-only CORS behavior ## Operator/evidence use case Hackmode's durable outbox and Nyxt evidence workflow need to distinguish: - locally accepted/queued evidence - server accepted - persisted - validation rejected - authorization rejected - retryable transport/server failure - unknown mutation outcome Do not encourage blind retries of mutations without idempotency guarantees. ## Tests Add hermetic client/server contract tests using canonical v0.9 fixtures and a minimal generic HTTP client shape: - capability discovery - auth success/failure with secret redaction - search + document lookup - ingest acceptance/validation failure - idempotent retry once supported - unavailable feature advertised as unavailable - legacy compatibility path only when capabilities declare it ## Dependencies - #58 versioned capability-discovered API - #59 idempotent batch ingest/target lifecycle - #61 versioned view registry - #62 auth/observability hardening ## Consumers - lost-rob0t/dotfiles Nyxt StarIntel mode - lost-rob0t/hackmode local-first StarIntel outbox/client integrations