[P1-02] Define explicit public library API on the existing runtime owner with typed ports #137

New issue

Open

opened 2026-09-02 17:26:32 +00:00 by nsaspy · 0 comments

nsaspy commented

2026-09-02 17:26:32 +00:00

Owner

ARDR reconciliation — 2026-08-29

Canonical research/design now exist for this issue:

Research: lost-rob0t/starintel-auto-research/roam/research/star-server/STAR-RESEARCH-040-explicit-library-api-runtime-ports.org — READY_FOR_DESIGN.
Design/adversarial review: lost-rob0t/starintel-auto-research/roam/design/star-server/STAR-SERVER-047-explicit-library-api-runtime-ports.org — DESIGN_READY_FOR_OPERATOR_REVIEW.
Auto-Research transactions: #193 / #194.
Implementation authorization: PENDING / AWAITING_OPERATOR_IMPLEMENTATION_APPROVAL.

Current source reality

Current master already has star.runtime:star-runtime, *runtime*, start-runtime, stop-runtime, readiness/liveness, and concrete resource accessors. Do not create a second runtime/lifecycle object.

The actual remaining gap is that application operations still depend heavily on ambient globals/concrete adapters (*runtime*, actor globals such as *sys*, producer/target globals, HTTP state, concrete persistence/store hooks). A caller holding a runtime is not yet sufficient to invoke a stable application contract independently of ambient process state.

Current auth code also already exports star.auth:service-call-context with principal/scopes/credential/correlation/deadline semantics. Reuse it; do not invent a duplicate request-context type.

Design decision

Evolve the existing star-runtime into the explicit public composition/application owner.

Public application operations take:

explicit runtime;
existing typed service-call-context;
typed request value;
runtime-owned narrow typed ports.

Results are typed and transport-neutral. HTTP/CLI/Rabbit/embedded callers project the same application result rather than owning separate persistence/auth/lease policy.

*runtime* may remain temporarily as a compatibility default used by outer wrappers only. An explicit operation must behave identically regardless of the ambient *runtime* binding.

Port boundary

Define protocols only for real current dependencies required by migrated operations, such as:

document validation/codec;
persistence/query repository;
authorization policy;
lease store/application lease authority;
event/message publication;
clock/ID generation;
audit/event sink;
scheduler where required.

No port/public result exposes raw CouchDB connections, Rabbit channels, Sento actors/routers, Clack handles, sockets, pools, or thread objects.

Concrete adapter extraction remains #41; this issue owns the contracts they implement.

Dependency order

#39 / STAR-SERVER-046 first establishes the side-effect-free starintel-server/core boundary.
#37 remains lifecycle authority.
This issue defines explicit runtime/application contracts and fake-backed isolation.
#41 extracts concrete adapters behind those ports.
Full simultaneous live-production multi-runtime support follows only after concrete singleton actor/HTTP/resource globals are actually migrated.

Proposed implementation slices — ALL PENDING OPERATOR APPROVAL

Slice 1 — explicit fake-backed runtime/service contract

Depends on #39 Slice 1.

Create the minimum public runtime constructor/protocol + port bundle for one pure operation. Reuse service-call-context. No network/thread/concrete adapter creation.

Mandatory RED-first target:

construct runtime A and runtime B with distinct fake repository/clock/event probes;
invoke the selected public operation on A;
only A's probes observe the call;
B remains untouched;
bind star.runtime:*runtime* to B or NIL and prove A's explicit call result is unchanged.

Untouched master must fail because no documented public constructor/application-operation contract provides this behavior.

Slice 2 — typed result/call semantics

For that operation prove authorization, absolute deadline, and idempotency semantics at the application boundary. Denial/expired deadline must invoke zero authoritative mutation ports.

Slice 3 — first real vertical application operation

Migrate the smallest current operation whose dependency contract can live below concrete adapters. Do not broaden this into all server APIs.

Slice 4 — HTTP/embedded equivalence

Route one HTTP endpoint through the same application operation. Embedded and HTTP fixtures must produce the same typed application outcome before HTTP serialization.

Slice 5 — compatibility-default demotion

Old wrapper may resolve *runtime* at its outer boundary and delegate. The explicit implementation cannot read ambient runtime/actor/persistence globals.

Slice 6 — expand vertically

Migrate document/search/target/lease/inspection operations one at a time; coordinate concrete adapter moves with #41.

Slice 7 — concrete multi-runtime proof

Only after actor/HTTP/resource globals become instance-owned. This is not a Slice-1 acceptance criterion.

Acceptance criteria

one existing star.runtime lifecycle authority;
explicit side-effect-free runtime construction;
explicit runtime + service-call-context + typed request for public operations;
two fake-backed runtimes cannot cross-observe operations;
explicit operation does not depend on compatibility *runtime*;
narrow typed ports expose no raw concrete resources;
application results are transport-neutral;
HTTP and embedded callers share application policy/result;
#41 remains concrete adapter-extraction authority;
no false claim of two live production runtimes before singleton resources are migrated;
no new StarLang syntax or second control plane.

Implementation authorization

PENDING / AWAITING_OPERATOR_IMPLEMENTATION_APPROVAL

P1 priority, READY_FOR_DESIGN, completed design/adversarial review, issue state, publication, or machine output do not authorize RAGE implementation.

