[MACHINE-SPIRIT 5/8] TaskRunner executor strategy + one-store persistence/resume #328

New issue

Open

opened 2026-09-08 02:03:33 +00:00 by nsaspy · 0 comments

nsaspy commented

2026-09-08 02:03:33 +00:00

Owner

Parent epic: #636
Depends on: #640

Goal

Integrate MACHINE-SPIRIT into Zara's existing durable long-horizon task subsystem without creating a second task loop or persistence store.

Current Zara already has RuntimeHost-owned TaskRunner + principal-scoped TaskStore, bounded steps/wall time, approval observation, interruption recovery, explicit resume, and task create/list/status/cancel/resume surfaces. Reuse those semantics.

Required integration

Introduce a narrow task-step executor strategy/protocol, conceptually:

TaskRunner
  -> TaskExecutor
       -> legacy agent-turn executor
       -> MACHINE-SPIRIT executor

The exact interface should be small and backend-neutral, carrying only the task identity/spec, bounded previous summaries/checkpoint, turn/cancellation context, and a typed step outcome.

Requirements:

existing executor remains behavior-compatible and default during v0;
MACHINE-SPIRIT can be selected explicitly by validated config and/or task creation option;
TaskRunner owns task lifecycle, concurrency, wall clock, cancellation, and RuntimeEvents;
TaskStore remains the only task persistence source;
MACHINE-SPIRIT's generic snapshot/checkpoint is persisted as bounded opaque/versioned task state, not in a second DB;
no transcript dump as persistence;
task/principal identity is supplied by Zara and cannot be rewritten by Prolog/model state;
restart recovery keeps current policy: in-flight task becomes interrupted; explicit resume continues same task identity and remaining budgets;
resume cannot reset step/tool/model/depth/time budgets;
cancellation reaches active MACHINE-SPIRIT graph/effect and canonical Zara turn/tool cancellation.

Config

Add a bounded explicit configuration surface, for example:

[tasks]
enabled = true
executor = "legacy"        # existing behavior remains default during v0

[machine_spirit]
enabled = false

Do not invent multiple overlapping toggles. Fail closed if MACHINE-SPIRIT is selected but runtime/pinned Prolog-RLM is unavailable.

Runtime events

Reuse/add only additive task events as required. Event payloads must remain bounded and secret-safe. Include enough metadata to audit:

executor kind;
task/run id;
step/checkpoint index;
typed outcome/reason;
budgets consumed/remaining at a coarse bounded level.

Do not expose raw prompts, tool payloads, credentials, or full internal Prolog state by default.

Adversarial TDD — RED first

legacy executor behavior regression;
MACHINE-SPIRIT disabled but selected;
task principal mismatch;
checkpoint from another principal/task;
stale checkpoint/schema version;
crash midway through effect;
daemon stop during graph run;
cancel vs complete race;
cancel vs approval race;
resume resets budget attempt;
resume terminal/cancelled task;
two concurrent tasks cross-contaminate checkpoint/evidence;
task store unavailable/corrupt write;
MACHINE-SPIRIT worker dies and TaskRunner incorrectly marks completion;
oversized snapshot/result.

Acceptance

TaskRunner has one explicit executor seam rather than MACHINE-SPIRIT-specific branches scattered through the loop.
Legacy behavior remains green.
MACHINE-SPIRIT runs as an opt-in executor using the exact existing TaskStore/task identity.
No second task DB/store or agent loop exists.
Crash -> interrupted -> explicit resume works with same task identity and remaining finite budgets.
Cancellation propagates to active graph/effect and is terminal where current TaskRunner contract says it is.
Principal isolation is proven under concurrent tasks.
Runtime events are bounded and auditable.
Full repository, Nix/package, shared-mic, and Android compatibility gates remain green.

Non-goals

No auto-resume after daemon crash, no task swarm, no new scheduler, no replacement of TodoStore/timers, no UI overhaul.

Parent epic: #636 Depends on: #640 ## Goal Integrate MACHINE-SPIRIT into Zara's existing durable long-horizon task subsystem without creating a second task loop or persistence store. Current Zara already has RuntimeHost-owned `TaskRunner` + principal-scoped `TaskStore`, bounded steps/wall time, approval observation, interruption recovery, explicit resume, and task create/list/status/cancel/resume surfaces. Reuse those semantics. ## Required integration Introduce a narrow task-step executor strategy/protocol, conceptually: ```text TaskRunner -> TaskExecutor -> legacy agent-turn executor -> MACHINE-SPIRIT executor ``` The exact interface should be small and backend-neutral, carrying only the task identity/spec, bounded previous summaries/checkpoint, turn/cancellation context, and a typed step outcome. Requirements: - existing executor remains behavior-compatible and default during v0; - MACHINE-SPIRIT can be selected explicitly by validated config and/or task creation option; - TaskRunner owns task lifecycle, concurrency, wall clock, cancellation, and RuntimeEvents; - TaskStore remains the only task persistence source; - MACHINE-SPIRIT's generic snapshot/checkpoint is persisted as bounded opaque/versioned task state, not in a second DB; - no transcript dump as persistence; - task/principal identity is supplied by Zara and cannot be rewritten by Prolog/model state; - restart recovery keeps current policy: in-flight task becomes `interrupted`; explicit resume continues same task identity and remaining budgets; - resume cannot reset step/tool/model/depth/time budgets; - cancellation reaches active MACHINE-SPIRIT graph/effect and canonical Zara turn/tool cancellation. ## Config Add a bounded explicit configuration surface, for example: ```toml [tasks] enabled = true executor = "legacy" # existing behavior remains default during v0 [machine_spirit] enabled = false ``` Do not invent multiple overlapping toggles. Fail closed if MACHINE-SPIRIT is selected but runtime/pinned Prolog-RLM is unavailable. ## Runtime events Reuse/add only additive task events as required. Event payloads must remain bounded and secret-safe. Include enough metadata to audit: - executor kind; - task/run id; - step/checkpoint index; - typed outcome/reason; - budgets consumed/remaining at a coarse bounded level. Do not expose raw prompts, tool payloads, credentials, or full internal Prolog state by default. ## Adversarial TDD — RED first - legacy executor behavior regression; - MACHINE-SPIRIT disabled but selected; - task principal mismatch; - checkpoint from another principal/task; - stale checkpoint/schema version; - crash midway through effect; - daemon stop during graph run; - cancel vs complete race; - cancel vs approval race; - resume resets budget attempt; - resume terminal/cancelled task; - two concurrent tasks cross-contaminate checkpoint/evidence; - task store unavailable/corrupt write; - MACHINE-SPIRIT worker dies and TaskRunner incorrectly marks completion; - oversized snapshot/result. ## Acceptance - [ ] `TaskRunner` has one explicit executor seam rather than MACHINE-SPIRIT-specific branches scattered through the loop. - [ ] Legacy behavior remains green. - [ ] MACHINE-SPIRIT runs as an opt-in executor using the exact existing TaskStore/task identity. - [ ] No second task DB/store or agent loop exists. - [ ] Crash -> interrupted -> explicit resume works with same task identity and remaining finite budgets. - [ ] Cancellation propagates to active graph/effect and is terminal where current TaskRunner contract says it is. - [ ] Principal isolation is proven under concurrent tasks. - [ ] Runtime events are bounded and auditable. - [ ] Full repository, Nix/package, shared-mic, and Android compatibility gates remain green. ## Non-goals No auto-resume after daemon crash, no task swarm, no new scheduler, no replacement of TodoStore/timers, no UI overhaul.