nsaspy/star-lang
1
0
Fork 0
Code Issues 15 Pull requests 6 Projects Releases Packages Wiki Activity Actions

Make real actor systems invariant for actor-semantic tests #42

New issue
Open
opened 2026-08-17 07:02:46 +00:00 by lost-rob0t · 0 comments
lost-rob0t commented 2026-08-17 07:02:46 +00:00 (Migrated from github.com)
Copy link

Context

StarLang now has two distinct actor layers that must stay distinct:

  • starlang-runtime owns deterministic StarLang actor semantics and the real star-mailbox execution path.
  • star-sento-compat owns translation to a concrete Sento/cl-gserver actor runtime.

The current migration ledger already names concrete Sento extraction plus deterministic/Sento lifecycle equivalence as the exact next actor-runtime slice. However, the final star-sento-compat tests still prove most operations with injected lambdas, and the Nix test environment does not currently install/run the concrete Sento backend.

This issue makes the testing invariant explicit before that extraction proceeds.

Non-negotiable invariant

Any test whose assertion is about actor semantics MUST execute through the production actor-runtime boundary whose semantics it claims to test.

For deterministic StarLang actor semantics, instantiate starlang-runtime and use its real star-mailbox mailboxes and actor instances.

For Sento compatibility/integration semantics, boot a real Sento actor system and use real actor refs, message boxes, dispatcher workers, enqueue/delivery, ask/reply, lifecycle, and shutdown operations.

Fakes/mocks may model non-actor external ports such as network, process, clock, journal, or artifact storage. They MUST NOT substitute for actor-system construction, actor creation, mailbox delivery, tell/ask, actor lookup/liveness, watch/termination, supervision, serialization/concurrency, stop, or shutdown when those behaviors are under test.

A wiring/unit test may still inject functions to prove that a port forwards arguments correctly. Such a test cannot count as evidence that the concrete actor behavior works.

Required layers

1. Deterministic semantic layer

Keep starlang-runtime as the fast semantic oracle. Its tests must instantiate the actual final runtime and actual star-mailbox implementation. The deterministic scheduler is allowed and desirable.

2. Concrete Sento integration layer

Add a test-only integration system/environment that loads Sento/cl-gserver and boots a real actor system while preserving star-sento-compat as a soft production dependency if desired.

Provide test helpers such as:

  • with-real-actor-system with unconditional teardown via unwind-protect;
  • unique actor names per test;
  • real probe/coordinator actors that receive observations through mailboxes;
  • bounded future/condition waits rather than arbitrary sleeps;
  • diagnostics that expose actor names/liveness/event observations on failure.

3. Full actor-system fixture

The integration suite must exercise a small but complete multi-actor topology, not a single receiver plus direct host-language calls. Minimum useful topology:

  • coordinator/root test actor;
  • worker actor for tell/ask behavior;
  • stateful counter/authority actor for serialization and state behavior;
  • observer/watch actor for lifecycle evidence when watch is implemented.

All actor-to-actor behavior under assertion travels through actor refs and mailboxes.

4. Lifecycle-equivalence contract

Compare the deterministic and concrete Sento-backed paths for the semantics the adapter claims to support:

  • spawn/registration;
  • asynchronous tell;
  • ask/reply correlation;
  • per-actor serialized handling/order guarantees that StarLang actually promises;
  • stop and late-delivery classification;
  • failure mapping;
  • shutdown;
  • lookup/liveness where exposed;
  • remoting smoke through final star-sento-compat entry points where the current backend supports it.

Restart/generation and watch must not be declared equivalent until the final adapter has explicit semantics and real integration evidence for them.

5. CI gate

Every PR that changes actor runtime/compat semantics must run both:

  • deterministic final-runtime actor tests; and
  • real Sento actor-system integration tests in a fresh SBCL process.

The current flake.nix test environment must be extended so the concrete integration job has the required Sento dependency and actually runs the final compatibility tests. Actor thread/process teardown is part of pass/fail correctness.

