clinkx 1.2.0 → 1.3.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 (270) hide show
  1. package/CHANGELOG.md +32 -0
  2. package/README.md +4 -2
  3. package/clinkx-workflows/dist/architecture-arena/admission.d.ts +16 -0
  4. package/clinkx-workflows/dist/architecture-arena/admission.js +107 -0
  5. package/clinkx-workflows/dist/architecture-arena/admission.js.map +1 -0
  6. package/clinkx-workflows/dist/architecture-arena/contract.d.ts +1368 -0
  7. package/clinkx-workflows/dist/architecture-arena/contract.js +254 -0
  8. package/clinkx-workflows/dist/architecture-arena/contract.js.map +1 -0
  9. package/clinkx-workflows/dist/architecture-arena/runtime.d.ts +53 -0
  10. package/clinkx-workflows/dist/architecture-arena/runtime.js +511 -0
  11. package/clinkx-workflows/dist/architecture-arena/runtime.js.map +1 -0
  12. package/clinkx-workflows/dist/architecture-comparison/admission.d.ts +17 -1
  13. package/clinkx-workflows/dist/architecture-comparison/admission.js +27 -4
  14. package/clinkx-workflows/dist/architecture-comparison/admission.js.map +1 -1
  15. package/clinkx-workflows/dist/architecture-comparison/contract.d.ts +59 -62
  16. package/clinkx-workflows/dist/architecture-comparison/contract.js +4 -21
  17. package/clinkx-workflows/dist/architecture-comparison/contract.js.map +1 -1
  18. package/clinkx-workflows/dist/architecture-comparison/runtime.d.ts +4 -3
  19. package/clinkx-workflows/dist/architecture-comparison/runtime.js +22 -67
  20. package/clinkx-workflows/dist/architecture-comparison/runtime.js.map +1 -1
  21. package/clinkx-workflows/dist/artifacts.d.ts +19 -4
  22. package/clinkx-workflows/dist/artifacts.js +16 -7
  23. package/clinkx-workflows/dist/artifacts.js.map +1 -1
  24. package/clinkx-workflows/dist/backend.d.ts +30 -0
  25. package/clinkx-workflows/dist/clink-client.d.ts +8 -2
  26. package/clinkx-workflows/dist/clink-client.js +4 -2
  27. package/clinkx-workflows/dist/clink-client.js.map +1 -1
  28. package/clinkx-workflows/dist/context-preflight.d.ts +6 -0
  29. package/clinkx-workflows/dist/context-preflight.js.map +1 -1
  30. package/clinkx-workflows/dist/council-execution-policy.d.ts +3 -1
  31. package/clinkx-workflows/dist/council-execution-policy.js +4 -0
  32. package/clinkx-workflows/dist/council-execution-policy.js.map +1 -1
  33. package/clinkx-workflows/dist/dashboard/contracts.d.ts +586 -586
  34. package/clinkx-workflows/dist/dashboard/progress-report-contract.d.ts +28 -28
  35. package/clinkx-workflows/dist/dashboard/session-log-contract.d.ts +32 -32
  36. package/clinkx-workflows/dist/dashboard-ui/assets/index-DRId2DVA.js +119 -0
  37. package/clinkx-workflows/dist/dashboard-ui/assets/style-CHAw57y5.css +1 -0
  38. package/clinkx-workflows/dist/dashboard-ui/index.html +2 -2
  39. package/clinkx-workflows/dist/delegate-signature.d.ts +4 -3
  40. package/clinkx-workflows/dist/delegate-signature.js +4 -3
  41. package/clinkx-workflows/dist/delegate-signature.js.map +1 -1
  42. package/clinkx-workflows/dist/durable-file.d.ts +69 -0
  43. package/clinkx-workflows/dist/durable-file.js +145 -0
  44. package/clinkx-workflows/dist/durable-file.js.map +1 -0
  45. package/clinkx-workflows/dist/engine.d.ts +42 -7
  46. package/clinkx-workflows/dist/engine.js +196 -24
  47. package/clinkx-workflows/dist/engine.js.map +1 -1
  48. package/clinkx-workflows/dist/ping-pong/admission.d.ts +127 -0
  49. package/clinkx-workflows/dist/ping-pong/admission.js +522 -0
  50. package/clinkx-workflows/dist/ping-pong/admission.js.map +1 -0
  51. package/clinkx-workflows/dist/ping-pong/contract.d.ts +2539 -0
  52. package/clinkx-workflows/dist/ping-pong/contract.js +819 -0
  53. package/clinkx-workflows/dist/ping-pong/contract.js.map +1 -0
  54. package/clinkx-workflows/dist/ping-pong/control.d.ts +67 -0
  55. package/clinkx-workflows/dist/ping-pong/control.js +12 -0
  56. package/clinkx-workflows/dist/ping-pong/control.js.map +1 -0
  57. package/clinkx-workflows/dist/ping-pong/runtime-handle.d.ts +24 -0
  58. package/clinkx-workflows/dist/ping-pong/runtime-handle.js +55 -0
  59. package/clinkx-workflows/dist/ping-pong/runtime-handle.js.map +1 -0
  60. package/clinkx-workflows/dist/ping-pong/runtime.d.ts +235 -0
  61. package/clinkx-workflows/dist/ping-pong/runtime.js +1183 -0
  62. package/clinkx-workflows/dist/ping-pong/runtime.js.map +1 -0
  63. package/clinkx-workflows/dist/ping-pong/settle.d.ts +57 -0
  64. package/clinkx-workflows/dist/ping-pong/settle.js +58 -0
  65. package/clinkx-workflows/dist/ping-pong/settle.js.map +1 -0
  66. package/clinkx-workflows/dist/ping-pong/sidecar.d.ts +65 -0
  67. package/clinkx-workflows/dist/ping-pong/sidecar.js +138 -0
  68. package/clinkx-workflows/dist/ping-pong/sidecar.js.map +1 -0
  69. package/clinkx-workflows/dist/plan-review/publication.d.ts +2 -1
  70. package/clinkx-workflows/dist/plan-review/publication.js +5 -6
  71. package/clinkx-workflows/dist/plan-review/publication.js.map +1 -1
  72. package/clinkx-workflows/dist/plan-review/snapshot.d.ts +3 -2
  73. package/clinkx-workflows/dist/plan-review/snapshot.js +8 -8
  74. package/clinkx-workflows/dist/plan-review/snapshot.js.map +1 -1
  75. package/clinkx-workflows/dist/recipe-host.d.ts +315 -0
  76. package/clinkx-workflows/dist/recipe-host.js +183 -0
  77. package/clinkx-workflows/dist/recipe-host.js.map +1 -0
  78. package/clinkx-workflows/dist/recipe-seats.d.ts +96 -0
  79. package/clinkx-workflows/dist/recipe-seats.js +163 -0
  80. package/clinkx-workflows/dist/recipe-seats.js.map +1 -0
  81. package/clinkx-workflows/dist/recipe-shared/evidence.d.ts +67 -0
  82. package/clinkx-workflows/dist/recipe-shared/evidence.js +111 -0
  83. package/clinkx-workflows/dist/recipe-shared/evidence.js.map +1 -0
  84. package/clinkx-workflows/dist/reducers/index.d.ts +9 -1
  85. package/clinkx-workflows/dist/reducers/index.js +30 -0
  86. package/clinkx-workflows/dist/reducers/index.js.map +1 -1
  87. package/clinkx-workflows/dist/run-lock-reclaim.d.ts +44 -0
  88. package/clinkx-workflows/dist/run-lock-reclaim.js +86 -0
  89. package/clinkx-workflows/dist/run-lock-reclaim.js.map +1 -0
  90. package/clinkx-workflows/dist/state-schema.d.ts +11 -0
  91. package/clinkx-workflows/dist/state-schema.js +4 -1
  92. package/clinkx-workflows/dist/state-schema.js.map +1 -1
  93. package/clinkx-workflows/dist/state.d.ts +178 -3
  94. package/clinkx-workflows/dist/state.js +618 -83
  95. package/clinkx-workflows/dist/state.js.map +1 -1
  96. package/clinkx-workflows/dist/transport.d.ts +2 -1
  97. package/clinkx-workflows/dist/transport.js +5 -0
  98. package/clinkx-workflows/dist/transport.js.map +1 -1
  99. package/clinkx-workflows/dist/validators/architecture-arena.d.ts +6 -0
  100. package/clinkx-workflows/dist/validators/architecture-arena.js +16 -0
  101. package/clinkx-workflows/dist/validators/architecture-arena.js.map +1 -0
  102. package/clinkx-workflows/dist/validators/index.js +4 -0
  103. package/clinkx-workflows/dist/validators/index.js.map +1 -1
  104. package/clinkx-workflows/dist/validators/ping-pong.d.ts +6 -0
  105. package/clinkx-workflows/dist/validators/ping-pong.js +10 -0
  106. package/clinkx-workflows/dist/validators/ping-pong.js.map +1 -0
  107. package/clinkx-workflows/dist/workflow-tools.d.ts +51 -5
  108. package/clinkx-workflows/dist/workflow-tools.js +785 -34
  109. package/clinkx-workflows/dist/workflow-tools.js.map +1 -1
  110. package/clinkx-workflows/dist/workflow-verification-contract.d.ts +4 -4
  111. package/clinkx-workflows/templates/architecture-arena/candidate.txt +39 -0
  112. package/clinkx-workflows/templates/architecture-arena/judge.txt +34 -0
  113. package/clinkx-workflows/templates/ping-pong/implement.txt +14 -0
  114. package/clinkx-workflows/templates/ping-pong/remediate.txt +14 -0
  115. package/clinkx-workflows/templates/ping-pong/review.txt +27 -0
  116. package/clinkx-workflows/workflows/architecture-arena.yaml +127 -0
  117. package/clinkx-workflows/workflows/ping-pong.yaml +158 -0
  118. package/dist/context-builder/bundle.js +4 -3
  119. package/dist/context-builder/bundle.js.map +1 -1
  120. package/dist/context-builder/delegate-packet.d.ts +1 -0
  121. package/dist/context-builder/delegate-packet.js +66 -7
  122. package/dist/context-builder/delegate-packet.js.map +1 -1
  123. package/dist/context-builder/delegate-validation.d.ts +12 -3
  124. package/dist/context-builder/delegate-validation.js +23 -13
  125. package/dist/context-builder/delegate-validation.js.map +1 -1
  126. package/dist/context-builder/external-gaps.d.ts +14 -3
  127. package/dist/context-builder/external-gaps.js +124 -18
  128. package/dist/context-builder/external-gaps.js.map +1 -1
  129. package/dist/context-builder/handler.js +108 -191
  130. package/dist/context-builder/handler.js.map +1 -1
  131. package/dist/context-builder/review-coverage.js +27 -1
  132. package/dist/context-builder/review-coverage.js.map +1 -1
  133. package/dist/context-builder/secrets.js +1 -1
  134. package/dist/context-builder/secrets.js.map +1 -1
  135. package/dist/context-builder/versions.d.ts +10 -4
  136. package/dist/context-builder/versions.js +10 -4
  137. package/dist/context-builder/versions.js.map +1 -1
  138. package/dist/context-builder/workflow-runner.js +33 -24
  139. package/dist/context-builder/workflow-runner.js.map +1 -1
  140. package/dist/dashboard-cli.d.ts +2 -0
  141. package/dist/dashboard-cli.js +147 -57
  142. package/dist/dashboard-cli.js.map +1 -1
  143. package/dist/dashboard-companion/client.d.ts +10 -0
  144. package/dist/dashboard-companion/client.js +43 -1
  145. package/dist/dashboard-companion/client.js.map +1 -1
  146. package/dist/dashboard-companion/config.d.ts +19 -1
  147. package/dist/dashboard-companion/config.js +104 -3
  148. package/dist/dashboard-companion/config.js.map +1 -1
  149. package/dist/dashboard-companion/protocol.d.ts +16 -0
  150. package/dist/dashboard-companion/protocol.js +38 -1
  151. package/dist/dashboard-companion/protocol.js.map +1 -1
  152. package/dist/dashboard-companion/workstation-binding.d.ts +69 -0
  153. package/dist/dashboard-companion/workstation-binding.js +192 -0
  154. package/dist/dashboard-companion/workstation-binding.js.map +1 -0
  155. package/dist/dashboard-gateway/admin-cli.d.ts +10 -0
  156. package/dist/dashboard-gateway/admin-cli.js +266 -0
  157. package/dist/dashboard-gateway/admin-cli.js.map +1 -0
  158. package/dist/dashboard-gateway/config.d.ts +50 -0
  159. package/dist/dashboard-gateway/config.js +235 -1
  160. package/dist/dashboard-gateway/config.js.map +1 -1
  161. package/dist/dashboard-gateway/connection-registry.d.ts +100 -0
  162. package/dist/dashboard-gateway/connection-registry.js +228 -0
  163. package/dist/dashboard-gateway/connection-registry.js.map +1 -0
  164. package/dist/dashboard-gateway/control-plane/account-auth.d.ts +78 -0
  165. package/dist/dashboard-gateway/control-plane/account-auth.js +198 -0
  166. package/dist/dashboard-gateway/control-plane/account-auth.js.map +1 -0
  167. package/dist/dashboard-gateway/control-plane/billing.d.ts +264 -0
  168. package/dist/dashboard-gateway/control-plane/billing.js +787 -0
  169. package/dist/dashboard-gateway/control-plane/billing.js.map +1 -0
  170. package/dist/dashboard-gateway/control-plane/contracts.d.ts +1293 -0
  171. package/dist/dashboard-gateway/control-plane/contracts.js +280 -0
  172. package/dist/dashboard-gateway/control-plane/contracts.js.map +1 -0
  173. package/dist/dashboard-gateway/control-plane/cookies.d.ts +13 -0
  174. package/dist/dashboard-gateway/control-plane/cookies.js +46 -0
  175. package/dist/dashboard-gateway/control-plane/cookies.js.map +1 -0
  176. package/dist/dashboard-gateway/control-plane/credentials.d.ts +63 -0
  177. package/dist/dashboard-gateway/control-plane/credentials.js +66 -0
  178. package/dist/dashboard-gateway/control-plane/credentials.js.map +1 -0
  179. package/dist/dashboard-gateway/control-plane/entitlements.d.ts +118 -0
  180. package/dist/dashboard-gateway/control-plane/entitlements.js +329 -0
  181. package/dist/dashboard-gateway/control-plane/entitlements.js.map +1 -0
  182. package/dist/dashboard-gateway/control-plane/errors.d.ts +17 -0
  183. package/dist/dashboard-gateway/control-plane/errors.js +23 -0
  184. package/dist/dashboard-gateway/control-plane/errors.js.map +1 -0
  185. package/dist/dashboard-gateway/control-plane/hosts.d.ts +6 -0
  186. package/dist/dashboard-gateway/control-plane/hosts.js +16 -0
  187. package/dist/dashboard-gateway/control-plane/hosts.js.map +1 -0
  188. package/dist/dashboard-gateway/control-plane/http.d.ts +34 -0
  189. package/dist/dashboard-gateway/control-plane/http.js +331 -0
  190. package/dist/dashboard-gateway/control-plane/http.js.map +1 -0
  191. package/dist/dashboard-gateway/control-plane/schema.d.ts +9 -0
  192. package/dist/dashboard-gateway/control-plane/schema.js +247 -0
  193. package/dist/dashboard-gateway/control-plane/schema.js.map +1 -0
  194. package/dist/dashboard-gateway/control-plane/secrets.d.ts +20 -0
  195. package/dist/dashboard-gateway/control-plane/secrets.js +39 -0
  196. package/dist/dashboard-gateway/control-plane/secrets.js.map +1 -0
  197. package/dist/dashboard-gateway/control-plane/store.d.ts +579 -0
  198. package/dist/dashboard-gateway/control-plane/store.js +1115 -0
  199. package/dist/dashboard-gateway/control-plane/store.js.map +1 -0
  200. package/dist/dashboard-gateway/cookie-boundary.d.ts +60 -0
  201. package/dist/dashboard-gateway/cookie-boundary.js +205 -0
  202. package/dist/dashboard-gateway/cookie-boundary.js.map +1 -0
  203. package/dist/dashboard-gateway/index.js +271 -494
  204. package/dist/dashboard-gateway/index.js.map +1 -1
  205. package/dist/dashboard-gateway/main.js +7 -2
  206. package/dist/dashboard-gateway/main.js.map +1 -1
  207. package/dist/dashboard-gateway/routing.d.ts +43 -0
  208. package/dist/dashboard-gateway/routing.js +65 -0
  209. package/dist/dashboard-gateway/routing.js.map +1 -0
  210. package/dist/dashboard-gateway/tenant-gateway.d.ts +56 -0
  211. package/dist/dashboard-gateway/tenant-gateway.js +989 -0
  212. package/dist/dashboard-gateway/tenant-gateway.js.map +1 -0
  213. package/dist/dashboard-gateway/tenant-main.d.ts +41 -0
  214. package/dist/dashboard-gateway/tenant-main.js +303 -0
  215. package/dist/dashboard-gateway/tenant-main.js.map +1 -0
  216. package/dist/dashboard-gateway/tunnel-errors.d.ts +16 -0
  217. package/dist/dashboard-gateway/tunnel-errors.js +22 -0
  218. package/dist/dashboard-gateway/tunnel-errors.js.map +1 -0
  219. package/dist/dashboard-gateway/tunnel-http.d.ts +21 -0
  220. package/dist/dashboard-gateway/tunnel-http.js +175 -0
  221. package/dist/dashboard-gateway/tunnel-http.js.map +1 -0
  222. package/dist/handler.d.ts +6 -0
  223. package/dist/handler.js +17 -1
  224. package/dist/handler.js.map +1 -1
  225. package/dist/local-clink-backend.d.ts +2 -1
  226. package/dist/local-clink-backend.js +28 -4
  227. package/dist/local-clink-backend.js.map +1 -1
  228. package/dist/parsers/extract.d.ts +19 -1
  229. package/dist/parsers/extract.js +68 -3
  230. package/dist/parsers/extract.js.map +1 -1
  231. package/dist/pipeline.d.ts +17 -1
  232. package/dist/pipeline.js +34 -6
  233. package/dist/pipeline.js.map +1 -1
  234. package/dist/process-group.d.ts +65 -0
  235. package/dist/process-group.js +153 -0
  236. package/dist/process-group.js.map +1 -0
  237. package/dist/progress-report/schema.d.ts +23 -23
  238. package/dist/project-verification/files.js +1 -1
  239. package/dist/project-verification/files.js.map +1 -1
  240. package/dist/project-verification/process.js +23 -44
  241. package/dist/project-verification/process.js.map +1 -1
  242. package/dist/project-verification/service.js +9 -1
  243. package/dist/project-verification/service.js.map +1 -1
  244. package/dist/prompt.d.ts +7 -0
  245. package/dist/prompt.js +18 -1
  246. package/dist/prompt.js.map +1 -1
  247. package/dist/recipe-host/git-trust.d.ts +43 -0
  248. package/dist/recipe-host/git-trust.js +360 -0
  249. package/dist/recipe-host/git-trust.js.map +1 -0
  250. package/dist/recipe-host/git.d.ts +42 -0
  251. package/dist/recipe-host/git.js +207 -0
  252. package/dist/recipe-host/git.js.map +1 -0
  253. package/dist/recipe-host/native-recipe-host.d.ts +127 -0
  254. package/dist/recipe-host/native-recipe-host.js +880 -0
  255. package/dist/recipe-host/native-recipe-host.js.map +1 -0
  256. package/dist/recipe-host/seat-cwd.d.ts +16 -0
  257. package/dist/recipe-host/seat-cwd.js +170 -0
  258. package/dist/recipe-host/seat-cwd.js.map +1 -0
  259. package/dist/runner.d.ts +43 -1
  260. package/dist/runner.js +234 -35
  261. package/dist/runner.js.map +1 -1
  262. package/dist/server.js +9 -1
  263. package/dist/server.js.map +1 -1
  264. package/docs/configuration.md +24 -3
  265. package/docs/engineering-recipes.md +291 -0
  266. package/docs/security.md +84 -0
  267. package/docs/verification/project-checks.md +24 -2
  268. package/package.json +5 -1
  269. package/clinkx-workflows/dist/dashboard-ui/assets/index-BdpmbPps.js +0 -115
  270. package/clinkx-workflows/dist/dashboard-ui/assets/style-Im5i1iAs.css +0 -1
