minicode-ai 0.11.1 → 0.13.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +89 -0
- package/LICENSE +21 -21
- package/README.md +4 -4
- package/cli/args.ts +46 -0
- package/cli/commands/acp.ts +163 -10
- package/cli/commands/config.ts +33 -18
- package/cli/commands/daemon.ts +515 -0
- package/cli/commands/exec.ts +145 -53
- package/cli/commands/openwork.ts +986 -0
- package/cli/commands/sessions.ts +4 -1
- package/cli/commands/stats.ts +34 -4
- package/cli/commands.ts +217 -2
- package/cli/index.ts +146 -14
- package/cli/recovery-warning.ts +115 -0
- package/cli/router.ts +32 -1
- package/cli/setup.ts +2332 -171
- package/cli/tui.ts +113 -7
- package/docs/OUTPUT_ARCHITECTURE_AUDIT.md +489 -0
- package/docs/OUTPUT_EVENT_MODEL.md +289 -0
- package/docs/OUTPUT_IMPLEMENTATION_PLAN.md +391 -0
- package/docs/OUTPUT_PROTOCOL_SPEC.md +285 -0
- package/docs/OUTPUT_RENDERING_SPEC.md +248 -0
- package/docs/OUTPUT_UX_RULES.md +449 -0
- package/docs/PLAN_UIUX_V6.md +2 -2
- package/docs/README.md +4 -3
- package/docs/TERMINAL_CONTRACT.md +278 -71
- package/docs/architecture.md +89 -7
- package/docs/changelog.md +1 -1
- package/docs/choosing-mode.md +2 -2
- package/docs/cli.md +9 -5
- package/docs/concepts.md +1 -1
- package/docs/contributing.md +9 -2
- package/docs/environment.md +6 -2
- package/docs/exec.md +46 -5
- package/docs/memory-sessions.md +2 -0
- package/docs/policy-sandbox.md +1 -1
- package/docs/pricing-budget.md +1 -1
- package/docs/quickstart.md +2 -2
- package/docs/repl.md +6 -2
- package/docs/security-model.md +1 -1
- package/docs/security.md +1 -1
- package/docs/skills.md +2 -2
- package/docs/terminal.md +9 -5
- package/docs/tools.md +1 -1
- package/package.json +35 -5
- package/src/app/session.ts +261 -15
- package/src/app/tool-layer.ts +94 -7
- package/src/daemon/approvals.ts +361 -0
- package/src/daemon/capability.ts +145 -0
- package/src/daemon/children.ts +142 -0
- package/src/daemon/client.ts +267 -0
- package/src/daemon/control.ts +350 -0
- package/src/daemon/discovery.ts +234 -0
- package/src/daemon/feed.ts +155 -0
- package/src/daemon/framing.ts +94 -0
- package/src/daemon/host.ts +316 -0
- package/src/daemon/protocol.ts +217 -0
- package/src/daemon/resource.ts +170 -0
- package/src/daemon/sanitize.ts +57 -0
- package/src/daemon/server.ts +627 -0
- package/src/daemon/store.ts +317 -0
- package/src/daemon/subscription.ts +270 -0
- package/src/daemon/telemetry.ts +81 -0
- package/src/hooks/run.ts +12 -1
- package/src/lib/atomic-write.ts +29 -3
- package/src/lib/db-path.ts +26 -0
- package/src/lib/keystore.ts +544 -42
- package/src/lib/net.ts +43 -1
- package/src/lib/safe-open.ts +116 -1
- package/src/lib/session-id.ts +15 -0
- package/src/lsp/client.ts +123 -5
- package/src/mcp/client.ts +139 -17
- package/src/mcp/server.ts +177 -50
- package/src/mcp/transport.ts +16 -19
- package/src/memory/vector.ts +770 -55
- package/src/policy/allowlist.ts +14 -2
- package/src/policy/bash-guard.ts +105 -10
- package/src/policy/compaction.ts +82 -5
- package/src/policy/consequence-engine.ts +220 -0
- package/src/policy/context.ts +132 -0
- package/src/policy/executor.ts +187 -121
- package/src/policy/no-progress.ts +559 -0
- package/src/policy/permission.ts +4 -8
- package/src/policy/pricing.ts +17 -3
- package/src/policy/scrub.ts +69 -2
- package/src/policy/tool-contract.ts +515 -0
- package/src/policy/usage.ts +310 -24
- package/src/policy/verifier.ts +6 -3
- package/src/policy/work-mode.ts +182 -0
- package/src/presentation/adapter.ts +533 -26
- package/src/presentation/events.ts +151 -0
- package/src/presentation/model.ts +180 -27
- package/src/presentation/projection.ts +858 -0
- package/src/presentation/reducer.ts +645 -310
- package/src/presentation/store.ts +12 -7
- package/src/providers/anthropic.ts +18 -10
- package/src/providers/responses.ts +2 -2
- package/src/runtime/capability.ts +409 -0
- package/src/runtime/child-execution.ts +274 -0
- package/src/runtime/composition.ts +958 -0
- package/src/runtime/dispatch.ts +591 -0
- package/src/runtime/execution-backend.ts +632 -0
- package/src/runtime/execution-events.ts +272 -0
- package/src/runtime/execution-id.ts +230 -0
- package/src/runtime/execution-journal.ts +926 -0
- package/src/runtime/execution-kernel.ts +456 -0
- package/src/runtime/execution-registry.ts +379 -0
- package/src/runtime/process-supervision.ts +276 -0
- package/src/runtime/production-execution.ts +551 -0
- package/src/runtime/production-runtime.ts +217 -0
- package/src/runtime/recovery-safety.ts +70 -0
- package/src/runtime/recovery.ts +477 -0
- package/src/runtime/runtime-capabilities.ts +179 -0
- package/src/runtime/runtime-diagnostics.ts +141 -0
- package/src/runtime/runtime-host.ts +365 -0
- package/src/runtime/runtime-status-facts.ts +222 -0
- package/src/runtime/runtime-status-provider.ts +74 -0
- package/src/runtime/runtime-status.ts +459 -0
- package/src/runtime/runtime-task-admission.ts +101 -0
- package/src/runtime/supervisor.ts +444 -0
- package/src/session/authority.ts +168 -0
- package/src/session/checkpoint.ts +88 -1
- package/src/session/context-adapter.ts +251 -0
- package/src/session/context-assembly.ts +242 -0
- package/src/session/context-identity.ts +389 -0
- package/src/session/context-projection.ts +248 -0
- package/src/session/context-selector.ts +500 -0
- package/src/session/cross-session-adoption.ts +249 -0
- package/src/session/full-history-fold.ts +171 -0
- package/src/session/identity.ts +192 -0
- package/src/session/journal.ts +805 -102
- package/src/session/open-work-intent.ts +732 -0
- package/src/session/open-work.ts +767 -0
- package/src/session/pending-tools.ts +94 -0
- package/src/session/persistence.ts +3569 -127
- package/src/session/runtime-header.ts +208 -0
- package/src/session/shadow-git.ts +13 -5
- package/src/session/verification.ts +1623 -0
- package/src/task/assignment.ts +136 -0
- package/src/task/autonomous-adapter.ts +168 -0
- package/src/task/autonomous-context.ts +630 -0
- package/src/task/autonomous-policy.ts +490 -0
- package/src/task/continuity.ts +179 -0
- package/src/task/execution-cancellation.ts +165 -0
- package/src/task/graph-validate.ts +379 -0
- package/src/task/graph.ts +305 -0
- package/src/task/identity.ts +230 -0
- package/src/task/model.ts +417 -0
- package/src/task/production-scheduler.ts +293 -0
- package/src/task/readiness.ts +229 -0
- package/src/task/scheduler-observability.ts +387 -0
- package/src/task/scheduler.ts +1197 -0
- package/src/task/scheduling-policy.ts +165 -0
- package/src/task/session-authority.ts +148 -0
- package/src/task/session-ownership.ts +211 -0
- package/src/task/store.ts +2887 -0
- package/src/task/sync.ts +343 -0
- package/src/task/trigger.ts +260 -0
- package/src/tools/bash.ts +377 -211
- package/src/tools/code_run.ts +1 -1
- package/src/tools/delete_file.ts +1 -1
- package/src/tools/edit.ts +33 -6
- package/src/tools/evidence.ts +30 -0
- package/src/tools/git.ts +4 -4
- package/src/tools/glob.ts +12 -3
- package/src/tools/grep.ts +1 -1
- package/src/tools/lsp.ts +4 -4
- package/src/tools/mcp_call.ts +11 -4
- package/src/tools/memory.ts +153 -18
- package/src/tools/move_file.ts +1 -1
- package/src/tools/patch.ts +1 -1
- package/src/tools/read_file.ts +1 -1
- package/src/tools/read_image.ts +1 -1
- package/src/tools/submit_result.ts +1 -1
- package/src/tools/task.ts +437 -41
- package/src/tools/todo.ts +662 -35
- package/src/tools/web_fetch.ts +4 -2
- package/src/tools/web_search.ts +9 -3
- package/src/tools/write_file.ts +1 -1
- package/src/ui/assistant/simple.ts +123 -50
- package/src/ui/assistant/turn-status.ts +17 -3
- package/src/ui/contract.ts +184 -0
- package/src/ui/footer.ts +52 -19
- package/src/ui/i18n/en.ts +58 -6
- package/src/ui/i18n/id.ts +58 -6
- package/src/ui/input/prompt-engine.ts +120 -25
- package/src/ui/render/errors.ts +39 -1
- package/src/ui/render/markdown-table.ts +455 -0
- package/src/ui/render/markdown.ts +22 -1
- package/src/ui/render/table-grid.ts +184 -0
- package/src/ui/render/table.ts +15 -76
- package/src/ui/runtime/screen.ts +7 -2
- package/src/ui/runtime/statusline.ts +25 -6
- package/src/ui/tui/app.ts +507 -169
- package/src/ui/tui/transcript.ts +531 -89
- package/vendor/minicore/VENDOR.md +1 -1
- package/vendor/minicore/src/core/budget.ts +25 -25
- package/vendor/minicore/src/core/compact.ts +75 -75
- package/vendor/minicore/src/core/errors.ts +59 -59
- package/vendor/minicore/src/core/events.ts +73 -73
- package/vendor/minicore/src/core/executor.ts +139 -139
- package/vendor/minicore/src/core/history.ts +31 -31
- package/vendor/minicore/src/core/index.ts +41 -41
- package/vendor/minicore/src/core/loop.ts +355 -355
- package/vendor/minicore/src/core/permission.ts +22 -22
- package/vendor/minicore/src/core/provider.ts +39 -39
- package/vendor/minicore/src/core/recovery.ts +35 -35
- package/vendor/minicore/src/core/session.ts +327 -327
- package/vendor/minicore/src/core/snapshot.ts +146 -146
- package/vendor/minicore/src/core/tokens.ts +107 -107
- package/vendor/minicore/src/core/tool.ts +115 -115
- package/vendor/minicore/src/core/types.ts +50 -50
- package/vendor/minicore/src/providers/openai-compat.ts +417 -417
- package/AGENTS.md +0 -45
- package/PLAN.md +0 -491
- package/docs/ARCHITECTURE.html +0 -1248
- package/docs/CONTROL-PLANE-MAP.md +0 -139
- package/docs/HARNESS.md +0 -150
- package/docs/SUMMARY.md +0 -52
- package/docs/UI_RENDER_PIPELINE.md +0 -169
- package/docs/USAGE.md +0 -11
|
@@ -0,0 +1,1197 @@
|
|
|
1
|
+
// Phase 6C — Scheduler core: headless, dependency-injected, single-session,
|
|
2
|
+
// serial. NEW ARCHITECTURE.
|
|
3
|
+
//
|
|
4
|
+
// Implements the Phase 6A design lock. NOT wired into production: nothing in
|
|
5
|
+
// src/ constructs a Scheduler, and this module imports nothing that could.
|
|
6
|
+
//
|
|
7
|
+
// ── WHAT IT IS ───────────────────────────────────────────────────────────────
|
|
8
|
+
//
|
|
9
|
+
// Three questions have three owners, kept strictly apart:
|
|
10
|
+
//
|
|
11
|
+
// TaskGraph "what is executable right now, and why?" (read-only)
|
|
12
|
+
// Scheduler "what do we attempt next, and under what lifecycle/recovery rules?"
|
|
13
|
+
// TaskStore "what is durably true?" (sole writer)
|
|
14
|
+
//
|
|
15
|
+
// ── WHAT IT DELIBERATELY DOES NOT DO ─────────────────────────────────────────
|
|
16
|
+
//
|
|
17
|
+
// * no SQLite, no bun:sqlite, no TaskStore internals
|
|
18
|
+
// * no readiness reimplementation — `readyTasks()` is consumed verbatim
|
|
19
|
+
// * no graph semantics, no dependency derivation, no blocker inference
|
|
20
|
+
// * never writes COMPLETED, never verifies, never manufactures evidence
|
|
21
|
+
// * never calls parallelExecutor, tools, providers or permissions
|
|
22
|
+
// * no retry policy, no lease, no heartbeat, no priority, no fairness
|
|
23
|
+
// * no message-history or transcript reads for task truth
|
|
24
|
+
// * presentation_events is never an input
|
|
25
|
+
//
|
|
26
|
+
// ── SHAPE PROVENANCE ─────────────────────────────────────────────────────────
|
|
27
|
+
//
|
|
28
|
+
// HISTORICAL DESIGN EVIDENCE (recovered `p77-repro.ts` call sites) justifies the
|
|
29
|
+
// SHAPE only: `new Scheduler(sessionId, { store, runTurn, instruction })`,
|
|
30
|
+
// `discover()`, `getActiveClaim()`. Those are signatures a test once used. They
|
|
31
|
+
// are not evidence of any behaviour, and none is inferred from them.
|
|
32
|
+
//
|
|
33
|
+
// NOT adopted, having no evidence anywhere: `canExecute`, `blockingDeps`,
|
|
34
|
+
// `topological`, `sourceRevision`. Those names appeared in a brief and were
|
|
35
|
+
// never found in any artifact; 5A recorded them as unsourced.
|
|
36
|
+
//
|
|
37
|
+
// ── V1 DEPLOYMENT INVARIANT ──────────────────────────────────────────────────
|
|
38
|
+
//
|
|
39
|
+
// A session must not be concurrently driven by independent Scheduler instances
|
|
40
|
+
// across OS processes. Session ownership is process-local (Phase 6B) and cannot
|
|
41
|
+
// see another OS process, so this module does not pretend to prevent it. It
|
|
42
|
+
// prevents concurrent ownership *within* a process, and refuses to act when
|
|
43
|
+
// ownership is uncertain.
|
|
44
|
+
|
|
45
|
+
import {
|
|
46
|
+
type ContinuityClass,
|
|
47
|
+
type ContinuityContext,
|
|
48
|
+
type ContinuityEvidence,
|
|
49
|
+
type ContinuityGate,
|
|
50
|
+
classifyContinuity,
|
|
51
|
+
} from "./continuity.ts"
|
|
52
|
+
import {
|
|
53
|
+
type CancelReason,
|
|
54
|
+
type ExecutionHandle,
|
|
55
|
+
newExecutionHandle,
|
|
56
|
+
type PerTurnCancellation,
|
|
57
|
+
} from "./execution-cancellation.ts"
|
|
58
|
+
import { TaskGraph } from "./graph.ts"
|
|
59
|
+
import { type ClaimOutcome, TaskError, type TaskSnapshot } from "./model.ts"
|
|
60
|
+
import { selectTask } from "./scheduling-policy.ts"
|
|
61
|
+
import { newOwnerToken, SESSION_LEASE_MS, SESSION_RENEW_INTERVAL_MS } from "./session-authority.ts"
|
|
62
|
+
import type { SessionOwner } from "./session-ownership.ts"
|
|
63
|
+
|
|
64
|
+
// Re-exported so a composition root needs one import to wire a cancellation-aware
|
|
65
|
+
// bridge, and so the Scheduler's public vocabulary stays in one file.
|
|
66
|
+
export type { CancelReason, ExecutionHandle } from "./execution-cancellation.ts"
|
|
67
|
+
|
|
68
|
+
import {
|
|
69
|
+
acquireSessionOwnership,
|
|
70
|
+
ownsSession,
|
|
71
|
+
releaseSessionOwnership,
|
|
72
|
+
} from "./session-ownership.ts"
|
|
73
|
+
import type { AttemptRecordOutcome, TaskStore } from "./store.ts"
|
|
74
|
+
|
|
75
|
+
// ── lifecycle ────────────────────────────────────────────────────────────────
|
|
76
|
+
|
|
77
|
+
export type SchedulerState = "CREATED" | "RUNNING" | "IDLE" | "STOPPING" | "STOPPED"
|
|
78
|
+
|
|
79
|
+
/** Why a cycle ended. Never inferred from events. */
|
|
80
|
+
export type CycleStop =
|
|
81
|
+
| "no-candidates"
|
|
82
|
+
| "invalid-graph"
|
|
83
|
+
| "claim-rejected-stale"
|
|
84
|
+
| "claim-not-found"
|
|
85
|
+
| "claim-wrong-state"
|
|
86
|
+
| "ownership-unavailable"
|
|
87
|
+
| "already-dispatched"
|
|
88
|
+
| "not-running"
|
|
89
|
+
/**
|
|
90
|
+
* [PHASE 6T] The runtime was already busy when the cycle was evaluated.
|
|
91
|
+
*
|
|
92
|
+
* NON-CONSUMING, and that is the entire point of the outcome. No claim, no
|
|
93
|
+
* generation, no owner, no attempt lineage. The task is left exactly as it was
|
|
94
|
+
* and the next trigger re-evaluates it.
|
|
95
|
+
*/
|
|
96
|
+
| "contended"
|
|
97
|
+
/** [PHASE 6T] Contention was known before evaluation began; nothing was read. */
|
|
98
|
+
| "pre-cancelled"
|
|
99
|
+
/**
|
|
100
|
+
* [PHASE 6T] The session this instance was serving no longer exists in the
|
|
101
|
+
* lifetime it started for. Self-disposed; ownership released for a replacement.
|
|
102
|
+
*/
|
|
103
|
+
| "session-superseded"
|
|
104
|
+
/** [PHASE 6X] Cross-process authority was lost; the instance self-disposed. */
|
|
105
|
+
| "authority-lost"
|
|
106
|
+
|
|
107
|
+
/** Why a work item could not be handed to the agent loop. */
|
|
108
|
+
export type DispatchFailure =
|
|
109
|
+
| "scheduler-not-running"
|
|
110
|
+
| "bridge-threw"
|
|
111
|
+
| "bridge-not-callable"
|
|
112
|
+
/**
|
|
113
|
+
* [PHASE 6Q] The turn ended but no active claim identified which generation it
|
|
114
|
+
* belonged to, so no lineage was recorded. Distinct from a persistence error:
|
|
115
|
+
* the instance stays usable, which is the whole point.
|
|
116
|
+
*/
|
|
117
|
+
| "attempt-unidentified"
|
|
118
|
+
|
|
119
|
+
export type ExecutionObservation =
|
|
120
|
+
/** The turn returned. `ok` is an OBSERVATION, not a verdict on the work. */
|
|
121
|
+
| { readonly kind: "returned"; readonly ok: boolean; readonly detail?: string }
|
|
122
|
+
/** The turn threw or rejected. The attempt WAS established. */
|
|
123
|
+
| { readonly kind: "rejected"; readonly detail: string }
|
|
124
|
+
|
|
125
|
+
/**
|
|
126
|
+
* The work item handed to the agent loop.
|
|
127
|
+
*
|
|
128
|
+
* Contains exactly the three locked fields, and nothing derived from message
|
|
129
|
+
* history: the composition root decides how to run it.
|
|
130
|
+
*/
|
|
131
|
+
export interface SchedulerWorkItem {
|
|
132
|
+
readonly taskId: string
|
|
133
|
+
readonly title: string
|
|
134
|
+
readonly instruction: string
|
|
135
|
+
readonly sessionId: string
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/**
|
|
139
|
+
* The injected execution bridge. Scheduler authorizes; this runs.
|
|
140
|
+
*
|
|
141
|
+
* A `dispatch-failed` (a synchronous throw before the promise exists) means the
|
|
142
|
+
* attempt was never established, which is materially different from a rejected
|
|
143
|
+
* turn. Scheduler must not fake that distinction with an invented flag — it is
|
|
144
|
+
* derived from whether the call returned a promise at all.
|
|
145
|
+
*/
|
|
146
|
+
export type RunTurn = (
|
|
147
|
+
work: SchedulerWorkItem,
|
|
148
|
+
/**
|
|
149
|
+
* [PHASE 6T] The per-execution cancellation handle for THIS dispatch.
|
|
150
|
+
*
|
|
151
|
+
* Optional so every existing bridge keeps compiling unchanged. A bridge that
|
|
152
|
+
* ignores it simply cannot be cancelled mid-turn — which is a capability gap,
|
|
153
|
+
* not a correctness gap, and the composition root chooses whether to close it.
|
|
154
|
+
*/
|
|
155
|
+
active?: ExecutionHandle,
|
|
156
|
+
) => Promise<ExecutionObservation> | ExecutionObservation
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* Observations. Strictly one-way: they are emitted, never consumed. Scheduler
|
|
160
|
+
* state is never reconstructed from them.
|
|
161
|
+
*/
|
|
162
|
+
export type SchedulerEvent =
|
|
163
|
+
| { readonly kind: "task:recovered"; readonly taskIds: readonly string[] }
|
|
164
|
+
| { readonly kind: "task:selected"; readonly taskId: string }
|
|
165
|
+
| { readonly kind: "task:claimed"; readonly taskId: string; readonly revision: number }
|
|
166
|
+
| {
|
|
167
|
+
readonly kind: "task:claim_rejected"
|
|
168
|
+
readonly taskId: string
|
|
169
|
+
readonly outcome: ClaimOutcome
|
|
170
|
+
}
|
|
171
|
+
| { readonly kind: "task:dispatch_started"; readonly taskId: string }
|
|
172
|
+
| { readonly kind: "task:execution_started"; readonly taskId: string }
|
|
173
|
+
| { readonly kind: "task:execution_completed"; readonly taskId: string; readonly ok: boolean }
|
|
174
|
+
/**
|
|
175
|
+
* [PHASE 6Q] The attempt ended but its completion could NOT be recorded, because
|
|
176
|
+
* the session was deleted under it or a later generation superseded it. Nothing
|
|
177
|
+
* was written; the task is left for the next owner to decide.
|
|
178
|
+
*/
|
|
179
|
+
| {
|
|
180
|
+
readonly kind: "task:execution_abandoned"
|
|
181
|
+
readonly taskId: string
|
|
182
|
+
readonly outcome: AttemptRecordOutcome
|
|
183
|
+
}
|
|
184
|
+
/**
|
|
185
|
+
* [P13.3 Stage C] A stranded generation was deliberately NOT reconciled.
|
|
186
|
+
*
|
|
187
|
+
* `class` is the retry-safety classification, `reason` names the missing
|
|
188
|
+
* proof. This is an observation only: the durable record is untouched, which
|
|
189
|
+
* is exactly what HOLD/REQUIRES_VERIFIER mean.
|
|
190
|
+
*/
|
|
191
|
+
| {
|
|
192
|
+
readonly kind: "task:continuity_held"
|
|
193
|
+
readonly taskId: string
|
|
194
|
+
readonly class: ContinuityClass
|
|
195
|
+
readonly reason: string
|
|
196
|
+
}
|
|
197
|
+
| { readonly kind: "cycle:invalid_graph" }
|
|
198
|
+
| { readonly kind: "cycle:stopped"; readonly reason: CycleStop }
|
|
199
|
+
|
|
200
|
+
export interface SchedulerOptions {
|
|
201
|
+
readonly store: TaskStore
|
|
202
|
+
readonly runTurn: RunTurn
|
|
203
|
+
/** The instruction template handed to the agent loop with every work item. */
|
|
204
|
+
readonly instruction: string
|
|
205
|
+
/** Optional observation sink. Absence means events are dropped, not queued. */
|
|
206
|
+
readonly onEvent?: (event: SchedulerEvent) => void
|
|
207
|
+
/** Optional cancellation the composition root owns. Scheduler never invents one. */
|
|
208
|
+
readonly cancellation?: { readonly isCancelled: () => boolean }
|
|
209
|
+
/**
|
|
210
|
+
* [PHASE 6X] Pre-existing authority token, when the composition root owns the
|
|
211
|
+
* lease. Omit and the Scheduler mints its own at start().
|
|
212
|
+
*/
|
|
213
|
+
readonly authorityToken?: string
|
|
214
|
+
/**
|
|
215
|
+
* [P13.3 Stage C] Retry-safety evidence for automatic reconciliation.
|
|
216
|
+
*
|
|
217
|
+
* ABSENT = HOLD. The Scheduler cannot prove that re-running arbitrary work is
|
|
218
|
+
* free of duplicate external effects, so it must not revert a stranded
|
|
219
|
+
* generation on lineage alone. A composition root that CAN prove it (the
|
|
220
|
+
* production autonomous bridge, whose tool scope is the 6S read-only matrix)
|
|
221
|
+
* supplies the evidence here.
|
|
222
|
+
*/
|
|
223
|
+
readonly continuity?: ContinuityGate
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
export interface ActiveClaim {
|
|
227
|
+
readonly taskId: string
|
|
228
|
+
/**
|
|
229
|
+
* The revision AFTER the accepted claim. Never the pre-claim revision, never
|
|
230
|
+
* the graph's revision, never a timestamp, never `sourceMaxRevision` -
|
|
231
|
+
* a release must address the state the claim actually produced.
|
|
232
|
+
*/
|
|
233
|
+
readonly claimRevision: number
|
|
234
|
+
/**
|
|
235
|
+
* [PHASE 6I] The EXECUTION GENERATION created by the accepted claim, returned
|
|
236
|
+
* by `claimTask` from the same atomic statement that set `IN_PROGRESS`.
|
|
237
|
+
*
|
|
238
|
+
* This is the identity an attempt belongs to, and it is deliberately NOT the
|
|
239
|
+
* revision: `claimRevision` changes on every unrelated task write, which is
|
|
240
|
+
* exactly what let a stale completion protect a later generation (6G D1).
|
|
241
|
+
* `execGeneration` advances only when a claim is accepted.
|
|
242
|
+
*/
|
|
243
|
+
readonly execGeneration: number
|
|
244
|
+
/**
|
|
245
|
+
* [PHASE 6Q] The session INCARNATION the claim was made under.
|
|
246
|
+
*
|
|
247
|
+
* `taskId` is allocated per session and restarts at `t1`, so a session deleted
|
|
248
|
+
* and recreated under the same id has task ids indistinguishable from the
|
|
249
|
+
* deleted ones - and a `execGeneration` that a fresh claim can legitimately
|
|
250
|
+
* match. This token is how a late execution recognises that the row it is
|
|
251
|
+
* about to touch belongs to a DIFFERENT session lifetime. Deletion bumps it.
|
|
252
|
+
*/
|
|
253
|
+
readonly sessionIncarnation: number
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
export class SchedulerError extends Error {
|
|
257
|
+
readonly reason: string
|
|
258
|
+
constructor(reason: string, message: string) {
|
|
259
|
+
super(message)
|
|
260
|
+
this.name = "SchedulerError"
|
|
261
|
+
this.reason = reason
|
|
262
|
+
}
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
export class Scheduler {
|
|
266
|
+
readonly sessionId: string
|
|
267
|
+
|
|
268
|
+
private readonly store: TaskStore
|
|
269
|
+
private readonly runTurn: RunTurn
|
|
270
|
+
private readonly instruction: string
|
|
271
|
+
private readonly onEvent: ((e: SchedulerEvent) => void) | undefined
|
|
272
|
+
private readonly cancellation: { readonly isCancelled: () => boolean } | undefined
|
|
273
|
+
/** [P13.3 Stage C] Null = no proof, so reconciliation holds (fail closed). */
|
|
274
|
+
private readonly continuity: ContinuityGate | null
|
|
275
|
+
|
|
276
|
+
private state: SchedulerState = "CREATED"
|
|
277
|
+
private owner: SessionOwner | null = null
|
|
278
|
+
private claim: ActiveClaim | null = null
|
|
279
|
+
|
|
280
|
+
/**
|
|
281
|
+
* [PHASE 6T] The cancellation handle for the turn currently in flight, or null.
|
|
282
|
+
*
|
|
283
|
+
* One at a time, because V1 is serial — the same guarantee `inFlight` provides
|
|
284
|
+
* for cycles. Replacing it rather than stacking is deliberate: a second handle
|
|
285
|
+
* could only mean a second concurrent turn, which this Scheduler never starts.
|
|
286
|
+
*/
|
|
287
|
+
private active: PerTurnCancellation | null = null
|
|
288
|
+
|
|
289
|
+
/**
|
|
290
|
+
* [PHASE 6T] The session incarnation this instance started under.
|
|
291
|
+
*
|
|
292
|
+
* [DESIGN DECISION] 6Q taught the Scheduler to self-dispose when a lineage
|
|
293
|
+
* write comes back `TASK_GONE`/`SESSION_SUPERSEDED` — but that only happens on
|
|
294
|
+
* the CLAIM path, while a turn is ending. A scheduler that is merely IDLE when
|
|
295
|
+
* its session is deleted never writes anything, never learns, and keeps
|
|
296
|
+
* holding the process-local ownership token, which wedges every replacement:
|
|
297
|
+
* a recreated session cannot start, because a dead instance still owns it.
|
|
298
|
+
* Proved by probe before this fix.
|
|
299
|
+
*
|
|
300
|
+
* The fix reuses 6Q's own fact rather than inventing a liveness mechanism: the
|
|
301
|
+
* incarnation is captured at `start()` and compared at the top of every cycle.
|
|
302
|
+
* If it moved, this session was deleted or superseded, and the instance's work
|
|
303
|
+
* is meaningless. This STRENGTHENS 6Q — same durable evidence, checked at cycle
|
|
304
|
+
* granularity instead of only at lineage-write time — and it is the answer to
|
|
305
|
+
* 6T's requirement that a Scheduler never need a restart because of stale
|
|
306
|
+
* internal ownership.
|
|
307
|
+
*/
|
|
308
|
+
private incarnationAtStart: number | null = null
|
|
309
|
+
|
|
310
|
+
// -- [PHASE 6X] cross-process authority ---------------------------------------
|
|
311
|
+
/** The durable lease token for THIS authority. Null until start(). */
|
|
312
|
+
private authorityToken: string | null = null
|
|
313
|
+
/** Set when a lease is lost; from then on this instance must not schedule. */
|
|
314
|
+
private authorityLost = false
|
|
315
|
+
/** Renewal heartbeat. unref'd, and cleared on every stop path. */
|
|
316
|
+
private renewTimer: ReturnType<typeof setInterval> | null = null
|
|
317
|
+
|
|
318
|
+
/**
|
|
319
|
+
* V1 is SERIAL. A cycle in progress makes any further call wait for it, which
|
|
320
|
+
* is why N concurrent `cycle()` calls can never produce two dispatches. This
|
|
321
|
+
* is the Scheduler serializing ITSELF — TaskStore is not asked to do it.
|
|
322
|
+
*/
|
|
323
|
+
private inFlight: Promise<CycleResult> | null = null
|
|
324
|
+
|
|
325
|
+
constructor(sessionId: string, opts: SchedulerOptions) {
|
|
326
|
+
this.sessionId = sessionId
|
|
327
|
+
this.store = opts.store
|
|
328
|
+
this.runTurn = opts.runTurn
|
|
329
|
+
this.instruction = opts.instruction
|
|
330
|
+
this.onEvent = opts.onEvent
|
|
331
|
+
this.cancellation = opts.cancellation
|
|
332
|
+
this.continuity = opts.continuity ?? null
|
|
333
|
+
// P2.2: token otoritas milik composition root (satu penulis per boot).
|
|
334
|
+
// Tanpa ini opsi authorityToken mati (selalu mint sendiri) dan sesi +
|
|
335
|
+
// scheduler-nya saling menolak lease. Bukan redesign protokol: acquire/
|
|
336
|
+
// renew/release/holds tak berubah; hanya sumber token disatukan.
|
|
337
|
+
this.authorityToken = opts.authorityToken ?? null
|
|
338
|
+
}
|
|
339
|
+
|
|
340
|
+
// ── lifecycle ──────────────────────────────────────────────────────────────
|
|
341
|
+
|
|
342
|
+
getLifecycle(): SchedulerState {
|
|
343
|
+
return this.state
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
/**
|
|
347
|
+
* Acquire session ownership, then begin scheduling.
|
|
348
|
+
*
|
|
349
|
+
* Idempotent while running. Refused after STOPPED: a stopped Scheduler never
|
|
350
|
+
* begins new work, and a silent no-op would make a dead subsystem look alive.
|
|
351
|
+
*
|
|
352
|
+
* Fails closed when ownership is unavailable — a competing in-process owner
|
|
353
|
+
* blocks this instance rather than being worked around.
|
|
354
|
+
*/
|
|
355
|
+
start(): void {
|
|
356
|
+
if (this.state === "STOPPED") {
|
|
357
|
+
throw new SchedulerError("stopped", "scheduler is STOPPED and cannot be restarted")
|
|
358
|
+
}
|
|
359
|
+
if (this.state === "RUNNING" || this.state === "IDLE") return
|
|
360
|
+
|
|
361
|
+
if (this.owner === null) {
|
|
362
|
+
const owner = acquireSessionOwnership(this.sessionId, "scheduler")
|
|
363
|
+
if (owner === null) {
|
|
364
|
+
// Another owner exists in this process. Fail closed; do not guess.
|
|
365
|
+
this.state = "STOPPED"
|
|
366
|
+
throw new SchedulerError(
|
|
367
|
+
"ownership-unavailable",
|
|
368
|
+
`session ${this.sessionId} is already owned in this process`,
|
|
369
|
+
)
|
|
370
|
+
}
|
|
371
|
+
this.owner = owner
|
|
372
|
+
// [PHASE 6W/6X] Remember which lifetime of this session we are serving, so a
|
|
373
|
+
// deletion that happens while we sit idle cannot go unnoticed.
|
|
374
|
+
this.incarnationAtStart = this.store.getSessionIncarnation(this.sessionId)
|
|
375
|
+
}
|
|
376
|
+
|
|
377
|
+
// [PHASE 6X] DURABLE, CROSS-PROCESS AUTHORITY.
|
|
378
|
+
//
|
|
379
|
+
// [DESIGN DECISION] Acquired HERE, before any cycle can run, and it is what
|
|
380
|
+
// closes FINDING-02. F02 required TWO reconcilers to coexist on one session;
|
|
381
|
+
// process-local ownership cannot see another OS process, so a second process
|
|
382
|
+
// used to sail past it and revert the first one's live execution. This is a
|
|
383
|
+
// single atomic statement, so a race has exactly one winner.
|
|
384
|
+
//
|
|
385
|
+
// The token is generated per `start()` and is never a PID or an object
|
|
386
|
+
// identity, so a restarted process can never present its predecessor's token.
|
|
387
|
+
const token = this.authorityToken ?? newOwnerToken()
|
|
388
|
+
this.authorityToken = token
|
|
389
|
+
const acquired = this.store.acquireSessionAuthority(this.sessionId, token, SESSION_LEASE_MS)
|
|
390
|
+
if (acquired === "REFUSED_LEASE_HELD") {
|
|
391
|
+
// Fail CLOSED, and release the process-local token we just took so the loser
|
|
392
|
+
// leaves nothing half-installed.
|
|
393
|
+
if (this.owner !== null) {
|
|
394
|
+
releaseSessionOwnership(this.sessionId, this.owner, "stopped")
|
|
395
|
+
this.owner = null
|
|
396
|
+
}
|
|
397
|
+
this.state = "STOPPED"
|
|
398
|
+
throw new SchedulerError(
|
|
399
|
+
"ownership-unavailable",
|
|
400
|
+
`session ${this.sessionId} already has a valid autonomous lease held by another process`,
|
|
401
|
+
)
|
|
402
|
+
}
|
|
403
|
+
|
|
404
|
+
// [PHASE 6X] Renewal while the scheduler is live. `unref()` so it never keeps
|
|
405
|
+
// the process alive on its own, and cleared on every stop path.
|
|
406
|
+
this.renewTimer = setInterval(() => {
|
|
407
|
+
if (this.authorityToken === null) return
|
|
408
|
+
if (
|
|
409
|
+
this.store.renewSessionAuthority(this.sessionId, this.authorityToken, SESSION_LEASE_MS) ===
|
|
410
|
+
"AUTHORITY_LOST"
|
|
411
|
+
) {
|
|
412
|
+
this.loseAuthority()
|
|
413
|
+
}
|
|
414
|
+
}, SESSION_RENEW_INTERVAL_MS)
|
|
415
|
+
this.renewTimer.unref?.()
|
|
416
|
+
|
|
417
|
+
this.state = "RUNNING"
|
|
418
|
+
}
|
|
419
|
+
|
|
420
|
+
/**
|
|
421
|
+
* [PHASE 6X] Authority lost: a lease expired and someone else took it, or the
|
|
422
|
+
* session was deleted out from under us.
|
|
423
|
+
*
|
|
424
|
+
* [DESIGN DECISION] Fail closed IMMEDIATELY and loudly. The alternative —
|
|
425
|
+
* carrying on and discovering the loss at the next write — would mean scheduling
|
|
426
|
+
* without authority in the meantime, which is exactly what F02 exploited. We
|
|
427
|
+
* cancel the in-flight turn because continuing to spend a provider on work we
|
|
428
|
+
* may no longer write is worse than stopping; 6Q's incarnation check remains the
|
|
429
|
+
* durable backstop if the turn completes anyway.
|
|
430
|
+
*/
|
|
431
|
+
private loseAuthority(): void {
|
|
432
|
+
if (this.state === "STOPPED") return
|
|
433
|
+
this.authorityLost = true
|
|
434
|
+
this.emit({ kind: "cycle:stopped", reason: "authority-lost" })
|
|
435
|
+
this.cancelActive("emergency-stop")
|
|
436
|
+
this.disposeSelf()
|
|
437
|
+
}
|
|
438
|
+
|
|
439
|
+
/** True only while this instance still holds valid cross-process authority. */
|
|
440
|
+
hasAuthority(): boolean {
|
|
441
|
+
if (this.authorityToken === null || this.authorityLost) return false
|
|
442
|
+
return this.store.holdsSessionAuthority(this.sessionId, this.authorityToken)
|
|
443
|
+
}
|
|
444
|
+
|
|
445
|
+
/**
|
|
446
|
+
* Prevent future dispatch. Does NOT cancel tasks, does NOT delete, does NOT
|
|
447
|
+
* silently release an in-flight claim, and writes no durable state merely
|
|
448
|
+
* because stopping happened. Safe to call repeatedly.
|
|
449
|
+
*
|
|
450
|
+
* STOPPED is not CANCELLED. A claimed task stays IN_PROGRESS until some
|
|
451
|
+
* legitimate transition (a verifier, an operator, or a later reconciliation by
|
|
452
|
+
* an owner) moves it.
|
|
453
|
+
*/
|
|
454
|
+
async stop(): Promise<void> {
|
|
455
|
+
if (this.state === "STOPPED" || this.state === "STOPPING") return
|
|
456
|
+
this.state = "STOPPING"
|
|
457
|
+
// [PHASE 6T] Ask the live turn to stop, THEN let the cycle finish unwinding.
|
|
458
|
+
//
|
|
459
|
+
// The await below is what makes this a graceful stop rather than a crash-like
|
|
460
|
+
// one: the abort gives the turn a chance to unwind and release its resources
|
|
461
|
+
// before we return, so the attempt can still be recorded as an attempt. The
|
|
462
|
+
// durable outcome does not depend on this succeeding — 6Q's reconciliation
|
|
463
|
+
// covers a turn that never came back.
|
|
464
|
+
this.cancelActive("scheduler-stopped")
|
|
465
|
+
// Let an in-flight cycle finish so a dispatch is never half-abandoned.
|
|
466
|
+
if (this.inFlight !== null) {
|
|
467
|
+
try {
|
|
468
|
+
await this.inFlight
|
|
469
|
+
} catch {
|
|
470
|
+
// An in-flight failure is already reported through the cycle result.
|
|
471
|
+
}
|
|
472
|
+
}
|
|
473
|
+
this.state = "STOPPED"
|
|
474
|
+
this.releaseAuthority()
|
|
475
|
+
if (this.owner !== null) {
|
|
476
|
+
releaseSessionOwnership(this.sessionId, this.owner, "stopped")
|
|
477
|
+
this.owner = null
|
|
478
|
+
}
|
|
479
|
+
}
|
|
480
|
+
|
|
481
|
+
getActiveClaim(): ActiveClaim | null {
|
|
482
|
+
return this.claim
|
|
483
|
+
}
|
|
484
|
+
|
|
485
|
+
/**
|
|
486
|
+
* [PHASE 6T] The handle for the turn in flight, or null when nothing is running.
|
|
487
|
+
*
|
|
488
|
+
* Exposed so a lifecycle owner can observe cancellation state without being able
|
|
489
|
+
* to fabricate it. Cancelling is `cancelActive`.
|
|
490
|
+
*/
|
|
491
|
+
getActiveExecution(): ExecutionHandle | null {
|
|
492
|
+
return this.active
|
|
493
|
+
}
|
|
494
|
+
|
|
495
|
+
/**
|
|
496
|
+
* [PHASE 6T] CANCEL THE TURN IN FLIGHT.
|
|
497
|
+
*
|
|
498
|
+
* Returns true when there was something to cancel. Safe to call repeatedly and
|
|
499
|
+
* safe to call when nothing is running — it simply reports that there was
|
|
500
|
+
* nothing to do.
|
|
501
|
+
*
|
|
502
|
+
* [DESIGN DECISION] This CANCELS, it does not RELEASE. The task stays
|
|
503
|
+
* IN_PROGRESS and keeps its generation: cancelling the work is not the same as
|
|
504
|
+
* declaring the work finished, and a cancelled task is moved by a legitimate
|
|
505
|
+
* authority (a verifier, an operator, or a later reconciliation), never by the
|
|
506
|
+
* thing that stopped it. Writing a status here would be exactly the scheduler
|
|
507
|
+
* inventing a verdict, which 6C/6I forbade.
|
|
508
|
+
*
|
|
509
|
+
* This is the LIVE half of the cancellation story. 6Q's incarnation check remains
|
|
510
|
+
* the durable half and is untouched: cancelling cannot be relied on (the turn may
|
|
511
|
+
* be blocked in a syscall the abort cannot reach, or the process may die first),
|
|
512
|
+
* so the write-time protection stays.
|
|
513
|
+
*/
|
|
514
|
+
cancelActive(reason: CancelReason): boolean {
|
|
515
|
+
const handle = this.active
|
|
516
|
+
if (handle === null) return false
|
|
517
|
+
handle.cancel(reason)
|
|
518
|
+
return true
|
|
519
|
+
}
|
|
520
|
+
|
|
521
|
+
/**
|
|
522
|
+
* [PHASE 6Q] Synchronously end this instance because its session is gone.
|
|
523
|
+
*
|
|
524
|
+
* Releases the process-local ownership token and moves to `STOPPED`, so a
|
|
525
|
+
* replacement Scheduler for a recreated session can acquire it.
|
|
526
|
+
*
|
|
527
|
+
* Deliberately NOT `stop()`: that awaits the in-flight cycle, and the only
|
|
528
|
+
* caller of this method is the in-flight cycle itself, so awaiting it would
|
|
529
|
+
* deadlock. Synchronous disposal is the only correct shape at this point.
|
|
530
|
+
*/
|
|
531
|
+
/**
|
|
532
|
+
* [PHASE 6X] Stop renewing and give the lease back — but only if it is still
|
|
533
|
+
* OURS. A stale instance whose lease was taken over must not clear the
|
|
534
|
+
* successor's authority (6X section 8).
|
|
535
|
+
*/
|
|
536
|
+
private releaseAuthority(): void {
|
|
537
|
+
if (this.renewTimer !== null) {
|
|
538
|
+
clearInterval(this.renewTimer)
|
|
539
|
+
this.renewTimer = null
|
|
540
|
+
}
|
|
541
|
+
if (this.authorityToken !== null) {
|
|
542
|
+
this.store.releaseSessionAuthority(this.sessionId, this.authorityToken)
|
|
543
|
+
this.authorityToken = null
|
|
544
|
+
}
|
|
545
|
+
}
|
|
546
|
+
|
|
547
|
+
private disposeSelf(): void {
|
|
548
|
+
// [PHASE 6X] Give the lease back here too, not just in stop(). 6Q's whole
|
|
549
|
+
// point is that a self-disposed instance must leave the session USABLE, and
|
|
550
|
+
// a retained lease would lock the replacement out for a full lease period.
|
|
551
|
+
// Safe on the authority-lost path as well: release is token-guarded, so a
|
|
552
|
+
// stale instance can only ever fail to release, never evict its successor.
|
|
553
|
+
this.releaseAuthority()
|
|
554
|
+
if (this.state === "STOPPED") return
|
|
555
|
+
// [PHASE 6T] Stop the WORK as well as the instance.
|
|
556
|
+
//
|
|
557
|
+
// 6Q made a late return harmless; it did not stop the turn from running. Now
|
|
558
|
+
// that a cancellation handle exists, session deletion asks the live execution
|
|
559
|
+
// to stop, which is the invariant 6T requires: deletion should end autonomous
|
|
560
|
+
// work as early as the runtime permits, with 6Q's incarnation check still
|
|
561
|
+
// there as the final boundary if the request is ignored or arrives too late.
|
|
562
|
+
//
|
|
563
|
+
// Ordering matters: cancel BEFORE releasing ownership, so nothing can start a
|
|
564
|
+
// replacement and race this instance's dying turn.
|
|
565
|
+
this.cancelActive("session-deleted")
|
|
566
|
+
// [PHASE 6X] ...and give the lease back, for the same reason: a superseded
|
|
567
|
+
// session must be immediately schedulable by its replacement. Ordering is
|
|
568
|
+
// unchanged - cancel first, then release.
|
|
569
|
+
this.releaseAuthority()
|
|
570
|
+
this.state = "STOPPED"
|
|
571
|
+
this.incarnationAtStart = null
|
|
572
|
+
if (this.owner !== null) {
|
|
573
|
+
releaseSessionOwnership(this.sessionId, this.owner, "stopped")
|
|
574
|
+
this.owner = null
|
|
575
|
+
}
|
|
576
|
+
}
|
|
577
|
+
|
|
578
|
+
// ── the cycle ──────────────────────────────────────────────────────────────
|
|
579
|
+
|
|
580
|
+
/**
|
|
581
|
+
* One cycle. Serialized: concurrent callers join the in-flight cycle rather
|
|
582
|
+
* than starting a second one.
|
|
583
|
+
*/
|
|
584
|
+
async cycle(): Promise<CycleResult> {
|
|
585
|
+
if (this.inFlight !== null) {
|
|
586
|
+
// Join the running cycle. This is the whole of V1 concurrency control.
|
|
587
|
+
return this.inFlight
|
|
588
|
+
}
|
|
589
|
+
const run = this.runCycle().finally(() => {
|
|
590
|
+
this.inFlight = null
|
|
591
|
+
})
|
|
592
|
+
this.inFlight = run
|
|
593
|
+
return run
|
|
594
|
+
}
|
|
595
|
+
|
|
596
|
+
private async runCycle(): Promise<CycleResult> {
|
|
597
|
+
if (this.state !== "RUNNING" && this.state !== "IDLE") {
|
|
598
|
+
return { stop: "not-running", dispatched: null, recovered: [] }
|
|
599
|
+
}
|
|
600
|
+
|
|
601
|
+
// [PHASE 6T] IS THIS SESSION STILL THE ONE I STARTED FOR?
|
|
602
|
+
//
|
|
603
|
+
// Checked before anything else, because every later step assumes the task
|
|
604
|
+
// namespace still means something. A session that was deleted underneath us is
|
|
605
|
+
// not "an empty queue" — it is a queue that no longer exists, and treating the
|
|
606
|
+
// two alike is what left an idle Scheduler holding ownership forever.
|
|
607
|
+
//
|
|
608
|
+
// Uses 6Q's incarnation, so it works across processes with no registry and no
|
|
609
|
+
// notification from the deletion path.
|
|
610
|
+
if (this.incarnationAtStart !== null) {
|
|
611
|
+
const current = this.store.getSessionIncarnation(this.sessionId)
|
|
612
|
+
if (current !== this.incarnationAtStart) {
|
|
613
|
+
this.emit({ kind: "cycle:stopped", reason: "session-superseded" })
|
|
614
|
+
this.disposeSelf()
|
|
615
|
+
return { stop: "session-superseded", dispatched: null, recovered: [] }
|
|
616
|
+
}
|
|
617
|
+
}
|
|
618
|
+
|
|
619
|
+
// [PHASE 6X] THE RECONCILIATION BOUNDARY.
|
|
620
|
+
//
|
|
621
|
+
// [DESIGN DECISION] This is the heart of the F02 fix, so it gates every durable
|
|
622
|
+
// effect - before reconciliation, before readiness, before a claim. A Scheduler
|
|
623
|
+
// that has lost its cross-process lease must not touch durable state at all, and
|
|
624
|
+
// `reconcile()` is precisely the code that reverts other people's work.
|
|
625
|
+
//
|
|
626
|
+
// Deliberately AFTER the 6T incarnation check, and that ordering is the point.
|
|
627
|
+
// A deleted-and-recreated session also stops us holding the lease, because the
|
|
628
|
+
// lease is keyed by (session, incarnation) - but "the session I serve was
|
|
629
|
+
// deleted" is the true cause and it has its own accurate diagnosis, release
|
|
630
|
+
// ordering and 6Q backstop. Reporting that as `authority-lost` would be a lie
|
|
631
|
+
// about WHY we stopped, and it would also point at the wrong suspect.
|
|
632
|
+
// `authority-lost` therefore means exactly one thing: our lease is gone and the
|
|
633
|
+
// session is still ours, so another process is the live owner.
|
|
634
|
+
if (!this.hasAuthority()) {
|
|
635
|
+
if (!this.authorityLost) this.loseAuthority()
|
|
636
|
+
return { stop: "authority-lost", dispatched: null, recovered: [] }
|
|
637
|
+
}
|
|
638
|
+
|
|
639
|
+
// [PHASE 6T] CAPACITY, checked BEFORE anything durable happens.
|
|
640
|
+
//
|
|
641
|
+
// [DESIGN DECISION] This is the cheap half of the contention policy and it
|
|
642
|
+
// costs nothing: if the runtime is known to be busy, the cycle stops before it
|
|
643
|
+
// reads a snapshot, builds a graph, or attempts a claim. A trigger that cannot
|
|
644
|
+
// be serviced must not leave a mark — 6O's requirement that "contention is
|
|
645
|
+
// indistinguishable from a real attempt" is satisfied here by not acting at
|
|
646
|
+
// all.
|
|
647
|
+
//
|
|
648
|
+
// It is NOT sufficient on its own: a probe is a read, and another process (or
|
|
649
|
+
// another session) can take the slot between this check and the claim. The
|
|
650
|
+
// atomic capacity predicate inside `claimTask` is the half that actually
|
|
651
|
+
// holds. This one just avoids the wasted work in the overwhelmingly common
|
|
652
|
+
// case of a live user turn.
|
|
653
|
+
if (this.cancellation?.isCancelled() === true) {
|
|
654
|
+
this.emit({ kind: "cycle:stopped", reason: "pre-cancelled" })
|
|
655
|
+
return { stop: "pre-cancelled", dispatched: null, recovered: [] }
|
|
656
|
+
}
|
|
657
|
+
|
|
658
|
+
// 1. Reconciliation first, so a cycle never plans around stranded work.
|
|
659
|
+
const recovered = this.reconcile()
|
|
660
|
+
|
|
661
|
+
// [P13.3 Stage C] The guards at the top of the cycle were true when the pass
|
|
662
|
+
// STARTED. Reconciliation is a durable mutation, and a lease or incarnation can
|
|
663
|
+
// move while it runs. Re-verify before this cycle is allowed to claim or
|
|
664
|
+
// dispatch: a cached "authority held" is never permission to keep going.
|
|
665
|
+
if (
|
|
666
|
+
this.incarnationAtStart !== null &&
|
|
667
|
+
this.store.getSessionIncarnation(this.sessionId) !== this.incarnationAtStart
|
|
668
|
+
) {
|
|
669
|
+
this.emit({ kind: "cycle:stopped", reason: "session-superseded" })
|
|
670
|
+
this.disposeSelf()
|
|
671
|
+
return { stop: "session-superseded", dispatched: null, recovered }
|
|
672
|
+
}
|
|
673
|
+
if (!this.hasAuthority()) {
|
|
674
|
+
if (!this.authorityLost) this.loseAuthority()
|
|
675
|
+
return { stop: "authority-lost", dispatched: null, recovered }
|
|
676
|
+
}
|
|
677
|
+
|
|
678
|
+
// An active claim means work is already associated with this Scheduler. Do
|
|
679
|
+
// not select anything else.
|
|
680
|
+
if (this.claim !== null) {
|
|
681
|
+
return { stop: "already-dispatched", dispatched: null, recovered }
|
|
682
|
+
}
|
|
683
|
+
|
|
684
|
+
// 2. Fresh snapshot. 3. Fresh graph. Never cached across cycles: a claim
|
|
685
|
+
// changes revision, so the graph is stale the moment it is used.
|
|
686
|
+
const snapshot: TaskSnapshot = this.store.getSnapshot(this.sessionId)
|
|
687
|
+
const graph = new TaskGraph(snapshot)
|
|
688
|
+
|
|
689
|
+
// 4. An invalid graph aborts the cycle. No dispatch, no claim.
|
|
690
|
+
if (!graph.validity().valid) {
|
|
691
|
+
this.emit({ kind: "cycle:invalid_graph" })
|
|
692
|
+
return { stop: "invalid-graph", dispatched: null, recovered }
|
|
693
|
+
}
|
|
694
|
+
|
|
695
|
+
// 5. Readiness is CONSUMED, never recomputed.
|
|
696
|
+
const ready = graph.readyTasks()
|
|
697
|
+
|
|
698
|
+
this.state = "IDLE"
|
|
699
|
+
|
|
700
|
+
// 6. Selection is a NAMED POLICY, not an expression.
|
|
701
|
+
//
|
|
702
|
+
// [PHASE 6T] This used to read `ready[0]` inline. That was the same
|
|
703
|
+
// behaviour, but nothing recorded that it WAS a policy, so there was no place
|
|
704
|
+
// to state what selection guarantees and no single function to point a
|
|
705
|
+
// property test at. Routing through `selectTask` makes ORDER ASC -> ID ASC a
|
|
706
|
+
// decision that can be read, argued and mutated, rather than a coincidence
|
|
707
|
+
// of array indexing.
|
|
708
|
+
//
|
|
709
|
+
// The policy does NOT re-derive readiness; it is handed the graph's answer and
|
|
710
|
+
// only chooses among it. A second readiness implementation here is the way a
|
|
711
|
+
// scheduler starts disagreeing with its own graph.
|
|
712
|
+
const selection = selectTask(ready, snapshot)
|
|
713
|
+
const taskId = selection.taskId
|
|
714
|
+
if (taskId === null) {
|
|
715
|
+
this.emit({
|
|
716
|
+
kind: "cycle:stopped",
|
|
717
|
+
reason: selection.reason === "no-ready-tasks" ? "no-candidates" : "no-candidates",
|
|
718
|
+
})
|
|
719
|
+
return { stop: "no-candidates", dispatched: null, recovered }
|
|
720
|
+
}
|
|
721
|
+
this.emit({ kind: "task:selected", taskId })
|
|
722
|
+
|
|
723
|
+
// 7. Re-read the authoritative row. The graph's view is NOT currency.
|
|
724
|
+
const current = this.store.getTask(this.sessionId, taskId)
|
|
725
|
+
if (current === null) {
|
|
726
|
+
this.emit({ kind: "task:claim_rejected", taskId, outcome: "NOT_FOUND" })
|
|
727
|
+
this.emit({ kind: "cycle:stopped", reason: "claim-not-found" })
|
|
728
|
+
return { stop: "claim-not-found", dispatched: null, recovered }
|
|
729
|
+
}
|
|
730
|
+
|
|
731
|
+
// 8. Atomic, revision-guarded claim. Never retried in a loop, never slept on.
|
|
732
|
+
//
|
|
733
|
+
// [PHASE 6T] `exclusive: true` adds the capacity predicate to this same
|
|
734
|
+
// statement, so losing the slot to another executor is reported exactly like
|
|
735
|
+
// losing the revision race: the row is untouched, and no generation is spent.
|
|
736
|
+
const claimResult = this.store.claimTask(this.sessionId, taskId, current.revision, {
|
|
737
|
+
exclusive: true,
|
|
738
|
+
})
|
|
739
|
+
if (claimResult.outcome !== "CLAIM_ACCEPTED") {
|
|
740
|
+
this.emit({ kind: "task:claim_rejected", taskId, outcome: claimResult.outcome })
|
|
741
|
+
const stop: CycleStop =
|
|
742
|
+
claimResult.outcome === "CLAIM_REJECTED_STALE"
|
|
743
|
+
? "claim-rejected-stale"
|
|
744
|
+
: claimResult.outcome === "NOT_FOUND"
|
|
745
|
+
? "claim-not-found"
|
|
746
|
+
: claimResult.outcome === "CLAIM_REJECTED_BUSY"
|
|
747
|
+
? "contended"
|
|
748
|
+
: "claim-wrong-state"
|
|
749
|
+
this.emit({ kind: "cycle:stopped", reason: stop })
|
|
750
|
+
return { stop, dispatched: null, recovered }
|
|
751
|
+
}
|
|
752
|
+
|
|
753
|
+
// 9. Record the POST-claim revision. This is the release currency.
|
|
754
|
+
const accepted = claimResult.task
|
|
755
|
+
if (accepted === null) {
|
|
756
|
+
// Cannot happen: a 1-row UPDATE always leaves a readable row. Treat as a
|
|
757
|
+
// persistence inconsistency rather than pretending it is fine.
|
|
758
|
+
throw new SchedulerError("persistence", "claim accepted but task is unreadable")
|
|
759
|
+
}
|
|
760
|
+
this.claim = {
|
|
761
|
+
taskId,
|
|
762
|
+
claimRevision: accepted.revision,
|
|
763
|
+
execGeneration: claimResult.execGeneration,
|
|
764
|
+
sessionIncarnation: claimResult.sessionIncarnation,
|
|
765
|
+
}
|
|
766
|
+
this.emit({ kind: "task:claimed", taskId, revision: accepted.revision })
|
|
767
|
+
|
|
768
|
+
// 10. Dispatch through the injected bridge only.
|
|
769
|
+
const dispatched = await this.dispatch({
|
|
770
|
+
taskId,
|
|
771
|
+
title: accepted.title,
|
|
772
|
+
instruction: this.instruction,
|
|
773
|
+
sessionId: this.sessionId,
|
|
774
|
+
})
|
|
775
|
+
return {
|
|
776
|
+
stop: dispatched.ok ? "already-dispatched" : "already-dispatched",
|
|
777
|
+
dispatched,
|
|
778
|
+
recovered,
|
|
779
|
+
}
|
|
780
|
+
}
|
|
781
|
+
|
|
782
|
+
private async dispatch(work: SchedulerWorkItem): Promise<DispatchResult> {
|
|
783
|
+
// [PHASE 6T] One cleanup point for the per-turn handle.
|
|
784
|
+
//
|
|
785
|
+
// `dispatchTracked` has seven terminal returns and more will be added over
|
|
786
|
+
// time; clearing the handle in each of them is exactly the kind of thing that
|
|
787
|
+
// rots silently when a path is missed. A `finally` makes "the handle never
|
|
788
|
+
// outlives its turn" a structural property instead of a per-branch intention.
|
|
789
|
+
try {
|
|
790
|
+
return await this.dispatchTracked(work)
|
|
791
|
+
} finally {
|
|
792
|
+
this.active?.dispose()
|
|
793
|
+
this.active = null
|
|
794
|
+
}
|
|
795
|
+
}
|
|
796
|
+
|
|
797
|
+
private async dispatchTracked(work: SchedulerWorkItem): Promise<DispatchResult> {
|
|
798
|
+
// An injected cancellation contract may refuse NEW work. It cannot abort an
|
|
799
|
+
// in-flight agent loop — that ability is the composition root's, not ours.
|
|
800
|
+
if (
|
|
801
|
+
this.state === "STOPPING" ||
|
|
802
|
+
this.state === "STOPPED" ||
|
|
803
|
+
this.cancellation?.isCancelled() === true
|
|
804
|
+
) {
|
|
805
|
+
// Stop (or cancellation) happened after the claim. The claim is NOT
|
|
806
|
+
// silently released; the task stays IN_PROGRESS for a legitimate authority
|
|
807
|
+
// to move. Cancelling is not releasing.
|
|
808
|
+
return {
|
|
809
|
+
ok: false,
|
|
810
|
+
failure: "scheduler-not-running",
|
|
811
|
+
observation: null,
|
|
812
|
+
released: false,
|
|
813
|
+
lineage: "NOT_ATTEMPTED",
|
|
814
|
+
}
|
|
815
|
+
}
|
|
816
|
+
this.emit({ kind: "task:dispatch_started", taskId: work.taskId })
|
|
817
|
+
|
|
818
|
+
// [PHASE 6T] Create the per-execution cancellation handle and publish it
|
|
819
|
+
// BEFORE the bridge is called, so a cancel racing dispatch is recorded rather
|
|
820
|
+
// than lost. The bridge attaches its abort function; if cancellation already
|
|
821
|
+
// happened, `attach` fires immediately.
|
|
822
|
+
//
|
|
823
|
+
// Held on the instance, not in a closure, so `cancelActive()` can reach it.
|
|
824
|
+
// Cleared on every terminal path below, so a dead turn is never retained.
|
|
825
|
+
const handle = newExecutionHandle()
|
|
826
|
+
this.active = handle
|
|
827
|
+
|
|
828
|
+
let produced: Promise<ExecutionObservation> | ExecutionObservation
|
|
829
|
+
try {
|
|
830
|
+
produced = this.runTurn(work, handle)
|
|
831
|
+
} catch (e) {
|
|
832
|
+
// A. Dispatch/setup failure: the attempt was NEVER established. The claim
|
|
833
|
+
// is released back to PENDING so the task is not stranded by our own
|
|
834
|
+
// inability to start it.
|
|
835
|
+
const detail = e instanceof Error ? e.message : String(e)
|
|
836
|
+
this.emit({ kind: "task:execution_completed", taskId: work.taskId, ok: false })
|
|
837
|
+
const released = this.releaseClaim("dispatch-failed")
|
|
838
|
+
return {
|
|
839
|
+
ok: false,
|
|
840
|
+
failure: "bridge-threw",
|
|
841
|
+
observation: { kind: "rejected", detail },
|
|
842
|
+
released,
|
|
843
|
+
lineage: "NOT_ATTEMPTED",
|
|
844
|
+
}
|
|
845
|
+
}
|
|
846
|
+
|
|
847
|
+
if (
|
|
848
|
+
!(produced instanceof Promise) &&
|
|
849
|
+
typeof (produced as ExecutionObservation)?.kind !== "string"
|
|
850
|
+
) {
|
|
851
|
+
const released = this.releaseClaim("dispatch-failed")
|
|
852
|
+
return {
|
|
853
|
+
ok: false,
|
|
854
|
+
failure: "bridge-not-callable",
|
|
855
|
+
observation: null,
|
|
856
|
+
released,
|
|
857
|
+
lineage: "NOT_ATTEMPTED",
|
|
858
|
+
}
|
|
859
|
+
}
|
|
860
|
+
|
|
861
|
+
this.emit({ kind: "task:execution_started", taskId: work.taskId })
|
|
862
|
+
|
|
863
|
+
// B. Execution began. Its outcome is an OBSERVATION. Scheduler does not
|
|
864
|
+
// decide whether the work succeeded and never writes COMPLETED.
|
|
865
|
+
let observation: ExecutionObservation
|
|
866
|
+
try {
|
|
867
|
+
observation = await produced
|
|
868
|
+
} catch (e) {
|
|
869
|
+
observation = { kind: "rejected", detail: e instanceof Error ? e.message : String(e) }
|
|
870
|
+
}
|
|
871
|
+
this.emit({
|
|
872
|
+
kind: "task:execution_completed",
|
|
873
|
+
taskId: work.taskId,
|
|
874
|
+
ok: observation.kind === "returned" && observation.ok,
|
|
875
|
+
})
|
|
876
|
+
|
|
877
|
+
// [PHASE 6I] Record that this EXECUTION GENERATION's attempt ended, before
|
|
878
|
+
// dropping the in-memory claim.
|
|
879
|
+
//
|
|
880
|
+
// The generation is the one the accepted claim created. It is NOT the
|
|
881
|
+
// revision, and it is NOT re-read from the task: inferring lineage from
|
|
882
|
+
// mutable task state is precisely the confusion 6G D1 exposed. An
|
|
883
|
+
// unrelated write that bumped `revision` after the claim cannot change
|
|
884
|
+
// what is recorded here.
|
|
885
|
+
//
|
|
886
|
+
// `observation.ok` is deliberately NOT consulted. A rejected turn and a
|
|
887
|
+
// successful turn are both "an attempt ended"; conflating them with
|
|
888
|
+
// success is the bug this replaces. EXECUTION != VERIFICATION !=
|
|
889
|
+
// COMPLETION.
|
|
890
|
+
//
|
|
891
|
+
// [PHASE 6Q] THE CLAIM IS RELEASED ON EVERY TERMINAL PATH.
|
|
892
|
+
//
|
|
893
|
+
// This is the fix for 6N F2, and the reason it is a restructure rather than
|
|
894
|
+
// a try/catch. Previously the claim was cleared on ONE line AFTER the
|
|
895
|
+
// lineage write, so any failure in between - above all the "session was
|
|
896
|
+
// deleted under this execution" case - escaped `cycle()` with the claim
|
|
897
|
+
// still set. `runCycle` returns `already-dispatched` whenever a claim
|
|
898
|
+
// exists, and `stop()` had already been passed, so the instance was
|
|
899
|
+
// permanently wedged AND still held session ownership, which prevented any
|
|
900
|
+
// replacement from starting.
|
|
901
|
+
//
|
|
902
|
+
// The attempt HAS ended at this point, whatever the store says about
|
|
903
|
+
// recording it. So the bookkeeping is settled first, unconditionally, and
|
|
904
|
+
// the lineage write is a pure side effect whose result is reported rather
|
|
905
|
+
// than allowed to strand the instance.
|
|
906
|
+
const generation = this.claim
|
|
907
|
+
this.claim = null
|
|
908
|
+
if (generation === null) {
|
|
909
|
+
// The claim was cleared while the turn was in flight. We no longer know
|
|
910
|
+
// which generation this was, so recording one would be a guess. Refuse to
|
|
911
|
+
// fabricate evidence - and return rather than throw, so an unidentified
|
|
912
|
+
// attempt can never become a lifecycle wedge either.
|
|
913
|
+
this.emit({ kind: "task:execution_completed", taskId: work.taskId, ok: false })
|
|
914
|
+
return {
|
|
915
|
+
ok: observation.kind === "returned" && observation.ok,
|
|
916
|
+
failure: "attempt-unidentified",
|
|
917
|
+
observation,
|
|
918
|
+
released: true,
|
|
919
|
+
lineage: "TASK_GONE",
|
|
920
|
+
}
|
|
921
|
+
}
|
|
922
|
+
const lineage = this.store.recordAttemptReturned(
|
|
923
|
+
this.sessionId,
|
|
924
|
+
generation.taskId,
|
|
925
|
+
generation.execGeneration,
|
|
926
|
+
generation.sessionIncarnation,
|
|
927
|
+
)
|
|
928
|
+
if (lineage !== "RECORDED") {
|
|
929
|
+
// The attempt ended but its completion was NOT recorded. This is now an
|
|
930
|
+
// ordinary, classified outcome - the session was deleted under this
|
|
931
|
+
// execution, or a later generation superseded it. Nothing was written, so
|
|
932
|
+
// the task is left exactly as it was and the next owner decides its fate.
|
|
933
|
+
this.emit({ kind: "task:execution_abandoned", taskId: generation.taskId, outcome: lineage })
|
|
934
|
+
}
|
|
935
|
+
if (lineage === "TASK_GONE" || lineage === "SESSION_SUPERSEDED") {
|
|
936
|
+
// [PHASE 6Q] The session this Scheduler was executing FOR no longer exists
|
|
937
|
+
// (or exists as a different lifetime). That is durable evidence, learned
|
|
938
|
+
// from the store rather than announced by anyone, so it works across
|
|
939
|
+
// processes without a registry and without the deletion path having to know
|
|
940
|
+
// that any Scheduler exists.
|
|
941
|
+
//
|
|
942
|
+
// Self-dispose: release the session ownership token and become STOPPED, so
|
|
943
|
+
// a REPLACEMENT Scheduler can start. Without this the instance stayed IDLE
|
|
944
|
+
// but kept the ownership, which is precisely the second half of 6N F2.
|
|
945
|
+
//
|
|
946
|
+
// `stop()` cannot be used here: it awaits the in-flight cycle, and this IS
|
|
947
|
+
// the in-flight cycle, so awaiting it would deadlock.
|
|
948
|
+
this.disposeSelf()
|
|
949
|
+
}
|
|
950
|
+
return {
|
|
951
|
+
ok: observation.kind === "returned" && observation.ok,
|
|
952
|
+
failure: null,
|
|
953
|
+
observation,
|
|
954
|
+
released: true,
|
|
955
|
+
lineage,
|
|
956
|
+
}
|
|
957
|
+
}
|
|
958
|
+
|
|
959
|
+
/**
|
|
960
|
+
* Revert THIS Scheduler's own claim from IN_PROGRESS back to PENDING using the
|
|
961
|
+
* POST-claim revision. Only justified for the case the design locked: the
|
|
962
|
+
* claim succeeded but dispatch could not be established, so the task is
|
|
963
|
+
* stranded by our own failure to start it.
|
|
964
|
+
*
|
|
965
|
+
* Never used because execution returned an error, because stop() was called,
|
|
966
|
+
* or because verification is pending — those belong to other authorities.
|
|
967
|
+
*/
|
|
968
|
+
private releaseClaim(why: "dispatch-failed"): boolean {
|
|
969
|
+
const active = this.claim
|
|
970
|
+
if (active === null) return false
|
|
971
|
+
// The reason is an observation, not a durable fact: it tells an operator why
|
|
972
|
+
// the task went back to PENDING without inventing a status for it.
|
|
973
|
+
this.emit({ kind: "cycle:stopped", reason: "claim-wrong-state" })
|
|
974
|
+
void why
|
|
975
|
+
const result = this.store.reconcileStranded(
|
|
976
|
+
this.sessionId,
|
|
977
|
+
active.taskId,
|
|
978
|
+
active.claimRevision,
|
|
979
|
+
{
|
|
980
|
+
ownsSession: ownsSession(this.sessionId, this.owner),
|
|
981
|
+
},
|
|
982
|
+
)
|
|
983
|
+
this.claim = null
|
|
984
|
+
return result.outcome === "RECONCILED"
|
|
985
|
+
}
|
|
986
|
+
|
|
987
|
+
// ── reconciliation ──────────────────────────────────────────────────────────
|
|
988
|
+
|
|
989
|
+
/**
|
|
990
|
+
* Revert stranded in-flight tasks. Runs at the START of every cycle — the P77
|
|
991
|
+
* lesson, where a scheduler went IDLE with no in-process path back.
|
|
992
|
+
*
|
|
993
|
+
* Ownership-aware and fail-closed: without positively-held ownership this
|
|
994
|
+
* refuses rather than guessing, because reverting live work is worse than
|
|
995
|
+
* leaving it stranded.
|
|
996
|
+
*
|
|
997
|
+
* [PHASE 6F] The decision is made on EVIDENCE, not on status. The old rule
|
|
998
|
+
* reverted every `IN_PROGRESS` row that was not this Scheduler's current
|
|
999
|
+
* in-memory claim — which, because the claim is cleared after every dispatch,
|
|
1000
|
+
* reverted the Scheduler's own freshly completed work and re-executed it
|
|
1001
|
+
* forever. A generation may be reverted only when it has no completion
|
|
1002
|
+
* marker.
|
|
1003
|
+
*
|
|
1004
|
+
* [P13.3 Stage C] NO MARKER IS NOT PROOF OF NO SIDE EFFECT. A crashed attempt
|
|
1005
|
+
* may already have written files or run commands; a new attempt would repeat
|
|
1006
|
+
* them. Every candidate is therefore classified before the store is asked to
|
|
1007
|
+
* revert it, and only SAFE_TO_RETRY (evidence-backed retry safety, e.g. a
|
|
1008
|
+
* bridge whose entire tool scope is read-only) proceeds. Without a continuity
|
|
1009
|
+
* gate the result is HOLD: the record is preserved and the next cycle
|
|
1010
|
+
* re-evaluates. Reconcile still never writes COMPLETED and never dispatches.
|
|
1011
|
+
*/
|
|
1012
|
+
reconcile(): readonly string[] {
|
|
1013
|
+
// [PHASE 6X] No authority, no reconciliation. Unconditionally: this is the single
|
|
1014
|
+
// function that reverts another party's in-flight work, and it is exactly what
|
|
1015
|
+
// FINDING-02 used.
|
|
1016
|
+
if (!this.hasAuthority()) {
|
|
1017
|
+
if (!this.authorityLost) this.loseAuthority()
|
|
1018
|
+
return []
|
|
1019
|
+
}
|
|
1020
|
+
const owned = ownsSession(this.sessionId, this.owner)
|
|
1021
|
+
if (!owned) {
|
|
1022
|
+
this.emit({ kind: "cycle:stopped", reason: "ownership-unavailable" })
|
|
1023
|
+
return []
|
|
1024
|
+
}
|
|
1025
|
+
const snapshot = this.store.getSnapshot(this.sessionId)
|
|
1026
|
+
const stranded: string[] = []
|
|
1027
|
+
const incarnationMatches =
|
|
1028
|
+
this.incarnationAtStart === null ||
|
|
1029
|
+
this.store.getSessionIncarnation(this.sessionId) === this.incarnationAtStart
|
|
1030
|
+
|
|
1031
|
+
// [P13.3 Stage C] ONE evidence read per reconcile pass, and only when there
|
|
1032
|
+
// is at least one in-flight candidate. The provider may probe the runtime,
|
|
1033
|
+
// storage and journal; doing that for an empty queue would be pure cost.
|
|
1034
|
+
let evidence: ContinuityEvidence | null = null
|
|
1035
|
+
const evidenceForPass = (): ContinuityEvidence => {
|
|
1036
|
+
if (evidence !== null) return evidence
|
|
1037
|
+
evidence = this.continuityEvidence({
|
|
1038
|
+
ownsSession: owned,
|
|
1039
|
+
authorityHeld: true,
|
|
1040
|
+
incarnationMatches,
|
|
1041
|
+
})
|
|
1042
|
+
return evidence
|
|
1043
|
+
}
|
|
1044
|
+
|
|
1045
|
+
for (const task of snapshot.tasks) {
|
|
1046
|
+
// Only the two in-flight states are ever targets. Terminal and operator
|
|
1047
|
+
// states are untouched by construction, not by a later check.
|
|
1048
|
+
if (task.status !== "IN_PROGRESS" && task.status !== "VERIFYING") continue
|
|
1049
|
+
// Never revert the task this Scheduler is actively executing.
|
|
1050
|
+
if (this.claim?.taskId === task.id) continue
|
|
1051
|
+
|
|
1052
|
+
// [PHASE 6I] Read the two durable facts separately. TaskStore remains the
|
|
1053
|
+
// owner of the atomic lineage predicate below; these reads are only the
|
|
1054
|
+
// INPUT to the retry-safety classification, never a replacement for it.
|
|
1055
|
+
const lineage = this.store.getExecutionLineage(this.sessionId, task.id)
|
|
1056
|
+
if (lineage === null) continue
|
|
1057
|
+
|
|
1058
|
+
// [PHASE 6I] An attempt newer than its execution is impossible. Preserve
|
|
1059
|
+
// the store's loud invariant instead of silently classifying it: guessing
|
|
1060
|
+
// which side is wrong either strands live work or re-runs finished work.
|
|
1061
|
+
if (
|
|
1062
|
+
lineage.attemptGeneration !== null &&
|
|
1063
|
+
lineage.attemptGeneration > lineage.execGeneration
|
|
1064
|
+
) {
|
|
1065
|
+
throw new TaskError(
|
|
1066
|
+
"TASK_PERSISTENCE_FAILURE",
|
|
1067
|
+
`attempt generation ${lineage.attemptGeneration} exceeds execution generation ${lineage.execGeneration} for ${this.sessionId}/${task.id}`,
|
|
1068
|
+
)
|
|
1069
|
+
}
|
|
1070
|
+
|
|
1071
|
+
const ownership = this.store.getExecutionOwnership(this.sessionId, task.id)
|
|
1072
|
+
if (ownership === null) continue
|
|
1073
|
+
|
|
1074
|
+
const verdict = classifyContinuity(
|
|
1075
|
+
{
|
|
1076
|
+
status: task.status,
|
|
1077
|
+
executionOwner: ownership.executionOwner,
|
|
1078
|
+
execGeneration: lineage.execGeneration,
|
|
1079
|
+
attemptGeneration: lineage.attemptGeneration,
|
|
1080
|
+
ownsSession: owned,
|
|
1081
|
+
authorityHeld: true,
|
|
1082
|
+
incarnationMatches,
|
|
1083
|
+
},
|
|
1084
|
+
evidenceForPass(),
|
|
1085
|
+
)
|
|
1086
|
+
|
|
1087
|
+
// [P13.3 Stage C] Only SAFE_TO_RETRY returns to the claim/dispatch cycle.
|
|
1088
|
+
// HOLD and REQUIRES_VERIFIER both leave the durable record untouched; the
|
|
1089
|
+
// next cycle re-evaluates, so recovery is never "dropped".
|
|
1090
|
+
if (!verdict.mayReconcile) {
|
|
1091
|
+
this.emit({
|
|
1092
|
+
kind: "task:continuity_held",
|
|
1093
|
+
taskId: task.id,
|
|
1094
|
+
class: verdict.class,
|
|
1095
|
+
reason: verdict.reason,
|
|
1096
|
+
})
|
|
1097
|
+
continue
|
|
1098
|
+
}
|
|
1099
|
+
|
|
1100
|
+
// [P13.3 Stage C] Re-verify IMMEDIATELY before the durable mutation. The
|
|
1101
|
+
// evidence was read earlier in this pass; a lease/incarnation that moved in
|
|
1102
|
+
// between must not authorise a revert with the old token. Stop the pass and
|
|
1103
|
+
// let TaskStore keep its record untouched.
|
|
1104
|
+
if (!this.hasAuthority()) {
|
|
1105
|
+
this.loseAuthority()
|
|
1106
|
+
break
|
|
1107
|
+
}
|
|
1108
|
+
if (
|
|
1109
|
+
this.incarnationAtStart !== null &&
|
|
1110
|
+
this.store.getSessionIncarnation(this.sessionId) !== this.incarnationAtStart
|
|
1111
|
+
) {
|
|
1112
|
+
this.disposeSelf()
|
|
1113
|
+
break
|
|
1114
|
+
}
|
|
1115
|
+
|
|
1116
|
+
// [PHASE 6I] The lineage decision belongs to TaskStore, which owns both
|
|
1117
|
+
// generation columns and can make it in ONE atomic guarded statement. The
|
|
1118
|
+
// Scheduler contributes ownership and nothing else: it does not compare
|
|
1119
|
+
// generations here, and has no rule of its own.
|
|
1120
|
+
//
|
|
1121
|
+
// This is what closes 6G D1. The decision cannot be influenced by an
|
|
1122
|
+
// unrelated task write, because `exec_generation` advances only on an
|
|
1123
|
+
// accepted claim - not by the title, order, dependency, evidence or status
|
|
1124
|
+
// writes that also advance `revision`. A stale snapshot still loses here.
|
|
1125
|
+
const result = this.store.reconcileIfNoCompletedAttempt(
|
|
1126
|
+
this.sessionId,
|
|
1127
|
+
task.id,
|
|
1128
|
+
task.revision,
|
|
1129
|
+
{
|
|
1130
|
+
ownsSession: owned,
|
|
1131
|
+
},
|
|
1132
|
+
)
|
|
1133
|
+
if (result.outcome === "RECONCILED") stranded.push(task.id)
|
|
1134
|
+
}
|
|
1135
|
+
if (stranded.length > 0) this.emit({ kind: "task:recovered", taskIds: stranded })
|
|
1136
|
+
return stranded
|
|
1137
|
+
}
|
|
1138
|
+
|
|
1139
|
+
/**
|
|
1140
|
+
* [P13.3 Stage C] Evidence for one reconcile pass, fail-closed.
|
|
1141
|
+
*
|
|
1142
|
+
* No gate and a throwing gate are the same verdict: evidence is MISSING.
|
|
1143
|
+
* Treating an unavailable provider as permission would turn a monitoring
|
|
1144
|
+
* failure into duplicate execution.
|
|
1145
|
+
*/
|
|
1146
|
+
private continuityEvidence(ctx: ContinuityContext): ContinuityEvidence {
|
|
1147
|
+
if (this.continuity === null) {
|
|
1148
|
+
return {
|
|
1149
|
+
resume: false,
|
|
1150
|
+
missing: ["continuity-gate-missing"],
|
|
1151
|
+
admission: "REFUSE",
|
|
1152
|
+
retrySafety: "UNPROVEN",
|
|
1153
|
+
}
|
|
1154
|
+
}
|
|
1155
|
+
try {
|
|
1156
|
+
return this.continuity.evidence(ctx)
|
|
1157
|
+
} catch {
|
|
1158
|
+
return {
|
|
1159
|
+
resume: false,
|
|
1160
|
+
missing: ["continuity-gate-error"],
|
|
1161
|
+
admission: "REFUSE",
|
|
1162
|
+
retrySafety: "UNPROVEN",
|
|
1163
|
+
}
|
|
1164
|
+
}
|
|
1165
|
+
}
|
|
1166
|
+
|
|
1167
|
+
private emit(event: SchedulerEvent): void {
|
|
1168
|
+
// A throwing sink must never take the Scheduler down; observations are not
|
|
1169
|
+
// authority and cannot be load-bearing.
|
|
1170
|
+
try {
|
|
1171
|
+
this.onEvent?.(event)
|
|
1172
|
+
} catch {
|
|
1173
|
+
/* deliberately swallowed: an observer cannot be allowed to fail a cycle */
|
|
1174
|
+
}
|
|
1175
|
+
}
|
|
1176
|
+
}
|
|
1177
|
+
|
|
1178
|
+
export interface DispatchResult {
|
|
1179
|
+
readonly ok: boolean
|
|
1180
|
+
readonly failure: DispatchFailure | null
|
|
1181
|
+
readonly observation: ExecutionObservation | null
|
|
1182
|
+
readonly released: boolean
|
|
1183
|
+
/**
|
|
1184
|
+
* [PHASE 6Q] What became of the completion marker. `RECORDED` in the normal
|
|
1185
|
+
* case; anything else means the session was deleted or superseded underneath
|
|
1186
|
+
* this execution and NOTHING was written. `NOT_ATTEMPTED` is the pre-attempt
|
|
1187
|
+
* shape: the bridge was never successfully entered, so there was never an
|
|
1188
|
+
* attempt whose completion could be recorded.
|
|
1189
|
+
*/
|
|
1190
|
+
readonly lineage: AttemptRecordOutcome | "NOT_ATTEMPTED"
|
|
1191
|
+
}
|
|
1192
|
+
|
|
1193
|
+
export interface CycleResult {
|
|
1194
|
+
readonly stop: CycleStop
|
|
1195
|
+
readonly dispatched: DispatchResult | null
|
|
1196
|
+
readonly recovered: readonly string[]
|
|
1197
|
+
}
|