Ownership constraints

  • StarLang language semantics stay in starlang-runtime / protocol systems, not in Sento.
  • Sento-specific translation stays in star-sento-compat.
  • star-supervisor owns StarLang supervision policy after base lifecycle equivalence is green; do not bury policy in the compat adapter.
  • Direct production Sento calls remaining under prototype/ should be moved behind final star-sento-compat entry points as the migration matrix requires.
  • Do not create duplicate authoritative actor implementations.

Immediate implementation slice

Follow docs/implementation-slices/ACTOR-RUNTIME-MIGRATION-MATRIX.md:

  1. extract/finish the concrete Sento actor-system/remoting adapter behind star-sento-compat;
  2. switch prototype BBP/remoting callers to final compatibility entry points;
  3. retain existing BBP/two-process smoke evidence but make it exercise the final adapter;
  4. add shared lifecycle-equivalence cases backed by a real Sento actor system;
  5. wire the integration suite into CI/Nix;
  6. remove direct production Sento calls from prototype once their callers have moved.

Known follow-up, not hidden scope creep

Research already identifies synchronous nested starlang-runtime ask as a separate semantic gap: A -> B -> A deterministically times out rather than providing split-phase mailbox progress. Do not disguise that as solved by this adapter/test slice. Track/implement split-phase ask separately after the concrete backend and semantic oracle share a proven base contract.

Acceptance criteria

  • Actor-semantic test policy is documented in-repo.
  • Concrete Sento tests boot an actual actor system and actual actors.
  • No mock/fake actor operations are counted as concrete actor evidence.
  • A multi-actor integration topology proves mailbox-mediated behavior.
  • Deterministic and Sento-backed lifecycle-equivalence tests cover the supported common contract.
  • Final Sento adapter owns the concrete calls used by migrated prototype callers.
  • CI/Nix runs the real actor integration suite on pull requests.
  • Tests use bounded synchronization and guaranteed teardown, not correctness-by-sleep.
  • No actor threads/systems are leaked after a test run.
  • Existing final runtime/protocol tests remain green.
  • The split-phase nested-ask gap remains explicitly tracked rather than silently broadened into this slice.

Primary repo/research references

  • docs/implementation-slices/ACTOR-RUNTIME-MIGRATION-MATRIX.md
  • docs/implementation-slices/FINAL-RUNTIME-OWNERSHIP-ACTORS-INGEST.md
  • starlang-runtime/src/runtime.lisp
  • starlang-runtime/tests/starlang-runtime-tests.lisp
  • star-sento-compat/src/runtime-port.lisp
  • star-sento-compat/src/sento-adapter.lisp
  • star-sento-compat/tests/star-sento-compat-tests.lisp
  • starintel-auto-research/roam/design/star-lang/STAR-LANG-002-durable-actor-runtime.org
  • starintel-auto-research/roam/research/star-lang/STAR-LANG-RESEARCH-013-cl-gserver-runtime-facade.org
  • starintel-auto-research/roam/research/star-lang/STAR-LANG-RESEARCH-024-proof-obligations-for-documents-actors-and-ingest.org
  • starintel-auto-research/roam/research/star-lang/STAR-LANG-RESEARCH-025-verification-experiment-program-for-actor-ingest.org