@@ -1,12 +1,16 @@
1
+ import { WorkflowError } from "./errors.js";
2
+ import { type RecipeStateDraft, type RecipeStateV1 } from "./ping-pong/contract.js";
3
+ import { type RecipeTerminalEnvelope } from "./ping-pong/settle.js";
1
4
  import type { EngineHooks, EngineResumeState } from "./engine.js";
2
5
  import type { NormalizedWorkflowDefinition } from "./definition-normalizer.js";
3
- import type { FailureClass, RunState } from "./state-schema.js";
6
+ import type { FailureClass, RunState, RunStatus } from "./state-schema.js";
4
7
  import { type WorkflowContext } from "./context-preflight.js";
5
8
  import type { WorkflowContextBuilderLifecycleTransition } from "./context-builder-lifecycle-router.js";
6
9
  import type { WorkflowContextPolicy } from "./context-mode-resolver.js";
7
10
  import { type ResolvedRoster } from "./roster-contract.js";
8
11
  import { type PlanReviewContextProvenance, type PlanReviewRunState } from "./plan-review/run-state.js";
9
12
  import { type CouncilPlanReviewError } from "./plan-review/publication.js";
13
+ import { type FileWriter } from "./durable-file.js";
10
14
  /**
11
15
  * Reader-side staleness floor the shipped cadence is designed against; the
12
16
  * dashboard observer derives its own threshold from the declared interval.
@@ -53,6 +57,8 @@ export interface CreateWorkflowStateOptions {
53
57
  readonly initialContextPolicy?: WorkflowContextPolicy | undefined;
54
58
  readonly resolvedRoster?: ResolvedRoster | undefined;
55
59
  readonly rosterName?: string | undefined;
60
+ /** Test seam; production omits it and gets the durable writer. */
61
+ readonly fileWriter?: FileWriter | undefined;
56
62
  }
