OperationSupervisor: operation-scoped actor topology over canonical Hackmode state

nsaspy commented

2026-09-02 17:24:35 +00:00

Owner

Parent

Epic: #150
ADR: #149

Outcome

Add the operation-scoped coordination layer for hackmoded: one supervised OperationActor per active operation, with operation-local child refs for Hackpert/capture/provider work while canonical state remains in Hackmode/Tek9.

Core invariant

OperationActor is a live coordination authority, not a durable operation database.

It may own/cache coordination facts such as:

stable operation identity;
active run IDs;
current objective refs/status summaries;
operation-local actor refs;
active capture/session refs;
pending provider/Hackpert work IDs;
budget/lease/generation metadata needed for routing.

It must not become canonical ownership for assets, evidence, graph persistence, KB entries or execution history.

Topology

OperationSupervisor
  +-- OperationActor(op-A)
  |     +-- Hackpert session refs
  |     +-- capture session refs
  |     `-- operation-local job refs
  +-- OperationActor(op-B)
  `-- ...

Provider pools may remain globally supervised where appropriate; the operation actor routes scoped requests rather than requiring one complete provider tree per operation.

Required semantics

deterministic operation actor identity from canonical operation identity;
bounded mailbox/backpressure;
no unbounded actor spawn per observed asset/result;
operation close/drain fences late results;
daemon restart reconstructs coordination from canonical state rather than actor-local serialized business state;
stale actor generations/refs fail closed;
one operation actor failure cannot corrupt or stop unrelated operations;
actor restart must not duplicate logical provider effects/evidence commits;
cancellation/deadline/run identity propagate to operation-local work.

Integration points

#24/#27 Hackpert runs become operation-scoped children/sessions without changing passive/active authority;
#135-#141 provider/capture/browser work uses the same operation/run identity and typed capability boundary;
#14/#17/#20 clients inspect/control the operation actor through the daemon protocol, not direct Sento refs;
database persistence remains behind typed canonical APIs owned by the database lane.

RED-first tests

create two canonical operations and materialize exactly two operation actors;
restart one actor and prove the other remains unaffected;
send cross-operation run/action identity and prove rejection;
close/drain an operation and prove late result fencing;
restart the daemon/runtime and rebuild operation actors from canonical operation state;
prove no duplicate logical evidence/provider completion is committed during actor restart/replay;
prove actor-local mutation alone cannot create a canonical asset/KB/evidence record.

Fence

Do not implement Tek9 persistence internals here. If recovery requires a missing typed canonical read/write primitive, specify that exact contract to the database issue/worker rather than storing a shadow operation database in actors.

## Parent - Epic: #150 - ADR: #149 ## Outcome Add the operation-scoped coordination layer for `hackmoded`: one supervised `OperationActor` per active operation, with operation-local child refs for Hackpert/capture/provider work while canonical state remains in Hackmode/Tek9. ## Core invariant `OperationActor` is a live coordination authority, not a durable operation database. It may own/cache coordination facts such as: - stable operation identity; - active run IDs; - current objective refs/status summaries; - operation-local actor refs; - active capture/session refs; - pending provider/Hackpert work IDs; - budget/lease/generation metadata needed for routing. It must not become canonical ownership for assets, evidence, graph persistence, KB entries or execution history. ## Topology ```text OperationSupervisor +-- OperationActor(op-A) | +-- Hackpert session refs | +-- capture session refs | `-- operation-local job refs +-- OperationActor(op-B) `-- ... ``` Provider pools may remain globally supervised where appropriate; the operation actor routes scoped requests rather than requiring one complete provider tree per operation. ## Required semantics - deterministic operation actor identity from canonical operation identity; - bounded mailbox/backpressure; - no unbounded actor spawn per observed asset/result; - operation close/drain fences late results; - daemon restart reconstructs coordination from canonical state rather than actor-local serialized business state; - stale actor generations/refs fail closed; - one operation actor failure cannot corrupt or stop unrelated operations; - actor restart must not duplicate logical provider effects/evidence commits; - cancellation/deadline/run identity propagate to operation-local work. ## Integration points - #24/#27 Hackpert runs become operation-scoped children/sessions without changing passive/active authority; - #135-#141 provider/capture/browser work uses the same operation/run identity and typed capability boundary; - #14/#17/#20 clients inspect/control the operation actor through the daemon protocol, not direct Sento refs; - database persistence remains behind typed canonical APIs owned by the database lane. ## RED-first tests 1. create two canonical operations and materialize exactly two operation actors; 2. restart one actor and prove the other remains unaffected; 3. send cross-operation run/action identity and prove rejection; 4. close/drain an operation and prove late result fencing; 5. restart the daemon/runtime and rebuild operation actors from canonical operation state; 6. prove no duplicate logical evidence/provider completion is committed during actor restart/replay; 7. prove actor-local mutation alone cannot create a canonical asset/KB/evidence record. ## Fence Do not implement Tek9 persistence internals here. If recovery requires a missing typed canonical read/write primitive, specify that exact contract to the database issue/worker rather than storing a shadow operation database in actors.

nsaspy referenced this issue

2026-09-02 17:24:35 +00:00

EPIC: hackmoded — always-on StarLang actor service for Hackmode #27

nsaspy referenced this issue

2026-09-02 17:24:36 +00:00

Migrate StarIntel RAGE/ARDR workers into Hackmode cyber/BBP workers #46

nsaspy referenced this issue

2026-09-02 17:24:37 +00:00

Make the Hackpert objective loop open and extensible #47

nsaspy referenced this issue

2026-09-02 17:24:37 +00:00

Embed Prolog-RLM inside Hackpert as the generative/escalation reasoning tier #48