[P0-01] Define the StarIntel Server v0.1 runtime contract and ordered implementation plan #9

New issue

Open

opened 2026-07-22 00:08:53 +00:00 by lost-rob0t · 0 comments

lost-rob0t commented

2026-07-22 00:08:53 +00:00

(Migrated from github.com)

Objective

This is the canonical execution ledger for the StarIntel Server rebuild after the July 21, 2026 audit.

Audited baseline

Repository: lost-rob0t/starintel-server
Implementation baseline: dev at 02d46c53826997f81b8bfa1bb110f7921ab0a16c
master at 3ef241192f670c43a8d27c13a641e4d445891386
Merge base: d289408213c2424391604be03d2619c65ce6e096
dev is 118 commits ahead of and 13 commits behind master.
No branch was moved or merged during the audit.

Execution rules

Work in the order below unless an issue explicitly declares a blocking cross-repository dependency.
One issue is the active implementation unit at a time.
Every bug fix begins with a failing regression test.
Required tests must fail red, pass green, then be refactored without changing behavior.
A required suite that discovers or executes zero tests is a failure.
Do not swallow test failures, dependency failures, or skipped integration coverage.
Do not promote the current dev tree directly to master; P0 acceptance gates must pass first.
Every completion records exact tests, results, commit/PR, and linked auto-research design evidence.

Runtime contract

The rebuilt system must provide:

an embeddable Common Lisp library and a separate service executable
one actor system per process by default
a strict total process thread budget
workload-specific dispatchers and cl-gserver router pools
bounded mailboxes, queues, tasks, and admission control
canonical document validation/encoding/decoding with shared fixtures
crash-safe persistence/publication and explicit delivery semantics
authenticated and authorized HTTP/library operations
distributed target leases with TTL and fencing tokens
managed lifecycle, health, recovery, supervision, metrics, and audit
resumable bounded research/analysis jobs

P0 — Foundation, correctness, and security

Complete these before the service/library architecture is treated as stable.

P1 — Importable library and deployable service

Begin after the relevant P0 contracts and regression suites exist.

P2 — Auto-research, managed runtime, validation, and release process

Completion gate

This roadmap is complete only when:

all P0 defects have regression coverage and pass
the library can load with zero network/thread side effects
the service composes the same public API used by embedded callers
authentication, authorization, leases, fencing, thread budgets, backpressure, recovery, and shutdown invariants are demonstrated
auto-research design/evidence links are synchronized
the branch reconciliation/release process is executed through reviewed PRs rather than direct ref movement.

