minicode-ai 0.11.0 → 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.
Files changed (221) hide show
  1. package/CHANGELOG.md +98 -0
  2. package/LICENSE +21 -21
  3. package/README.md +4 -4
  4. package/cli/args.ts +46 -0
  5. package/cli/commands/acp.ts +163 -10
  6. package/cli/commands/config.ts +33 -18
  7. package/cli/commands/daemon.ts +515 -0
  8. package/cli/commands/exec.ts +145 -53
  9. package/cli/commands/openwork.ts +986 -0
  10. package/cli/commands/sessions.ts +4 -1
  11. package/cli/commands/stats.ts +34 -4
  12. package/cli/commands.ts +217 -2
  13. package/cli/index.ts +146 -14
  14. package/cli/recovery-warning.ts +115 -0
  15. package/cli/router.ts +32 -1
  16. package/cli/setup.ts +2332 -171
  17. package/cli/tui.ts +113 -7
  18. package/docs/OUTPUT_ARCHITECTURE_AUDIT.md +489 -0
  19. package/docs/OUTPUT_EVENT_MODEL.md +289 -0
  20. package/docs/OUTPUT_IMPLEMENTATION_PLAN.md +391 -0
  21. package/docs/OUTPUT_PROTOCOL_SPEC.md +285 -0
  22. package/docs/OUTPUT_RENDERING_SPEC.md +248 -0
  23. package/docs/OUTPUT_UX_RULES.md +449 -0
  24. package/docs/PLAN_UIUX_V6.md +2 -2
  25. package/docs/README.md +4 -3
  26. package/docs/TERMINAL_CONTRACT.md +278 -66
  27. package/docs/architecture.md +89 -7
  28. package/docs/changelog.md +1 -1
  29. package/docs/choosing-mode.md +2 -2
  30. package/docs/cli.md +9 -5
  31. package/docs/concepts.md +1 -1
  32. package/docs/contributing.md +9 -2
  33. package/docs/environment.md +6 -2
  34. package/docs/exec.md +46 -5
  35. package/docs/memory-sessions.md +2 -0
  36. package/docs/policy-sandbox.md +1 -1
  37. package/docs/pricing-budget.md +1 -1
  38. package/docs/quickstart.md +2 -2
  39. package/docs/repl.md +6 -2
  40. package/docs/security-model.md +1 -1
  41. package/docs/security.md +1 -1
  42. package/docs/skills.md +2 -2
  43. package/docs/terminal.md +9 -5
  44. package/docs/tools.md +1 -1
  45. package/package.json +35 -5
  46. package/src/app/session.ts +261 -15
  47. package/src/app/tool-layer.ts +94 -7
  48. package/src/daemon/approvals.ts +361 -0
  49. package/src/daemon/capability.ts +145 -0
  50. package/src/daemon/children.ts +142 -0
  51. package/src/daemon/client.ts +267 -0
  52. package/src/daemon/control.ts +350 -0
  53. package/src/daemon/discovery.ts +234 -0
  54. package/src/daemon/feed.ts +155 -0
  55. package/src/daemon/framing.ts +94 -0
  56. package/src/daemon/host.ts +316 -0
  57. package/src/daemon/protocol.ts +217 -0
  58. package/src/daemon/resource.ts +170 -0
  59. package/src/daemon/sanitize.ts +57 -0
  60. package/src/daemon/server.ts +627 -0
  61. package/src/daemon/store.ts +317 -0
  62. package/src/daemon/subscription.ts +270 -0
  63. package/src/daemon/telemetry.ts +81 -0
  64. package/src/hooks/run.ts +12 -1
  65. package/src/lib/atomic-write.ts +29 -3
  66. package/src/lib/db-path.ts +26 -0
  67. package/src/lib/keystore.ts +544 -42
  68. package/src/lib/net.ts +43 -1
  69. package/src/lib/safe-open.ts +116 -1
  70. package/src/lib/session-id.ts +15 -0
  71. package/src/lsp/client.ts +123 -5
  72. package/src/mcp/client.ts +139 -17
  73. package/src/mcp/server.ts +177 -50
  74. package/src/mcp/transport.ts +16 -19
  75. package/src/memory/vector.ts +770 -55
  76. package/src/policy/allowlist.ts +14 -2
  77. package/src/policy/bash-guard.ts +105 -10
  78. package/src/policy/compaction.ts +82 -5
  79. package/src/policy/consequence-engine.ts +220 -0
  80. package/src/policy/context.ts +132 -0
  81. package/src/policy/executor.ts +187 -121
  82. package/src/policy/no-progress.ts +559 -0
  83. package/src/policy/permission.ts +4 -8
  84. package/src/policy/pricing.ts +17 -3
  85. package/src/policy/scrub.ts +69 -2
  86. package/src/policy/tool-contract.ts +515 -0
  87. package/src/policy/usage.ts +310 -24
  88. package/src/policy/verifier.ts +6 -3
  89. package/src/policy/work-mode.ts +182 -0
  90. package/src/presentation/adapter.ts +533 -26
  91. package/src/presentation/events.ts +151 -0
  92. package/src/presentation/model.ts +180 -27
  93. package/src/presentation/projection.ts +858 -0
  94. package/src/presentation/reducer.ts +645 -310
  95. package/src/presentation/store.ts +12 -7
  96. package/src/providers/anthropic.ts +18 -10
  97. package/src/providers/responses.ts +17 -7
  98. package/src/runtime/capability.ts +409 -0
  99. package/src/runtime/child-execution.ts +274 -0
  100. package/src/runtime/composition.ts +958 -0
  101. package/src/runtime/dispatch.ts +591 -0
  102. package/src/runtime/execution-backend.ts +632 -0
  103. package/src/runtime/execution-events.ts +272 -0
  104. package/src/runtime/execution-id.ts +230 -0
  105. package/src/runtime/execution-journal.ts +926 -0
  106. package/src/runtime/execution-kernel.ts +456 -0
  107. package/src/runtime/execution-registry.ts +379 -0
  108. package/src/runtime/process-supervision.ts +276 -0
  109. package/src/runtime/production-execution.ts +551 -0
  110. package/src/runtime/production-runtime.ts +217 -0
  111. package/src/runtime/recovery-safety.ts +70 -0
  112. package/src/runtime/recovery.ts +477 -0
  113. package/src/runtime/runtime-capabilities.ts +179 -0
  114. package/src/runtime/runtime-diagnostics.ts +141 -0
  115. package/src/runtime/runtime-host.ts +365 -0
  116. package/src/runtime/runtime-status-facts.ts +222 -0
  117. package/src/runtime/runtime-status-provider.ts +74 -0
  118. package/src/runtime/runtime-status.ts +459 -0
  119. package/src/runtime/runtime-task-admission.ts +101 -0
  120. package/src/runtime/supervisor.ts +444 -0
  121. package/src/session/authority.ts +168 -0
  122. package/src/session/checkpoint.ts +88 -1
  123. package/src/session/context-adapter.ts +251 -0
  124. package/src/session/context-assembly.ts +242 -0
  125. package/src/session/context-identity.ts +389 -0
  126. package/src/session/context-projection.ts +248 -0
  127. package/src/session/context-selector.ts +500 -0
  128. package/src/session/cross-session-adoption.ts +249 -0
  129. package/src/session/full-history-fold.ts +171 -0
  130. package/src/session/identity.ts +192 -0
  131. package/src/session/journal.ts +805 -102
  132. package/src/session/open-work-intent.ts +732 -0
  133. package/src/session/open-work.ts +767 -0
  134. package/src/session/pending-tools.ts +94 -0
  135. package/src/session/persistence.ts +3569 -127
  136. package/src/session/runtime-header.ts +208 -0
  137. package/src/session/shadow-git.ts +13 -5
  138. package/src/session/verification.ts +1623 -0
  139. package/src/task/assignment.ts +136 -0
  140. package/src/task/autonomous-adapter.ts +168 -0
  141. package/src/task/autonomous-context.ts +630 -0
  142. package/src/task/autonomous-policy.ts +490 -0
  143. package/src/task/continuity.ts +179 -0
  144. package/src/task/execution-cancellation.ts +165 -0
  145. package/src/task/graph-validate.ts +379 -0
  146. package/src/task/graph.ts +305 -0
  147. package/src/task/identity.ts +230 -0
  148. package/src/task/model.ts +417 -0
  149. package/src/task/production-scheduler.ts +293 -0
  150. package/src/task/readiness.ts +229 -0
  151. package/src/task/scheduler-observability.ts +387 -0
  152. package/src/task/scheduler.ts +1197 -0
  153. package/src/task/scheduling-policy.ts +165 -0
  154. package/src/task/session-authority.ts +148 -0
  155. package/src/task/session-ownership.ts +211 -0
  156. package/src/task/store.ts +2887 -0
  157. package/src/task/sync.ts +343 -0
  158. package/src/task/trigger.ts +260 -0
  159. package/src/tools/bash.ts +377 -211
  160. package/src/tools/code_run.ts +1 -1
  161. package/src/tools/delete_file.ts +1 -1
  162. package/src/tools/edit.ts +33 -6
  163. package/src/tools/evidence.ts +30 -0
  164. package/src/tools/git.ts +4 -4
  165. package/src/tools/glob.ts +12 -3
  166. package/src/tools/grep.ts +1 -1
  167. package/src/tools/lsp.ts +4 -4
  168. package/src/tools/mcp_call.ts +11 -4
  169. package/src/tools/memory.ts +153 -18
  170. package/src/tools/move_file.ts +1 -1
  171. package/src/tools/patch.ts +1 -1
  172. package/src/tools/read_file.ts +1 -1
  173. package/src/tools/read_image.ts +1 -1
  174. package/src/tools/submit_result.ts +1 -1
  175. package/src/tools/task.ts +437 -41
  176. package/src/tools/todo.ts +662 -35
  177. package/src/tools/web_fetch.ts +4 -2
  178. package/src/tools/web_search.ts +9 -3
  179. package/src/tools/write_file.ts +1 -1
  180. package/src/ui/assistant/simple.ts +123 -50
  181. package/src/ui/assistant/turn-status.ts +17 -3
  182. package/src/ui/contract.ts +184 -0
  183. package/src/ui/footer.ts +54 -18
  184. package/src/ui/i18n/en.ts +62 -6
  185. package/src/ui/i18n/id.ts +62 -6
  186. package/src/ui/input/prompt-engine.ts +120 -25
  187. package/src/ui/render/errors.ts +39 -1
  188. package/src/ui/render/markdown-table.ts +455 -0
  189. package/src/ui/render/markdown.ts +22 -1
  190. package/src/ui/render/table-grid.ts +184 -0
  191. package/src/ui/render/table.ts +15 -76
  192. package/src/ui/runtime/screen.ts +7 -2
  193. package/src/ui/runtime/statusline.ts +25 -6
  194. package/src/ui/tui/app.ts +598 -133
  195. package/src/ui/tui/transcript.ts +531 -89
  196. package/vendor/minicore/VENDOR.md +1 -1
  197. package/vendor/minicore/src/core/budget.ts +25 -25
  198. package/vendor/minicore/src/core/compact.ts +75 -75
  199. package/vendor/minicore/src/core/errors.ts +59 -59
  200. package/vendor/minicore/src/core/events.ts +73 -73
  201. package/vendor/minicore/src/core/executor.ts +139 -139
  202. package/vendor/minicore/src/core/history.ts +31 -31
  203. package/vendor/minicore/src/core/index.ts +41 -41
  204. package/vendor/minicore/src/core/loop.ts +355 -355
  205. package/vendor/minicore/src/core/permission.ts +22 -22
  206. package/vendor/minicore/src/core/provider.ts +39 -39
  207. package/vendor/minicore/src/core/recovery.ts +35 -35
  208. package/vendor/minicore/src/core/session.ts +327 -327
  209. package/vendor/minicore/src/core/snapshot.ts +146 -146
  210. package/vendor/minicore/src/core/tokens.ts +107 -107
  211. package/vendor/minicore/src/core/tool.ts +115 -115
  212. package/vendor/minicore/src/core/types.ts +50 -50
  213. package/vendor/minicore/src/providers/openai-compat.ts +417 -417
  214. package/AGENTS.md +0 -45
  215. package/PLAN.md +0 -491
  216. package/docs/ARCHITECTURE.html +0 -1248
  217. package/docs/CONTROL-PLANE-MAP.md +0 -139
  218. package/docs/HARNESS.md +0 -150
  219. package/docs/SUMMARY.md +0 -52
  220. package/docs/UI_RENDER_PIPELINE.md +0 -165
  221. package/docs/USAGE.md +0 -11
