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

New issue

Open

opened 2026-09-06 17:04:06 +00:00 by nsaspy · 1 comment

nsaspy commented 2026-09-06 17:04:06 +00:00

Owner

Copy link

Verification result

starintel-server does not support star:// URIs today. Verified at 8fb297d146e7332fae7e38170b5b49d49530ac53 (2026-08-29):

• grep -rn "star://" source/ docs/ schema/ → zero matches
• no star-uri / service-uri / StarRouter / resource-kind / authority concepts anywhere in source or docs
• the only URI machinery is the quri HTTP dependency (source/starintel-gserver.asd:92)
• actor identity is a plain string regex (source/target-dispatch.lisp:65-67); external actors are addressed purely by RabbitMQ routing key (source/actors.lisp:209-216)
• actor manifests exist only for local Sento actors (docs/actors.org:89-100); there is no capability/identity registry for remote actors

Meanwhile the rest of the ecosystem has already moved:

Component	star:// status	Evidence
STAR-RESEARCH-041	APPROVED protocol (RFC 3986 authority model)	auto-research #137, operator approvals
STAR-SERVER-040/041 design	APPROVED design, implementation NOT STARTED	roam/design/star-server/STAR-SERVER-041-*.org Phase A–E
star-lang service-uri.lisp	emits only the legacy tuple star://domain:address:actor-name	star-actor-protocol/src/service-uri.lisp:55,63
star-bbpd	emits + consumes canonical star://bbpd.../actor/<name> (merged this week, PR nsaspy/star-bbpd#1)	bbp/star_uri.py, startup manifest event
starintel-server	nothing	this issue

The server is now the lagging side of its own approved protocol.

Problem

