@calliopelabs/cli 3.5.4 → 3.7.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 (311) hide show
  1. package/README.md +8 -0
  2. package/dist/acp/controls.d.ts +10 -0
  3. package/dist/acp/controls.d.ts.map +1 -0
  4. package/dist/acp/controls.js +81 -0
  5. package/dist/acp/controls.js.map +1 -0
  6. package/dist/acp.d.ts +21 -7
  7. package/dist/acp.d.ts.map +1 -1
  8. package/dist/acp.js +139 -23
  9. package/dist/acp.js.map +1 -1
  10. package/dist/bin.d.ts.map +1 -1
  11. package/dist/bin.js +28 -8
  12. package/dist/bin.js.map +1 -1
  13. package/dist/build-identity.d.ts +27 -0
  14. package/dist/build-identity.d.ts.map +1 -0
  15. package/dist/build-identity.js +32 -0
  16. package/dist/build-identity.js.map +1 -0
  17. package/dist/build-metadata.json +1 -0
  18. package/dist/execution/authority.d.ts +4 -1
  19. package/dist/execution/authority.d.ts.map +1 -1
  20. package/dist/execution/authority.js +23 -7
  21. package/dist/execution/authority.js.map +1 -1
  22. package/dist/execution/child-grants.d.ts +2 -0
  23. package/dist/execution/child-grants.d.ts.map +1 -1
  24. package/dist/execution/child-grants.js +19 -4
  25. package/dist/execution/child-grants.js.map +1 -1
  26. package/dist/execution/delegated.d.ts +14 -0
  27. package/dist/execution/delegated.d.ts.map +1 -0
  28. package/dist/execution/delegated.js +66 -0
  29. package/dist/execution/delegated.js.map +1 -0
  30. package/dist/execution/files.js +6 -6
  31. package/dist/execution/files.js.map +1 -1
  32. package/dist/execution/guard.d.ts +5 -0
  33. package/dist/execution/guard.d.ts.map +1 -1
  34. package/dist/execution/guard.js +31 -16
  35. package/dist/execution/guard.js.map +1 -1
  36. package/dist/execution/index.d.ts +4 -0
  37. package/dist/execution/index.d.ts.map +1 -1
  38. package/dist/execution/index.js +4 -0
  39. package/dist/execution/index.js.map +1 -1
  40. package/dist/execution/ledger-cli.d.ts +2 -1
  41. package/dist/execution/ledger-cli.d.ts.map +1 -1
  42. package/dist/execution/ledger-cli.js +51 -14
  43. package/dist/execution/ledger-cli.js.map +1 -1
  44. package/dist/execution/ledger-protocol.d.ts +6 -2
  45. package/dist/execution/ledger-protocol.d.ts.map +1 -1
  46. package/dist/execution/ledger-protocol.js +110 -24
  47. package/dist/execution/ledger-protocol.js.map +1 -1
  48. package/dist/execution/ledger-server.d.ts +13 -0
  49. package/dist/execution/ledger-server.d.ts.map +1 -1
  50. package/dist/execution/ledger-server.js +57 -13
  51. package/dist/execution/ledger-server.js.map +1 -1
  52. package/dist/execution/ledger-tunnel.d.ts +50 -0
  53. package/dist/execution/ledger-tunnel.d.ts.map +1 -0
  54. package/dist/execution/ledger-tunnel.js +307 -0
  55. package/dist/execution/ledger-tunnel.js.map +1 -0
  56. package/dist/execution/ledger.d.ts +4 -0
  57. package/dist/execution/ledger.d.ts.map +1 -1
  58. package/dist/execution/ledger.js +30 -4
  59. package/dist/execution/ledger.js.map +1 -1
  60. package/dist/execution/parent-accounting.d.ts +41 -0
  61. package/dist/execution/parent-accounting.d.ts.map +1 -0
  62. package/dist/execution/parent-accounting.js +52 -0
  63. package/dist/execution/parent-accounting.js.map +1 -0
  64. package/dist/execution/parent-budget.d.ts +25 -0
  65. package/dist/execution/parent-budget.d.ts.map +1 -0
  66. package/dist/execution/parent-budget.js +102 -0
  67. package/dist/execution/parent-budget.js.map +1 -0
  68. package/dist/execution/project-spend.d.ts.map +1 -1
  69. package/dist/execution/project-spend.js +35 -5
  70. package/dist/execution/project-spend.js.map +1 -1
  71. package/dist/execution/remote-checkpoint.d.ts +15 -0
  72. package/dist/execution/remote-checkpoint.d.ts.map +1 -0
  73. package/dist/execution/remote-checkpoint.js +165 -0
  74. package/dist/execution/remote-checkpoint.js.map +1 -0
  75. package/dist/execution/remote-ledger.d.ts +12 -2
  76. package/dist/execution/remote-ledger.d.ts.map +1 -1
  77. package/dist/execution/remote-ledger.js +53 -21
  78. package/dist/execution/remote-ledger.js.map +1 -1
  79. package/dist/execution/types.d.ts +23 -5
  80. package/dist/execution/types.d.ts.map +1 -1
  81. package/dist/execution/types.js.map +1 -1
  82. package/dist/goals/supervised.js +2 -2
  83. package/dist/goals/supervised.js.map +1 -1
  84. package/dist/headless.d.ts +2 -6
  85. package/dist/headless.d.ts.map +1 -1
  86. package/dist/headless.js +17 -21
  87. package/dist/headless.js.map +1 -1
  88. package/dist/improvement/actions.d.ts +3 -4
  89. package/dist/improvement/actions.d.ts.map +1 -1
  90. package/dist/improvement/actions.js +10 -7
  91. package/dist/improvement/actions.js.map +1 -1
  92. package/dist/improvement/capabilities.d.ts +54 -0
  93. package/dist/improvement/capabilities.d.ts.map +1 -0
  94. package/dist/improvement/capabilities.js +44 -0
  95. package/dist/improvement/capabilities.js.map +1 -0
  96. package/dist/improvement/cli.d.ts +1 -1
  97. package/dist/improvement/cli.d.ts.map +1 -1
  98. package/dist/improvement/cli.js +29 -3
  99. package/dist/improvement/cli.js.map +1 -1
  100. package/dist/improvement/host-capabilities.d.ts +119 -0
  101. package/dist/improvement/host-capabilities.d.ts.map +1 -0
  102. package/dist/improvement/host-capabilities.js +18 -0
  103. package/dist/improvement/host-capabilities.js.map +1 -0
  104. package/dist/improvement/index.d.ts +6 -0
  105. package/dist/improvement/index.d.ts.map +1 -1
  106. package/dist/improvement/index.js +6 -0
  107. package/dist/improvement/index.js.map +1 -1
  108. package/dist/improvement/proposal-hash.d.ts +3 -0
  109. package/dist/improvement/proposal-hash.d.ts.map +1 -0
  110. package/dist/improvement/proposal-hash.js +5 -0
  111. package/dist/improvement/proposal-hash.js.map +1 -0
  112. package/dist/improvement/review-contract.d.ts +32 -0
  113. package/dist/improvement/review-contract.d.ts.map +1 -0
  114. package/dist/improvement/review-contract.js +62 -0
  115. package/dist/improvement/review-contract.js.map +1 -0
  116. package/dist/improvement/review-requests.d.ts +72 -0
  117. package/dist/improvement/review-requests.d.ts.map +1 -0
  118. package/dist/improvement/review-requests.js +63 -0
  119. package/dist/improvement/review-requests.js.map +1 -0
  120. package/dist/improvement/source-changes.d.ts +78 -0
  121. package/dist/improvement/source-changes.d.ts.map +1 -0
  122. package/dist/improvement/source-changes.js +91 -0
  123. package/dist/improvement/source-changes.js.map +1 -0
  124. package/dist/improvement/task-outcomes.d.ts +82 -0
  125. package/dist/improvement/task-outcomes.d.ts.map +1 -0
  126. package/dist/improvement/task-outcomes.js +72 -0
  127. package/dist/improvement/task-outcomes.js.map +1 -0
  128. package/dist/index.d.ts +10 -0
  129. package/dist/index.d.ts.map +1 -1
  130. package/dist/index.js +6 -0
  131. package/dist/index.js.map +1 -1
  132. package/dist/isolation/contracts.d.ts +13 -0
  133. package/dist/isolation/contracts.d.ts.map +1 -1
  134. package/dist/isolation/contracts.js +9 -1
  135. package/dist/isolation/contracts.js.map +1 -1
  136. package/dist/isolation/coordinator.d.ts.map +1 -1
  137. package/dist/isolation/coordinator.js +4 -0
  138. package/dist/isolation/coordinator.js.map +1 -1
  139. package/dist/isolation/process.d.ts.map +1 -1
  140. package/dist/isolation/process.js +3 -1
  141. package/dist/isolation/process.js.map +1 -1
  142. package/dist/isolation/worktree.d.ts +9 -1
  143. package/dist/isolation/worktree.d.ts.map +1 -1
  144. package/dist/isolation/worktree.js +8 -3
  145. package/dist/isolation/worktree.js.map +1 -1
  146. package/dist/memory.d.ts +5 -3
  147. package/dist/memory.d.ts.map +1 -1
  148. package/dist/memory.js +8 -6
  149. package/dist/memory.js.map +1 -1
  150. package/dist/migration/assessment-contract.d.ts +60 -0
  151. package/dist/migration/assessment-contract.d.ts.map +1 -0
  152. package/dist/migration/assessment-contract.js +132 -0
  153. package/dist/migration/assessment-contract.js.map +1 -0
  154. package/dist/migration/assessment-schema.d.ts +19 -0
  155. package/dist/migration/assessment-schema.d.ts.map +1 -0
  156. package/dist/migration/assessment-schema.js +43 -0
  157. package/dist/migration/assessment-schema.js.map +1 -0
  158. package/dist/migration/assessment.d.ts +159 -0
  159. package/dist/migration/assessment.d.ts.map +1 -0
  160. package/dist/migration/assessment.js +219 -0
  161. package/dist/migration/assessment.js.map +1 -0
  162. package/dist/migration/cli.d.ts +6 -0
  163. package/dist/migration/cli.d.ts.map +1 -0
  164. package/dist/migration/cli.js +101 -0
  165. package/dist/migration/cli.js.map +1 -0
  166. package/dist/migration/evidence.d.ts +27 -0
  167. package/dist/migration/evidence.d.ts.map +1 -0
  168. package/dist/migration/evidence.js +124 -0
  169. package/dist/migration/evidence.js.map +1 -0
  170. package/dist/migration/example.d.ts +33 -0
  171. package/dist/migration/example.d.ts.map +1 -0
  172. package/dist/migration/example.js +28 -0
  173. package/dist/migration/example.js.map +1 -0
  174. package/dist/migration/index.d.ts +21 -0
  175. package/dist/migration/index.d.ts.map +1 -0
  176. package/dist/migration/index.js +15 -0
  177. package/dist/migration/index.js.map +1 -0
  178. package/dist/migration/inventory.d.ts +70 -0
  179. package/dist/migration/inventory.d.ts.map +1 -0
  180. package/dist/migration/inventory.js +233 -0
  181. package/dist/migration/inventory.js.map +1 -0
  182. package/dist/migration/schema.d.ts +61 -0
  183. package/dist/migration/schema.d.ts.map +1 -0
  184. package/dist/migration/schema.js +76 -0
  185. package/dist/migration/schema.js.map +1 -0
  186. package/dist/migration/verification.d.ts +146 -0
  187. package/dist/migration/verification.d.ts.map +1 -0
  188. package/dist/migration/verification.js +260 -0
  189. package/dist/migration/verification.js.map +1 -0
  190. package/dist/orchestration/actions.d.ts +2 -0
  191. package/dist/orchestration/actions.d.ts.map +1 -1
  192. package/dist/orchestration/actions.js.map +1 -1
  193. package/dist/orchestration/artifact-host.d.ts +46 -0
  194. package/dist/orchestration/artifact-host.d.ts.map +1 -0
  195. package/dist/orchestration/artifact-host.js +64 -0
  196. package/dist/orchestration/artifact-host.js.map +1 -0
  197. package/dist/orchestration/coordinator-actions.d.ts +1 -1
  198. package/dist/orchestration/coordinator-actions.d.ts.map +1 -1
  199. package/dist/orchestration/coordinator-actions.js +5 -3
  200. package/dist/orchestration/coordinator-actions.js.map +1 -1
  201. package/dist/orchestration/coordinator-types.d.ts +23 -2
  202. package/dist/orchestration/coordinator-types.d.ts.map +1 -1
  203. package/dist/orchestration/coordinator.d.ts +5 -0
  204. package/dist/orchestration/coordinator.d.ts.map +1 -1
  205. package/dist/orchestration/coordinator.js +30 -13
  206. package/dist/orchestration/coordinator.js.map +1 -1
  207. package/dist/orchestration/execution-cli.d.ts +1 -1
  208. package/dist/orchestration/execution-cli.d.ts.map +1 -1
  209. package/dist/orchestration/execution-cli.js +29 -6
  210. package/dist/orchestration/execution-cli.js.map +1 -1
  211. package/dist/orchestration/execution-journal.d.ts.map +1 -1
  212. package/dist/orchestration/execution-journal.js +79 -6
  213. package/dist/orchestration/execution-journal.js.map +1 -1
  214. package/dist/orchestration/execution-store.d.ts +5 -1
  215. package/dist/orchestration/execution-store.d.ts.map +1 -1
  216. package/dist/orchestration/execution-store.js +66 -5
  217. package/dist/orchestration/execution-store.js.map +1 -1
  218. package/dist/orchestration/execution.d.ts.map +1 -1
  219. package/dist/orchestration/execution.js +37 -10
  220. package/dist/orchestration/execution.js.map +1 -1
  221. package/dist/orchestration/index.d.ts +6 -0
  222. package/dist/orchestration/index.d.ts.map +1 -1
  223. package/dist/orchestration/index.js +6 -0
  224. package/dist/orchestration/index.js.map +1 -1
  225. package/dist/orchestration/interruption.d.ts +10 -0
  226. package/dist/orchestration/interruption.d.ts.map +1 -0
  227. package/dist/orchestration/interruption.js +38 -0
  228. package/dist/orchestration/interruption.js.map +1 -0
  229. package/dist/orchestration/question-contract.d.ts +19 -0
  230. package/dist/orchestration/question-contract.d.ts.map +1 -0
  231. package/dist/orchestration/question-contract.js +21 -0
  232. package/dist/orchestration/question-contract.js.map +1 -0
  233. package/dist/orchestration/questions.d.ts +9 -0
  234. package/dist/orchestration/questions.d.ts.map +1 -0
  235. package/dist/orchestration/questions.js +75 -0
  236. package/dist/orchestration/questions.js.map +1 -0
  237. package/dist/orchestration/reviewed-ledger.d.ts +23 -0
  238. package/dist/orchestration/reviewed-ledger.d.ts.map +1 -0
  239. package/dist/orchestration/reviewed-ledger.js +57 -0
  240. package/dist/orchestration/reviewed-ledger.js.map +1 -0
  241. package/dist/orchestration/routing.d.ts +3 -0
  242. package/dist/orchestration/routing.d.ts.map +1 -1
  243. package/dist/orchestration/routing.js +5 -1
  244. package/dist/orchestration/routing.js.map +1 -1
  245. package/dist/orchestration/source-candidates.d.ts +64 -0
  246. package/dist/orchestration/source-candidates.d.ts.map +1 -0
  247. package/dist/orchestration/source-candidates.js +95 -0
  248. package/dist/orchestration/source-candidates.js.map +1 -0
  249. package/dist/orchestration/validation.js +1 -1
  250. package/dist/orchestration/validation.js.map +1 -1
  251. package/dist/runlog.js +2 -2
  252. package/dist/runlog.js.map +1 -1
  253. package/dist/runtime/permissions.d.ts.map +1 -1
  254. package/dist/runtime/permissions.js +3 -2
  255. package/dist/runtime/permissions.js.map +1 -1
  256. package/dist/runtime/turn.d.ts +2 -0
  257. package/dist/runtime/turn.d.ts.map +1 -1
  258. package/dist/runtime/turn.js +21 -7
  259. package/dist/runtime/turn.js.map +1 -1
  260. package/dist/session-management/actions.js +1 -1
  261. package/dist/session-management/actions.js.map +1 -1
  262. package/dist/sessions/execution-binding.d.ts +8 -0
  263. package/dist/sessions/execution-binding.d.ts.map +1 -0
  264. package/dist/sessions/execution-binding.js +9 -0
  265. package/dist/sessions/execution-binding.js.map +1 -0
  266. package/dist/sessions/index.d.ts +1 -0
  267. package/dist/sessions/index.d.ts.map +1 -1
  268. package/dist/sessions/index.js +1 -0
  269. package/dist/sessions/index.js.map +1 -1
  270. package/dist/source-changes/writer.d.ts +77 -0
  271. package/dist/source-changes/writer.d.ts.map +1 -0
  272. package/dist/source-changes/writer.js +189 -0
  273. package/dist/source-changes/writer.js.map +1 -0
  274. package/dist/spawning/actions.d.ts +10 -1
  275. package/dist/spawning/actions.d.ts.map +1 -1
  276. package/dist/spawning/actions.js +26 -7
  277. package/dist/spawning/actions.js.map +1 -1
  278. package/dist/spawning/cli.js +1 -1
  279. package/dist/spawning/cli.js.map +1 -1
  280. package/dist/spawning/execution.d.ts.map +1 -1
  281. package/dist/spawning/execution.js +2 -0
  282. package/dist/spawning/execution.js.map +1 -1
  283. package/dist/spawning/types.d.ts +19 -6
  284. package/dist/spawning/types.d.ts.map +1 -1
  285. package/dist/spawning/validation.d.ts +16 -0
  286. package/dist/spawning/validation.d.ts.map +1 -1
  287. package/dist/spawning/validation.js +44 -8
  288. package/dist/spawning/validation.js.map +1 -1
  289. package/dist/storage.d.ts +5 -0
  290. package/dist/storage.d.ts.map +1 -1
  291. package/dist/storage.js +10 -1
  292. package/dist/storage.js.map +1 -1
  293. package/dist/supervision/contracts.js +4 -1
  294. package/dist/supervision/contracts.js.map +1 -1
  295. package/dist/tools.d.ts +1 -0
  296. package/dist/tools.d.ts.map +1 -1
  297. package/dist/tools.js +5 -0
  298. package/dist/tools.js.map +1 -1
  299. package/docs/README.md +66 -0
  300. package/docs/acp.md +228 -0
  301. package/docs/delegation-ledger.md +331 -0
  302. package/docs/improvement-cycles.md +304 -0
  303. package/docs/migration-assessment.md +113 -0
  304. package/docs/migration-example-plan.json +88 -0
  305. package/docs/migration-example-report.json +511 -0
  306. package/docs/migration-inventory.md +63 -0
  307. package/docs/migration-playbook.md +152 -0
  308. package/docs/migration-verification.md +177 -0
  309. package/docs/releases/3.6.0.md +43 -0
  310. package/docs/releases/3.7.0.md +53 -0
  311. package/package.json +11 -3
