Extract final star-supervisor semantics for long-lived service actor trees #54

New issue

Open

opened 2026-09-02 17:26:05 +00:00 by nsaspy · 0 comments

nsaspy commented

2026-09-02 17:26:05 +00:00

Owner

Parent

Epic: #56
Production runtime epic: #47
Actor-semantic evidence gate: #42

Goal

Make star-supervisor the final owner of service-grade supervision policy needed by long-lived StarLang hosts such as Hackmode hackmoded.

The migration ledger currently leaves supervision/restart strategy incomplete. Do not bury this policy in star-sento-compat or in host applications.

Required semantics

explicit supervisor/child identity;
permanent / transient / temporary restart classes;
one-for-one strategy first unless existing approved semantics require more;
bounded restart intensity within a bounded time window;
deterministic terminal classification when intensity is exhausted;
optional bounded backoff without unbounded sleeping correctness;
child generation advance on replacement/restart;
stale refs to replaced generations fail closed;
shutdown/drain mode suppresses restart of intentionally stopped children;
child failure isolation;
structured inspectable supervisor/child state;
no application business-state persistence in supervisor metadata.

Backend boundary

star-supervisor owns policy. starlang-runtime owns portable actor lifecycle semantics. star-sento-compat translates supported operations to concrete Sento. The Sento adapter must not become an alternate restart-policy authority.

Mandatory RED-first tests

Use the real final runtime semantic path required by #42:

permanent child crashes and is restarted with generation advance;
transient child restarts only for failure, not normal stop;
temporary child never restarts;
repeated crash exceeds restart intensity and becomes terminal/failed;
intentional supervisor drain does not trigger restart;
stale pre-restart actor ref is rejected;
sibling continues when one child fails;
full shutdown leaves no actors/threads alive.

Then prove the subset claimed equivalent through the real Sento integration path after #42's concrete adapter gate is available.

Non-goals

no cron/scheduler;
no application retry policy for HTTP/tools;
no durable business workflow engine;
no Hackmode-specific operation semantics;
no journal/lease implementation in this slice beyond interfaces needed to compose later.

Definition of done

star-supervisor is final-owned and independently tested for the above semantics, #47's migration ledger can mark supervision/restart policy accordingly, and a host like Hackmode does not need its own actor restart framework.

## Parent - Epic: #56 - Production runtime epic: #47 - Actor-semantic evidence gate: #42 ## Goal Make `star-supervisor` the final owner of service-grade supervision policy needed by long-lived StarLang hosts such as Hackmode `hackmoded`. The migration ledger currently leaves supervision/restart strategy incomplete. Do not bury this policy in `star-sento-compat` or in host applications. ## Required semantics - explicit supervisor/child identity; - permanent / transient / temporary restart classes; - one-for-one strategy first unless existing approved semantics require more; - bounded restart intensity within a bounded time window; - deterministic terminal classification when intensity is exhausted; - optional bounded backoff without unbounded sleeping correctness; - child generation advance on replacement/restart; - stale refs to replaced generations fail closed; - shutdown/drain mode suppresses restart of intentionally stopped children; - child failure isolation; - structured inspectable supervisor/child state; - no application business-state persistence in supervisor metadata. ## Backend boundary `star-supervisor` owns policy. `starlang-runtime` owns portable actor lifecycle semantics. `star-sento-compat` translates supported operations to concrete Sento. The Sento adapter must not become an alternate restart-policy authority. ## Mandatory RED-first tests Use the real final runtime semantic path required by #42: 1. permanent child crashes and is restarted with generation advance; 2. transient child restarts only for failure, not normal stop; 3. temporary child never restarts; 4. repeated crash exceeds restart intensity and becomes terminal/failed; 5. intentional supervisor drain does not trigger restart; 6. stale pre-restart actor ref is rejected; 7. sibling continues when one child fails; 8. full shutdown leaves no actors/threads alive. Then prove the subset claimed equivalent through the real Sento integration path after #42's concrete adapter gate is available. ## Non-goals - no cron/scheduler; - no application retry policy for HTTP/tools; - no durable business workflow engine; - no Hackmode-specific operation semantics; - no journal/lease implementation in this slice beyond interfaces needed to compose later. ## Definition of done `star-supervisor` is final-owned and independently tested for the above semantics, #47's migration ledger can mark supervision/restart policy accordingly, and a host like Hackmode does not need its own actor restart framework.