1. No logical identity: documents, targets, and services are addressable only through transport artifacts (RabbitMQ keys, CouchDB _ids, HTTP paths). STAR-RESEARCH-041 requires transport-neutral identity: star://<authority>/<resource-kind>/<resource-path>.
2. No authority ownership: STAR-SERVER-041 Phase D assigns the gserver a configured stable authority that owns /document/... /target/... /dataset/... /relation/... /job/... /service/... /actor/... namespaces and advertises implemented prefixes. Nothing in the server registers or advertises one.
3. No Common Lisp conformance surface: Phase A requires shared parse/serialize fixtures with "Common Lisp/Nim semantic equivalence" (Conformance Requirements 1–12). The CL implementation does not exist, so cross-language conformance cannot even start.
4. Legacy tuple still emitted by star-lang and there is no server-side compatibility/migration boundary for it (parse_legacy_star_uri equivalents + explicit migration targets).
5. Ecosystem drift: star-bbpd now publishes canonical actor URIs (subfinder@star://bbpd.smoke.actor/actor/subfinder observed on the wire in E2E smoke), but the server that routes its targets cannot represent, validate, or echo them.

Approved basis (do not re-litigate)

• STAR-RESEARCH-041 (APPROVED, issue #137): RFC 3986 syntax authority; lowercase authority; no userinfo/port/dot-segments/query/fragment; pchar paths; resource-kind registry (document actor service target dataset relation job); legacy tuple is compatibility input only; migration requires explicit targets.
• STAR-SERVER-040 (design): leased registration, deadlines, cancellation, canonical operations — authority routing must reuse it, not fork it.
• STAR-SERVER-041 (design): Phase A reusable URI library, Phase B StarRouter routing, Phase D starintel-gserver authority — the two phases this issue covers; Phase C (StarLang) and Phase E (FediWatch) are separate.
• STAR-LANG-004 (APPROVED): manifest identity vs runtime descriptors; cross-process resolution delegates to StarRouter; no second distributed registry.

Scope (this repo)

1. Phase A (CL half): reusable STAR URI library
   • new system/package (e.g. star-uri) with RFC 3986 parsing, STAR v1 profile validation/canonicalization, immutable URI value, resource-kind/path helpers;
   • legacy star://domain:address:actor-name parser confined to a compatibility module; explicit migration API requiring a canonical target;
   • conformance fixtures implementing STAR-SERVER-041 items 1–12 (authority case normalization, percent-encoding, rejections, one/multi-segment actor paths proving no domain slot, legacy compat parse, explicit migration validation).
2. Phase D: gserver authority ownership
   • configured stable authority (setting + env, mirroring COUCHDB_DATABASE conventions);
   • registration/advertisement of implemented resource prefixes and capabilities (data only — StarRouter forwarding itself stays out of scope);
   • native STAR resource URIs surfaced where the server already exposes addressable resources: HTTP document/target responses, actor registry records, target acceptance records (source/target-dispatch.lisp:181-192), and the MCP service URIs — as additional fields, not schema-breaking changes;
   • RabbitMQ bindings stay unchanged: documents.target.dispatch.<actor> remains the delivery key; STAR URI is identity metadata (STAR-RESEARCH-041: "identity and durable work transport are separate concerns").
3. Compatibility
   • accept legacy tuple input only through the compat API, validate against explicit migration targets, never emit it in new code;
   • existing routing keys, strict v0.9 ingest, and the actors.<actor>.new.target compat key keep working unchanged.

Non-scope

• StarLang port of any server code (Phase C lives in star-lang);
• StarRouter broker/router implementation (separate repo, Phase B);
• FediWatch RabbitMQ migration (Phase E);
• changing the strict v0.9 document schema or CouchDB _id conventions;
• per-actor AMQP authentication changes.

Acceptance criteria

1. CL STAR URI library passes the shared Phase A fixtures (1–12) and fixture files are importable by star-lang's conformance harness;
2. server exposes a configured authority and advertises implemented prefixes/capabilities;
3. target acceptance and actor registry records carry canonical STAR URIs alongside existing fields;
4. HTTP/MCP responses expose native STAR resource URIs for existing resources;
5. legacy tuple parsing exists only in the compatibility module and new code emits zero legacy tuples (grep-gated test);
6. strict v0.9 ingest/update validation unchanged (rabbit.lisp:67-75 byte-for-byte behavior);
7. documents.target.dispatch.<actor> + actors.<actor>.new.target behavior unchanged;
8. all existing tests plus new conformance suite green at exact head; CI green on both hosts.

References

• auto-research: STAR-RESEARCH-041, STAR-SERVER-040, STAR-SERVER-041 (design), STAR-LANG-004, STAR-RESEARCH-060 (star-bbpd modernization, already consumes canonical URIs)
• source: source/target-dispatch.lisp:65-98,181-192, source/actors.lisp:209-216, source/actor-systems/event-actor.lisp:24-131, source/starintel-gserver.asd:92

## Verification result starintel-server does **not** support `star://` URIs today. Verified at `8fb297d146e7332fae7e38170b5b49d49530ac53` (2026-08-29): - `grep -rn "star://" source/ docs/ schema/` → **zero matches** - no `star-uri` / `service-uri` / StarRouter / resource-kind / authority concepts anywhere in source or docs - the only URI machinery is the `quri` HTTP dependency (`source/starintel-gserver.asd:92`) - actor identity is a plain string regex (`source/target-dispatch.lisp:65-67`); external actors are addressed purely by RabbitMQ routing key (`source/actors.lisp:209-216`) - actor manifests exist only for local Sento actors (`docs/actors.org:89-100`); there is no capability/identity registry for remote actors Meanwhile the rest of the ecosystem has already moved: | Component | star:// status | Evidence | |---|---|---| | STAR-RESEARCH-041 | APPROVED protocol (RFC 3986 authority model) | auto-research #137, operator approvals | | STAR-SERVER-040/041 design | APPROVED design, **implementation NOT STARTED** | `roam/design/star-server/STAR-SERVER-041-*.org` Phase A–E | | star-lang `service-uri.lisp` | emits only the **legacy tuple** `star://domain:address:actor-name` | `star-actor-protocol/src/service-uri.lisp:55,63` | | star-bbpd | emits + consumes canonical `star://bbpd.../actor/<name>` (merged this week, PR nsaspy/star-bbpd#1) | `bbp/star_uri.py`, startup manifest event | | starintel-server | **nothing** | this issue | The server is now the lagging side of its own approved protocol. ## Problem 1. **No logical identity**: documents, targets, and services are addressable only through transport artifacts (RabbitMQ keys, CouchDB `_id`s, HTTP paths). STAR-RESEARCH-041 requires transport-neutral identity: `star://<authority>/<resource-kind>/<resource-path>`. 2. **No authority ownership**: STAR-SERVER-041 Phase D assigns the gserver a configured stable authority that owns `/document/... /target/... /dataset/... /relation/... /job/... /service/... /actor/...` namespaces and advertises implemented prefixes. Nothing in the server registers or advertises one. 3. **No Common Lisp conformance surface**: Phase A requires shared parse/serialize fixtures with "Common Lisp/Nim semantic equivalence" (Conformance Requirements 1–12). The CL implementation does not exist, so cross-language conformance cannot even start. 4. **Legacy tuple still emitted by star-lang** and there is no server-side compatibility/migration boundary for it (`parse_legacy_star_uri` equivalents + explicit migration targets). 5. **Ecosystem drift**: star-bbpd now publishes canonical actor URIs (`subfinder@star://bbpd.smoke.actor/actor/subfinder` observed on the wire in E2E smoke), but the server that routes its targets cannot represent, validate, or echo them. ## Approved basis (do not re-litigate) - STAR-RESEARCH-041 (APPROVED, issue #137): RFC 3986 syntax authority; lowercase authority; no userinfo/port/dot-segments/query/fragment; pchar paths; resource-kind registry (`document actor service target dataset relation job`); legacy tuple is compatibility input only; migration requires explicit targets. - STAR-SERVER-040 (design): leased registration, deadlines, cancellation, canonical operations — authority routing must reuse it, not fork it. - STAR-SERVER-041 (design): Phase A reusable URI library, Phase B StarRouter routing, **Phase D starintel-gserver authority** — the two phases this issue covers; Phase C (StarLang) and Phase E (FediWatch) are separate. - STAR-LANG-004 (APPROVED): manifest identity vs runtime descriptors; cross-process resolution delegates to StarRouter; no second distributed registry. ## Scope (this repo) 1. **Phase A (CL half): reusable STAR URI library** - new system/package (e.g. `star-uri`) with RFC 3986 parsing, STAR v1 profile validation/canonicalization, immutable URI value, resource-kind/path helpers; - legacy `star://domain:address:actor-name` parser confined to a compatibility module; explicit migration API requiring a canonical target; - conformance fixtures implementing STAR-SERVER-041 items 1–12 (authority case normalization, percent-encoding, rejections, one/multi-segment actor paths proving no `domain` slot, legacy compat parse, explicit migration validation). 2. **Phase D: gserver authority ownership** - configured stable authority (setting + env, mirroring `COUCHDB_DATABASE` conventions); - registration/advertisement of implemented resource prefixes and capabilities (data only — StarRouter forwarding itself stays out of scope); - native STAR resource URIs surfaced where the server already exposes addressable resources: HTTP document/target responses, actor registry records, target acceptance records (`source/target-dispatch.lisp:181-192`), and the MCP service URIs — as **additional fields**, not schema-breaking changes; - RabbitMQ bindings stay unchanged: `documents.target.dispatch.<actor>` remains the delivery key; STAR URI is identity metadata (STAR-RESEARCH-041: "identity and durable work transport are separate concerns"). 3. **Compatibility** - accept legacy tuple input only through the compat API, validate against explicit migration targets, never emit it in new code; - existing routing keys, strict v0.9 ingest, and the `actors.<actor>.new.target` compat key keep working unchanged. ## Non-scope - StarLang port of any server code (Phase C lives in star-lang); - StarRouter broker/router implementation (separate repo, Phase B); - FediWatch RabbitMQ migration (Phase E); - changing the strict v0.9 document schema or CouchDB `_id` conventions; - per-actor AMQP authentication changes. ## Acceptance criteria 1. CL STAR URI library passes the shared Phase A fixtures (1–12) and fixture files are importable by star-lang's conformance harness; 2. server exposes a configured authority and advertises implemented prefixes/capabilities; 3. target acceptance and actor registry records carry canonical STAR URIs alongside existing fields; 4. HTTP/MCP responses expose native STAR resource URIs for existing resources; 5. legacy tuple parsing exists only in the compatibility module and new code emits zero legacy tuples (grep-gated test); 6. strict v0.9 ingest/update validation unchanged (`rabbit.lisp:67-75` byte-for-byte behavior); 7. `documents.target.dispatch.<actor>` + `actors.<actor>.new.target` behavior unchanged; 8. all existing tests plus new conformance suite green at exact head; CI green on both hosts. ## References - auto-research: STAR-RESEARCH-041, STAR-SERVER-040, STAR-SERVER-041 (design), STAR-LANG-004, STAR-RESEARCH-060 (star-bbpd modernization, already consumes canonical URIs) - source: `source/target-dispatch.lisp:65-98,181-192`, `source/actors.lisp:209-216`, `source/actor-systems/event-actor.lisp:24-131`, `source/starintel-gserver.asd:92`

nsaspy commented 2026-09-06 17:04:48 +00:00

Author

Owner

Copy link

Implementation prompt (copy into the agent loop / implementation slot)

Mission. Implement STAR-SERVER-041 Phase A (Common Lisp half) and Phase D (starintel-gserver authority) in starintel-labs/starintel-server. Do not re-research the URI protocol: STAR-RESEARCH-041 and STAR-SERVER-041 are approved and normative. Phase C (StarLang) and Phase E (FediWatch) are out of scope.

Ground rules.

• Current source and tests are authoritative over prose. Read docs/testing.md before writing tests: canonical entries are (asdf:test-system :starintel-gserver-tests) via nix run .#star-unit-tests (hermetic, FiveAM) and :starintel-gserver-integration-tests via nix run .#star-integration-tests (needs CouchDB+RabbitMQ). A suite that discovers or executes zero tests FAILS.
• TDD-first in the STAR-SERVER-041 order: write the Phase A conformance fixtures before the library (items 1–12 of Conformance Requirements), then implement, then wire Phase D.
• One narrowly-scoped commit per iteration; keep diffs minimal; no formatting-only refactors.
• Never emit the legacy tuple star://domain:address:actor-name from new code; grep-gate it.

Slice 1 — Phase A fixtures (TDD).
Create t/star-uri-test.lisp + fixture data files shared with star-lang's harness layout. Cover: RFC 3986 parse/serialize round-trips; lowercase authority normalization; percent-encoding normalization (unreserved → unreserved, hex uppercase); rejection of userinfo, ports, dot segments, query, fragment, malformed escapes, empty/missing resource kind; path case preservation; one- and multi-segment actor paths with NO fixed domain slot; legacy tuple parse via compat API only; explicit migration-target validation (reject non-canonical targets).

Slice 2 — Phase A library.
New ASDF system/package star-uri (add to source/starintel-gserver.asd). API: parse (error taxonomy: malformed vs noncanonical), canonical serialize, accessors authority / resource-kind / resource-path (no domain/address/actor-name accessors), immutable value, resource-kind registry restricted to document actor service target dataset relation job, and a separate compatibility module with parse-legacy-star-uri + migrate-legacy-star-uri (uri target) requiring a canonical target URI. Reuse quri for RFC parsing where it fits; do not fork URI grammar.

Slice 3 — Phase D authority configuration.
Settings: STAR_AUTHORITY env + settings default (illustrative gserver.starintel.actor; never hardcode as "the" production name), validated through the new library at startup; startup log/config surface prints the authority.

Slice 4 — Phase D identity wiring (additive only).

• target acceptance records (source/target-dispatch.lisp:181-192) gain star-uri metadata alongside existing fields;
• actor registry/manifest records for remote actors gain a canonical actor URI built from the authority + actor path;
• HTTP document/target responses and the MCP service URIs expose star://<authority>/document/<_id>-style resource URIs as additional response fields;
• keep documents.target.dispatch.<actor> and actors.<actor>.new.target keys, strict v0.9 ingest (rabbit.lisp:67-75), and CouchDB _id conventions byte-for-byte unchanged. STAR URI is identity metadata; RabbitMQ remains the durable transport (STAR-RESEARCH-041).

Slice 5 — Conformance + interop gates.

• unit suite green: nix run .#star-unit-tests;
• integration suite green: nix run .#star-integration-tests;
• cross-language check: run the shared fixtures against star-lang's URI harness (Phase A item 12, CL↔CL for now; Nim equivalence tracked separately);
• interop smoke with star-bbpd modernize/starintel-runtime-adapter: BBPD startup manifest URIs parse under the server's library and the server validates its own emitted URIs;
• grep-gate: no legacy tuple emission in source/ outside the compat module;
• both hosts CI green (forgejo primary, github mirror) at exact head.

Definition of done. All slices merged behind green gates; complete in the PR description maps each acceptance criterion of issue #1 to a test name; no approval-table bypass in auto-research (this implements the already-approved research; no new research artifact is needed — cross-reference STAR-SERVER-041 Phase A/D instead).

Interop contact points. star-bbpd: bbp/star_uri.py (canonical v1 rules), startup manifest event; server: source/target-dispatch.lisp, docs/actors.org, docs/messaging.org (update these docs in the same slices that change behavior).

## Implementation prompt (copy into the agent loop / implementation slot) **Mission.** Implement STAR-SERVER-041 **Phase A (Common Lisp half)** and **Phase D (starintel-gserver authority)** in `starintel-labs/starintel-server`. Do not re-research the URI protocol: STAR-RESEARCH-041 and STAR-SERVER-041 are approved and normative. Phase C (StarLang) and Phase E (FediWatch) are out of scope. **Ground rules.** - Current source and tests are authoritative over prose. Read `docs/testing.md` before writing tests: canonical entries are `(asdf:test-system :starintel-gserver-tests)` via `nix run .#star-unit-tests` (hermetic, FiveAM) and `:starintel-gserver-integration-tests` via `nix run .#star-integration-tests` (needs CouchDB+RabbitMQ). A suite that discovers or executes zero tests FAILS. - TDD-first in the STAR-SERVER-041 order: write the Phase A conformance fixtures before the library (items 1–12 of Conformance Requirements), then implement, then wire Phase D. - One narrowly-scoped commit per iteration; keep diffs minimal; no formatting-only refactors. - Never emit the legacy tuple `star://domain:address:actor-name` from new code; grep-gate it. **Slice 1 — Phase A fixtures (TDD).** Create `t/star-uri-test.lisp` + fixture data files shared with star-lang's harness layout. Cover: RFC 3986 parse/serialize round-trips; lowercase authority normalization; percent-encoding normalization (unreserved → unreserved, hex uppercase); rejection of userinfo, ports, dot segments, query, fragment, malformed escapes, empty/missing resource kind; path case preservation; one- and multi-segment actor paths with NO fixed `domain` slot; legacy tuple parse via compat API only; explicit migration-target validation (reject non-canonical targets). **Slice 2 — Phase A library.** New ASDF system/package `star-uri` (add to `source/starintel-gserver.asd`). API: parse (error taxonomy: malformed vs noncanonical), canonical serialize, accessors `authority` / `resource-kind` / `resource-path` (no `domain`/`address`/`actor-name` accessors), immutable value, `resource-kind` registry restricted to `document actor service target dataset relation job`, and a **separate compatibility module** with `parse-legacy-star-uri` + `migrate-legacy-star-uri (uri target)` requiring a canonical target URI. Reuse `quri` for RFC parsing where it fits; do not fork URI grammar. **Slice 3 — Phase D authority configuration.** Settings: `STAR_AUTHORITY` env + settings default (illustrative `gserver.starintel.actor`; never hardcode as "the" production name), validated through the new library at startup; startup log/config surface prints the authority. **Slice 4 — Phase D identity wiring (additive only).** - target acceptance records (`source/target-dispatch.lisp:181-192`) gain `star-uri` metadata alongside existing fields; - actor registry/manifest records for remote actors gain a canonical actor URI built from the authority + actor path; - HTTP document/target responses and the MCP service URIs expose `star://<authority>/document/<_id>`-style resource URIs as additional response fields; - keep `documents.target.dispatch.<actor>` and `actors.<actor>.new.target` keys, strict v0.9 ingest (`rabbit.lisp:67-75`), and CouchDB `_id` conventions byte-for-byte unchanged. STAR URI is identity metadata; RabbitMQ remains the durable transport (STAR-RESEARCH-041). **Slice 5 — Conformance + interop gates.** - unit suite green: `nix run .#star-unit-tests`; - integration suite green: `nix run .#star-integration-tests`; - cross-language check: run the shared fixtures against star-lang's URI harness (Phase A item 12, CL↔CL for now; Nim equivalence tracked separately); - interop smoke with star-bbpd `modernize/starintel-runtime-adapter`: BBPD startup manifest URIs parse under the server's library and the server validates its own emitted URIs; - grep-gate: no legacy tuple emission in `source/` outside the compat module; - both hosts CI green (forgejo primary, github mirror) at exact head. **Definition of done.** All slices merged behind green gates; `complete` in the PR description maps each acceptance criterion of issue #1 to a test name; no approval-table bypass in auto-research (this implements the already-approved research; no new research artifact is needed — cross-reference STAR-SERVER-041 Phase A/D instead). **Interop contact points.** star-bbpd: `bbp/star_uri.py` (canonical v1 rules), startup manifest event; server: `source/target-dispatch.lisp`, `docs/actors.org`, `docs/messaging.org` (update these docs in the same slices that change behavior).

nsaspy referenced this issue from a commit 2026-09-06 18:53:39 +00:00

feat: canonical STAR URI actor identity for target dispatch (STAR-SERVER-041)

nsaspy referenced this issue 2026-09-06 18:54:20 +00:00

feat: canonical STAR URI actor identity for target dispatch (STAR-SERVER-041) #2

Sign in to join this conversation.

No Branch/Tag specified

Branches Tags

master

codex/10-forgejo-nix-path

codex/17-proxy-gateway

fix/189-release-terminal-bulk-payloads

fix/187-concurrent-ulid-quarantine

feat/ingest-tenant-adapter

feat/valkey-lease-runtime

feat/observability-slice

rage/staging-youtube-actor

rage/5-http-contract-documents

fix/v09-false-value-pipeline

agent/star-uri-identity-compat

agent/emacs-osint-workbench

agent/emacs-client-contract

dev

docs-document-star-server

deadlock

migrate-queue

api-improvements

docker-compose-fixes

fix-settings

lost-rob0t-patch-actions

patch-docker

update-deps

events

docs

detangle

No results found.

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

starintel-labs/starintel-server#1

No description provided.