@@ -0,0 +1,304 @@
1
+ # Bounded improvement cycles
2
+
3
+ Version-4 [supervised runs](continuous-supervision.md) record each final `retry`,
4
+ `replan` or `decompose` decision as an improvement cycle. The controller optimizes
5
+ for the reviewed principle (`speed`, `robustness`, `stability`, `security`,
6
+ `performance` or `cost`), reviews executor evidence, and receives the latest four
7
+ cycles' measured outcomes. A reviewer, when configured, owns the final decision;
8
+ its controller draft is not a second improvement.
9
+
10
+ ## Host capability discovery
11
+
12
+ `calliope improve host-capabilities --contract-version 1 --json` returns the
13
+ additive version-1 `improvement.host-capabilities` contract. It inventories the
14
+ native execution, review-request, task-outcome and source-change interfaces with
15
+ their independent versions. Discovery uses CLI JSON; operations use the native
16
+ library APIs described below. This declaration does not create remote RPC methods.
17
+ Unknown requested versions and run/approval/mutation selectors are refused.
18
+
19
+ `implementation` identifies the installed package version, artifact form and
20
+ build metadata status. Source metadata records the build's Git commit and dirty
21
+ state when available; builds outside their own source repository retain `null`.
22
+ The query never runs Git in the caller's project. Missing, malformed or mismatched
23
+ metadata cannot establish source identity. Even clean metadata is self-reported:
24
+ verify npm integrity and publisher provenance, or standalone release checksums
25
+ and binary attestations, against the same release tag and source commit before
26
+ trusting it. The query explicitly reports `external-attestation-required`.
27
+
28
+ Legacy execution discovery remains unchanged:
29
+
30
+ `calliope improve capabilities --json` returns a version-1 `improvement` envelope
31
+ whose action is `capabilities` and whose data kind is `improvement.capabilities`.
32
+ The data contract is version 2; its `hostAdmission` field advertises the native
33
+ `expectedExecutionRevision` option for propose/run and binding to the controller's
34
+ own committed reset event. Version-1 declarations do not promise this admission
35
+ contract. The outer CLI response envelope remains version 1.
36
+ This read-only query does not select a project/run, call a model, import feedback,
37
+ or grant execution authority. Run selectors, approval hashes and mutation flags
38
+ are rejected for this action. Hosts must negotiate this declaration instead of
39
+ inferring learning support from the package version or command names.
40
+
41
+ The current declaration advertises native recursive task-strategy improvement,
42
+ history schema versions, operation effects, exact-proposal approval, inherited
43
+ limits and withdrawal semantics. External feedback import, cross-run learned
44
+ strategy selection and model training are explicitly unavailable. Project brain
45
+ memory remains a separate interface. A supported operation still requires the
46
+ exact native run's current state and policy; this declaration is not evidence
47
+ that an installed run can execute it. Unknown contract versions are not compatible
48
+ by implication. This is the capability-discovery part of #413, not a completed
49
+ external feedback or reinforcement-learning interface.
50
+
51
+ ## Host review requests
52
+
53
+ The separately negotiated `improvementReviewCapabilities()` API (version 1,
54
+ `improvement.review-capabilities`) advertises `requestImprovementReview`,
55
+ `inspectImprovementReviews` and `dismissImprovementReview`. It is request-only;
56
+ existing version-2 execution capabilities are unchanged. Hosts must negotiate
57
+ this API separately before exposing a model request tool. Hosts supply the model-tool and human-review UI adapters. This API increment
58
+ does not add a CLI subcommand.
59
+
60
+ Requests carry version 1, `action` (`propose`, `run`, `rollback`), the exact
61
+ `executionRevision`, `cycleId` and `proposalHash` (both null for `propose`), and a
62
+ nonempty untrusted `reason` of at most 1,024 characters. Recording requires an
63
+ inactive approved supervised run and native policy/confirmation. It calls no
64
+ model, starts no worker, approves no proposal, and changes neither task state nor
65
+ budget. Run/withdrawal requests bind the native proposal hash; a new proposal
66
+ request needs retained task outcomes and remaining original controller time and
67
+ round capacity. Withdrawal requests can outlive the original deadline.
68
+
69
+ Version-9 events append to the existing private execution journal. Each request
70
+ is bound to the immediately preceding revision. Only one request can be current;
71
+ identical retries after a lost acknowledgement return that same request ID after
72
+ rechecking policy and run approval. A competing changed request fails. Native
73
+ ownership, revision and revocation checks run again before commit. At most 64
74
+ requests are retained per run, within the existing journal byte/event bounds.
75
+ Replay independently validates requests and never derives execution authority
76
+ from them. Older readers that do not support event version 9 must refuse these
77
+ journals; do not downgrade a run's owner after recording a request.
78
+
79
+ Inspection projects `pending`, `expired`, `stale` or `dismissed` from native
80
+ events. Any later execution/control event makes the old request stale, not
81
+ approved or completed. Human execution must use a fresh native inspection and
82
+ the existing proposal/run/withdrawal APIs with their normal review and policy.
83
+ Dismissal requires the exact current request ID/revision and a separate native
84
+ confirmation; it retains all history and does not withdraw the strategy. The
85
+ request reason remains untrusted display data, never an instruction or reward.
86
+
87
+ ## Controls
88
+
89
+ ```sh
90
+ calliope improve history --run RUN_ID --json
91
+ calliope improve propose --run RUN_ID --allow-mutations --json
92
+ calliope improve run CYCLE_ID --run RUN_ID --approve PROPOSAL_HASH --allow-mutations --json
93
+ calliope improve rollback CYCLE_ID --run RUN_ID --allow-mutations --json
94
+ ```
95
+
96
+ The REPL exposes the same arguments under `/improve`. Without a subcommand it
97
+ shows history; without `--run` it inspects the latest run in the active project.
98
+ Headless mutations require `--allow-mutations` or an approval callback, and still
99
+ pass project policy. REPL approvals use the existing scope preview and audit log.
100
+
101
+ `propose` reviews an inactive supervised run's retained outcomes, or returns its
102
+ existing pending proposal without another model call. Explicit recovery of a
103
+ halted controller retains its original rounds, task attempts, reservations and
104
+ deadline. It starts no workers and applies no proposed changes. It needs recorded
105
+ outcomes and remaining controller authority; a completed run or a `continue` or
106
+ `stop` decision can produce no improvement proposal. Inspect that decision before
107
+ resuming ordinary execution.
108
+
109
+ A recorded proposal hold survives restart. `run` requires its exact review hash;
110
+ ordinary `run resume` cannot bypass that hold. Approval is recorded in the same
111
+ execution journal before application, and checked again under coordinator
112
+ ownership. All subsequent decisions remain subject to the original reviewed
113
+ supervision policy. To inspect and retire a strategy, stop the coordinator first.
114
+
115
+ Native hosts can pass `expectedExecutionRevision` to `proposeImprovement` and
116
+ `runImprovement`. It must match the execution revision from their reviewed
117
+ inspection. Malformed, missing-history and stale bindings are refused before
118
+ execution approval. The coordinator rechecks after asynchronous authorization,
119
+ under its ownership lease and inside the journal append lock before starting
120
+ work. The execution permission request includes that bound `executionRevision`.
121
+ An explicit controller reset advances the binding only to its own committed
122
+ reset event; another writer's revision is never silently adopted. Existing
123
+ callers that omit the option bind to the history inspected by the improvement
124
+ action. This host API does not add a CLI flag; hosts negotiate the version-2 data
125
+ contract before relying on it. It does not authorize execution, change proposal hashes, or replenish
126
+ the original budget or deadline.
127
+
128
+ `rollback` **withdraws the execution strategy**. For a replan it restores the
129
+ previous unwithdrawn applied strategy; for decomposition it stops the admitted
130
+ child agents and their descendants. It stops controller continuation and preserves
131
+ the task graph, allocations, attempts, checks, candidate worktrees and artifacts.
132
+ It does not apply an inverse patch to source: this loop edits isolated candidates,
133
+ and never automatically applies them to the source checkout. Inspect the retained
134
+ base commit and patch artifacts to compare or recover a candidate. A different
135
+ pending decision must be resolved before withdrawing an older cycle. Withdrawing
136
+ an expired cycle is allowed because it reduces authority; it cannot revive the
137
+ clock or refund spend.
138
+
139
+ ## Evidence and schema
140
+
141
+ History is a deterministic projection of the existing private, hash-chained
142
+ journals, not a second mutable database. Legacy histories and cycles retain
143
+ `version: 1`; runs with [request attribution](request-attribution.md) use version 2
144
+ and identify the observed budget revision. Cycles whose review events carry
145
+ sanitized [provider-health evidence](provider-health.md) use version 3 and retain
146
+ the controller snapshot plus the reviewer snapshot when that separate role is
147
+ configured. This records the aggregate operational evidence available to each
148
+ decision without importing credentials, endpoint strings, provider text or new
149
+ execution authority. Each cycle's immutable ID is its final decision event ID. It
150
+ includes:
151
+
152
+ - Trigger event IDs/hashes, principle, proposed hypothesis/change/metric.
153
+ - Parent decomposition and previous attempt links, target tasks, original run
154
+ deadline and limits, scoped worker/controller/reviewer accounts and ancestors.
155
+ - Review hold, explicit approval, application and withdrawal event references;
156
+ original plan approval and separate production approval (`not-approved`).
157
+ - Baseline and direct next-attempt outcomes, checks, artifact hashes, observed
158
+ duration/tool results, unresolved risks, isolation image and rollback references.
159
+ - Original manifest hash and the inspected execution revision.
160
+ - Controller and optional reviewer provider-health snapshots, their observation
161
+ times, relevant-event counts and history hashes.
162
+
163
+ Inspection validates journal ancestry, current artifact read permissions, retained
164
+ artifact bytes and the pinned worktree base. Evidence reads are bounded to 64 MiB
165
+ per inspection; histories retain the execution store's existing event/size bounds.
166
+ No inspection calls a model or replays a tool. Recorded run replay reproduces the
167
+ same cycles without execution. Keep history private: task evidence can contain
168
+ project information even though API keys are not part of the cycle contract.
169
+
170
+ A cycle measures its **direct next attempts**. If a decomposed child fails and a
171
+ nested replan fixes it, the parent cycle retains that first failed result and the
172
+ nested cycle records the verified retry. This preserves the failure instead of
173
+ retroactively claiming every experiment succeeded. `verified` means the recorded
174
+ targets completed their acceptance process, not that every optimization claim was
175
+ proved. Human acceptance remains distinguishable by its source event.
176
+
177
+ ## Measurements and limitations
178
+
179
+ | Measurement | Definition | Comparison requirement |
180
+ |---|---|---|
181
+ | `acceptance-check-pass-rate` | Passed recorded acceptance checks / all recorded checks | Same tasks and check definitions |
182
+ | `attempt-duration` | Sum of task-start to task-finish event durations, milliseconds | Same complete task population |
183
+ | `tool-failure-rate` | Failed completed tool calls / completed tool calls | Same complete task population |
184
+ | `provider-accounted-cost` | Accounted provider charges for the recorded worker attempts, integer nano-dollars | Same complete task population, bound request provenance and fully settled usage |
185
+
186
+ Missing measurements are `null`, never zero. New task populations and changed
187
+ check definitions are explicitly non-comparable. These observations do not prove
188
+ causality or provide an automatic security/performance certification. Requested
189
+ metrics remain proposed even when checks pass. The duration is summed task time,
190
+ not workflow wall time; acceptance checks are not the individual assertions inside
191
+ a test process. The cost measurement excludes planning and controller/reviewer
192
+ overhead, and is not whole-goal cost per successful task or an invoice. Those
193
+ roles retain separate request attribution in run diagnostics. Unknown or pending
194
+ requests retain their conservative charge, but prevent a comparable cost delta.
195
+ Legacy/missing bindings yield unavailable costs rather than fabricated zeroes;
196
+ the shared run/project ledgers continue enforcing their original reservations.
197
+
198
+ For linked goals, [whole-goal metrics](goal-accounting.md) separately include
199
+ planning and review overhead and inspect final artifacts before reporting cost
200
+ per verified task. This total is not a comparable before/after cycle metric.
201
+
202
+ The HUD adds the latest cycle's status, comparable check rate and comparable
203
+ worker-attempt cost. Explicit Brain run ingestion cites the budget revision and
204
+ stores a separate snapshot when accounting changes; hypotheses remain proposed.
205
+ Headless output
206
+ uses `version: 1`, `type: improvement` for results and `type: improvement.event`
207
+ for streamed execution events; enclosed events keep their own schema version.
208
+ Execution exit codes remain 0 success, 4 partial, 3 policy denial, 130 cancellation
209
+ and 1 failure; malformed command arguments exit 2. History is local-only JSON and
210
+ can be redirected for diagnostics. There is no import of execution authority.
211
+
212
+ ## Safety and recovery
213
+
214
+ The loop cannot edit permissions, expand budgets/depth/count, reset deadlines,
215
+ erase evidence, publish, merge, deploy or send external messages. Every file/tool
216
+ mutation uses the shared runtime gates; child admission rechecks inherited scope
217
+ and grants. All coding attempts use retained Git worktrees and reviewed isolated
218
+ verification. Unknown requests retain their reservation, and interrupted calls
219
+ require explicit recovery. A cancelled or denied experiment keeps its partial
220
+ results; a new run is not an automatic escape from its allowance.
221
+
222
+ This implements recursive, evidence-driven **task strategy improvement**. It does
223
+ not automatically patch Calliope itself or promote knowledge to accepted fact.
224
+ The [project Brain](project-brain.md) can explicitly ingest verified run evidence;
225
+ improvement hypotheses remain proposed. [Opt-in agent retrieval](agent-knowledge.md)
226
+ lets planners and workers read that knowledge within their inherited source scopes.
227
+
228
+ ## Reviewed source proposals
229
+
230
+ The native `sourceChangeCapabilities`, `previewSourceChange`,
231
+ `proposeSourceChange`, `inspectSourceChange` and `listSourceChanges` APIs let a host offer verified
232
+ source changes for human review. A source-owned skill or interface uses the Git
233
+ repository that owns its files. Installed skills keep their separate installation
234
+ and trust lifecycle.
235
+
236
+ The selection binds the original run, execution revision, verified cycle, task
237
+ and executor-collected patch hash. Preview checks the original approval, task
238
+ write scope, pinned source commit and repository-local author. It returns the
239
+ patch, affected paths and a review hash without creating Git objects or refs.
240
+ Creating a proposal requires the exact `orchestration_source_proposal` permission
241
+ and rechecks those inputs under the execution lease.
242
+
243
+ The writer creates one commit and one local branch under
244
+ `refs/heads/calliope-proposals/<run>/<review hash>` using a temporary private
245
+ index. It leaves the source checkout/index and execution journal unchanged.
246
+ Immutable intent and candidate records support retry after cancellation or a lost
247
+ response; repeated publication recovers the same branch instead of overwriting
248
+ it. Inspection reports `prepared` when the branch is absent and `proposed` when
249
+ the exact recorded commit is present. Absence alone does not establish whether
250
+ someone previously removed the branch. A moved branch is a conflict.
251
+ Listing retains original review identities across restart and source HEAD changes;
252
+ it reads the same native intent/candidate records and checks each branch.
253
+
254
+ This API does not install skills, merge, push, release or invoke a model. A host
255
+ must explicitly support the separate versioned source-change capability before
256
+ offering the action. Desktop integration and platform qualification are separate
257
+ from native API validation.
258
+
259
+ ## Ordinary task evidence
260
+
261
+ `taskOutcomeCapabilities()` and `inspectTaskOutcome(project, runId, selection,
262
+ options)` expose the same native evidence for an ordinary task outside an
263
+ improvement cycle. Select `{taskId, attempt, executionRevision}` from an inactive
264
+ run. The reader replays the journal at that attempt's start, retains its task,
265
+ agent and strategy configuration hash, and revalidates each artifact's bytes
266
+ under the native read policy. It refuses active ownership, stale selections and
267
+ changed or missing evidence. In particular, a historical live project file that
268
+ a later retry overwrote cannot be freshly verified; retained run artifacts allow
269
+ independent inspection of both attempts.
270
+
271
+ The returned `{value, hash}` separates executor status from native human task
272
+ acceptance, includes original event/check/artifact references, and attributes
273
+ charges to the exact start event using the reservation ledger. Missing or
274
+ unsettled costs remain `null`; reservations are not reported as settled cost.
275
+ Duration, tool calls and failures are recorded observations. An interrupted
276
+ attempt without a finish remains unknown. The accounting snapshot carries its
277
+ own ledger revision and may advance independently of the execution journal.
278
+
279
+ This read-only API performs no inference, artifact execution, ledger writes,
280
+ user assessment, feedback import or reward assignment. A host may separately
281
+ propose a human assessment for memory review; doing so does not change the
282
+ executor evidence. Ordinary-task UI and memory feedback require their own host
283
+ qualification.
284
+
285
+ ## Native validation
286
+
287
+ The [native Brain-loop receipt](docs/evidence/native-brain-loop-smoke.json) records a
288
+ Fable planner/controller and a Haiku worker on a public clamp fixture. All 12 paid
289
+ requests used the native provider after live discovery. Planning recovered from
290
+ one output cutoff within its original allowance. After exact-plan review, the
291
+ worker submitted a deliberately unchanged baseline, the real Docker check failed,
292
+ the controller replanned, and a one-line repair passed the same unchanged tests.
293
+ The live HUD showed both agents, attempts, controller rounds and remaining budgets.
294
+
295
+ Planner and worker Brain reads left its journal unchanged. A fresh process resumed
296
+ and replayed the completed run without model calls or execution/budget changes.
297
+ Explicit run ingestion then preserved both failed and passed checks as observations
298
+ and the improvement hypothesis as proposed knowledge. All artifact hashes were
299
+ verified, and the source checkout remained unchanged.
300
+
301
+ The probe retained $3.068752 of conservative reservations, including the cutoff,
302
+ within a $5 cap. This demonstrates one staged repair cycle; it does not establish
303
+ general coding reliability, causal improvement, or native nested decomposition.
304
+ Provider conformance and signing remain separate release gates.
@@ -0,0 +1,113 @@
1
+ # Read-only migration assessment
2
+
3
+ `calliope migration assess --repository /path/to/clone --request request.json --json`
4
+ produces a feasibility report, rulebook and work manifest from a pinned source
5
+ inventory and supplied pilot evidence. It does not run scripts, invoke Docker,
6
+ start workers, create a workflow, write project artifacts or propose brain changes.
7
+ Save the returned JSON through the project's authorized artifact owner when wanted.
8
+
9
+ `migration assessment-schema` returns the request/report JSON Schemas.
10
+ `migration review-assessment --request request.json` validates the request and
11
+ returns its digest without reading a repository. Schemas describe structure;
12
+ runtime validation also checks normalized paths, ownership and cross-references.
13
+ The assessment CLI exits 0 when it produced a report, including `investigate` or
14
+ `do-not-migrate`. Read `recommendation`; exit 0 is not a migration approval.
15
+
16
+ ## Request and inventory
17
+
18
+ The versioned request records:
19
+
20
+ - Source commit and authorized literal read paths, target adapter/stack/runtime.
21
+ - Port, redesign or incremental-upgrade intent, motivation, compatibility
22
+ obligations, deployment constraints and success criteria.
23
+ - USD budget in integer micros, duration limit and maximum concurrency.
24
+ - The rulebook's exact commit/path/blob, unique source/target unit ownership,
25
+ explicit source-file dependencies, risk and rationale, and reasoned exclusions.
26
+ - Up to 16 pilot plan/report pairs with separately evidenced implementation,
27
+ verification and review measurements. Measurements bind the exact report digest.
28
+
29
+ One request is bounded to 2 MiB, 128 units, 128 exclusions and 64 read prefixes.
30
+ All repository reads use the existing bounded committed inventory. The repository
31
+ is canonicalized before asynchronous work; moving a path alias cannot redirect
32
+ later reads. Evidence pins outside the selected read scope are reported without
33
+ reading them. Hosts must supply a scope already authorized for the user/task.
34
+
35
+ Every selected source file must be owned by a unit or explicitly excluded. Original
36
+ tests, build configuration, manifests and lockfiles remain listed in the rulebook.
37
+ The assessment identifies unsupported adapter/runtime/unit shapes, unavailable
38
+ sources, uncovered code, external dependencies, declared package cycles and unit
39
+ cycles. Unit dependencies must include declared local-package ordering. This is
40
+ declaration analysis, not an import parser or proof of dynamic dependency coverage.
41
+
42
+ The current adapter supports self-contained `.mjs` to `.mts` CLI ports on the pinned
43
+ Node 24 runtime. A redesign or incremental upgrade requires a different plan;
44
+ passing old CLI cases does not make it a structure-preserving port. Unsupported
45
+ scope yields `do-not-migrate` **for this plan and adapter**, not a general claim
46
+ that the selected technology or a migration is unsuitable.
47
+
48
+ ## Evidence and independent host review
49
+
50
+ Each pilot goes through [saved evidence review](migration-verification.md#review-saved-observations).
51
+ The assessment then checks every source, candidate, negative-control and rules pin
52
+ against actual committed blobs. Self-consistent JSON with invented Git pins is not
53
+ enough. Changed source, rules, runtime, cases or pilot accounting require a new
54
+ assessment and review. Missing or nonpassing baselines, known-failure checks or
55
+ candidate observations remain findings, regardless of a host's acceptance.
56
+
57
+ Library hosts call `assessMigration(repository, request, { signal, implementation, review })`.
58
+ `implementation` contains `kitSha256` and `verifierSha256`, supplied by the trusted
59
+ host from its installed kit artifact and the verifier that produced the pilot
60
+ evidence. These exact identities join the logical versions in the report, review
61
+ digest and unit bindings. Missing identities prevent `go`; request JSON cannot
62
+ supply them as authority. The host must check these hashes against its own
63
+ installation and evidence-producer records, not blindly copy a client's claims.
64
+ The optional `review` callback is trusted host code, never deserialized request
65
+ data. It receives the canonical repository, request, inventory digest, findings
66
+ and a digest binding that exact review context. The host must verify evidence
67
+ provenance, behavioral/compatibility coverage, risk classification, representative
68
+ pilot selection and measurement receipts through its owning records. It returns
69
+ `{ decision: 'accepted' | 'rejected', receipt: 'opaque-review-reference' }`.
70
+
71
+ Callbacks get a detached copy and cannot rewrite the assessment's inputs or
72
+ findings. A rejection, invalid receipt, unavailable review or absent host callback
73
+ prevents `go`. The standalone CLI deliberately has no flag that turns an authored
74
+ JSON report into independent review authority; it can still complete a read-only
75
+ assessment and return the work to investigate. A future native host adapter must
76
+ resolve review receipts through its existing authenticated owner.
77
+
78
+ `go` means the supported, pinned plan has no unresolved assessment findings and
79
+ its pilot evidence/coverage has been accepted by that host. It does not mean all
80
+ manifest units were migrated or verified. Every unit remains `planned`. Neither
81
+ the output digest nor an opaque review reference is portable authentication or
82
+ execution permission. A workflow owner must validate current bindings and its own
83
+ authority before dispatch; merely loading this report must never start work.
84
+
85
+ ## Measured ranges and work artifacts
86
+
87
+ Every populated risk group, including high-risk units, requires a passing pilot,
88
+ with representativeness checked by the host. The manifest shows coverage by risk
89
+ group; one passing example does not establish coverage of every unit. A measurement
90
+ records total pilot cost, work time (implementation plus verification), independent
91
+ review time and an accounting evidence ID. Zero billed cost is valid for an
92
+ evidenced local fixture; missing measurements are not represented as zero.
93
+
94
+ Only accepted, fully qualified evidence produces estimates. Cost bounds multiply
95
+ the observed pilot minimum/maximum by the exact manifest unit count. Lower time
96
+ uses concurrency and dependency depth, then serial review; upper time assumes
97
+ serial work and review. These are explicit extrapolation assumptions, not
98
+ statistical confidence intervals. Unmeasured deployment, external data migration
99
+ and operating costs are excluded. A lower bound over budget yields
100
+ `do-not-migrate`; an overlapping range yields `investigate`.
101
+
102
+ The manifest has stable source-path unit IDs, deterministic dependency ordering
103
+ or cycle components, exact source blobs, per-unit binding digests and pilot
104
+ references. Binding digests conservatively include the complete assessment inputs,
105
+ including source/config/rules, logical revisions and exact kit/verifier hashes. A changed plan
106
+ requires re-review; this version does not claim minimal per-unit invalidation or
107
+ resume reconciliation. Execution must honor the pinned worker package artifact.
108
+
109
+ The evidence storage plan names a project-relative directory, assessment/rulebook/
110
+ manifest files and per-unit pin, verification, accounting and review artifacts.
111
+ `written: false` makes its status explicit. Native Astrolift project/agent bindings,
112
+ artifact persistence, conversational setup, reviewed compatibility exceptions,
113
+ rule-update replay and resumable execution remain separate host integration work.
@@ -0,0 +1,88 @@
1
+ {
2
+ "format": "calliope.migration.verification-plan/v1",
3
+ "adapter": "javascript-to-typescript-cli/v1",
4
+ "verifier": "byte-parity-v1",
5
+ "runtime": {
6
+ "image": "sha256:55fb5f5a527ea2c5c4a95f963e48ef90aa38c7b346054fdc8ee9957a2b55d205",
7
+ "node": "v24.22.1"
8
+ },
9
+ "source": {
10
+ "revision": "54bdcbfa6e40806cd709736e448bd50c453799ea",
11
+ "path": "source.mjs",
12
+ "object": "b96c6972d5a4bfc7e1c52fea78ba340ff24b97c5"
13
+ },
14
+ "negative": {
15
+ "revision": "54bdcbfa6e40806cd709736e448bd50c453799ea",
16
+ "path": "negative.mts",
17
+ "object": "0d6091a5c5d47ed8b4c97b7f74f296853fcc09a0"
18
+ },
19
+ "rules": {
20
+ "revision": "54bdcbfa6e40806cd709736e448bd50c453799ea",
21
+ "path": "RULES.md",
22
+ "object": "ece25894441e04857adea069e792b6f622fb2e7b"
23
+ },
24
+ "cases": [
25
+ {
26
+ "id": "positive",
27
+ "argument": "[1,2,3]",
28
+ "expected": {
29
+ "exitCode": 0,
30
+ "stdout": "{\"sum\":6,\"count\":3}\n",
31
+ "stderr": ""
32
+ }
33
+ },
34
+ {
35
+ "id": "empty",
36
+ "argument": "[]",
37
+ "expected": {
38
+ "exitCode": 0,
39
+ "stdout": "{\"sum\":0,\"count\":0}\n",
40
+ "stderr": ""
41
+ }
42
+ },
43
+ {
44
+ "id": "negative-values",
45
+ "argument": "[-2,5]",
46
+ "expected": {
47
+ "exitCode": 0,
48
+ "stdout": "{\"sum\":3,\"count\":2}\n",
49
+ "stderr": ""
50
+ }
51
+ },
52
+ {
53
+ "id": "invalid-type",
54
+ "argument": "[\"1\"]",
55
+ "expected": {
56
+ "exitCode": 2,
57
+ "stdout": "",
58
+ "stderr": "Expected an array of safe integers.\n"
59
+ }
60
+ },
61
+ {
62
+ "id": "invalid-json",
63
+ "argument": "not-json",
64
+ "expected": {
65
+ "exitCode": 2,
66
+ "stdout": "",
67
+ "stderr": "Invalid JSON.\n"
68
+ }
69
+ }
70
+ ],
71
+ "negativeControl": {
72
+ "caseId": "positive",
73
+ "expected": {
74
+ "exitCode": 0,
75
+ "stdout": "{\"sum\":9,\"count\":3}\n",
76
+ "stderr": ""
77
+ }
78
+ },
79
+ "limits": {
80
+ "commandTimeoutMs": 10000,
81
+ "totalMs": 120000
82
+ },
83
+ "candidate": {
84
+ "revision": "f4732441c67d285f5005ac0afb25d412c2d74f93",
85
+ "path": "candidate.mts",
86
+ "object": "4b551e05cce761a68a30a20207c47add9a9f4eff"
87
+ }
88
+ }