57
63
  /**
58
64
  * Warn-only signal recorded at create() when a sibling run with byte-identical
@@ -67,9 +73,59 @@ export interface ResumeWorkflowStateOptions {
67
73
  readonly runId: string;
68
74
  readonly runDir?: string | undefined;
69
75
  readonly debugKeepArtifacts?: boolean | undefined;
76
+ /** Test seam; production omits it and gets the durable writer. */
77
+ readonly fileWriter?: FileWriter | undefined;
78
+ }
79
+ /** Why `WorkflowStateStore.reopen()` refused; nothing was written in any case. */
80
+ export type RecipeReopenFailure = "run_busy" | "not_found" | "not_recipe" | "not_awaiting_decision" | "integrity";
81
+ /**
82
+ * The terminal recipe sidecar for a failed/cancelled settlement could not be
83
+ * committed, so `state.json` was left active rather than claiming an outcome
84
+ * the sidecar does not record. Once run.lock is released the run is an
85
+ * orphan: reconcile fails it, or cancel_workflow records it.
86
+ */
87
+ export declare class RecipeTerminalUnrecordedError extends WorkflowError {
88
+ readonly intent: "succeeded" | "failed" | "cancelled";
89
+ constructor(intent: "succeeded" | "failed" | "cancelled", cause: unknown);
90
+ }
91
+ export declare class RecipeReopenError extends WorkflowError {
92
+ readonly reason: RecipeReopenFailure;
93
+ /** Current sidecar position, when one could be read. */
94
+ readonly current?: {
95
+ readonly phase: string;
96
+ readonly revision: number;
97
+ readonly status: RunStatus;
98
+ } | undefined;
99
+ constructor(reason: RecipeReopenFailure, message: string,
100
+ /** Current sidecar position, when one could be read. */
101
+ current?: {
102
+ readonly phase: string;
103
+ readonly revision: number;
104
+ readonly status: RunStatus;
105
+ } | undefined);
106
+ }
107
+ export interface ReopenRecipeRunOptions {
108
+ readonly runId: string;
109
+ readonly runDir?: string | undefined;
110
+ readonly debugKeepArtifacts?: boolean | undefined;
111
+ /** Test seam; production omits it and gets the durable writer. */
112
+ readonly fileWriter?: FileWriter | undefined;
70
113
  }
