[P1-02] Define the public library API, runtime object, and dependency-injection ports #40

New issue

Open

opened 2026-07-22 00:16:39 +00:00 by lost-rob0t · 0 comments

lost-rob0t commented

2026-07-22 00:16:39 +00:00

(Migrated from github.com)

Problem

Current APIs are globals and package internals: *sys*, *targets*, global pools, global producer agent, global Ningle app, global settings, and startup hooks. Multiple runtime instances cannot be safely composed or tested.

Required public API

Define stable operations equivalent to:

make-runtime
start-runtime
stop-runtime
runtime-state
runtime-health
submit-document
update-document
get-document
search-documents
submit-target
acquire-target-lease
renew-target-lease
release-target-lease
component/router inspection operations

Required ports

Protocols for:

document registry/codec/validator
persistence repository
message bus/publisher/consumer
lease store
clock/id generator
authorization policy
event/audit sink
scheduler

Requirements

Every operation takes runtime/service context explicitly.
No caller receives raw internal actor, socket, channel, connection, or pool objects.
Public result/condition types are documented and versioned.
Deadlines, idempotency keys, principal, trace context, and cancellation propagate explicitly.
Compatibility wrappers may bind a default runtime but are not the core API.

Acceptance tests

Two runtimes with different fake adapters do not share state.
Embedded calls and HTTP calls produce equivalent service results.
Public API tests import only documented external symbols.
Package-internal refactoring does not break public contract tests.

## Problem Current APIs are globals and package internals: `*sys*`, `*targets*`, global pools, global producer agent, global Ningle app, global settings, and startup hooks. Multiple runtime instances cannot be safely composed or tested. ## Required public API Define stable operations equivalent to: - `make-runtime` - `start-runtime` - `stop-runtime` - `runtime-state` - `runtime-health` - `submit-document` - `update-document` - `get-document` - `search-documents` - `submit-target` - `acquire-target-lease` - `renew-target-lease` - `release-target-lease` - component/router inspection operations ## Required ports Protocols for: - document registry/codec/validator - persistence repository - message bus/publisher/consumer - lease store - clock/id generator - authorization policy - event/audit sink - scheduler ## Requirements - Every operation takes runtime/service context explicitly. - No caller receives raw internal actor, socket, channel, connection, or pool objects. - Public result/condition types are documented and versioned. - Deadlines, idempotency keys, principal, trace context, and cancellation propagate explicitly. - Compatibility wrappers may bind a default runtime but are not the core API. ## Acceptance tests - Two runtimes with different fake adapters do not share state. - Embedded calls and HTTP calls produce equivalent service results. - Public API tests import only documented external symbols. - Package-internal refactoring does not break public contract tests.