modernize(runtime): align BBPD with current StarIntel identity and wire contracts #1

Merged

nsaspy merged 1 commit from modernize/starintel-runtime-adapter into master 2026-09-07 02:49:55 +00:00

Conversation 0 Commits 1 Files changed 18 +737 -23

nsaspy commented 2026-09-06 16:40:27 +00:00

Owner

Copy link

Summary

BBPD stays BBPD. This PR modernizes the runtime/integration layer around the existing Pykka tool actors without rewriting any domain logic and without porting anything to StarLang.

Architecture before / after

BEFORE
  BBPD tool actors (Pykka, unchanged behavior)
    -> plain event payload (relies on server decode defaults)
    -> binds only legacy actors.<actor>.new.target
    -> no star:// identity
AFTER
  BBPD tool actors (unchanged)
    -> bbp.runtime adapter: star_uri identity + actorevent contract
    -> dual target bindings: canonical documents.target.dispatch.<actor> + legacy compat
    -> canonical actor manifest published at startup
    -> modern StarIntel runtime/protocol (starintel-server) -> RabbitMQ/CouchDB

Migration matrix (derived and cross-checked in Prolog; 10 components)

Component	Action	StarLang seam
topology	bind canonical + compat keys via TOML templates	none (deployment material)
rabbit	keep per-thread ownership; reconnect covered by tests	none (transport adapter)
consumer	unchanged intake; queue shared by both key generations	intake adapter
tool_actor	behavior preserved; run-identity rules recorded	becomes StarLang keyed program actor (STAR-LANG-RESEARCH-014/016)
publisher_pool	settlement kept; documented as transport adapter	none — RabbitMQ stays (STAR-RESEARCH-041)
dns_resolver	settlement kept; event contract aligned	StarLang domain actor later (STAR-LANG-RESEARCH-017)
events	emit dtype=actorevent + generation	journal records later
document_boundary	pin kept (0.9.0 == upstream tip)	StarLang typed contracts (024/025)
config	optional star_authority; templates unchanged in spirit	deployment material
deployment	STAR manifest at startup	deployment material

Auto-research used

