Connectors: 22 real pytest modules (186 pass / 7 optional-dep skips) exercising
every connector's dependency-free surface + missing-driver degradation; SSRF
guard verified; errors_connector.py as a thin re-export (no forked taxonomy).
Services: config/{dev,staging,prod,test,limits,logging}.yaml + docs/*.md for
api/gateway/scheduler/worker, mapped to the real config structs; gateway/scheduler
Dockerfiles + scheduler .env/README. All YAML validated.
Closes 66 manifest files (gap 175->109). No source behavior changed.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
3.4 KiB
API contract
lawsynth-api is a stdlib WSGI adapter over lawsynth_server.Application. It
adds no routes of its own except the streaming endpoint and an explicit marker
for the not-yet-deployed worker transport; every other operation is dispatched
unchanged to the domain core (app.py). All routes are served under the /v1
prefix (unprefixed aliases exist for /health and /version).
Versioning
Every response carries X-Api-Version: 1. A request may send X-Api-Version
with 1 or v1; any other value is rejected 406 unsupported_api_version.
GET /v1/version returns {"version": <package>, "protocol": "1"}.
Routes
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/health |
database + storage readiness (ok/degraded) |
| GET | /v1/version |
package version and protocol version |
| GET | /v1/projects /v1/datasets /v1/worlds /v1/runs |
list (paginated) |
| POST | /v1/projects /v1/datasets /v1/worlds /v1/runs |
create |
| GET | /v1/{collection}/{id} |
fetch one |
| PATCH | /v1/{collection}/{id} |
update one |
| DELETE | /v1/{collection}/{id} |
delete one (204) |
| POST | /v1/worlds/{id}/simulate |
run the RK4 simulator for a world |
| POST | /v1/runs/{id}/cancel |
cancel a non-terminal run |
| GET | /v1/runs/{id}/events |
events filtered to one run |
| POST | /v1/artifacts |
upload base64 bytes; returns sha256 metadata |
| GET | /v1/artifacts/{sha256} |
download bytes (base64 in JSON) |
| GET | /v1/events |
list events, or SSE stream (see below) |
/v1/worker and /v1/worker/* always return 501 worker_transport_unavailable:
this process is not a worker gateway.
Authentication
Every route except /health and /version requires
Authorization: Bearer <token>. Tokens are provisioned through
LAWSYNTH_API_TOKENS_JSON and map to one organization_id (the tenant) and a
set of scopes (read, write, admin). Reads require read; mutations require
write; admin implies both. Missing/invalid tokens return 401; insufficient
scope returns 403.
Writes, idempotency, media type
Request bodies must be application/json objects. Every mutating request must
send an Idempotency-Key header; the domain replays a stored result for a
repeated key and marks the response Idempotency-Replayed: true. Bodies larger
than max_request_bytes are rejected 413.
Pagination
List routes accept ?limit=<n>&cursor=<opaque>. Responses are enveloped as
{"items": [...], "next_cursor": <opaque|null>, "total": <n>, "limit": <n>}.
limit must be within 1..max_page_size; next_cursor is an opaque base64
offset to pass back for the next page.
Events (SSE)
GET /v1/events with Accept: text/event-stream returns, as framed SSE, every
retained event for the caller's tenant whose sequence is greater than the
Last-Event-ID request header (0 when absent), then closes the connection — the
socket is not held open. Clients resume by reconnecting with the last id they
saw. Retention is bounded and in-process (event_stream_retention); evicted
events are not replayable. Without the SSE Accept header the same path returns
a plain JSON {"items": [...]} list.
Error envelope
Every error body is {"error": {"code": <string>, "message": <string>, "request_id": <uuid>}} with the same request_id echoed in the X-Request-ID
header. See docs/failures.md for the code-to-status mapping.