[P1-03] Extract concrete adapters behind explicit runtime-owned typed ports #136

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-041-concrete-adapter-extraction.org — READY_FOR_DESIGN.
Design/adversarial review: lost-rob0t/starintel-auto-research/roam/design/star-server/STAR-SERVER-048-concrete-adapter-extraction.org — DESIGN_READY_FOR_OPERATOR_REVIEW.
Auto-Research transactions: #195 / #196.
Implementation authorization: PENDING / AWAITING_OPERATOR_IMPLEMENTATION_APPROVAL.

Current-source findings

Current master remains one serial :starintel-gserver ASDF system whose direct dependency closure includes cl-couch, cl-rabbit, Sento, Dexador, Clack/Hunchentoot, Ningle, lparallel and related service/runtime libraries.

Do not interpret this issue as a mechanical five-package rewrite. Current code already has useful seams that must be preserved and promoted:

authorization/document services already accept explicit fetch/delete/update/publish functions for several operations;
target repository querying accepts an injected query function;
star.leases:lease-store is already a backend-neutral protocol with memory and Valkey implementations.

The missing invariant is dependency direction: application operations from #40 depend only on narrow typed ports; concrete adapters implement those ports; the existing star.runtime / service composition root constructs and owns concrete instances.

Dependency order

#39 / STAR-SERVER-046 establishes the useful side-effect-free core ASDF boundary.
#40 / STAR-SERVER-047 establishes explicit runtime + existing service-call-context + typed application ports/results.
This issue extracts concrete integrations behind those ports one vertical operation at a time.
#37 remains lifecycle/composition authority.
#42 and later manifest/observability work consume the resulting component/adapter boundaries rather than inventing another integration layer.

Adapter responsibilities

HTTP

Transport parsing, auth-context projection, request/result serialization, status/headers, CORS/version aliases. HTTP must not perform CouchDB/Rabbit/lease/scheduling application orchestration directly once the corresponding application operation migrates.

CouchDB

Pool/session/request/view/revision/storage/outbox mechanics and concrete failure normalization. Application code sees capability-specific repository/query/outbox ports, not raw clients or *couchdb-pool*.

RabbitMQ

Connection/channel ownership, topology, envelope transport, settlement, bounded prefetch/backpressure, retry/DLQ/quarantine transport mechanics and broker-failure normalization. Application services decide logical policy/events.

Valkey

Reuse the existing lease-store protocol. Valkey scripts/serialization/server-time/fencing remain concrete details. Do not create another KV/lease abstraction.

Scheduler/timers

Own timer registration/cancellation effects under #37 lifecycle. Application services produce typed schedule/recovery intentions and callbacks re-enter application operations.

Proposed implementation slices — ALL PENDING OPERATOR APPROVAL

Slice 1 — first read-only repository vertical

Depends on realized #39/#40 first slices.

Choose the smallest existing document/query operation with an injected-I/O seam. Define one narrow repository port, fake implementation, typed application result, and concrete CouchDB implementation.

Mandatory RED-first target: on the untouched post-#39/#40 baseline, the selected application operation still requires the concrete/default CouchDB seam or lacks the runtime-owned port. The RED must prove the application/core test cannot run with only a fake repository and a dependency closure excluding cl-couch.

GREEN must prove:

runtime A with fake repository A invokes only A;
application/core package/test loads without cl-couch;
no network/thread side effect is needed;
the concrete CouchDB adapter independently satisfies the same application-visible contract.

Do not obtain GREEN by mocking/rebinding a concrete CouchDB package symbol.

Slice 2 — concrete CouchDB conformance

Success, not-found, conflict/invalid where relevant, deadline/timeout, backend-unavailable and malformed-backend-result behavior normalize into the typed port contract.

Slice 3 — HTTP projection

Route one existing endpoint through that exact application operation. A fake application service must drive HTTP response projection with zero CouchDB/Rabbit invocation.

Slice 4 — Rabbit vertical

Migrate one ingress/publication path through the same application policy. Broker ingress cannot bypass authorization/idempotency/deadline semantics.

Slice 5 — existing lease-store composition

Wire the current backend-neutral lease-store through the runtime-owned port used by the #32 lease application service. No lease algebra rewrite.

Slice 6 — scheduler effect

Extract one target/recovery timer operation behind a scheduler port while #37 remains lifecycle authority.

Slice 7 — dependency gates and vertical expansion

Expand operation-by-operation and add ASDF/package tests preventing concrete libraries from leaking back into application/core systems.

Acceptance criteria

explicit application/core dependency closure excludes concrete integrations it does not implement;
one existing runtime owns adapter instances;
fake-backed application tests run without network/actor/database/broker/timer effects;
concrete adapters satisfy typed contract suites;
HTTP and Rabbit ingress share application policy for equivalent operations;
adapter errors normalize before transport projection;
adapters do not orchestrate through each other;
ambiguous mutation outcomes are not hidden-retried without idempotency authority;
existing lease-store remains authoritative;
no generic callback bag/service locator, renamed globals, new StarLang syntax, or external supervisor.

Implementation authorization

PENDING / AWAITING_OPERATOR_IMPLEMENTATION_APPROVAL

READY_FOR_DESIGN, design completion/adversarial review, issue state, CI, or publication do not authorize RAGE implementation. Only explicit operator authorization recorded in the canonical approval workflow may do that.