• STAR-RESEARCH-041 (approved): RFC 3986 star://authority/resource-kind/path identity; legacy tuple is compat-input-only; RabbitMQ owns durable dataflow.
• STAR-LANG-004 (approved): BBPD authority examples (star://bbpd.starintel.actor/actor/nmap); manifest identity vs transport endpoints.
• STAR-LANG-RESEARCH-014/016/017: BBP domain server, run identity (program-id+run-id+tool+target, star.bbp.* terminal codes), runtime journal/reconnect.
• Current source (authoritative): starintel-server target-dispatch.lisp:69-98 (canonical dispatch key + compat), event-actor.lisp:24-131 (actorevent contract, lenient defaults), rabbit.lisp (ingest keys); starintel-doc 980f7a2 == master tip (pin is current).
• New artifact: STAR-RESEARCH-060 (starintel-auto-research, branch research/star-bbpd-runtime-modernization, pushed to forgejo+github) records the reconciliation and this matrix.

Compatibility decisions

• target_key (legacy) stays bound; target_dispatch_key (canonical) is optional TOML — old configs keep working unchanged.
• Events now carry dtype/generation the server previously defaulted — no schema change, no behavior change server-side.
• Legacy star://domain:address:actor-name parse exists only behind an explicit parse_legacy_star_uri API and is never emitted.
• No new dependencies. AGENT.md thread-safety and template constraints respected.

Tests performed

• full pytest suite green (incl. 31 new tests): canonical URI rules (userinfo/port/dot-segments/query/fragment/trailing-slash rejected), legacy compat parsing, dual-key topology bindings, queue-declaration dedup, actorevent contract
• new live-broker test: both dispatch generations deliver to the same BBPD queue (disposable rabbitmq:3-alpine)
• existing RabbitMQ integration tests green
• ruff check bbp tests clean; python -m compileall clean
• live startup/shutdown smoke: service declares dual-key topology and publishes service-ready with dtype: actorevent and manifest subfinder@star://bbpd.smoke.actor/actor/subfinder on the wire
• prolog-verify gate: verification passed at HEAD e3d5646

Remaining legacy components

• Pykka/pika runtime (intentional — StarLang migration is out of scope)
• legacy target key binding (kept for older starintel-server generations; removable once servers publish only the canonical key)
• starintel-doc git pin (currently the upstream tip; bump with the next schema release)

StarLang migration points

Marked TODO(starlang-migration) in bbp/star_uri.py, bbp/tool_actor.py, bbp/document_boundary.py, bbp/dns_resolver.py, bbp/publisher_pool.py, bbp/main.py; the README "Future StarLang migration" section lists each seam, its replacement, and the research artifact that must stabilize first. BBPD is not ported to StarLang.

## Summary BBPD stays BBPD. This PR modernizes the runtime/integration layer **around** the existing Pykka tool actors without rewriting any domain logic and without porting anything to StarLang. ## Architecture before / after ```text BEFORE BBPD tool actors (Pykka, unchanged behavior) -> plain event payload (relies on server decode defaults) -> binds only legacy actors.<actor>.new.target -> no star:// identity AFTER BBPD tool actors (unchanged) -> bbp.runtime adapter: star_uri identity + actorevent contract -> dual target bindings: canonical documents.target.dispatch.<actor> + legacy compat -> canonical actor manifest published at startup -> modern StarIntel runtime/protocol (starintel-server) -> RabbitMQ/CouchDB ``` ## Migration matrix (derived and cross-checked in Prolog; 10 components) | Component | Action | StarLang seam | |---|---|---| | topology | bind canonical + compat keys via TOML templates | none (deployment material) | | rabbit | keep per-thread ownership; reconnect covered by tests | none (transport adapter) | | consumer | unchanged intake; queue shared by both key generations | intake adapter | | tool_actor | behavior preserved; run-identity rules recorded | becomes StarLang keyed program actor (STAR-LANG-RESEARCH-014/016) | | publisher_pool | settlement kept; documented as transport adapter | none — RabbitMQ stays (STAR-RESEARCH-041) | | dns_resolver | settlement kept; event contract aligned | StarLang domain actor later (STAR-LANG-RESEARCH-017) | | events | emit dtype=actorevent + generation | journal records later | | document_boundary | pin kept (0.9.0 == upstream tip) | StarLang typed contracts (024/025) | | config | optional star_authority; templates unchanged in spirit | deployment material | | deployment | STAR manifest at startup | deployment material | ## Auto-research used - **STAR-RESEARCH-041** (approved): RFC 3986 `star://authority/resource-kind/path` identity; legacy tuple is compat-input-only; RabbitMQ owns durable dataflow. - **STAR-LANG-004** (approved): BBPD authority examples (`star://bbpd.starintel.actor/actor/nmap`); manifest identity vs transport endpoints. - **STAR-LANG-RESEARCH-014/016/017**: BBP domain server, run identity (`program-id+run-id+tool+target`, `star.bbp.*` terminal codes), runtime journal/reconnect. - **Current source** (authoritative): starintel-server `target-dispatch.lisp:69-98` (canonical dispatch key + compat), `event-actor.lisp:24-131` (actorevent contract, lenient defaults), `rabbit.lisp` (ingest keys); starintel-doc `980f7a2` == master tip (pin is current). - **New artifact**: STAR-RESEARCH-060 (`starintel-auto-research`, branch `research/star-bbpd-runtime-modernization`, pushed to forgejo+github) records the reconciliation and this matrix. ## Compatibility decisions - `target_key` (legacy) stays bound; `target_dispatch_key` (canonical) is optional TOML — old configs keep working unchanged. - Events now carry `dtype`/`generation` the server previously defaulted — no schema change, no behavior change server-side. - Legacy `star://domain:address:actor-name` parse exists only behind an explicit `parse_legacy_star_uri` API and is never emitted. - No new dependencies. AGENT.md thread-safety and template constraints respected. ## Tests performed - full pytest suite green (incl. 31 new tests): canonical URI rules (userinfo/port/dot-segments/query/fragment/trailing-slash rejected), legacy compat parsing, dual-key topology bindings, queue-declaration dedup, actorevent contract - new live-broker test: both dispatch generations deliver to the same BBPD queue (disposable `rabbitmq:3-alpine`) - existing RabbitMQ integration tests green - `ruff check bbp tests` clean; `python -m compileall` clean - live startup/shutdown smoke: service declares dual-key topology and publishes `service-ready` with `dtype: actorevent` and manifest `subfinder@star://bbpd.smoke.actor/actor/subfinder` on the wire - prolog-verify gate: **verification passed** at HEAD e3d5646 ## Remaining legacy components - Pykka/pika runtime (intentional — StarLang migration is out of scope) - legacy target key binding (kept for older starintel-server generations; removable once servers publish only the canonical key) - `starintel-doc` git pin (currently the upstream tip; bump with the next schema release) ## StarLang migration points Marked `TODO(starlang-migration)` in `bbp/star_uri.py`, `bbp/tool_actor.py`, `bbp/document_boundary.py`, `bbp/dns_resolver.py`, `bbp/publisher_pool.py`, `bbp/main.py`; the README "Future StarLang migration" section lists each seam, its replacement, and the research artifact that must stabilize first. BBPD is **not** ported to StarLang.

nsaspy added 1 commit 2026-09-06 16:40:27 +00:00

modernize(runtime): align BBPD with current StarIntel identity and wire contracts ... e3d564629d

BBPD stays BBPD: tool actors, parsers, settlement, and provenance are
unchanged. The runtime boundary is modernized around them:

- add bbp.star_uri: RFC 3986 star://authority/actor/<path> canonicalization
  per STAR-RESEARCH-041 / STAR-LANG-004, with the legacy
  star://domain:address:actor-name tuple as bounded compat input only
- add optional [service].star_authority and publish a canonical actor
  manifest at startup
- bind actor queues to both the canonical documents.target.dispatch.<actor>
  key (starintel-server durable coordinator) and the legacy
  actors.<actor>.new.target compat key; templates stay in TOML and the
  dispatch template is optional for older deployments
- emit dtype=actorevent and generation on actor events per the
  starintel-server event contract instead of relying on decode defaults
- dedupe queue declarations when one queue binds multiple keys
- document the architecture layering and Future StarLang Migration seam
  (TODO(starlang-migration) annotations) without porting anything to StarLang

Tests: canonical URI rules, legacy compat parsing, dual-key topology
bindings, actorevent contract, plus a live-broker test proving both
dispatch generations deliver to the same queue. Full suite and ruff green;
RabbitMQ integration tests green against a disposable broker; live
startup/shutdown smoke verified the manifest on the wire.

Research: STAR-RESEARCH-060 in starintel-auto-research (forgejo origin
branch research/star-bbpd-runtime-modernization).

nsaspy referenced this pull request from starintel-labs/starintel-server 2026-09-06 17:04:06 +00:00

Adopt canonical star:// resource identity (STAR-SERVER-041 Phase A/D): CL URI library, gserver authority, conformance fixtures #1

nsaspy referenced this pull request 2026-09-06 19:12:31 +00:00

Remove unsafe ad hoc STAR URI implementation from runtime modernization #2

nsaspy merged commit 5f584014e4 into master 2026-09-07 02:49:55 +00:00

nsaspy referenced this pull request from a commit 2026-09-07 02:49:57 +00:00

modernize(runtime): align BBPD with current StarIntel identity and wire contracts (#1)

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

nsaspy/star-bbpd!1

No description provided.