## ARDR reconciliation — 2026-08-29 Canonical research/design now exist for this issue: - Research: `lost-rob0t/starintel-auto-research/roam/research/star-server/STAR-RESEARCH-040-explicit-library-api-runtime-ports.org` — `READY_FOR_DESIGN`. - Design/adversarial review: `lost-rob0t/starintel-auto-research/roam/design/star-server/STAR-SERVER-047-explicit-library-api-runtime-ports.org` — `DESIGN_READY_FOR_OPERATOR_REVIEW`. - Auto-Research transactions: #193 / #194. - **Implementation authorization: PENDING / AWAITING_OPERATOR_IMPLEMENTATION_APPROVAL.** ## Current source reality Current `master` already has `star.runtime:star-runtime`, `*runtime*`, `start-runtime`, `stop-runtime`, readiness/liveness, and concrete resource accessors. Do **not** create a second runtime/lifecycle object. The actual remaining gap is that application operations still depend heavily on ambient globals/concrete adapters (`*runtime*`, actor globals such as `*sys*`, producer/target globals, HTTP state, concrete persistence/store hooks). A caller holding a runtime is not yet sufficient to invoke a stable application contract independently of ambient process state. Current auth code also already exports `star.auth:service-call-context` with principal/scopes/credential/correlation/deadline semantics. Reuse it; do not invent a duplicate request-context type. ## Design decision Evolve the existing `star-runtime` into the explicit public composition/application owner. Public application operations take: 1. explicit runtime; 2. existing typed `service-call-context`; 3. typed request value; 4. runtime-owned narrow typed ports. Results are typed and transport-neutral. HTTP/CLI/Rabbit/embedded callers project the same application result rather than owning separate persistence/auth/lease policy. `*runtime*` may remain temporarily as a compatibility default used by outer wrappers only. An explicit operation must behave identically regardless of the ambient `*runtime*` binding. ## Port boundary Define protocols only for real current dependencies required by migrated operations, such as: - document validation/codec; - persistence/query repository; - authorization policy; - lease store/application lease authority; - event/message publication; - clock/ID generation; - audit/event sink; - scheduler where required. No port/public result exposes raw CouchDB connections, Rabbit channels, Sento actors/routers, Clack handles, sockets, pools, or thread objects. Concrete adapter extraction remains #41; this issue owns the contracts they implement. ## Dependency order 1. #39 / `STAR-SERVER-046` first establishes the side-effect-free `starintel-server/core` boundary. 2. #37 remains lifecycle authority. 3. This issue defines explicit runtime/application contracts and fake-backed isolation. 4. #41 extracts concrete adapters behind those ports. 5. Full simultaneous live-production multi-runtime support follows only after concrete singleton actor/HTTP/resource globals are actually migrated. ## Proposed implementation slices — ALL PENDING OPERATOR APPROVAL ### Slice 1 — explicit fake-backed runtime/service contract Depends on #39 Slice 1. Create the minimum public runtime constructor/protocol + port bundle for one pure operation. Reuse `service-call-context`. No network/thread/concrete adapter creation. **Mandatory RED-first target:** - construct runtime A and runtime B with distinct fake repository/clock/event probes; - invoke the selected public operation on A; - only A's probes observe the call; - B remains untouched; - bind `star.runtime:*runtime*` to B or NIL and prove A's explicit call result is unchanged. Untouched `master` must fail because no documented public constructor/application-operation contract provides this behavior. ### Slice 2 — typed result/call semantics For that operation prove authorization, absolute deadline, and idempotency semantics at the application boundary. Denial/expired deadline must invoke zero authoritative mutation ports. ### Slice 3 — first real vertical application operation Migrate the smallest current operation whose dependency contract can live below concrete adapters. Do not broaden this into all server APIs. ### Slice 4 — HTTP/embedded equivalence Route one HTTP endpoint through the same application operation. Embedded and HTTP fixtures must produce the same typed application outcome before HTTP serialization. ### Slice 5 — compatibility-default demotion Old wrapper may resolve `*runtime*` at its outer boundary and delegate. The explicit implementation cannot read ambient runtime/actor/persistence globals. ### Slice 6 — expand vertically Migrate document/search/target/lease/inspection operations one at a time; coordinate concrete adapter moves with #41. ### Slice 7 — concrete multi-runtime proof Only after actor/HTTP/resource globals become instance-owned. This is not a Slice-1 acceptance criterion. ## Acceptance criteria - one existing `star.runtime` lifecycle authority; - explicit side-effect-free runtime construction; - explicit runtime + `service-call-context` + typed request for public operations; - two fake-backed runtimes cannot cross-observe operations; - explicit operation does not depend on compatibility `*runtime*`; - narrow typed ports expose no raw concrete resources; - application results are transport-neutral; - HTTP and embedded callers share application policy/result; - #41 remains concrete adapter-extraction authority; - no false claim of two live production runtimes before singleton resources are migrated; - no new StarLang syntax or second control plane. ## Implementation authorization `PENDING / AWAITING_OPERATOR_IMPLEMENTATION_APPROVAL` P1 priority, READY_FOR_DESIGN, completed design/adversarial review, issue state, publication, or machine output do **not** authorize RAGE implementation.