71
114
  export declare function classifyRunDirectory(runDirPath: string): RunDirectoryClassification;
72
115
  export declare function pruneRunDirectories(runsRootDir: string, options?: PruneRunDirectoriesOptions): Promise<PruneRunDirectoriesResult>;
116
+ export type RecipeRunPrePruneDecision = "allow" | "veto";
117
+ export interface RecipeRunPrePruneContext {
118
+ readonly runId: string;
119
+ readonly runDir: string;
120
+ }
121
+ export type RecipeRunPrePruneObserver = (context: RecipeRunPrePruneContext) => Promise<RecipeRunPrePruneDecision> | RecipeRunPrePruneDecision;
122
+ /**
123
+ * Install the root host's pre-prune observer for recipe runs (CONTRACTS C5).
124
+ * It runs under the prune lock immediately before a run directory holding
125
+ * `recipe-state.json` is removed; "veto" keeps the directory. Process-local,
126
+ * like `setWorkflowActivityObserver`.
127
+ */
128
+ export declare function setRecipeRunPrePruneObserver(observer: RecipeRunPrePruneObserver | undefined): void;
73
129
  export declare class WorkflowStateStore {
74
130
  readonly runDir: string;
75
131
  /** Portable journal identity; absent only for a legacy or failed-open run. */
@@ -95,10 +151,74 @@ export declare class WorkflowStateStore {
95
151
  private heartbeatError;
96
152
  private readonly persistInvocationAuditV2;
97
153
  private readonly persistObservedInvocation;
154
+ /** Last committed recipe sidecar; `undefined` until loaded or when absent. */
155
+ private recipeStateCache;
156
+ private recipeStateLoaded;
157
+ private readonly writer;
98
158
  private constructor();
99
159
  static create(options: CreateWorkflowStateOptions): Promise<WorkflowStateStore>;
100
160
  static resume(options: ResumeWorkflowStateOptions): Promise<WorkflowStateStore>;
161
+ /**
162
+ * Reopen a paused recipe run for a control or decision execution (CONTRACTS
163
+ * 0-2 step 4, 0-7). Acquires `run.lock` with a heartbeat, verifies the
164
+ * workflow and inputs snapshot hashes, and requires terminal `succeeded`
165
+ * plus a sidecar at `awaiting_decision`. Read-only: nothing is written until
166
+ * the caller validates and calls `beginRecipeExecution()`. Calls are never
167
+ * generically rewritten, and the child-config fingerprint is not consulted
168
+ * (a pause can outlive adapter edits; the snapshots pin the definition).
169
+ * On refusal the lock is released and a `RecipeReopenError` is thrown.
170
+ */
171
+ static reopen(options: ReopenRecipeRunOptions): Promise<WorkflowStateStore>;
101
172
  get runState(): RunState;
173
+ /** The writer every file of this run goes through (durable in production). */
174
+ get fileWriter(): FileWriter;
175
+ /** Last committed recipe sidecar held by this store (reopen loads it; commits refresh it). */
176
+ get recipeState(): RecipeStateV1 | undefined;
177
+ /**
178
+ * Turn a reopened terminal envelope into a new active execution: status
179
+ * `running`, terminal fields and the previous execution id cleared. The
180
+ * caller then binds the new id (`bindExecution` via the run owner) before
181
+ * any sidecar commit. A crash in between leaves `running` with no id, which
182
+ * reconcile fails rather than settling the old pin.
183
+ */
184
+ beginRecipeExecution(): Promise<void>;
185
+ /**
186
+ * Commit `recipe-state.json` on this store's write chain under its
187
+ * `run.lock` (CONTRACTS 0-7). The store stamps `execution_id` (the bound
188
+ * id; unbound -> error), `revision` (previous + 1), `updated_at` and
189
+ * `unresolved_operations`, enforces the phase machine and the 0-4 byte
190
+ * budget, and returns the committed state. Over budget throws
191
+ * `RecipeStateCapacityError`; a non-terminal write may use 1 MiB minus the
192
+ * 64 KiB terminal reserve. State.json is not touched.
193
+ */
194
+ commitRecipeState(draft: RecipeStateDraft): Promise<RecipeStateV1>;
195
+ /**
196
+ * Terminal recipe commit in ONE critical section: the terminal sidecar first,
197
+ * then the matching terminal `state.json` (`qualified`/`stopped` ->
198
+ * succeeded, `failed` -> failed, `cancelled` -> cancelled). A crash between
199
+ * the two is rolled forward by reconcile. Used by control executions
200
+ * (decision stop, deadline, paused cancel) and by the runtime for a terminal
201
+ * stop it publishes itself.
202
+ */
203
+ commitRecipeTerminal(draft: RecipeStateDraft, options?: {
204
+ readonly error?: string | undefined;
205
+ readonly failureClass?: FailureClass | undefined;
206
+ }): Promise<RecipeStateV1>;
207
+ /**
208
+ * D1 terminal precedence for a recipe run, inside the write chain: the
209
+ * terminal fields to publish INSTEAD of `intent`, or `undefined` to publish
210
+ * `intent` as the caller would. A committed terminal sidecar of this
211
+ * execution decides; a non-terminal one is terminalized first (cancelled or
212
+ * failed), so the sidecar is never behind the state that settles it. A
213
+ * failed sidecar commit throws `RecipeTerminalUnrecordedError` and the
214
+ * caller must leave state.json active, as after a crash between the two
215
+ * writes. Non-recipe runs return `undefined` without any I/O.
216
+ */
217
+ private recipeTerminalOverrideLocked;
218
+ /** Runs inside the write chain. */
219
+ private recipeAuthorityLocked;
220
+ /** Runs inside the write chain; never enqueue from here. */
221
+ private writeRecipeStateLocked;
102
222
  /**
103
223
  * Open a new generic resume attempt before any context preflight or provider
104
224
  * setup. Provider-call attempt counters remain untouched; only the run-level
@@ -198,11 +318,49 @@ export declare function readRunStateForStatus(runId: string, containedRead?: boo
198
318
  * The caller re-reads to report already_terminal.
199
319
  * - "cancelled" — lock acquired and run was pending/running; terminal
200
320
  * "cancelled" state is written and the lock removed.
321
+ * - "settled" — recipe runs only: the sidecar of this execution already
322
+ * recorded a terminal outcome, so that outcome's status is
323
+ * written instead of "cancelled" (first committed terminal
324
+ * intent wins, D1).
325
+ * - "recipe_state_unavailable" — recipe runs only: the sidecar could not be
326
+ * read, or its terminal record could not be committed;
327
+ * nothing is written (fail closed).
201
328
  *
202
329
  * NOTE: This intentionally does NOT use WorkflowStateStore.resume() (which
203
330
  * recovers + re-locks the run — the wrong intent here).
204
331
  */
205
- export declare function reapRunCancelled(runId: string): Promise<"cancelled" | "skipped" | "locked" | "ownership_unknown">;
332
+ export interface ReapRunCancelledOptions {
333
+ /**
334
+ * Runs under the acquired `run.lock` after the run is re-verified
335
+ * non-terminal and before the terminal write (CONTRACTS 0-7 orphan cancel).
336
+ * Its disposition decides that write; a throw counts as `unavailable`, so
337
+ * nothing is written.
338
+ */
339
+ readonly beforeWrite?: ((context: RecipeOrphanCancelContext) => Promise<RecipeOrphanCancelDisposition | void>) | undefined;
340
+ /** Test seam; production omits it and gets the durable writer. */
341
+ readonly fileWriter?: FileWriter | undefined;
342
+ }
343
+ export interface RecipeOrphanCancelContext {
344
+ readonly runDir: string;
345
+ readonly state: RunState;
346
+ readonly fileWriter?: FileWriter | undefined;
347
+ }
348
+ export type RecipeOrphanCancelDisposition =
349
+ /** Write terminal `cancelled`. */
350
+ {
351
+ readonly kind: "cancel";
352
+ }
353
+ /** Write the outcome a committed terminal sidecar of this execution records. */
354
+ | {
355
+ readonly kind: "settled";
356
+ readonly envelope: RecipeTerminalEnvelope;
357
+ }
358
+ /** Write nothing: the sidecar is unreadable or its record failed. */
359
+ | {
360
+ readonly kind: "unavailable";
361
+ readonly reason: string;
362
+ };
363
+ export declare function reapRunCancelled(runId: string, options?: ReapRunCancelledOptions): Promise<"cancelled" | "settled" | "skipped" | "locked" | "ownership_unknown" | "recipe_state_unavailable">;
206
364
  /**
207
365
  * Terminalize run directories frozen as running/pending with no live worker.
208
366
  *
@@ -225,4 +383,21 @@ export declare function reapRunCancelled(runId: string): Promise<"cancelled" | "
225
383
  * once, then release. Idempotent: reconciled runs are terminal `failed` and
226
384
  * count as skipped_terminal on re-scan.
227
385
  */
228
- export declare function reconcileStaleRunDirectories(runsRootDir: string): Promise<ReconcileStaleRunDirectoriesResult>;
386
+ export declare function reconcileStaleRunDirectories(runsRootDir: string, options?: {
387
+ readonly fileWriter?: FileWriter | undefined;
388
+ }): Promise<ReconcileStaleRunDirectoriesResult>;
389
+ export declare const RECIPE_ROLL_FORWARD_FAILED_ERROR = "Reconciled: recipe sidecar recorded a failed outcome";
390
+ /**
391
+ * `reapRunCancelled` beforeWrite hook for an orphaned ping-pong run (CONTRACTS
392
+ * 0-7, D1), under the lock. Only a sidecar of THIS execution is ever written
393
+ * or decides:
394
+ * - a terminal one settles the run with its own outcome's status;
395
+ * - a non-terminal one records terminal `stopped(cancelled)` (every operation
396
+ * without a result becomes `uncertain`; `effects_stopped` only when none
397
+ * remain), then the run is cancelled;
398
+ * - absent, another execution's, or an unbound state: the sidecar bytes stay
399
+ * as they are and the run is cancelled;
400
+ * - unreadable, or a record that cannot be committed: `unavailable`, and the
401
+ * reap writes nothing.
402
+ */
403
+ export declare function recordRecipeOrphanCancel(context: RecipeOrphanCancelContext): Promise<RecipeOrphanCancelDisposition>;