@senpi-ai/runtime 1.1.3 → 3.0.4

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 (483) hide show
  1. package/README.md +10 -9
  2. package/dist/actions/action-runtime-module.d.ts.map +1 -1
  3. package/dist/actions/action-runtime-module.js +1 -1
  4. package/dist/actions/action-runtime-module.js.map +1 -1
  5. package/dist/actions/close-position/close-position.action.d.ts.map +1 -1
  6. package/dist/actions/close-position/close-position.action.js +61 -14
  7. package/dist/actions/close-position/close-position.action.js.map +1 -1
  8. package/dist/actions/decision-engine.d.ts.map +1 -1
  9. package/dist/actions/decision-engine.js +3 -0
  10. package/dist/actions/decision-engine.js.map +1 -1
  11. package/dist/actions/open-position/open-position.action.d.ts.map +1 -1
  12. package/dist/actions/open-position/open-position.action.js +155 -35
  13. package/dist/actions/open-position/open-position.action.js.map +1 -1
  14. package/dist/actions/open-position/resolve-margin.d.ts +18 -3
  15. package/dist/actions/open-position/resolve-margin.d.ts.map +1 -1
  16. package/dist/actions/open-position/resolve-margin.js +22 -9
  17. package/dist/actions/open-position/resolve-margin.js.map +1 -1
  18. package/dist/actions/position-tracker/position-tracker.action.d.ts +6 -0
  19. package/dist/actions/position-tracker/position-tracker.action.d.ts.map +1 -1
  20. package/dist/actions/position-tracker/position-tracker.action.js +48 -0
  21. package/dist/actions/position-tracker/position-tracker.action.js.map +1 -1
  22. package/dist/actions/tracking-helpers.d.ts +16 -1
  23. package/dist/actions/tracking-helpers.d.ts.map +1 -1
  24. package/dist/actions/tracking-helpers.js +55 -9
  25. package/dist/actions/tracking-helpers.js.map +1 -1
  26. package/dist/actions/types.d.ts +10 -2
  27. package/dist/actions/types.d.ts.map +1 -1
  28. package/dist/actions/types.js +8 -0
  29. package/dist/actions/types.js.map +1 -1
  30. package/dist/cli/guide-commands.d.ts.map +1 -1
  31. package/dist/cli/guide-commands.js +102 -82
  32. package/dist/cli/guide-commands.js.map +1 -1
  33. package/dist/cli/senpi-commands.d.ts.map +1 -1
  34. package/dist/cli/senpi-commands.js +16 -110
  35. package/dist/cli/senpi-commands.js.map +1 -1
  36. package/dist/constants/dsl/index.d.ts +2 -0
  37. package/dist/constants/dsl/index.d.ts.map +1 -1
  38. package/dist/constants/dsl/index.js +2 -0
  39. package/dist/constants/dsl/index.js.map +1 -1
  40. package/dist/dsl/config/parse-tiers.d.ts.map +1 -1
  41. package/dist/dsl/config/parse-tiers.js +6 -2
  42. package/dist/dsl/config/parse-tiers.js.map +1 -1
  43. package/dist/dsl/engine-client/config-mapping.d.ts +3 -1
  44. package/dist/dsl/engine-client/config-mapping.d.ts.map +1 -1
  45. package/dist/dsl/engine-client/config-mapping.js +3 -1
  46. package/dist/dsl/engine-client/config-mapping.js.map +1 -1
  47. package/dist/dsl/engine-client/event-mapping.d.ts +2 -0
  48. package/dist/dsl/engine-client/event-mapping.d.ts.map +1 -1
  49. package/dist/dsl/engine-client/event-mapping.js +3 -0
  50. package/dist/dsl/engine-client/event-mapping.js.map +1 -1
  51. package/dist/dsl/events/build-closed-event.d.ts.map +1 -1
  52. package/dist/dsl/events/build-closed-event.js +1 -0
  53. package/dist/dsl/events/build-closed-event.js.map +1 -1
  54. package/dist/dsl/events/guards.d.ts.map +1 -1
  55. package/dist/dsl/events/guards.js +10 -0
  56. package/dist/dsl/events/guards.js.map +1 -1
  57. package/dist/dsl/events/handlers.d.ts +18 -2
  58. package/dist/dsl/events/handlers.d.ts.map +1 -1
  59. package/dist/dsl/events/handlers.js +304 -208
  60. package/dist/dsl/events/handlers.js.map +1 -1
  61. package/dist/dsl/events/initial-state.d.ts.map +1 -1
  62. package/dist/dsl/events/initial-state.js +3 -1
  63. package/dist/dsl/events/initial-state.js.map +1 -1
  64. package/dist/dsl/monitor/create-monitor.d.ts +15 -0
  65. package/dist/dsl/monitor/create-monitor.d.ts.map +1 -1
  66. package/dist/dsl/monitor/create-monitor.js +76 -9
  67. package/dist/dsl/monitor/create-monitor.js.map +1 -1
  68. package/dist/dsl/monitor/process-one-position.d.ts.map +1 -1
  69. package/dist/dsl/monitor/process-one-position.js +268 -82
  70. package/dist/dsl/monitor/process-one-position.js.map +1 -1
  71. package/dist/dsl/plugin/index.d.ts +16 -1
  72. package/dist/dsl/plugin/index.d.ts.map +1 -1
  73. package/dist/dsl/plugin/index.js +35 -4
  74. package/dist/dsl/plugin/index.js.map +1 -1
  75. package/dist/dsl/plugin/options.d.ts +18 -0
  76. package/dist/dsl/plugin/options.d.ts.map +1 -1
  77. package/dist/index.d.ts +14 -1
  78. package/dist/index.d.ts.map +1 -1
  79. package/dist/index.js +276 -32
  80. package/dist/index.js.map +1 -1
  81. package/dist/recording/emitter.d.ts +27 -0
  82. package/dist/recording/emitter.d.ts.map +1 -0
  83. package/dist/recording/emitter.js +2 -0
  84. package/dist/recording/emitter.js.map +1 -0
  85. package/dist/recording/identity.d.ts +34 -0
  86. package/dist/recording/identity.d.ts.map +1 -0
  87. package/dist/recording/identity.js +2 -0
  88. package/dist/recording/identity.js.map +1 -0
  89. package/dist/recording/index.d.ts +11 -0
  90. package/dist/recording/index.d.ts.map +1 -0
  91. package/dist/recording/index.js +2 -0
  92. package/dist/recording/index.js.map +1 -0
  93. package/dist/recording/noop-emitter.d.ts +23 -0
  94. package/dist/recording/noop-emitter.d.ts.map +1 -0
  95. package/dist/recording/noop-emitter.js +22 -0
  96. package/dist/recording/noop-emitter.js.map +1 -0
  97. package/dist/recording/otel/attributes.d.ts +35 -0
  98. package/dist/recording/otel/attributes.d.ts.map +1 -0
  99. package/dist/recording/otel/attributes.js +131 -0
  100. package/dist/recording/otel/attributes.js.map +1 -0
  101. package/dist/recording/otel/constants.d.ts +123 -0
  102. package/dist/recording/otel/constants.d.ts.map +1 -0
  103. package/dist/recording/otel/constants.js +172 -0
  104. package/dist/recording/otel/constants.js.map +1 -0
  105. package/dist/recording/otel/ids.d.ts +25 -0
  106. package/dist/recording/otel/ids.d.ts.map +1 -0
  107. package/dist/recording/otel/ids.js +37 -0
  108. package/dist/recording/otel/ids.js.map +1 -0
  109. package/dist/recording/otel/index.d.ts +13 -0
  110. package/dist/recording/otel/index.d.ts.map +1 -0
  111. package/dist/recording/otel/index.js +9 -0
  112. package/dist/recording/otel/index.js.map +1 -0
  113. package/dist/recording/otel/mappers.d.ts +100 -0
  114. package/dist/recording/otel/mappers.d.ts.map +1 -0
  115. package/dist/recording/otel/mappers.js +683 -0
  116. package/dist/recording/otel/mappers.js.map +1 -0
  117. package/dist/recording/otel/otel-emitter.d.ts +43 -0
  118. package/dist/recording/otel/otel-emitter.d.ts.map +1 -0
  119. package/dist/recording/otel/otel-emitter.js +99 -0
  120. package/dist/recording/otel/otel-emitter.js.map +1 -0
  121. package/dist/recording/otel/redaction.d.ts +47 -0
  122. package/dist/recording/otel/redaction.d.ts.map +1 -0
  123. package/dist/recording/otel/redaction.js +88 -0
  124. package/dist/recording/otel/redaction.js.map +1 -0
  125. package/dist/recording/records.d.ts +565 -0
  126. package/dist/recording/records.d.ts.map +1 -0
  127. package/dist/recording/records.js +14 -0
  128. package/dist/recording/records.js.map +1 -0
  129. package/dist/recording/transport/batcher.d.ts +59 -0
  130. package/dist/recording/transport/batcher.d.ts.map +1 -0
  131. package/dist/recording/transport/batcher.js +234 -0
  132. package/dist/recording/transport/batcher.js.map +1 -0
  133. package/dist/recording/transport/client.d.ts +41 -0
  134. package/dist/recording/transport/client.d.ts.map +1 -0
  135. package/dist/recording/transport/client.js +69 -0
  136. package/dist/recording/transport/client.js.map +1 -0
  137. package/dist/recording/transport/config.d.ts +53 -0
  138. package/dist/recording/transport/config.d.ts.map +1 -0
  139. package/dist/recording/transport/config.js +41 -0
  140. package/dist/recording/transport/config.js.map +1 -0
  141. package/dist/recording/transport/index.d.ts +16 -0
  142. package/dist/recording/transport/index.d.ts.map +1 -0
  143. package/dist/recording/transport/index.js +12 -0
  144. package/dist/recording/transport/index.js.map +1 -0
  145. package/dist/recording/transport/rows.d.ts +88 -0
  146. package/dist/recording/transport/rows.d.ts.map +1 -0
  147. package/dist/recording/transport/rows.js +15 -0
  148. package/dist/recording/transport/rows.js.map +1 -0
  149. package/dist/recording/wiring/emitter-factory.d.ts +39 -0
  150. package/dist/recording/wiring/emitter-factory.d.ts.map +1 -0
  151. package/dist/recording/wiring/emitter-factory.js +62 -0
  152. package/dist/recording/wiring/emitter-factory.js.map +1 -0
  153. package/dist/recording/wiring/identity.d.ts +27 -0
  154. package/dist/recording/wiring/identity.d.ts.map +1 -0
  155. package/dist/recording/wiring/identity.js +51 -0
  156. package/dist/recording/wiring/identity.js.map +1 -0
  157. package/dist/recording/wiring/index.d.ts +12 -0
  158. package/dist/recording/wiring/index.d.ts.map +1 -0
  159. package/dist/recording/wiring/index.js +9 -0
  160. package/dist/recording/wiring/index.js.map +1 -0
  161. package/dist/recording/wiring/record-builders.d.ts +107 -0
  162. package/dist/recording/wiring/record-builders.d.ts.map +1 -0
  163. package/dist/recording/wiring/record-builders.js +706 -0
  164. package/dist/recording/wiring/record-builders.js.map +1 -0
  165. package/dist/recording/wiring/subscriber.d.ts +28 -0
  166. package/dist/recording/wiring/subscriber.d.ts.map +1 -0
  167. package/dist/recording/wiring/subscriber.js +173 -0
  168. package/dist/recording/wiring/subscriber.js.map +1 -0
  169. package/dist/recording/wiring/values.d.ts +19 -0
  170. package/dist/recording/wiring/values.d.ts.map +1 -0
  171. package/dist/recording/wiring/values.js +49 -0
  172. package/dist/recording/wiring/values.js.map +1 -0
  173. package/dist/runtime/auto-update/command-runner.d.ts.map +1 -1
  174. package/dist/runtime/auto-update/command-runner.js +5 -1
  175. package/dist/runtime/auto-update/command-runner.js.map +1 -1
  176. package/dist/runtime/auto-update/resolve-package-name.d.ts +10 -0
  177. package/dist/runtime/auto-update/resolve-package-name.d.ts.map +1 -0
  178. package/dist/runtime/auto-update/resolve-package-name.js +35 -0
  179. package/dist/runtime/auto-update/resolve-package-name.js.map +1 -0
  180. package/dist/runtime/auto-update/run-update-command.d.ts +2 -0
  181. package/dist/runtime/auto-update/run-update-command.d.ts.map +1 -0
  182. package/dist/runtime/auto-update/run-update-command.js +37 -0
  183. package/dist/runtime/auto-update/run-update-command.js.map +1 -0
  184. package/dist/runtime/create-runtime-context.d.ts +2 -0
  185. package/dist/runtime/create-runtime-context.d.ts.map +1 -1
  186. package/dist/runtime/create-runtime-context.js +1 -0
  187. package/dist/runtime/create-runtime-context.js.map +1 -1
  188. package/dist/runtime/create-scanner-module.d.ts +4 -3
  189. package/dist/runtime/create-scanner-module.d.ts.map +1 -1
  190. package/dist/runtime/create-scanner-module.js +14 -5
  191. package/dist/runtime/create-scanner-module.js.map +1 -1
  192. package/dist/runtime/create-scanner-providers-for-run.d.ts.map +1 -1
  193. package/dist/runtime/create-scanner-providers-for-run.js +12 -1
  194. package/dist/runtime/create-scanner-providers-for-run.js.map +1 -1
  195. package/dist/runtime/load-runtime-config.d.ts +9 -0
  196. package/dist/runtime/load-runtime-config.d.ts.map +1 -1
  197. package/dist/runtime/load-runtime-config.js +41 -8
  198. package/dist/runtime/load-runtime-config.js.map +1 -1
  199. package/dist/runtime/map-strategies-registration.js +7 -8
  200. package/dist/runtime/map-strategies-registration.js.map +1 -1
  201. package/dist/runtime/map-strategies.d.ts.map +1 -1
  202. package/dist/runtime/map-strategies.js +12 -3
  203. package/dist/runtime/map-strategies.js.map +1 -1
  204. package/dist/runtime/recipe-version.d.ts +1 -1
  205. package/dist/runtime/recipe-version.d.ts.map +1 -1
  206. package/dist/runtime/recipe-version.js +1 -1
  207. package/dist/runtime/recipe-version.js.map +1 -1
  208. package/dist/runtime/reconcile-decide.d.ts +73 -0
  209. package/dist/runtime/reconcile-decide.d.ts.map +1 -0
  210. package/dist/runtime/reconcile-decide.js +186 -0
  211. package/dist/runtime/reconcile-decide.js.map +1 -0
  212. package/dist/runtime/reconcile-run.d.ts +62 -0
  213. package/dist/runtime/reconcile-run.d.ts.map +1 -0
  214. package/dist/runtime/reconcile-run.js +173 -0
  215. package/dist/runtime/reconcile-run.js.map +1 -0
  216. package/dist/runtime/reconcile-state.d.ts +44 -0
  217. package/dist/runtime/reconcile-state.d.ts.map +1 -1
  218. package/dist/runtime/reconcile-state.js +80 -44
  219. package/dist/runtime/reconcile-state.js.map +1 -1
  220. package/dist/runtime/risk-guard.d.ts.map +1 -1
  221. package/dist/runtime/risk-guard.js +17 -12
  222. package/dist/runtime/risk-guard.js.map +1 -1
  223. package/dist/runtime/run.d.ts.map +1 -1
  224. package/dist/runtime/run.js +3 -2
  225. package/dist/runtime/run.js.map +1 -1
  226. package/dist/runtime/runtime-schema.d.ts +4056 -793
  227. package/dist/runtime/runtime-schema.d.ts.map +1 -1
  228. package/dist/runtime/runtime-schema.js +183 -46
  229. package/dist/runtime/runtime-schema.js.map +1 -1
  230. package/dist/runtime/runtime-version.d.ts +3 -6
  231. package/dist/runtime/runtime-version.d.ts.map +1 -1
  232. package/dist/runtime/runtime-version.js +3 -6
  233. package/dist/runtime/runtime-version.js.map +1 -1
  234. package/dist/runtime/runtime.d.ts +47 -0
  235. package/dist/runtime/runtime.d.ts.map +1 -1
  236. package/dist/runtime/runtime.js +516 -146
  237. package/dist/runtime/runtime.js.map +1 -1
  238. package/dist/runtime/scanner-registry.d.ts +1 -1
  239. package/dist/runtime/scanner-registry.d.ts.map +1 -1
  240. package/dist/runtime/scanner-registry.js +3 -12
  241. package/dist/runtime/scanner-registry.js.map +1 -1
  242. package/dist/runtime/strategy-registry.d.ts +6 -0
  243. package/dist/runtime/strategy-registry.d.ts.map +1 -1
  244. package/dist/runtime/strategy-registry.js +1 -0
  245. package/dist/runtime/strategy-registry.js.map +1 -1
  246. package/dist/runtime/supervisor/long-running-supervisor.d.ts +222 -0
  247. package/dist/runtime/supervisor/long-running-supervisor.d.ts.map +1 -0
  248. package/dist/runtime/supervisor/long-running-supervisor.js +625 -0
  249. package/dist/runtime/supervisor/long-running-supervisor.js.map +1 -0
  250. package/dist/runtime/supervisor/orphan-sweep.d.ts +36 -0
  251. package/dist/runtime/supervisor/orphan-sweep.d.ts.map +1 -0
  252. package/dist/runtime/supervisor/orphan-sweep.js +255 -0
  253. package/dist/runtime/supervisor/orphan-sweep.js.map +1 -0
  254. package/dist/runtime/supervisor/supervisor-utils.d.ts +37 -0
  255. package/dist/runtime/supervisor/supervisor-utils.d.ts.map +1 -0
  256. package/dist/runtime/supervisor/supervisor-utils.js +175 -0
  257. package/dist/runtime/supervisor/supervisor-utils.js.map +1 -0
  258. package/dist/runtime-api/handlers/ingest-signals.d.ts +3 -3
  259. package/dist/runtime-api/handlers/ingest-signals.js +3 -3
  260. package/dist/runtime-api/intake/acceptance-record.d.ts +103 -0
  261. package/dist/runtime-api/intake/acceptance-record.d.ts.map +1 -0
  262. package/dist/runtime-api/intake/acceptance-record.js +192 -0
  263. package/dist/runtime-api/intake/acceptance-record.js.map +1 -0
  264. package/dist/runtime-api/intake/intake-context.d.ts +31 -0
  265. package/dist/runtime-api/intake/intake-context.d.ts.map +1 -0
  266. package/dist/runtime-api/intake/intake-context.js +21 -0
  267. package/dist/runtime-api/intake/intake-context.js.map +1 -0
  268. package/dist/runtime-api/intake/intake-mount.d.ts +118 -0
  269. package/dist/runtime-api/intake/intake-mount.d.ts.map +1 -0
  270. package/dist/runtime-api/intake/intake-mount.js +202 -0
  271. package/dist/runtime-api/intake/intake-mount.js.map +1 -0
  272. package/dist/runtime-api/intake/liveness-store.d.ts +32 -0
  273. package/dist/runtime-api/intake/liveness-store.d.ts.map +1 -0
  274. package/dist/runtime-api/intake/liveness-store.js +31 -0
  275. package/dist/runtime-api/intake/liveness-store.js.map +1 -0
  276. package/dist/runtime-api/intake/process-error-post.d.ts +15 -0
  277. package/dist/runtime-api/intake/process-error-post.d.ts.map +1 -0
  278. package/dist/runtime-api/intake/process-error-post.js +19 -0
  279. package/dist/runtime-api/intake/process-error-post.js.map +1 -0
  280. package/dist/runtime-api/intake/process-signal-post.d.ts +73 -0
  281. package/dist/runtime-api/intake/process-signal-post.d.ts.map +1 -0
  282. package/dist/runtime-api/intake/process-signal-post.js +188 -0
  283. package/dist/runtime-api/intake/process-signal-post.js.map +1 -0
  284. package/dist/runtime-api/intake/scanner-launcher.d.ts +133 -0
  285. package/dist/runtime-api/intake/scanner-launcher.d.ts.map +1 -0
  286. package/dist/runtime-api/intake/scanner-launcher.js +204 -0
  287. package/dist/runtime-api/intake/scanner-launcher.js.map +1 -0
  288. package/dist/runtime-api/intake/scanner-registry.d.ts +36 -0
  289. package/dist/runtime-api/intake/scanner-registry.d.ts.map +1 -0
  290. package/dist/runtime-api/intake/scanner-registry.js +29 -0
  291. package/dist/runtime-api/intake/scanner-registry.js.map +1 -0
  292. package/dist/runtime-api/intake/types.d.ts +60 -0
  293. package/dist/runtime-api/intake/types.d.ts.map +1 -0
  294. package/dist/runtime-api/intake/types.js +8 -0
  295. package/dist/runtime-api/intake/types.js.map +1 -0
  296. package/dist/runtime-api/routes/signals.d.ts +20 -40
  297. package/dist/runtime-api/routes/signals.d.ts.map +1 -1
  298. package/dist/runtime-api/routes/signals.js +120 -75
  299. package/dist/runtime-api/routes/signals.js.map +1 -1
  300. package/dist/runtime-api/routes/signals.schema.d.ts +23 -86
  301. package/dist/runtime-api/routes/signals.schema.d.ts.map +1 -1
  302. package/dist/runtime-api/routes/signals.schema.js +37 -50
  303. package/dist/runtime-api/routes/signals.schema.js.map +1 -1
  304. package/dist/runtime-api/server.d.ts +15 -6
  305. package/dist/runtime-api/server.d.ts.map +1 -1
  306. package/dist/runtime-api/server.js +12 -12
  307. package/dist/runtime-api/server.js.map +1 -1
  308. package/dist/scanners/events.d.ts +6 -0
  309. package/dist/scanners/events.d.ts.map +1 -1
  310. package/dist/scanners/events.js.map +1 -1
  311. package/dist/scanners/external/scaffold/__init__.py +16 -0
  312. package/dist/scanners/external/scaffold/__main__.py +155 -0
  313. package/dist/scanners/external/scaffold/ctx.py +78 -0
  314. package/dist/scanners/external/scaffold/delivery.py +282 -0
  315. package/dist/scanners/external/scaffold/entrypoint_loader.py +151 -0
  316. package/dist/scanners/external/scaffold/http_post.py +70 -0
  317. package/dist/scanners/external/scaffold/journal.py +247 -0
  318. package/dist/scanners/external/scaffold/loop_primitives.py +65 -0
  319. package/dist/scanners/external/scaffold/requirements.txt +11 -0
  320. package/dist/scanners/external/scaffold/scaffold.py +361 -0
  321. package/dist/scanners/external/scaffold/scaffold_state.py +114 -0
  322. package/dist/scanners/external/scaffold/senpi_mcp.py +250 -0
  323. package/dist/scanners/external/scaffold/signal_envelope.py +258 -0
  324. package/dist/scanners/external/scaffold/state_manager.py +175 -0
  325. package/dist/scanners/external-scanner-receiver.d.ts +23 -1
  326. package/dist/scanners/external-scanner-receiver.d.ts.map +1 -1
  327. package/dist/scanners/external-scanner-receiver.js +24 -3
  328. package/dist/scanners/external-scanner-receiver.js.map +1 -1
  329. package/dist/scanners/implementations/external-scanner.d.ts.map +1 -1
  330. package/dist/scanners/implementations/external-scanner.js +7 -1
  331. package/dist/scanners/implementations/external-scanner.js.map +1 -1
  332. package/dist/scanners/implementations/momentum.d.ts.map +1 -1
  333. package/dist/scanners/implementations/momentum.js +16 -0
  334. package/dist/scanners/implementations/momentum.js.map +1 -1
  335. package/dist/scanners/providers/factory.d.ts.map +1 -1
  336. package/dist/scanners/providers/factory.js +17 -19
  337. package/dist/scanners/providers/factory.js.map +1 -1
  338. package/dist/scanners/runtime-module.d.ts.map +1 -1
  339. package/dist/scanners/runtime-module.js +9 -1
  340. package/dist/scanners/runtime-module.js.map +1 -1
  341. package/dist/scripts/run-dsl-standalone-live.d.ts +1 -1
  342. package/dist/scripts/run-dsl-standalone-live.js +5 -3
  343. package/dist/scripts/run-dsl-standalone-live.js.map +1 -1
  344. package/dist/senpi/client.d.ts +56 -4
  345. package/dist/senpi/client.d.ts.map +1 -1
  346. package/dist/senpi/client.js +123 -24
  347. package/dist/senpi/client.js.map +1 -1
  348. package/dist/senpi/index.d.ts +2 -1
  349. package/dist/senpi/index.d.ts.map +1 -1
  350. package/dist/senpi/index.js +1 -1
  351. package/dist/senpi/index.js.map +1 -1
  352. package/dist/senpi/types.d.ts +1 -2
  353. package/dist/senpi/types.d.ts.map +1 -1
  354. package/dist/state/state-manager.d.ts +17 -0
  355. package/dist/state/state-manager.d.ts.map +1 -1
  356. package/dist/state/state-manager.js +55 -4
  357. package/dist/state/state-manager.js.map +1 -1
  358. package/dist/strategy/strategy-state.d.ts +9 -1
  359. package/dist/strategy/strategy-state.d.ts.map +1 -1
  360. package/dist/strategy/strategy-state.js +78 -28
  361. package/dist/strategy/strategy-state.js.map +1 -1
  362. package/dist/tracking/build-rehydrate-items.d.ts +15 -0
  363. package/dist/tracking/build-rehydrate-items.d.ts.map +1 -0
  364. package/dist/tracking/build-rehydrate-items.js +19 -0
  365. package/dist/tracking/build-rehydrate-items.js.map +1 -0
  366. package/dist/tracking/constants.d.ts.map +1 -1
  367. package/dist/tracking/constants.js +2 -0
  368. package/dist/tracking/constants.js.map +1 -1
  369. package/dist/tracking/index.d.ts +3 -0
  370. package/dist/tracking/index.d.ts.map +1 -1
  371. package/dist/tracking/index.js +2 -0
  372. package/dist/tracking/index.js.map +1 -1
  373. package/dist/tracking/position-id-registry.d.ts +69 -0
  374. package/dist/tracking/position-id-registry.d.ts.map +1 -0
  375. package/dist/tracking/position-id-registry.js +139 -0
  376. package/dist/tracking/position-id-registry.js.map +1 -0
  377. package/dist/tracking/spans/fan-out-span-transport.d.ts +22 -0
  378. package/dist/tracking/spans/fan-out-span-transport.d.ts.map +1 -0
  379. package/dist/tracking/spans/fan-out-span-transport.js +49 -0
  380. package/dist/tracking/spans/fan-out-span-transport.js.map +1 -0
  381. package/dist/tracking/spans/otel/fit-row-budget.d.ts +22 -0
  382. package/dist/tracking/spans/otel/fit-row-budget.d.ts.map +1 -0
  383. package/dist/tracking/spans/otel/fit-row-budget.js +91 -0
  384. package/dist/tracking/spans/otel/fit-row-budget.js.map +1 -0
  385. package/dist/tracking/spans/otel/map-span-to-trace-row.d.ts +16 -0
  386. package/dist/tracking/spans/otel/map-span-to-trace-row.d.ts.map +1 -0
  387. package/dist/tracking/spans/otel/map-span-to-trace-row.js +227 -0
  388. package/dist/tracking/spans/otel/map-span-to-trace-row.js.map +1 -0
  389. package/dist/tracking/spans/otel/recording-span-transport.d.ts +43 -0
  390. package/dist/tracking/spans/otel/recording-span-transport.d.ts.map +1 -0
  391. package/dist/tracking/spans/otel/recording-span-transport.js +67 -0
  392. package/dist/tracking/spans/otel/recording-span-transport.js.map +1 -0
  393. package/dist/tracking/spans/otel/span-ids.d.ts +22 -0
  394. package/dist/tracking/spans/otel/span-ids.d.ts.map +1 -0
  395. package/dist/tracking/spans/otel/span-ids.js +32 -0
  396. package/dist/tracking/spans/otel/span-ids.js.map +1 -0
  397. package/dist/tracking/spans/plugin-span-tracker.d.ts +6 -0
  398. package/dist/tracking/spans/plugin-span-tracker.d.ts.map +1 -1
  399. package/dist/tracking/spans/plugin-span-tracker.js +82 -9
  400. package/dist/tracking/spans/plugin-span-tracker.js.map +1 -1
  401. package/dist/tracking/spans/redact-pii.d.ts +3 -1
  402. package/dist/tracking/spans/redact-pii.d.ts.map +1 -1
  403. package/dist/tracking/spans/redact-pii.js +5 -1
  404. package/dist/tracking/spans/redact-pii.js.map +1 -1
  405. package/dist/tracking/spans/span-transport.d.ts +6 -0
  406. package/dist/tracking/spans/span-transport.d.ts.map +1 -1
  407. package/dist/tracking/spans/span-transport.js +1 -1
  408. package/dist/tracking/spans/span-transport.js.map +1 -1
  409. package/dist/types/dsl/index.d.ts +24 -1
  410. package/dist/types/dsl/index.d.ts.map +1 -1
  411. package/dist/types/runtime.d.ts +6 -0
  412. package/dist/types/runtime.d.ts.map +1 -1
  413. package/dist/types/scanner.d.ts +16 -0
  414. package/dist/types/scanner.d.ts.map +1 -1
  415. package/dist/types/strategy.d.ts +3 -1
  416. package/dist/types/strategy.d.ts.map +1 -1
  417. package/dist/utils/clearing-house-aggregate.d.ts +32 -0
  418. package/dist/utils/clearing-house-aggregate.d.ts.map +1 -0
  419. package/dist/utils/clearing-house-aggregate.js +41 -0
  420. package/dist/utils/clearing-house-aggregate.js.map +1 -0
  421. package/dist/utils/keyed-mutex.d.ts +37 -0
  422. package/dist/utils/keyed-mutex.d.ts.map +1 -0
  423. package/dist/utils/keyed-mutex.js +77 -0
  424. package/dist/utils/keyed-mutex.js.map +1 -0
  425. package/dist/utils/safe-spawn.d.ts +6 -0
  426. package/dist/utils/safe-spawn.d.ts.map +1 -0
  427. package/dist/utils/safe-spawn.js +62 -0
  428. package/dist/utils/safe-spawn.js.map +1 -0
  429. package/examples/strategies/README.md +17 -12
  430. package/examples/strategies/iguana/README.md +135 -0
  431. package/examples/strategies/iguana/recipe.yaml +137 -0
  432. package/examples/strategies/iguana/scanners/scan.py +242 -0
  433. package/examples/strategies/iguana/scanners/scoring.py +152 -0
  434. package/examples/strategies/raptor/README.md +156 -0
  435. package/examples/strategies/raptor/recipe.yaml +154 -0
  436. package/examples/strategies/raptor/scanners/scan.py +348 -0
  437. package/examples/strategies/raptor/scanners/scoring.py +452 -0
  438. package/examples/strategies/spider/README.md +89 -0
  439. package/examples/strategies/spider/scalp/recipe.yaml +129 -0
  440. package/examples/strategies/spider/scalp/scanners/scan.py +219 -0
  441. package/examples/strategies/spider/scalp/scanners/scoring.py +179 -0
  442. package/examples/strategies/spider/swing/recipe.yaml +137 -0
  443. package/examples/strategies/spider/swing/scanners/scan.py +334 -0
  444. package/examples/strategies/spider/swing/scanners/scoring.py +184 -0
  445. package/examples/strategies/turbine/README.md +169 -0
  446. package/examples/strategies/turbine/recipe-runners.yaml +123 -0
  447. package/examples/strategies/turbine/recipe-volume.yaml +129 -0
  448. package/examples/strategies/turbine/scanners/scan.py +287 -0
  449. package/examples/strategies/turbine/scanners/scoring.py +190 -0
  450. package/openclaw.plugin.json +12 -1
  451. package/package.json +3 -3
  452. package/dist/runtime-api/handlers/group-by-scanner.d.ts +0 -43
  453. package/dist/runtime-api/handlers/group-by-scanner.d.ts.map +0 -1
  454. package/dist/runtime-api/handlers/group-by-scanner.js +0 -43
  455. package/dist/runtime-api/handlers/group-by-scanner.js.map +0 -1
  456. package/dist/scanners/external/liquidation-watchdog/README.md +0 -107
  457. package/dist/scanners/external/liquidation-watchdog/liquidation-watchdog.yaml +0 -48
  458. package/dist/scanners/external/liquidation-watchdog/producer.mjs +0 -336
  459. package/dist/scanners/external/momentum/README.md +0 -148
  460. package/dist/scanners/external/momentum/momentum.yaml +0 -116
  461. package/dist/scanners/external/momentum/producer.mjs +0 -251
  462. package/dist/scanners/external/shared/ingest.mjs +0 -112
  463. package/examples/README.md +0 -89
  464. package/examples/scanners-consumer-quickstart.mjs +0 -134
  465. package/examples/scanners-emerging-movers-v4.mjs +0 -287
  466. package/examples/scanners-liquidation-watchdog.mjs +0 -341
  467. package/examples/scanners-live-mcp.mjs +0 -208
  468. package/examples/scanners-multi-strategy.mjs +0 -165
  469. package/examples/scanners-position-tracker-e2e.mjs +0 -225
  470. package/examples/scanners-scheduled-events.mjs +0 -96
  471. package/examples/scanners-senpi-provider-client.mjs +0 -182
  472. package/examples/scanners-single-strategy.mjs +0 -198
  473. package/examples/strategies/dsl-showcase.yaml +0 -68
  474. package/examples/strategies/dsl.yaml +0 -51
  475. package/examples/strategies/fox-minimal-loosened.yaml +0 -240
  476. package/examples/strategies/fox-minimal.yaml +0 -242
  477. package/examples/strategies/minimal.yaml +0 -46
  478. package/examples/strategies/momentum/how-it-works.md +0 -48
  479. package/examples/strategies/momentum/momentum-guarded.yaml +0 -161
  480. package/examples/strategies/risk-showcase.yaml +0 -93
  481. package/examples/strategies/viper.yaml +0 -67
  482. package/examples/strategies/wolf.yaml +0 -72
  483. package/examples/yamls/sample-with-dsl-and-emerging-movers.yaml +0 -123