@@ -0,0 +1,417 @@
1
+ // Task model types — the *domain* half of Phase 1.
2
+ //
3
+ // EVIDENCE NOTE. This file did NOT survive the wipe: there is no
4
+ // `model.orig.ts` artifact and no `src/task/` in the recovered baseline. It is
5
+ // reconstructed from the only two surviving sources of truth about it:
6
+ //
7
+ // 1. `store.orig.ts` — the actual pre-wipe implementation. Every field below
8
+ // is pinned by `TaskRow` + `rowToTask()` + the construction sites in
9
+ // `synchronizeTasks()`. Where the artifact *uses* a field, that field is
10
+ // PROVEN, not guessed.
11
+ // 2. `docs/TASK_IDENTITY_SPEC.md` + `docs/TASK_STATE_MACHINE_SPEC.md` —
12
+ // in-repo design docs committed at baseline HEAD (`aa76dfb`).
13
+ //
14
+ // The two sources DISAGREE, and the disagreement is recorded rather than
15
+ // smoothed over:
16
+ //
17
+ // | aspect | design doc | store.orig.ts (ACTUAL) |
18
+ // |---------------|-------------------------------|------------------------|
19
+ // | status casing | lowercase ("pending") | UPPERCASE ("PENDING") |
20
+ // | blocker | `blocker: TaskBlocker` object | `blockedReason: string`|
21
+ // | timestamps | `createdAt: number` | `createdAt: string` ISO|
22
+ // | verification | `at: number` | `checkedAt: string` |
23
+ // | provenance | `{source, actor, at}` | `{origin, source}` |
24
+ // | titleKey | present | ABSENT |
25
+ // | revision | ABSENT | present |
26
+ //
27
+ // The artifact wins. It is later evidence and it is the code that actually
28
+ // ran. The doc is DESIGN-mode and predates the implementation.
29
+ //
30
+ // Every inference below is tagged `[INFERRED]`. Everything untagged is proven
31
+ // by `store.orig.ts`.
32
+
33
+ /**
34
+ * Task lifecycle states.
35
+ *
36
+ * PROVEN by artifact usage: `PENDING` (the `rowToTask` fallback), `BLOCKED`
37
+ * (the only status compared in `validate()`), `CANCELLED` (named in the
38
+ * `deleteTask` comment as the sanctioned alternative to deletion).
39
+ *
40
+ * [INFERRED] the remaining five, from `docs/TASK_STATE_MACHINE_SPEC.md` which
41
+ * states the enum is "diperluas dari 5 ke 8" and lists them lowercase. Uppercased
42
+ * to match the artifact's casing convention. None is ever written by the store
43
+ * itself; they only widen what `isTaskStatus` accepts.
44
+ */
45
+ export type TaskStatus =
46
+ | "PENDING"
47
+ | "IN_PROGRESS"
48
+ | "VERIFYING"
49
+ | "BLOCKED"
50
+ | "FAILED"
51
+ | "RETRYING"
52
+ | "COMPLETED"
53
+ | "CANCELLED"
54
+
55
+ const TASK_STATUSES: readonly TaskStatus[] = [
56
+ "PENDING",
57
+ "IN_PROGRESS",
58
+ "VERIFYING",
59
+ "BLOCKED",
60
+ "FAILED",
61
+ "RETRYING",
62
+ "COMPLETED",
63
+ "CANCELLED",
64
+ ]
65
+
66
+ /** PROVEN: `rowToTask` calls this to decide whether a stored status is valid. */
67
+ export function isTaskStatus(value: unknown): value is TaskStatus {
68
+ return typeof value === "string" && TASK_STATUSES.includes(value as TaskStatus)
69
+ }
70
+
71
+ /**
72
+ * [Fase 1 / LOOP-INV-02] Status yang mengakhiri siklus hidup task.
73
+ *
74
+ * Keduanya TIDAK punya transisi keluar di `TASK_EDGES`. Keluar dari status ini
75
+ * hanya mungkin lewat permit eksplisit `allowReopen` pada `patchTask` — jadi
76
+ * "hidup lagi" selalu keputusan operator yang tercatat di kode pemanggil,
77
+ * bukan efek samping tulisan status biasa.
78
+ */
79
+ export const TERMINAL_TASK_STATUSES: ReadonlySet<TaskStatus> = new Set(["COMPLETED", "CANCELLED"])
80
+
81
+ export function isTerminalTaskStatus(status: TaskStatus): boolean {
82
+ return TERMINAL_TASK_STATUSES.has(status)
83
+ }
84
+
85
+ /**
86
+ * [Fase 1 / LOOP-INV-02] Tabel transisi status task.
87
+ *
88
+ * BENTUK KEPUTUSAN — baca sebelum mengubah:
89
+ *
90
+ * 1. Terminal bersifat ABSOLUT: `COMPLETED`/`CANCELLED` hanya boleh ke dirinya
91
+ * sendiri. Itu inti invariant "terminal tidak bisa hidup kembali".
92
+ * 2. Status non-terminal sengaja PERMISIF (semua status non-terminal boleh
93
+ * saling menuju). Alasannya bukan kemalasan: alur nyata hari ini memakai
94
+ * FAILED→PENDING (retry), BLOCKED→PENDING (unblock), IN_PROGRESS→PENDING
95
+ * (requeue/reconcile), dan VERIFYING→PENDING (revert). Memperketat edge
96
+ * tanpa bukti pemanggil akan memutus jalur yang sah; guard baru di sini
97
+ * adalah terminalitas + wiring VERIFYING yang eksplisit, persis yang
98
+ * dituntut invariant. Pengetatan lebih lanjut harus datang dari bukti.
99
+ * 3. `VERIFYING` terhubung dua arah dengan produsen/penilai yang sah:
100
+ * PENDING/IN_PROGRESS→VERIFYING (masuk verifikasi), lalu
101
+ * VERIFYING→COMPLETED (lulus), →IN_PROGRESS (perbaikan), →BLOCKED,
102
+ * →FAILED, →CANCELLED, dan →PENDING (revert oleh reconciliation).
103
+ * 4. Self-loop selalu sah: `patchTask` yang hanya mengubah judul/urutan tidak
104
+ * boleh dipaksa berpindah status.
105
+ */
106
+ export const TASK_EDGES: Readonly<Record<TaskStatus, ReadonlySet<TaskStatus>>> = {
107
+ PENDING: new Set<TaskStatus>([
108
+ "PENDING",
109
+ "IN_PROGRESS",
110
+ "VERIFYING",
111
+ "BLOCKED",
112
+ "FAILED",
113
+ "RETRYING",
114
+ "COMPLETED",
115
+ "CANCELLED",
116
+ ]),
117
+ IN_PROGRESS: new Set<TaskStatus>([
118
+ "IN_PROGRESS",
119
+ "PENDING",
120
+ "VERIFYING",
121
+ "BLOCKED",
122
+ "FAILED",
123
+ "RETRYING",
124
+ "COMPLETED",
125
+ "CANCELLED",
126
+ ]),
127
+ VERIFYING: new Set<TaskStatus>([
128
+ "VERIFYING",
129
+ "PENDING",
130
+ "IN_PROGRESS",
131
+ "BLOCKED",
132
+ "FAILED",
133
+ "RETRYING",
134
+ "COMPLETED",
135
+ "CANCELLED",
136
+ ]),
137
+ BLOCKED: new Set<TaskStatus>([
138
+ "BLOCKED",
139
+ "PENDING",
140
+ "IN_PROGRESS",
141
+ "VERIFYING",
142
+ "FAILED",
143
+ "RETRYING",
144
+ "COMPLETED",
145
+ "CANCELLED",
146
+ ]),
147
+ FAILED: new Set<TaskStatus>([
148
+ "FAILED",
149
+ "PENDING",
150
+ "IN_PROGRESS",
151
+ "VERIFYING",
152
+ "BLOCKED",
153
+ "RETRYING",
154
+ "COMPLETED",
155
+ "CANCELLED",
156
+ ]),
157
+ RETRYING: new Set<TaskStatus>([
158
+ "RETRYING",
159
+ "PENDING",
160
+ "IN_PROGRESS",
161
+ "VERIFYING",
162
+ "BLOCKED",
163
+ "FAILED",
164
+ "COMPLETED",
165
+ "CANCELLED",
166
+ ]),
167
+ COMPLETED: new Set<TaskStatus>(["COMPLETED"]),
168
+ CANCELLED: new Set<TaskStatus>(["CANCELLED"]),
169
+ }
170
+
171
+ /** [Fase 1 / LOOP-INV-02] Apakah `from → to` legal menurut `TASK_EDGES`. */
172
+ export function isLegalTaskTransition(from: TaskStatus, to: TaskStatus): boolean {
173
+ return TASK_EDGES[from]?.has(to) === true
174
+ }
175
+
176
+ /**
177
+ * Canonical task id = `t<n>`, `<n>` monotonic from 1, per session.
178
+ *
179
+ * `taskIdFromIndex` is the inverse of what `nextId()` needs. `nextId()` starts
180
+ * its running max at `0` and returns `taskIdFromIndex(max)`, so for an EMPTY
181
+ * session (max = 0) the very first id must be `t1` — therefore the index is
182
+ * 1-based and the mapping is `n -> t(n+1)`. This also reproduces the
183
+ * artifact's own worked example: `t1,t2,t5` -> max 5 -> `t6`, not `t3`.
184
+ */
185
+ export function taskIdFromIndex(index: number): string {
186
+ return `t${index + 1}`
187
+ }
188
+
189
+ /**
190
+ * [INFERRED] Strict guard for a canonical id. `docs/TASK_IDENTITY_SPEC.md` fixes
191
+ * the form as `t<n>` starting at 1, so `t0`, `t01` and `t-1` are all rejected.
192
+ * `store.orig.ts` relies on this to reject model-supplied ids before they can
193
+ * reach SQL, and `nextId()` re-parses with `Number(id.slice(1))`, which only
194
+ * round-trips cleanly for `^t[1-9][0-9]*$`.
195
+ */
196
+ const TASK_ID_RE = /^t[1-9][0-9]*$/
197
+
198
+ /** PROVEN: guard used by `getTask`, `patchTask`, `deleteTask`. */
199
+ export function isTaskId(value: unknown): value is string {
200
+ return typeof value === "string" && TASK_ID_RE.test(value)
201
+ }
202
+
203
+ /**
204
+ * Verification record attached to a task.
205
+ *
206
+ * PROVEN from the artifact's only construction site
207
+ * (`synchronizeTasks`): `{ verdict, detail?, checkedAt }` where `checkedAt` is
208
+ * an ISO string from `nowIso()`. Note the field is `checkedAt`, NOT the
209
+ * `at: number` the design doc proposed — artifact wins.
210
+ */
211
+ export interface TaskVerification {
212
+ verdict: "passed" | "failed" | "unverified"
213
+ detail?: string
214
+ checkedAt: string
215
+ }
216
+
217
+ export type TaskEvidenceKind = "completion" | "receipt" | "test" | "verify" | "checkpoint" | "file"
218
+
219
+ /**
220
+ * Evidence record appended on every synchronization.
221
+ *
222
+ * PROVEN from the artifact's construction site: `{ kind: "completion", detail,
223
+ * at }` with `at` an ISO string.
224
+ *
225
+ * [INFERRED] the wider kind union, from `docs/TASK_STATE_MACHINE_SPEC.md`
226
+ * (`EvidenceKind`). The store only ever writes `"completion"`; the rest exist so
227
+ * a later phase can name evidence without another migration.
228
+ */
229
+ export interface TaskEvidence {
230
+ kind: TaskEvidenceKind
231
+ detail: string
232
+ at: string
233
+ }
234
+
235
+ /**
236
+ * [INFERRED] Acceptance criteria.
237
+ *
238
+ * UNRECOVERABLE SHAPE: the artifact stores and returns this value but never
239
+ * reads a field from it and never constructs a non-null one, so its real shape
240
+ * is unrecoverable. Modelled as an opaque record — the store round-trips it
241
+ * verbatim via JSON and deliberately interprets nothing. Guessing concrete
242
+ * fields here would be pure invention with no behavioural consequence.
243
+ */
244
+ export type TaskAcceptance = Record<string, unknown>
245
+
246
+ /**
247
+ * Where a task came from.
248
+ *
249
+ * PROVEN from the artifact: the `rowToTask` default is
250
+ * `{ origin: "runtime", source: "unknown" }` and `synchronizeTasks` writes
251
+ * `{ origin: "model", source: "todo_write" }`. So `origin` is a closed
252
+ * two-value union and `source` is an open string.
253
+ */
254
+ export interface TaskProvenance {
255
+ origin: "runtime" | "model"
256
+ source: string
257
+ }
258
+
259
+ /**
260
+ * One durable task row.
261
+ *
262
+ * PROVEN field-for-field by `rowToTask()`, which is the authoritative
263
+ * projection: the DB column set and this object are in 1:1 correspondence.
264
+ * `sessionId` and `revision` do not appear in the design doc at all — they
265
+ * exist only in the artifact, and `revision` is the stale-write substrate
266
+ * Phase 1 must preserve.
267
+ */
268
+ export interface Task {
269
+ /** Stable, canonical `t<n>`, allocated by the store. Never reused. */
270
+ id: string
271
+ sessionId: string
272
+ title: string
273
+ status: TaskStatus
274
+ /** Display order only. Mutable; explicitly NOT identity. */
275
+ order: number
276
+ parentId: string | null
277
+ dependsOn: string[]
278
+ /** Required whenever `status === "BLOCKED"` (PF-04). */
279
+ blockedReason: string | null
280
+ verification: TaskVerification | null
281
+ evidence: TaskEvidence[]
282
+ acceptance: TaskAcceptance | null
283
+ provenance: TaskProvenance
284
+ /** ISO-8601 strings, not epoch numbers. */
285
+ createdAt: string
286
+ updatedAt: string
287
+ /** Starts at 1; incremented by every successful mutation. */
288
+ revision: number
289
+ }
290
+
291
+ /** PROVEN: `getSnapshot()` returns exactly this. */
292
+ export interface TaskSnapshot {
293
+ sessionId: string
294
+ tasks: Task[]
295
+ }
296
+
297
+ /** Error codes the artifact actually raises, plus nothing invented. */
298
+ export type TaskErrorCode =
299
+ | "TASK_DB_INIT_FAILURE"
300
+ | "TASK_INVALID_ID"
301
+ | "TASK_INVALID_DEPENDENCY"
302
+ | "TASK_INVALID_TRANSITION"
303
+ | "TASK_NOT_FOUND"
304
+ | "TASK_PERSISTENCE_FAILURE"
305
+ | "TASK_DUPLICATE_ID"
306
+ | "TASK_STALE_REVISION"
307
+ | "TASK_MIGRATION_FAILURE"
308
+ | "TASK_TX_ACTIVE"
309
+ // PHASE 4A.5: a full declaration that carries no canonical identity at all,
310
+ // submitted to a session that ALREADY has canonical tasks. Distinct from
311
+ // TASK_INVALID_ID on purpose: no id was malformed, the payload simply lacks the
312
+ // information required to address existing canonical state safely.
313
+ | "TASK_IDENTITY_REQUIRED"
314
+ // PHASE 6B: a write tried to author `IN_PROGRESS` outside the Scheduler claim
315
+ // primitive while Scheduler authority is active. Deliberately distinct from
316
+ // TASK_INVALID_TRANSITION: nothing is malformed, the *caller* lacks authority.
317
+ // This is the fail-closed boundary that stops model-facing todo_write from
318
+ // creating an authoritative claim (6B P2).
319
+ | "TASK_AUTHORITY_VIOLATION"
320
+ // [Fase 1 / LOOP-INV-02] From-state gate: transisi yang tidak ada di
321
+ // `TASK_EDGES` (termasuk keluar dari terminal) ditolak. Dipisah dari
322
+ // TASK_INVALID_TRANSITION (yang berarti payload tidak lengkap, mis. BLOCKED
323
+ // tanpa alasan) supaya operator bisa membedakan "salah bentuk" dari "salah
324
+ // urutan status".
325
+ | "TASK_ILLEGAL_TRANSITION"
326
+ // [Fase 1 / LOOP-INV-13] Pemanggil menyertakan token lease yang sudah tidak
327
+ // memegang `session_authority` (diambil alih worker lain atau kedaluwarsa).
328
+ | "TASK_AUTHORITY_LOST"
329
+
330
+ /**
331
+ * PHASE 6B: outcome of `TaskStore.claimTask`.
332
+ *
333
+ * Adjudicated by TaskStore, never by a caller. The four cases are disjoint and
334
+ * exhaustive for a canonical `taskId`.
335
+ */
336
+ export type ClaimOutcome =
337
+ /** The atomic, revision-guarded mutation changed exactly one row. */
338
+ | "CLAIM_ACCEPTED"
339
+ /** The row exists but `expectedRevision` no longer matched. Never retried. */
340
+ | "CLAIM_REJECTED_STALE"
341
+ /** No such row in this session. Never recreated by a claim. */
342
+ | "NOT_FOUND"
343
+ /**
344
+ * [PHASE 6T] The row was claimable, but ANOTHER task in this session already
345
+ * holds a live Scheduler execution. Reported by the SAME statement that would
346
+ * otherwise have claimed, so a contention rejection is as invisible as a lost
347
+ * revision race: no generation, no owner, no status change, no attempt.
348
+ */
349
+ | "CLAIM_REJECTED_BUSY"
350
+ /** The row exists and the revision matched, but the status is not claimable. */
351
+ | "WRONG_STATE"
352
+
353
+ /**
354
+ * PHASE 6B: outcome of `TaskStore.reconcileStranded`.
355
+ *
356
+ * `REFUSED_NO_OWNERSHIP` is the fail-closed case required by 6B S8/P3: when
357
+ * ownership of the session cannot be positively established, reconciliation is
358
+ * refused rather than guessing. It is a first-class outcome, not an error,
359
+ * because refusing is the correct behaviour.
360
+ */
361
+ export type ReconcileOutcome =
362
+ | "RECONCILED"
363
+ | "NOT_FOUND"
364
+ | "NOT_STRANDED"
365
+ | "REJECTED_STALE"
366
+ | "REFUSED_NO_OWNERSHIP"
367
+
368
+ /**
369
+ * Domain error. `code` is the stable, machine-checkable discriminator; the
370
+ * message stays human-facing. Extends `Error` so existing
371
+ * `catch (e) { (e as Error).message }` call sites keep working unchanged.
372
+ */
373
+ export class TaskError extends Error {
374
+ readonly code: TaskErrorCode
375
+ constructor(code: TaskErrorCode, message: string) {
376
+ super(message)
377
+ this.name = "TaskError"
378
+ this.code = code
379
+ }
380
+ }
381
+
382
+ /**
383
+ * [Fase 1 / LOOP-INV-02] Transisi status yang tidak diizinkan `TASK_EDGES`.
384
+ *
385
+ * Subclass `TaskError` supaya seluruh `catch (e) { e instanceof TaskError }`
386
+ * yang sudah ada tetap menangkapnya; `from`/`to` diekspos agar pemanggil bisa
387
+ * membedakan "terminal resurrection" dari pelanggaran edge lain tanpa
388
+ * mem-parsing pesan.
389
+ */
390
+ export class IllegalTaskTransitionError extends TaskError {
391
+ readonly from: TaskStatus
392
+ readonly to: TaskStatus
393
+ constructor(from: TaskStatus, to: TaskStatus) {
394
+ const terminal = isTerminalTaskStatus(from)
395
+ ? " (terminal state; requires explicit allowReopen)"
396
+ : ""
397
+ super("TASK_ILLEGAL_TRANSITION", `illegal task transition ${from} -> ${to}${terminal}`)
398
+ this.name = "IllegalTaskTransitionError"
399
+ this.from = from
400
+ this.to = to
401
+ }
402
+ }
403
+
404
+ /**
405
+ * [Fase 1 / LOOP-INV-13] Penulis menyertakan token lease yang tidak lagi
406
+ * memegang otoritas sesi. Fail-closed: lebih baik menolak tulisan daripada
407
+ * mengizinkan worker yang sudah tersingkir menimpa state.
408
+ */
409
+ export class TaskAuthorityLostError extends TaskError {
410
+ constructor(sessionId: string) {
411
+ super(
412
+ "TASK_AUTHORITY_LOST",
413
+ `session authority lost for ${sessionId}: the presented lease token is no longer current`,
414
+ )
415
+ this.name = "TaskAuthorityLostError"
416
+ }
417
+ }