starintel-labs/star-lang
3
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

Adopt the shared RFC 3986 STAR URI model as canonical actor identity #1

Open
nsaspy wants to merge 2 commits from agent/star-uri-canonical into main
pull from: agent/star-uri-canonical
merge into: starintel-labs:main
Conversation 1 Commits 2 Files changed 33 +1506 -366
nsaspy commented 2026-09-11 05:01:10 +00:00
Owner
Copy link

Goal

Resolve the STAR URI architecture conflict (issue #52, STAR-SERVER-041, STAR-LANG-004 amendment): final StarLang now uses the approved shared RFC-based STAR URI model as canonical actor/service identity, and the legacy star://domain:address:actor-name tuple is bounded compatibility input only.

Authoritative source

The approved grammar and rules are STAR-SERVER-041 (RFC 3986 star://authority/resource-kind/resource-path, canonicalization rules 1-12, reviewed resource-kind registry). The reviewed reference implementation lives in starintel-server source/star-uri.lisp + star-uri-legacy.lisp (temporary gserver-local layer whose replacement marker designates the shared StarLang library); this PR implements that same model in star-actor-protocol/src/star-uri.lisp and shares its conformance fixtures. No second URI parser/model was invented; nothing new was added under prototype/ (the service-uri shell only forwards the legacy API and the migration entry point).

RED evidence

Commit fdc8f75 adds the failing conformance/canonicalization tests first. Machine-recorded RED runs (--non-interactive, so failures cannot hide behind REPL exits): star-actor-protocol-tests, starlang-compiler-tests, and starlang-runtime all exited 1 at the base head (missing canonical API; tuple-only compiler/runtime). A gate-runner hazard was found and recorded in the KB: without --non-interactive the runner exits 0 on failure.

Exact semantic change

  • Canonical identity is the RFC 3986 profile: lowercase reg-name authority, no userinfo/ports, pchar segments with percent normalization, reviewed resource kinds, dot segments/query/fragment rejected.
  • A declared actor :service-uri must be a canonical actor URI whose terminal resource-path segment equals the actor contract name; one- and multi-segment paths are both valid with no domain semantics (STAR-LANG-004 manifest example honored).
  • Runtime defaults undeclared actors to star://local/actor/<name> (configurable authority).
  • Runtime directory entries validate canonical actor URIs plus optional :authority/:resource-kind/:resource-path metadata; :domain/:address are no longer validated fields.
  • star-actor-reference carries authority + resource-path (no domain-id/node-id/logical-path) and serializes canonical identity.
  • Wire dispatcher translates malformed or legacy-tuple URI targets into wire-dispatcher-invalid-actor-error.

Compatibility retained

  • The legacy tuple parses only through the explicit compatibility API (parse-star-service-uri and friends) and the prototype shell forwards it unchanged.
  • migrate-legacy-star-uri requires an explicit :to canonical target or :map migration map, normalizes immediately into the canonical representation, and never reuses the legacy domain as an authority (STAR-SERVER-041 forbids legacy. rewrites).
  • Bare actor-name addressing at runtime/dispatch remains valid and bounded.

Tests and gates (all green at head b467d04)

  • star-actor-protocol-tests (shared RFC conformance fixtures, legacy compat, migration, references)
  • starlang-compiler-tests (35/35 FiveAM checks incl. fresh-SBCL proof)
  • starlang-runtime + wire dispatcher tests
  • starlang-prototype (34 child scripts, incl. updated service-uri compat tests)
  • bash ci/check-repository-contracts.sh, bash ci/check-prototype-migration.sh
  • nix flake check -L (all checks passed)

Docs updated: README migration map and actor-runtime state, ACTOR-RUNTIME-MIGRATION-MATRIX, migration ledger note, CHANGELOG; historical slice docs carry explicit superseded-URI notes; durable .prolog/kb facts (star-uri-architecture.pl, updated compiler-ownership/toolchain/verification-workflow) describe the same architecture.

## Goal Resolve the STAR URI architecture conflict (issue #52, STAR-SERVER-041, STAR-LANG-004 amendment): final StarLang now uses the approved shared RFC-based STAR URI model as canonical actor/service identity, and the legacy `star://domain:address:actor-name` tuple is bounded compatibility input only. ## Authoritative source The approved grammar and rules are STAR-SERVER-041 (RFC 3986 `star://authority/resource-kind/resource-path`, canonicalization rules 1-12, reviewed resource-kind registry). The reviewed reference implementation lives in starintel-server `source/star-uri.lisp` + `star-uri-legacy.lisp` (temporary gserver-local layer whose replacement marker designates the shared StarLang library); this PR implements that same model in `star-actor-protocol/src/star-uri.lisp` and shares its conformance fixtures. No second URI parser/model was invented; nothing new was added under `prototype/` (the service-uri shell only forwards the legacy API and the migration entry point). ## RED evidence Commit fdc8f75 adds the failing conformance/canonicalization tests first. Machine-recorded RED runs (`--non-interactive`, so failures cannot hide behind REPL exits): star-actor-protocol-tests, starlang-compiler-tests, and starlang-runtime all exited 1 at the base head (missing canonical API; tuple-only compiler/runtime). A gate-runner hazard was found and recorded in the KB: without `--non-interactive` the runner exits 0 on failure. ## Exact semantic change - Canonical identity is the RFC 3986 profile: lowercase reg-name authority, no userinfo/ports, pchar segments with percent normalization, reviewed resource kinds, dot segments/query/fragment rejected. - A declared actor `:service-uri` must be a canonical actor URI whose terminal resource-path segment equals the actor contract name; one- and multi-segment paths are both valid with no domain semantics (STAR-LANG-004 manifest example honored). - Runtime defaults undeclared actors to `star://local/actor/<name>` (configurable authority). - Runtime directory entries validate canonical actor URIs plus optional `:authority`/`:resource-kind`/`:resource-path` metadata; `:domain`/`:address` are no longer validated fields. - `star-actor-reference` carries authority + resource-path (no domain-id/node-id/logical-path) and serializes canonical identity. - Wire dispatcher translates malformed or legacy-tuple URI targets into `wire-dispatcher-invalid-actor-error`. ## Compatibility retained - The legacy tuple parses only through the explicit compatibility API (`parse-star-service-uri` and friends) and the prototype shell forwards it unchanged. - `migrate-legacy-star-uri` requires an explicit `:to` canonical target or `:map` migration map, normalizes immediately into the canonical representation, and never reuses the legacy domain as an authority (STAR-SERVER-041 forbids legacy.<domain> rewrites). - Bare actor-name addressing at runtime/dispatch remains valid and bounded. ## Tests and gates (all green at head b467d04) - star-actor-protocol-tests (shared RFC conformance fixtures, legacy compat, migration, references) - starlang-compiler-tests (35/35 FiveAM checks incl. fresh-SBCL proof) - starlang-runtime + wire dispatcher tests - starlang-prototype (34 child scripts, incl. updated service-uri compat tests) - `bash ci/check-repository-contracts.sh`, `bash ci/check-prototype-migration.sh` - `nix flake check -L` (all checks passed) Docs updated: README migration map and actor-runtime state, ACTOR-RUNTIME-MIGRATION-MATRIX, migration ledger note, CHANGELOG; historical slice docs carry explicit superseded-URI notes; durable `.prolog/kb` facts (`star-uri-architecture.pl`, updated compiler-ownership/toolchain/verification-workflow) describe the same architecture.
Final-system tests now assert the approved STAR-SERVER-041 RFC 3986
star://authority/resource-kind/resource-path identity model:

- star-actor-protocol gains the shared conformance fixture set (ported
  from the starintel-server STAR URI suite) covering parsing,
  canonicalization, v1 rejections, predicates, legacy-tuple separation,
  explicit legacy migration, and the authority/resource-path actor
  reference model.
- starlang-compiler actor tests, the fresh-process proof, and the
  actor fixture require canonical RFC actor URIs, accept one- and
  multi-segment actor resource paths, and reject the legacy tuple as
  canonical identity.
- starlang-runtime registry, runtime-directory, and wire dispatcher
  tests route on canonical URIs, validate authority/resource-kind/
  resource-path directory metadata, and reject legacy tuple input.
- portable wire, canonical JSON, scrape, and artifact test fixtures
  carry canonical URIs.
- prototype service-uri compatibility tests keep tuple parsing as
  bounded compat input and exercise migrate-legacy-star-uri.

All three final suites fail (RED) at this commit: the protocol
canonical API does not exist yet and final systems still treat the
legacy tuple as canonical.
feat(protocol): adopt the shared RFC 3986 STAR URI model as canonical identity
Some checks failed
StarLang artifact writer / JSON file writer actor (pull_request) Successful in 39s
Details
star-lang logic IR / Engine-free logic IR contract (pull_request) Failing after 43s
Details
SWI logic adapter / Real SWI MQI adapter (pull_request) Failing after 4s
Details
star-lang Nix / Real Sento actor/remoting integration (pull_request) Failing after 5s
Details
star-lang Nix / Nix flake check (pull_request) Failing after 5s
Details
StarLang production readiness / Prototype authority ledger (pull_request) Successful in 4s
Details
star-lang CI / SBCL ASDF contract (pull_request) Failing after 2m1s
Details
b467d04890 
Final StarLang now uses the approved shared STAR URI architecture
(STAR-SERVER-041, the STAR-LANG-004 amendment, and issue #52) instead of
treating the star://domain:address:actor-name tuple as canonical:

- star-actor-protocol owns the canonical model in src/star-uri.lisp: the
  RFC 3986 reg-name authority (lowercase, no userinfo, no transport
  ports), pchar path segments with percent-encoding normalization, the
  reviewed resource-kind registry, and the fail-closed v1 profile. The
  conformance fixtures are shared with the reviewed starintel-server STAR
  URI suite so no second grammar exists.
- The legacy tuple grammar is demoted to an explicit compatibility module
  (src/service-uri.lisp): parse-star-uri rejects it, it parses only via
  the legacy API, and migrate-legacy-star-uri requires an explicit :to
  canonical target or :map migration map, normalizing immediately into
  the canonical representation. The legacy domain never becomes an
  authority. The prototype shell forwards the legacy API and the
  migration entry point only; no URI authority is created under
  prototype/.
- Compiler actor lowering, portable manifests, the runtime registry, the
  runtime directory, and the deterministic wire dispatcher emit and
  resolve canonical RFC URIs only. A declared actor URI must address an
  actor resource and end its actor resource path with the actor contract
  name (one- and multi-segment paths both valid, deterministic and
  fail-closed). The runtime directory validates authority/resource-kind/
  resource-path metadata; :domain/:address are no longer validated
  fields. Undeclared actors default to star://local/actor/<name>.
- star-actor-reference now carries authority and resource-path instead
  of domain-id/node-id/logical-path and serializes canonical identity.
- Fixtures, prototype compatibility tests, scrape/artifact/canonical-JSON
  tests, README, the actor runtime migration matrix, the migration
  ledger, the changelog, and the durable Prolog KB describe the same
  architecture. Historical slice documents carry explicit superseded
  URI notes.

Gates: star-actor-protocol-tests, starlang-compiler-tests (35/35 with
the fresh-SBCL proof), starlang-runtime, starlang-prototype (34 child
scripts), check-repository-contracts.sh, check-prototype-migration.sh,
and nix flake check -L all pass at this head.
nsaspy commented 2026-09-11 05:12:37 +00:00
Author
Owner
Copy link

CI status at head b467d04: every failing job is infrastructure, not tests.

  • SBCL ASDF contract + Engine-free logic IR: all test steps passed (34 prototype child scripts, 35/35 compiler FiveAM checks incl. the fresh-SBCL proof, frozen-fixture validation OK); the jobs fail only at actions/upload-artifact@v4, which Forgejo runners do not support (GHESNotSupportedError).
  • Real SWI MQI + Nix flake check / Sento integration: DeterminateSystems/determinate-nix-action@v3 is not mirrored at data.forgejo.org, so the clone fails before any test step runs.
  • JSON file writer actor and Prototype authority ledger jobs pass.

The same five jobs fail identically on pristine main (0343d65, runs 1-5), so this PR introduces no regression. All authoritative gates pass locally at this exact head: star-actor-protocol-tests, starlang-compiler-tests (35/35), starlang-runtime, starlang-prototype (34 scripts), check-repository-contracts.sh, check-prototype-migration.sh, and nix flake check -L.

Left unmerged per the green-head rule. Unblock options: pin upload-artifact to v3 (or drop the upload step on forgejo), mirror determinate-nix-action at data.forgejo.org or preinstall nix in the runner image, and/or run the authoritative CI matrix on github.com/lost-rob0t/star-lang.

CI status at head b467d04: every failing job is infrastructure, not tests. - SBCL ASDF contract + Engine-free logic IR: all test steps passed (34 prototype child scripts, 35/35 compiler FiveAM checks incl. the fresh-SBCL proof, frozen-fixture validation OK); the jobs fail only at actions/upload-artifact@v4, which Forgejo runners do not support (GHESNotSupportedError). - Real SWI MQI + Nix flake check / Sento integration: DeterminateSystems/determinate-nix-action@v3 is not mirrored at data.forgejo.org, so the clone fails before any test step runs. - JSON file writer actor and Prototype authority ledger jobs pass. The same five jobs fail identically on pristine main (0343d65, runs 1-5), so this PR introduces no regression. All authoritative gates pass locally at this exact head: star-actor-protocol-tests, starlang-compiler-tests (35/35), starlang-runtime, starlang-prototype (34 scripts), check-repository-contracts.sh, check-prototype-migration.sh, and nix flake check -L. Left unmerged per the green-head rule. Unblock options: pin upload-artifact to v3 (or drop the upload step on forgejo), mirror determinate-nix-action at data.forgejo.org or preinstall nix in the runner image, and/or run the authoritative CI matrix on github.com/lost-rob0t/star-lang.
Some checks failed
StarLang artifact writer / JSON file writer actor (pull_request) Successful in 39s
Details
star-lang logic IR / Engine-free logic IR contract (pull_request) Failing after 43s
Details
SWI logic adapter / Real SWI MQI adapter (pull_request) Failing after 4s
Details
star-lang Nix / Real Sento actor/remoting integration (pull_request) Failing after 5s
Details
star-lang Nix / Nix flake check (pull_request) Failing after 5s
Details
StarLang production readiness / Prototype authority ledger (pull_request) Successful in 4s
Details
star-lang CI / SBCL ASDF contract (pull_request) Failing after 2m1s
Details
This pull request has changes conflicting with the target branch.
  • .prolog/kb/load.pl
View command line instructions

Manual merge helper

Use this merge commit message when completing the merge manually.

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin agent/star-uri-canonical:agent/star-uri-canonical
git switch agent/star-uri-canonical

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch main
git merge --no-ff agent/star-uri-canonical
git switch agent/star-uri-canonical
git rebase main
git switch main
git merge --ff-only agent/star-uri-canonical
git switch agent/star-uri-canonical
git rebase main
git switch main
git merge --no-ff agent/star-uri-canonical
git switch main
git merge --squash agent/star-uri-canonical
git switch main
git merge --ff-only agent/star-uri-canonical
git switch main
git merge agent/star-uri-canonical
git push origin main
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
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/star-lang!1
No description provided.