@@ -0,0 +1,361 @@
1
+ """Scaffold core loop (v2).
2
+
3
+ run_scaffold(...) loads the author's entrypoint, finds and validates scan(),
4
+ builds the ScanContext, then drives the interval loop: time-box per tick, graceful
5
+ stop on SIGTERM/SIGINT, parent-death detection via ppid, transactional state via
6
+ ctx.state, candidates to sink.
7
+
8
+ `path` is a scaffold concern only — it is put on sys.path before import and never
9
+ passed to scan(). scan() is called as scan(inputs, ctx) — 2-arg, sync, returning a
10
+ plain list[dict]. State mutates ONLY via ctx.state (commit on a clean tick, rollback
11
+ on error/timeout/malformed/failed-persist — transactional discard wins on failure).
12
+ """
13
+
14
+ import inspect
15
+ import os
16
+ import time
17
+ import threading
18
+ from typing import Any, Callable, Optional
19
+
20
+ from .ctx import ScanContext
21
+ from .entrypoint_loader import (
22
+ ScanEntrypointError,
23
+ ScanSignatureError,
24
+ import_entrypoint,
25
+ locate_scan,
26
+ verify_scan_signature,
27
+ )
28
+ from .loop_primitives import (
29
+ _TickTimeout,
30
+ _arm_tick_alarm,
31
+ _disarm_tick_alarm,
32
+ _install_shutdown_handlers,
33
+ _interruptible_sleep,
34
+ log_event,
35
+ )
36
+ from .state_manager import StateManager
37
+
38
+
39
+ def _build_senpi_mcp() -> Any:
40
+ """Construct the MCP client when creds are present; else return None.
41
+
42
+ Creds come from the launch env (SENPI_API_KEY / SENPI_MCP_URL), injected by
43
+ the launcher regardless of how the operator supplied them. With neither set,
44
+ return None so the no-creds path does not crash — the client is loud at FIRST
45
+ USE (see scaffold.senpi_mcp). Reference the class through the module attribute
46
+ so a test stub patched onto scaffold.senpi_mcp is honored.
47
+ """
48
+ api_key = os.environ.get("SENPI_API_KEY") or None
49
+ mcp_url = os.environ.get("SENPI_MCP_URL") or None
50
+ if not api_key and not mcp_url:
51
+ return None
52
+
53
+ from . import senpi_mcp as senpi_mcp_mod
54
+
55
+ # Read-only-by-default producer MCP boundary: the set of MUTATION tools
56
+ # producers are permitted to call is owned SOLELY by the scaffold-source
57
+ # PRODUCER_WRITE_ALLOWLIST constant (EMPTY by default → all mutations
58
+ # blocked). It is edited by the scaffold maintainer in senpi_mcp.py — it is
59
+ # NOT operator/env-configurable and NOT reachable by authored producer code.
60
+ return senpi_mcp_mod.SenpiMcpClient(
61
+ api_key=api_key,
62
+ mcp_url=mcp_url,
63
+ write_allowlist=senpi_mcp_mod.PRODUCER_WRITE_ALLOWLIST,
64
+ )
65
+
66
+
67
+ def _call_scan(scan: Callable, inputs: dict, ctx: Any):
68
+ """Call scan(inputs, ctx) — the v2 2-arg contract.
69
+
70
+ There is no `client` and no 3-arg path. scan returns a plain list[dict];
71
+ validation of that return happens in the tick loop.
72
+ """
73
+ return scan(inputs, ctx)
74
+
75
+
76
+ def run_scaffold(
77
+ path: str,
78
+ entrypoint: str,
79
+ *,
80
+ interval: float,
81
+ timeout_seconds: Optional[float] = None,
82
+ inputs: Optional[dict] = None,
83
+ state_path: Optional[str] = None,
84
+ scanner_name: str,
85
+ wallet: str,
86
+ default_signal_validity_seconds: int,
87
+ state_history_max_count: int = 0,
88
+ sink: Optional[Callable] = None,
89
+ max_ticks: Optional[int] = None,
90
+ install_signal_handlers: bool = True,
91
+ ) -> int:
92
+ """Load the author's entrypoint and run its scan() on an interval loop (v2).
93
+
94
+ Args:
95
+ path: Directory added to sys.path before import. Never passed to scan().
96
+ entrypoint: Module name to import from `path`.
97
+ interval: Seconds between tick starts. Must be > 0.
98
+ timeout_seconds:
99
+ Per-tick wall-clock budget. Defaults to `interval`. Must be > 0.
100
+ Enforced via SIGALRM on platforms that support it.
101
+ inputs: Tunables dict passed as scan()'s first argument. Default {}.
102
+ state_path: Path to the JSON state file. None means no persistence.
103
+ scanner_name: This scanner's recipe name (read-only ctx metadata).
104
+ wallet: Strategy wallet (read-only ctx metadata).
105
+ default_signal_validity_seconds:
106
+ Fallback signal TTL (seconds); threaded to the envelope path.
107
+ state_history_max_count:
108
+ Bound on the persisted state series. 0/unset = history disabled
109
+ (ctx.state.append raises).
110
+ sink: Callable(candidates) invoked after each clean tick. Default no-op.
111
+ max_ticks: Stop after this many ticks (for tests). None = unbounded.
112
+ install_signal_handlers:
113
+ Install SIGTERM/SIGINT graceful-stop handlers. False for tests.
114
+
115
+ Returns:
116
+ Total ticks attempted.
117
+
118
+ Raises:
119
+ ValueError: interval <= 0 or timeout_seconds <= 0.
120
+ ScanEntrypointError: import failure, scan missing or not callable.
121
+ ScanSignatureError: scan call-shape incompatible with scaffold contract.
122
+ """
123
+ # ---------- Launch validation (raises before any tick) ----------
124
+
125
+ if interval <= 0:
126
+ raise ValueError(f"interval must be > 0; got {interval!r}")
127
+
128
+ if timeout_seconds is None:
129
+ timeout_seconds = interval
130
+ if timeout_seconds <= 0:
131
+ raise ValueError(f"timeout_seconds must be > 0; got {timeout_seconds!r}")
132
+
133
+ if inputs is None:
134
+ inputs = {}
135
+
136
+ # Import and locate scan — any failure raises before tick 1.
137
+ module = import_entrypoint(path, entrypoint)
138
+ scan = locate_scan(module)
139
+ verify_scan_signature(scan)
140
+
141
+ # ---------- ctx + state setup ----------
142
+
143
+ # The StateManager (B2) is the persisted series. It reads any prior state from
144
+ # disk on construction. state_history_max_count 0/unset => history disabled
145
+ # (append raises). It is passed into ctx AS-IS (never wrapped).
146
+ state = StateManager(state_path, state_history_max_count) if state_path is not None \
147
+ else StateManager(None, state_history_max_count)
148
+
149
+ # ctx.interval_seconds is the integer-seconds cadence (design §2.1). The loop's
150
+ # `interval` may be a sub-second float in tests; expose the int seconds when it
151
+ # is whole, else the float as-is.
152
+ interval_seconds = int(interval) if float(interval).is_integer() else interval
153
+
154
+ # B5: fill ctx.senpi_mcp when MCP creds are present (resolved at launch from
155
+ # SENPI_API_KEY / SENPI_MCP_URL). With no creds the slot stays None and launch
156
+ # must NOT crash — the client is loud at FIRST USE, not at construction. Import
157
+ # is deferred so a stub patched onto scaffold.senpi_mcp in tests is honored.
158
+ senpi_mcp = _build_senpi_mcp()
159
+
160
+ ctx = ScanContext(
161
+ state=state,
162
+ wallet=wallet,
163
+ scanner_name=scanner_name,
164
+ interval_seconds=interval_seconds,
165
+ senpi_mcp=senpi_mcp,
166
+ )
167
+
168
+ # ---------- Lifecycle setup ----------
169
+
170
+ stop_event = threading.Event()
171
+ if install_signal_handlers:
172
+ _install_shutdown_handlers(stop_event)
173
+
174
+ start_ppid = os.getppid()
175
+
176
+ log_event(
177
+ "scaffold_started",
178
+ path=path,
179
+ entrypoint=entrypoint,
180
+ interval=interval,
181
+ timeout_seconds=timeout_seconds,
182
+ scanner_name=scanner_name,
183
+ max_ticks=max_ticks,
184
+ )
185
+
186
+ tick_count = 0
187
+
188
+ try:
189
+ while not stop_event.is_set():
190
+ # --- Parent-death check (before tick) ---
191
+ current_ppid = os.getppid()
192
+ if current_ppid != start_ppid or current_ppid == 1:
193
+ log_event("scaffold_parent_gone", start_ppid=start_ppid, current_ppid=current_ppid)
194
+ break
195
+
196
+ tick_count += 1
197
+ tick_started_at = time.time()
198
+ tick_status = "ok"
199
+ tick_error = None
200
+ candidates: list = []
201
+
202
+ armed = False
203
+ try:
204
+ armed = _arm_tick_alarm(timeout_seconds)
205
+ try:
206
+ result = _call_scan(scan, inputs, ctx)
207
+
208
+ # v2 return contract: a PLAIN list[dict]. Anything else is
209
+ # malformed (a tuple — the old v1 shape — included).
210
+ if not isinstance(result, list):
211
+ tick_status = "malformed"
212
+ log_event(
213
+ "scaffold_tick_malformed",
214
+ tick=tick_count,
215
+ reason=(
216
+ f"scan() returned {type(result).__name__!r}; expected a "
217
+ f"plain list[dict] (the v1 (candidates, state) tuple is gone)"
218
+ ),
219
+ )
220
+ else:
221
+ candidates = result
222
+
223
+ except _TickTimeout as exc:
224
+ tick_status = "timeout"
225
+ candidates = []
226
+ tick_error = {"type": "timeout", "message": str(exc)}
227
+ log_event(
228
+ "scaffold_tick_timeout",
229
+ tick=tick_count,
230
+ reason=str(exc),
231
+ )
232
+ except Exception as exc: # noqa: BLE001 — author bug must not crash scaffold
233
+ tick_status = "error"
234
+ candidates = []
235
+ tick_error = {
236
+ "type": "error",
237
+ "error_type": type(exc).__name__,
238
+ "message": str(exc),
239
+ }
240
+ log_event(
241
+ "scaffold_tick_error",
242
+ tick=tick_count,
243
+ error_type=type(exc).__name__,
244
+ error=str(exc),
245
+ )
246
+ finally:
247
+ if armed:
248
+ _disarm_tick_alarm()
249
+
250
+ duration_ms = int((time.time() - tick_started_at) * 1000)
251
+
252
+ # --- Clean tick: commit ctx.state, deliver candidates ---
253
+ if tick_status == "ok":
254
+ # Transactional commit. A failed persist RAISES (StateManager
255
+ # enforces it) and does NOT advance the committed snapshot — so
256
+ # the next tick recomputes from the un-advanced state. On a
257
+ # commit failure we roll back and treat the tick as failed
258
+ # (discard wins on failed-persist; no advance-on-persist-failure).
259
+ committed = True
260
+ try:
261
+ ctx.state.commit()
262
+ except Exception as commit_exc: # noqa: BLE001
263
+ committed = False
264
+ ctx.state.rollback()
265
+ log_event(
266
+ "scaffold_state_persist_failed",
267
+ tick=tick_count,
268
+ error_type=type(commit_exc).__name__,
269
+ error=str(commit_exc),
270
+ )
271
+ if sink is not None and hasattr(sink, "post_error"):
272
+ _post_error_safe(
273
+ sink,
274
+ {
275
+ "type": "state_persist_failed",
276
+ "tick": tick_count,
277
+ "message": (
278
+ "scanner state could not be persisted; "
279
+ "tick discarded, state not advanced"
280
+ ),
281
+ },
282
+ tick_count,
283
+ )
284
+
285
+ if committed and sink is not None:
286
+ try:
287
+ sink(candidates)
288
+ except Exception as sink_exc: # noqa: BLE001
289
+ log_event(
290
+ "scaffold_sink_error",
291
+ tick=tick_count,
292
+ error_type=type(sink_exc).__name__,
293
+ error=str(sink_exc),
294
+ )
295
+ else:
296
+ # Non-ok tick (error / timeout / malformed): roll back the
297
+ # working buffer (discard the tick's mutations — state not
298
+ # advanced) and report to /errors via the sink, when supported.
299
+ ctx.state.rollback()
300
+ if sink is not None and hasattr(sink, "post_error"):
301
+ _post_error_safe(
302
+ sink, tick_error or {"type": tick_status}, tick_count
303
+ )
304
+
305
+ log_event(
306
+ "scaffold_tick_finished",
307
+ tick=tick_count,
308
+ status=tick_status,
309
+ duration_ms=duration_ms,
310
+ candidate_count=len(candidates),
311
+ )
312
+
313
+ except _TickTimeout as late_exc:
314
+ # A SIGALRM queued by the OS, delivered after the inner try/except
315
+ # exited (e.g. during commit, sink, or log_event). Absorb it: the
316
+ # tick already did its work; disarm, roll back any uncommitted
317
+ # mutations, log the late arrival, and let the loop continue.
318
+ _disarm_tick_alarm()
319
+ try:
320
+ ctx.state.rollback()
321
+ except Exception: # noqa: BLE001
322
+ pass
323
+ log_event(
324
+ "scaffold_tick_timeout_late",
325
+ tick=tick_count,
326
+ reason=str(late_exc),
327
+ )
328
+
329
+ # --- max_ticks bound ---
330
+ if max_ticks is not None and tick_count >= max_ticks:
331
+ break
332
+
333
+ # --- Parent-death check (after tick) ---
334
+ current_ppid = os.getppid()
335
+ if current_ppid != start_ppid or current_ppid == 1:
336
+ log_event("scaffold_parent_gone", start_ppid=start_ppid, current_ppid=current_ppid)
337
+ break
338
+
339
+ # --- Inter-tick sleep ---
340
+ elapsed = time.time() - tick_started_at
341
+ sleep_for = max(0.0, interval - elapsed)
342
+ if sleep_for > 0 and not stop_event.is_set():
343
+ _interruptible_sleep(sleep_for, stop_event)
344
+
345
+ finally:
346
+ log_event("scaffold_stopping", tick_count=tick_count)
347
+
348
+ return tick_count
349
+
350
+
351
+ def _post_error_safe(sink: Any, error: dict, tick_count: int) -> None:
352
+ """Call sink.post_error(error), swallowing/logging any failure."""
353
+ try:
354
+ sink.post_error(error)
355
+ except Exception as perr: # noqa: BLE001
356
+ log_event(
357
+ "scaffold_post_error_failed",
358
+ tick=tick_count,
359
+ error_type=type(perr).__name__,
360
+ error=str(perr),
361
+ )
@@ -0,0 +1,114 @@
1
+ """State persistence for the scaffold core.
2
+
3
+ read_state — tolerant read: missing -> None, corrupt -> None + log, valid -> value.
4
+ write_state — process-crash-safe write (temp + os.replace); unserialisable/IO failure -> False + log.
5
+
6
+ Never raises. The scaffold threads state between ticks via these two functions.
7
+ """
8
+
9
+ import json
10
+ import os
11
+ import tempfile
12
+
13
+ from .loop_primitives import log_event
14
+
15
+
16
+ def read_state(state_path: str):
17
+ """Read the JSON state file at state_path.
18
+
19
+ Returns:
20
+ The parsed JSON value, or None if:
21
+ - the file does not exist (silently), or
22
+ - the file is empty, corrupt, or truncated (logs scaffold_state_corrupt).
23
+ JSON null in the file is returned as Python None (indistinguishable from
24
+ "no state" — both mean "start fresh").
25
+
26
+ The file is never deleted or modified by this function.
27
+ """
28
+ if not os.path.exists(state_path):
29
+ return None
30
+
31
+ try:
32
+ with open(state_path, "r", encoding="utf-8") as fh:
33
+ content = fh.read()
34
+ except OSError as exc:
35
+ log_event("scaffold_state_corrupt", state_path=state_path, reason=str(exc))
36
+ return None
37
+
38
+ if not content.strip():
39
+ log_event("scaffold_state_corrupt", state_path=state_path, reason="empty file")
40
+ return None
41
+
42
+ try:
43
+ return json.loads(content)
44
+ except json.JSONDecodeError as exc:
45
+ log_event(
46
+ "scaffold_state_corrupt",
47
+ state_path=state_path,
48
+ reason=f"JSON parse error: {exc}",
49
+ )
50
+ return None
51
+
52
+
53
+ def write_state(state_path: str, new_state) -> bool:
54
+ """Write new_state as JSON to state_path, replacing it atomically.
55
+
56
+ Uses a temp file in the same directory and os.replace. This is atomic
57
+ with respect to a process crash (container SIGKILL): a reader always
58
+ sees the complete old file or the complete new file, never a partial
59
+ write. However, neither the temp fd nor the directory is fsynced before
60
+ the rename, so the guarantee does NOT extend to an OS crash or power
61
+ loss — in that case the target file may be zero-length or partial.
62
+
63
+ Returns:
64
+ True on success.
65
+ False (never raises) on:
66
+ - unserialisable new_state (logs scaffold_state_unserialisable, prior file intact).
67
+ - IO failure, e.g. read-only directory (logs, prior file intact).
68
+ """
69
+ # Serialise first — before touching the filesystem — so a bad value never
70
+ # creates a partial temp file at the destination directory.
71
+ try:
72
+ serialised = json.dumps(new_state)
73
+ except (TypeError, ValueError) as exc:
74
+ log_event(
75
+ "scaffold_state_unserialisable",
76
+ state_path=state_path,
77
+ reason=f"{type(exc).__name__}: {exc}",
78
+ )
79
+ return False
80
+
81
+ # Write to a temp file in the same directory so os.replace is atomic
82
+ # (same filesystem, no cross-device rename).
83
+ dir_path = os.path.dirname(os.path.abspath(state_path))
84
+ tmp_fd = None
85
+ tmp_path = None
86
+ try:
87
+ tmp_fd, tmp_path = tempfile.mkstemp(dir=dir_path, suffix=".tmp")
88
+ try:
89
+ os.write(tmp_fd, serialised.encode("utf-8"))
90
+ finally:
91
+ os.close(tmp_fd)
92
+ tmp_fd = None
93
+ os.replace(tmp_path, state_path)
94
+ tmp_path = None # successfully replaced; don't clean up
95
+ return True
96
+ except OSError as exc:
97
+ log_event(
98
+ "scaffold_state_write_failed",
99
+ state_path=state_path,
100
+ reason=f"{type(exc).__name__}: {exc}",
101
+ )
102
+ return False
103
+ finally:
104
+ # Clean up the temp file if it was not consumed by os.replace.
105
+ if tmp_fd is not None:
106
+ try:
107
+ os.close(tmp_fd)
108
+ except OSError:
109
+ pass
110
+ if tmp_path is not None:
111
+ try:
112
+ os.unlink(tmp_path)
113
+ except OSError:
114
+ pass