## Objective This is the canonical execution ledger for the StarIntel Server rebuild after the July 21, 2026 audit. ## Audited baseline - Repository: `lost-rob0t/starintel-server` - Implementation baseline: `dev` at `02d46c53826997f81b8bfa1bb110f7921ab0a16c` - `master` at `3ef241192f670c43a8d27c13a641e4d445891386` - Merge base: `d289408213c2424391604be03d2619c65ce6e096` - `dev` is 118 commits ahead of and 13 commits behind `master`. - No branch was moved or merged during the audit. ## Execution rules 1. Work in the order below unless an issue explicitly declares a blocking cross-repository dependency. 2. One issue is the active implementation unit at a time. 3. Every bug fix begins with a failing regression test. 4. Required tests must fail red, pass green, then be refactored without changing behavior. 5. A required suite that discovers or executes zero tests is a failure. 6. Do not swallow test failures, dependency failures, or skipped integration coverage. 7. Do not promote the current `dev` tree directly to `master`; P0 acceptance gates must pass first. 8. Every completion records exact tests, results, commit/PR, and linked auto-research design evidence. ## Runtime contract The rebuilt system must provide: - an embeddable Common Lisp library and a separate service executable - one actor system per process by default - a strict total process thread budget - workload-specific dispatchers and cl-gserver router pools - bounded mailboxes, queues, tasks, and admission control - canonical document validation/encoding/decoding with shared fixtures - crash-safe persistence/publication and explicit delivery semantics - authenticated and authorized HTTP/library operations - distributed target leases with TTL and fencing tokens - managed lifecycle, health, recovery, supervision, metrics, and audit - resumable bounded research/analysis jobs # P0 — Foundation, correctness, and security Complete these before the service/library architecture is treated as stable. 1. [#10 Repair the test system and make zero executed tests a hard failure](https://github.com/lost-rob0t/starintel-server/issues/10) 2. [#11 Add shared document conformance fixtures and round-trip tests](https://github.com/lost-rob0t/starintel-server/issues/11) 3. [#12 Remove the broken duplicate server document encoder and decoder](https://github.com/lost-rob0t/starintel-server/issues/12) 4. [#13 Fix canonical star-cl codec type semantics and contract drift](https://github.com/lost-rob0t/starintel-server/issues/13) 5. [#14 Make CouchDB ingest and documents.new publication crash-safe](https://github.com/lost-rob0t/starintel-server/issues/14) 6. [#15 Keep RabbitMQ settlement on the connection owner thread and settle filtered deliveries](https://github.com/lost-rob0t/starintel-server/issues/15) 7. [#16 Add bounded retries, dead-letter queues, and poison-message quarantine](https://github.com/lost-rob0t/starintel-server/issues/16) 8. [#17 Repair persisted target loading and restart recovery](https://github.com/lost-rob0t/starintel-server/issues/17) 9. [#18 Fix target routing, recurrence, and destination semantics](https://github.com/lost-rob0t/starintel-server/issues/18) 10. [#19 Fix stale CouchDB revision merging and upsert behavior](https://github.com/lost-rob0t/starintel-server/issues/19) 11. [#20 Reconcile CouchDB design-document view names with every query wrapper and endpoint](https://github.com/lost-rob0t/starintel-server/issues/20) 12. [#21 Fix CouchDB view query parameter transport and group-level handling](https://github.com/lost-rob0t/starintel-server/issues/21) 13. [#22 Fix dataset export pagination and stop querying a reduce-only count view for documents](https://github.com/lost-rob0t/starintel-server/issues/22) 14. [#23 Fix CouchDB actor request/reply, delete, and connection semantics](https://github.com/lost-rob0t/starintel-server/issues/23) 15. [#24 Fix actor-event schema initialization and Rabbit delivery settlement](https://github.com/lost-rob0t/starintel-server/issues/24) 16. [#25 Validate HTTP input, bound bulk work, and stop leaking internal tracebacks](https://github.com/lost-rob0t/starintel-server/issues/25) 17. [#26 Define the HTTP authentication threat model and principal/capability contract](https://github.com/lost-rob0t/starintel-server/issues/26) 18. [#27 Implement authenticated request context and API-key lifecycle](https://github.com/lost-rob0t/starintel-server/issues/27) 19. [#28 Enforce capability, tenant, dataset, actor, and target authorization](https://github.com/lost-rob0t/starintel-server/issues/28) 20. [#29 Define distributed target lease and fencing semantics](https://github.com/lost-rob0t/starintel-server/issues/29) 21. [#30 Add a backend-neutral KV lease-store protocol](https://github.com/lost-rob0t/starintel-server/issues/30) 22. [#31 Implement the initial Valkey target-lease backend with atomic fencing scripts](https://github.com/lost-rob0t/starintel-server/issues/31) 23. [#32 Expose authenticated target-lease HTTP APIs and enforce leases in target execution](https://github.com/lost-rob0t/starintel-server/issues/32) 24. [#33 Add target-lease expiry, crash recovery, and race-condition test matrix](https://github.com/lost-rob0t/starintel-server/issues/33) 25. [#34 Enforce one total process thread budget across actors, consumers, tasks, HTTP, timers, and transports](https://github.com/lost-rob0t/starintel-server/issues/34) 26. [#35 Introduce workload-specific dispatchers and cl-gserver router pools](https://github.com/lost-rob0t/starintel-server/issues/35) 27. [#36 Add bounded mailboxes, admission control, and structured overload results](https://github.com/lost-rob0t/starintel-server/issues/36) 28. [#37 Implement managed startup, graceful shutdown, reconnect, and owned-thread cleanup](https://github.com/lost-rob0t/starintel-server/issues/37) 29. [#38 Fix Docker, Compose, launcher, configuration, and secret-handling failures](https://github.com/lost-rob0t/starintel-server/issues/38) # P1 — Importable library and deployable service Begin after the relevant P0 contracts and regression suites exist. 1. [#39 Split the embeddable StarIntel Server library from the service executable](https://github.com/lost-rob0t/starintel-server/issues/39) 2. [#40 Define the public library API, runtime object, and dependency-injection ports](https://github.com/lost-rob0t/starintel-server/issues/40) 3. [#41 Extract HTTP, RabbitMQ, CouchDB, Valkey, and scheduler adapters from domain services](https://github.com/lost-rob0t/starintel-server/issues/41) 4. [#42 Add component handles, registry, readiness, and dependency-aware health](https://github.com/lost-rob0t/starintel-server/issues/42) 5. [#43 Implement actor manifests and dataset manifests as validated runtime configuration](https://github.com/lost-rob0t/starintel-server/issues/43) 6. [#44 Repair the matcher and URL-extractor document pipeline](https://github.com/lost-rob0t/starintel-server/issues/44) 7. [#45 Rebuild user-hunt as a bounded router pool or remove the dead subsystem](https://github.com/lost-rob0t/starintel-server/issues/45) 8. [#46 Add structured metrics, tracing, audit events, and operational diagnostics](https://github.com/lost-rob0t/starintel-server/issues/46) 9. [#47 Add end-to-end idempotency and duplicate suppression across HTTP, Rabbit, persistence, targets, and leases](https://github.com/lost-rob0t/starintel-server/issues/47) 10. [#48 Stabilize packages, configuration schema, API versioning, and generated documentation](https://github.com/lost-rob0t/starintel-server/issues/48) # P2 — Auto-research, managed runtime, validation, and release process 1. [#49 Integrate resumable auto-research and analysis jobs as a bounded service subsystem](https://github.com/lost-rob0t/starintel-server/issues/49) 2. [#50 Synchronize auto-research designs with implementation issues, tests, commits, and runtime evidence](https://github.com/lost-rob0t/starintel-server/issues/50) 3. [#51 Add managed supervision, failure policy, and router lifecycle aligned with the cl-gserver roadmap](https://github.com/lost-rob0t/starintel-server/issues/51) 4. [#52 Add load, chaos, restart, and dependency-failover validation](https://github.com/lost-rob0t/starintel-server/issues/52) 5. [#53 Establish Git Flow and reconcile the diverged dev/master histories without moving branches during the audit](https://github.com/lost-rob0t/starintel-server/issues/53) ## Completion gate This roadmap is complete only when: - all P0 defects have regression coverage and pass - the library can load with zero network/thread side effects - the service composes the same public API used by embedded callers - authentication, authorization, leases, fencing, thread budgets, backpressure, recovery, and shutdown invariants are demonstrated - auto-research design/evidence links are synchronized - the branch reconciliation/release process is executed through reviewed PRs rather than direct ref movement.