## Context StarLang now has two distinct actor layers that must stay distinct: - `starlang-runtime` owns deterministic StarLang actor semantics and the real `star-mailbox` execution path. - `star-sento-compat` owns translation to a concrete Sento/cl-gserver actor runtime. The current migration ledger already names concrete Sento extraction plus deterministic/Sento lifecycle equivalence as the exact next actor-runtime slice. However, the final `star-sento-compat` tests still prove most operations with injected lambdas, and the Nix test environment does not currently install/run the concrete Sento backend. This issue makes the testing invariant explicit before that extraction proceeds. ## Non-negotiable invariant > Any test whose assertion is about actor semantics MUST execute through the production actor-runtime boundary whose semantics it claims to test. > > For deterministic StarLang actor semantics, instantiate `starlang-runtime` and use its real `star-mailbox` mailboxes and actor instances. > > For Sento compatibility/integration semantics, boot a real Sento actor system and use real actor refs, message boxes, dispatcher workers, enqueue/delivery, ask/reply, lifecycle, and shutdown operations. > > Fakes/mocks may model non-actor external ports such as network, process, clock, journal, or artifact storage. They MUST NOT substitute for actor-system construction, actor creation, mailbox delivery, tell/ask, actor lookup/liveness, watch/termination, supervision, serialization/concurrency, stop, or shutdown when those behaviors are under test. A wiring/unit test may still inject functions to prove that a port forwards arguments correctly. Such a test cannot count as evidence that the concrete actor behavior works. ## Required layers ### 1. Deterministic semantic layer Keep `starlang-runtime` as the fast semantic oracle. Its tests must instantiate the actual final runtime and actual `star-mailbox` implementation. The deterministic scheduler is allowed and desirable. ### 2. Concrete Sento integration layer Add a test-only integration system/environment that loads Sento/cl-gserver and boots a real actor system while preserving `star-sento-compat` as a soft production dependency if desired. Provide test helpers such as: - `with-real-actor-system` with unconditional teardown via `unwind-protect`; - unique actor names per test; - real probe/coordinator actors that receive observations through mailboxes; - bounded future/condition waits rather than arbitrary sleeps; - diagnostics that expose actor names/liveness/event observations on failure. ### 3. Full actor-system fixture The integration suite must exercise a small but complete multi-actor topology, not a single receiver plus direct host-language calls. Minimum useful topology: - coordinator/root test actor; - worker actor for tell/ask behavior; - stateful counter/authority actor for serialization and state behavior; - observer/watch actor for lifecycle evidence when watch is implemented. All actor-to-actor behavior under assertion travels through actor refs and mailboxes. ### 4. Lifecycle-equivalence contract Compare the deterministic and concrete Sento-backed paths for the semantics the adapter claims to support: - spawn/registration; - asynchronous `tell`; - ask/reply correlation; - per-actor serialized handling/order guarantees that StarLang actually promises; - stop and late-delivery classification; - failure mapping; - shutdown; - lookup/liveness where exposed; - remoting smoke through final `star-sento-compat` entry points where the current backend supports it. Restart/generation and watch must not be declared equivalent until the final adapter has explicit semantics and real integration evidence for them. ### 5. CI gate Every PR that changes actor runtime/compat semantics must run both: - deterministic final-runtime actor tests; and - real Sento actor-system integration tests in a fresh SBCL process. The current `flake.nix` test environment must be extended so the concrete integration job has the required Sento dependency and actually runs the final compatibility tests. Actor thread/process teardown is part of pass/fail correctness. ## Ownership constraints - StarLang language semantics stay in `starlang-runtime` / protocol systems, not in Sento. - Sento-specific translation stays in `star-sento-compat`. - `star-supervisor` owns StarLang supervision policy after base lifecycle equivalence is green; do not bury policy in the compat adapter. - Direct production Sento calls remaining under `prototype/` should be moved behind final `star-sento-compat` entry points as the migration matrix requires. - Do not create duplicate authoritative actor implementations. ## Immediate implementation slice Follow `docs/implementation-slices/ACTOR-RUNTIME-MIGRATION-MATRIX.md`: 1. extract/finish the concrete Sento actor-system/remoting adapter behind `star-sento-compat`; 2. switch prototype BBP/remoting callers to final compatibility entry points; 3. retain existing BBP/two-process smoke evidence but make it exercise the final adapter; 4. add shared lifecycle-equivalence cases backed by a real Sento actor system; 5. wire the integration suite into CI/Nix; 6. remove direct production Sento calls from prototype once their callers have moved. ## Known follow-up, not hidden scope creep Research already identifies synchronous nested `starlang-runtime` `ask` as a separate semantic gap: A -> B -> A deterministically times out rather than providing split-phase mailbox progress. Do not disguise that as solved by this adapter/test slice. Track/implement split-phase ask separately after the concrete backend and semantic oracle share a proven base contract. ## Acceptance criteria - [ ] Actor-semantic test policy is documented in-repo. - [ ] Concrete Sento tests boot an actual actor system and actual actors. - [ ] No mock/fake actor operations are counted as concrete actor evidence. - [ ] A multi-actor integration topology proves mailbox-mediated behavior. - [ ] Deterministic and Sento-backed lifecycle-equivalence tests cover the supported common contract. - [ ] Final Sento adapter owns the concrete calls used by migrated prototype callers. - [ ] CI/Nix runs the real actor integration suite on pull requests. - [ ] Tests use bounded synchronization and guaranteed teardown, not correctness-by-`sleep`. - [ ] No actor threads/systems are leaked after a test run. - [ ] Existing final runtime/protocol tests remain green. - [ ] The split-phase nested-ask gap remains explicitly tracked rather than silently broadened into this slice. ## Primary repo/research references - `docs/implementation-slices/ACTOR-RUNTIME-MIGRATION-MATRIX.md` - `docs/implementation-slices/FINAL-RUNTIME-OWNERSHIP-ACTORS-INGEST.md` - `starlang-runtime/src/runtime.lisp` - `starlang-runtime/tests/starlang-runtime-tests.lisp` - `star-sento-compat/src/runtime-port.lisp` - `star-sento-compat/src/sento-adapter.lisp` - `star-sento-compat/tests/star-sento-compat-tests.lisp` - `starintel-auto-research/roam/design/star-lang/STAR-LANG-002-durable-actor-runtime.org` - `starintel-auto-research/roam/research/star-lang/STAR-LANG-RESEARCH-013-cl-gserver-runtime-facade.org` - `starintel-auto-research/roam/research/star-lang/STAR-LANG-RESEARCH-024-proof-obligations-for-documents-actors-and-ingest.org` - `starintel-auto-research/roam/research/star-lang/STAR-LANG-RESEARCH-025-verification-experiment-program-for-actor-ingest.org`
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
feature/real-actor-system-tests
hydra/fleet-jobs-20260904
ipx/actor-system-foundation
agent/swi-mqi-worker-adapter
agent/production-readiness-20260825
agent/json-file-output-actor
agent/logic-call-ir-policy
agent/portable-logic-foundation
agent/freeze-verification-certificate-claims
extract/deterministic-wire-dispatcher
extract/canonical-wire-encoding
extract/portable-payload-validation
extract/portable-wire-contract
extract/runtime-directory-core
extract/heartbeat-lease-core
extract/runtime-journal-core
extract/canonical-json-core
extract/wire-lifecycle-contract
agent/sento-compat-concrete-adapter
agent/actor-runtime-mailbox-extraction
runtimecompiler
agent/scraping-library-core
agent/final-runtime-ownership-actors-ingest
agent/rabbitmq-transport-binding
agent/actor-protocol-service-uri-clean
agent/actor-protocol-service-uri
agent/native-sha256-ironclad
agent/resolver-effect-ports-phase1
design/star-funds-prediction-market-gap
agent/canonical-manifest-fixtures
agent/full-sha256-locks
agent/star-service-uri
agent/hygienic-macros
agent/camelcase-ir-stability
agent/compiler-foundation
agent/asdf-prototype-test-contract
agent/relation-target-compat
agent/research-006-star-cl-destination
agent/research-006-relation-destination
agent/research-006-https-imports
agent/nix-flake-agpl3
No results found.
Labels
Clear labels   
bug
Something isn't working

  
documentation
Improvements or additions to documentation

  
duplicate
This issue or pull request already exists

  
enhancement
New feature or request

  
good first issue
Good for newcomers

  
help wanted
Extra attention is needed

  
invalid
This doesn't seem right

  
question
Further information is requested

  
wontfix
This will not be worked on

No labels
bug
documentation
duplicate
enhancement
good first issue
help wanted
invalid
question
wontfix
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
nsaspy/star-lang#42
No description provided.