## 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-041-concrete-adapter-extraction.org` — `READY_FOR_DESIGN`. - Design/adversarial review: `lost-rob0t/starintel-auto-research/roam/design/star-server/STAR-SERVER-048-concrete-adapter-extraction.org` — `DESIGN_READY_FOR_OPERATOR_REVIEW`. - Auto-Research transactions: #195 / #196. - **Implementation authorization: PENDING / AWAITING_OPERATOR_IMPLEMENTATION_APPROVAL.** ## Current-source findings Current `master` remains one serial `:starintel-gserver` ASDF system whose direct dependency closure includes cl-couch, cl-rabbit, Sento, Dexador, Clack/Hunchentoot, Ningle, lparallel and related service/runtime libraries. Do not interpret this issue as a mechanical five-package rewrite. Current code already has useful seams that must be preserved and promoted: - authorization/document services already accept explicit fetch/delete/update/publish functions for several operations; - target repository querying accepts an injected query function; - `star.leases:lease-store` is already a backend-neutral protocol with memory and Valkey implementations. The missing invariant is dependency direction: application operations from #40 depend only on narrow typed ports; concrete adapters implement those ports; the existing `star.runtime` / service composition root constructs and owns concrete instances. ## Dependency order 1. #39 / STAR-SERVER-046 establishes the useful side-effect-free core ASDF boundary. 2. #40 / STAR-SERVER-047 establishes explicit runtime + existing `service-call-context` + typed application ports/results. 3. This issue extracts concrete integrations behind those ports one vertical operation at a time. 4. #37 remains lifecycle/composition authority. 5. #42 and later manifest/observability work consume the resulting component/adapter boundaries rather than inventing another integration layer. ## Adapter responsibilities ### HTTP Transport parsing, auth-context projection, request/result serialization, status/headers, CORS/version aliases. HTTP must not perform CouchDB/Rabbit/lease/scheduling application orchestration directly once the corresponding application operation migrates. ### CouchDB Pool/session/request/view/revision/storage/outbox mechanics and concrete failure normalization. Application code sees capability-specific repository/query/outbox ports, not raw clients or `*couchdb-pool*`. ### RabbitMQ Connection/channel ownership, topology, envelope transport, settlement, bounded prefetch/backpressure, retry/DLQ/quarantine transport mechanics and broker-failure normalization. Application services decide logical policy/events. ### Valkey Reuse the existing `lease-store` protocol. Valkey scripts/serialization/server-time/fencing remain concrete details. Do **not** create another KV/lease abstraction. ### Scheduler/timers Own timer registration/cancellation effects under #37 lifecycle. Application services produce typed schedule/recovery intentions and callbacks re-enter application operations. ## Proposed implementation slices — ALL PENDING OPERATOR APPROVAL ### Slice 1 — first read-only repository vertical Depends on realized #39/#40 first slices. Choose the smallest existing document/query operation with an injected-I/O seam. Define one narrow repository port, fake implementation, typed application result, and concrete CouchDB implementation. **Mandatory RED-first target:** on the untouched post-#39/#40 baseline, the selected application operation still requires the concrete/default CouchDB seam or lacks the runtime-owned port. The RED must prove the application/core test cannot run with only a fake repository and a dependency closure excluding `cl-couch`. GREEN must prove: - runtime A with fake repository A invokes only A; - application/core package/test loads without `cl-couch`; - no network/thread side effect is needed; - the concrete CouchDB adapter independently satisfies the same application-visible contract. Do not obtain GREEN by mocking/rebinding a concrete CouchDB package symbol. ### Slice 2 — concrete CouchDB conformance Success, not-found, conflict/invalid where relevant, deadline/timeout, backend-unavailable and malformed-backend-result behavior normalize into the typed port contract. ### Slice 3 — HTTP projection Route one existing endpoint through that exact application operation. A fake application service must drive HTTP response projection with zero CouchDB/Rabbit invocation. ### Slice 4 — Rabbit vertical Migrate one ingress/publication path through the same application policy. Broker ingress cannot bypass authorization/idempotency/deadline semantics. ### Slice 5 — existing lease-store composition Wire the current backend-neutral lease-store through the runtime-owned port used by the #32 lease application service. No lease algebra rewrite. ### Slice 6 — scheduler effect Extract one target/recovery timer operation behind a scheduler port while #37 remains lifecycle authority. ### Slice 7 — dependency gates and vertical expansion Expand operation-by-operation and add ASDF/package tests preventing concrete libraries from leaking back into application/core systems. ## Acceptance criteria - explicit application/core dependency closure excludes concrete integrations it does not implement; - one existing runtime owns adapter instances; - fake-backed application tests run without network/actor/database/broker/timer effects; - concrete adapters satisfy typed contract suites; - HTTP and Rabbit ingress share application policy for equivalent operations; - adapter errors normalize before transport projection; - adapters do not orchestrate through each other; - ambiguous mutation outcomes are not hidden-retried without idempotency authority; - existing lease-store remains authoritative; - no generic callback bag/service locator, renamed globals, new StarLang syntax, or external supervisor. ## Implementation authorization `PENDING / AWAITING_OPERATOR_IMPLEMENTATION_APPROVAL` READY_FOR_DESIGN, design completion/adversarial review, issue state, CI, or publication do **not** authorize RAGE implementation. Only explicit operator authorization recorded in the canonical approval workflow may do that.