@senpi-ai/runtime 1.1.2 → 3.0.3

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 (481) 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 +161 -26
  13. package/dist/actions/open-position/open-position.action.js.map +1 -1
  14. package/dist/actions/position-tracker/position-tracker.action.d.ts +6 -0
  15. package/dist/actions/position-tracker/position-tracker.action.d.ts.map +1 -1
  16. package/dist/actions/position-tracker/position-tracker.action.js +48 -0
  17. package/dist/actions/position-tracker/position-tracker.action.js.map +1 -1
  18. package/dist/actions/tracking-helpers.d.ts +16 -1
  19. package/dist/actions/tracking-helpers.d.ts.map +1 -1
  20. package/dist/actions/tracking-helpers.js +55 -9
  21. package/dist/actions/tracking-helpers.js.map +1 -1
  22. package/dist/actions/types.d.ts +10 -2
  23. package/dist/actions/types.d.ts.map +1 -1
  24. package/dist/actions/types.js +8 -0
  25. package/dist/actions/types.js.map +1 -1
  26. package/dist/cli/guide-commands.d.ts.map +1 -1
  27. package/dist/cli/guide-commands.js +84 -82
  28. package/dist/cli/guide-commands.js.map +1 -1
  29. package/dist/cli/senpi-commands.d.ts.map +1 -1
  30. package/dist/cli/senpi-commands.js +16 -110
  31. package/dist/cli/senpi-commands.js.map +1 -1
  32. package/dist/constants/dsl/index.d.ts +2 -0
  33. package/dist/constants/dsl/index.d.ts.map +1 -1
  34. package/dist/constants/dsl/index.js +2 -0
  35. package/dist/constants/dsl/index.js.map +1 -1
  36. package/dist/dsl/config/parse-tiers.d.ts.map +1 -1
  37. package/dist/dsl/config/parse-tiers.js +6 -2
  38. package/dist/dsl/config/parse-tiers.js.map +1 -1
  39. package/dist/dsl/engine-client/config-mapping.d.ts +3 -1
  40. package/dist/dsl/engine-client/config-mapping.d.ts.map +1 -1
  41. package/dist/dsl/engine-client/config-mapping.js +3 -1
  42. package/dist/dsl/engine-client/config-mapping.js.map +1 -1
  43. package/dist/dsl/engine-client/event-mapping.d.ts +2 -0
  44. package/dist/dsl/engine-client/event-mapping.d.ts.map +1 -1
  45. package/dist/dsl/engine-client/event-mapping.js +3 -0
  46. package/dist/dsl/engine-client/event-mapping.js.map +1 -1
  47. package/dist/dsl/events/build-closed-event.d.ts.map +1 -1
  48. package/dist/dsl/events/build-closed-event.js +1 -0
  49. package/dist/dsl/events/build-closed-event.js.map +1 -1
  50. package/dist/dsl/events/guards.d.ts.map +1 -1
  51. package/dist/dsl/events/guards.js +10 -0
  52. package/dist/dsl/events/guards.js.map +1 -1
  53. package/dist/dsl/events/handlers.d.ts +18 -2
  54. package/dist/dsl/events/handlers.d.ts.map +1 -1
  55. package/dist/dsl/events/handlers.js +304 -208
  56. package/dist/dsl/events/handlers.js.map +1 -1
  57. package/dist/dsl/events/initial-state.d.ts.map +1 -1
  58. package/dist/dsl/events/initial-state.js +3 -1
  59. package/dist/dsl/events/initial-state.js.map +1 -1
  60. package/dist/dsl/monitor/create-monitor.d.ts +15 -0
  61. package/dist/dsl/monitor/create-monitor.d.ts.map +1 -1
  62. package/dist/dsl/monitor/create-monitor.js +76 -9
  63. package/dist/dsl/monitor/create-monitor.js.map +1 -1
  64. package/dist/dsl/monitor/process-one-position.d.ts.map +1 -1
  65. package/dist/dsl/monitor/process-one-position.js +268 -82
  66. package/dist/dsl/monitor/process-one-position.js.map +1 -1
  67. package/dist/dsl/plugin/index.d.ts +16 -1
  68. package/dist/dsl/plugin/index.d.ts.map +1 -1
  69. package/dist/dsl/plugin/index.js +35 -4
  70. package/dist/dsl/plugin/index.js.map +1 -1
  71. package/dist/dsl/plugin/options.d.ts +18 -0
  72. package/dist/dsl/plugin/options.d.ts.map +1 -1
  73. package/dist/index.d.ts +14 -1
  74. package/dist/index.d.ts.map +1 -1
  75. package/dist/index.js +272 -32
  76. package/dist/index.js.map +1 -1
  77. package/dist/recording/emitter.d.ts +27 -0
  78. package/dist/recording/emitter.d.ts.map +1 -0
  79. package/dist/recording/emitter.js +2 -0
  80. package/dist/recording/emitter.js.map +1 -0
  81. package/dist/recording/identity.d.ts +34 -0
  82. package/dist/recording/identity.d.ts.map +1 -0
  83. package/dist/recording/identity.js +2 -0
  84. package/dist/recording/identity.js.map +1 -0
  85. package/dist/recording/index.d.ts +11 -0
  86. package/dist/recording/index.d.ts.map +1 -0
  87. package/dist/recording/index.js +2 -0
  88. package/dist/recording/index.js.map +1 -0
  89. package/dist/recording/noop-emitter.d.ts +23 -0
  90. package/dist/recording/noop-emitter.d.ts.map +1 -0
  91. package/dist/recording/noop-emitter.js +22 -0
  92. package/dist/recording/noop-emitter.js.map +1 -0
  93. package/dist/recording/otel/attributes.d.ts +35 -0
  94. package/dist/recording/otel/attributes.d.ts.map +1 -0
  95. package/dist/recording/otel/attributes.js +131 -0
  96. package/dist/recording/otel/attributes.js.map +1 -0
  97. package/dist/recording/otel/constants.d.ts +123 -0
  98. package/dist/recording/otel/constants.d.ts.map +1 -0
  99. package/dist/recording/otel/constants.js +172 -0
  100. package/dist/recording/otel/constants.js.map +1 -0
  101. package/dist/recording/otel/ids.d.ts +25 -0
  102. package/dist/recording/otel/ids.d.ts.map +1 -0
  103. package/dist/recording/otel/ids.js +37 -0
  104. package/dist/recording/otel/ids.js.map +1 -0
  105. package/dist/recording/otel/index.d.ts +13 -0
  106. package/dist/recording/otel/index.d.ts.map +1 -0
  107. package/dist/recording/otel/index.js +9 -0
  108. package/dist/recording/otel/index.js.map +1 -0
  109. package/dist/recording/otel/mappers.d.ts +100 -0
  110. package/dist/recording/otel/mappers.d.ts.map +1 -0
  111. package/dist/recording/otel/mappers.js +683 -0
  112. package/dist/recording/otel/mappers.js.map +1 -0
  113. package/dist/recording/otel/otel-emitter.d.ts +43 -0
  114. package/dist/recording/otel/otel-emitter.d.ts.map +1 -0
  115. package/dist/recording/otel/otel-emitter.js +99 -0
  116. package/dist/recording/otel/otel-emitter.js.map +1 -0
  117. package/dist/recording/otel/redaction.d.ts +47 -0
  118. package/dist/recording/otel/redaction.d.ts.map +1 -0
  119. package/dist/recording/otel/redaction.js +88 -0
  120. package/dist/recording/otel/redaction.js.map +1 -0
  121. package/dist/recording/records.d.ts +565 -0
  122. package/dist/recording/records.d.ts.map +1 -0
  123. package/dist/recording/records.js +14 -0
  124. package/dist/recording/records.js.map +1 -0
  125. package/dist/recording/transport/batcher.d.ts +59 -0
  126. package/dist/recording/transport/batcher.d.ts.map +1 -0
  127. package/dist/recording/transport/batcher.js +234 -0
  128. package/dist/recording/transport/batcher.js.map +1 -0
  129. package/dist/recording/transport/client.d.ts +41 -0
  130. package/dist/recording/transport/client.d.ts.map +1 -0
  131. package/dist/recording/transport/client.js +69 -0
  132. package/dist/recording/transport/client.js.map +1 -0
  133. package/dist/recording/transport/config.d.ts +53 -0
  134. package/dist/recording/transport/config.d.ts.map +1 -0
  135. package/dist/recording/transport/config.js +41 -0
  136. package/dist/recording/transport/config.js.map +1 -0
  137. package/dist/recording/transport/index.d.ts +16 -0
  138. package/dist/recording/transport/index.d.ts.map +1 -0
  139. package/dist/recording/transport/index.js +12 -0
  140. package/dist/recording/transport/index.js.map +1 -0
  141. package/dist/recording/transport/rows.d.ts +88 -0
  142. package/dist/recording/transport/rows.d.ts.map +1 -0
  143. package/dist/recording/transport/rows.js +15 -0
  144. package/dist/recording/transport/rows.js.map +1 -0
  145. package/dist/recording/wiring/emitter-factory.d.ts +39 -0
  146. package/dist/recording/wiring/emitter-factory.d.ts.map +1 -0
  147. package/dist/recording/wiring/emitter-factory.js +62 -0
  148. package/dist/recording/wiring/emitter-factory.js.map +1 -0
  149. package/dist/recording/wiring/identity.d.ts +27 -0
  150. package/dist/recording/wiring/identity.d.ts.map +1 -0
  151. package/dist/recording/wiring/identity.js +51 -0
  152. package/dist/recording/wiring/identity.js.map +1 -0
  153. package/dist/recording/wiring/index.d.ts +12 -0
  154. package/dist/recording/wiring/index.d.ts.map +1 -0
  155. package/dist/recording/wiring/index.js +9 -0
  156. package/dist/recording/wiring/index.js.map +1 -0
  157. package/dist/recording/wiring/record-builders.d.ts +107 -0
  158. package/dist/recording/wiring/record-builders.d.ts.map +1 -0
  159. package/dist/recording/wiring/record-builders.js +706 -0
  160. package/dist/recording/wiring/record-builders.js.map +1 -0
  161. package/dist/recording/wiring/subscriber.d.ts +28 -0
  162. package/dist/recording/wiring/subscriber.d.ts.map +1 -0
  163. package/dist/recording/wiring/subscriber.js +173 -0
  164. package/dist/recording/wiring/subscriber.js.map +1 -0
  165. package/dist/recording/wiring/values.d.ts +19 -0
  166. package/dist/recording/wiring/values.d.ts.map +1 -0
  167. package/dist/recording/wiring/values.js +49 -0
  168. package/dist/recording/wiring/values.js.map +1 -0
  169. package/dist/runtime/auto-update/command-runner.d.ts.map +1 -1
  170. package/dist/runtime/auto-update/command-runner.js +5 -1
  171. package/dist/runtime/auto-update/command-runner.js.map +1 -1
  172. package/dist/runtime/auto-update/resolve-package-name.d.ts +10 -0
  173. package/dist/runtime/auto-update/resolve-package-name.d.ts.map +1 -0
  174. package/dist/runtime/auto-update/resolve-package-name.js +35 -0
  175. package/dist/runtime/auto-update/resolve-package-name.js.map +1 -0
  176. package/dist/runtime/auto-update/run-update-command.d.ts +2 -0
  177. package/dist/runtime/auto-update/run-update-command.d.ts.map +1 -0
  178. package/dist/runtime/auto-update/run-update-command.js +37 -0
  179. package/dist/runtime/auto-update/run-update-command.js.map +1 -0
  180. package/dist/runtime/create-runtime-context.d.ts +2 -0
  181. package/dist/runtime/create-runtime-context.d.ts.map +1 -1
  182. package/dist/runtime/create-runtime-context.js +1 -0
  183. package/dist/runtime/create-runtime-context.js.map +1 -1
  184. package/dist/runtime/create-scanner-module.d.ts +4 -3
  185. package/dist/runtime/create-scanner-module.d.ts.map +1 -1
  186. package/dist/runtime/create-scanner-module.js +14 -5
  187. package/dist/runtime/create-scanner-module.js.map +1 -1
  188. package/dist/runtime/create-scanner-providers-for-run.d.ts.map +1 -1
  189. package/dist/runtime/create-scanner-providers-for-run.js +12 -1
  190. package/dist/runtime/create-scanner-providers-for-run.js.map +1 -1
  191. package/dist/runtime/load-runtime-config.d.ts +9 -0
  192. package/dist/runtime/load-runtime-config.d.ts.map +1 -1
  193. package/dist/runtime/load-runtime-config.js +41 -8
  194. package/dist/runtime/load-runtime-config.js.map +1 -1
  195. package/dist/runtime/map-strategies-registration.js +7 -8
  196. package/dist/runtime/map-strategies-registration.js.map +1 -1
  197. package/dist/runtime/map-strategies.d.ts.map +1 -1
  198. package/dist/runtime/map-strategies.js +12 -3
  199. package/dist/runtime/map-strategies.js.map +1 -1
  200. package/dist/runtime/recipe-version.d.ts +1 -1
  201. package/dist/runtime/recipe-version.d.ts.map +1 -1
  202. package/dist/runtime/recipe-version.js +1 -1
  203. package/dist/runtime/recipe-version.js.map +1 -1
  204. package/dist/runtime/reconcile-decide.d.ts +73 -0
  205. package/dist/runtime/reconcile-decide.d.ts.map +1 -0
  206. package/dist/runtime/reconcile-decide.js +186 -0
  207. package/dist/runtime/reconcile-decide.js.map +1 -0
  208. package/dist/runtime/reconcile-run.d.ts +62 -0
  209. package/dist/runtime/reconcile-run.d.ts.map +1 -0
  210. package/dist/runtime/reconcile-run.js +173 -0
  211. package/dist/runtime/reconcile-run.js.map +1 -0
  212. package/dist/runtime/reconcile-state.d.ts +44 -0
  213. package/dist/runtime/reconcile-state.d.ts.map +1 -1
  214. package/dist/runtime/reconcile-state.js +80 -44
  215. package/dist/runtime/reconcile-state.js.map +1 -1
  216. package/dist/runtime/risk-guard.d.ts +10 -0
  217. package/dist/runtime/risk-guard.d.ts.map +1 -1
  218. package/dist/runtime/risk-guard.js +23 -24
  219. package/dist/runtime/risk-guard.js.map +1 -1
  220. package/dist/runtime/run.d.ts.map +1 -1
  221. package/dist/runtime/run.js +3 -2
  222. package/dist/runtime/run.js.map +1 -1
  223. package/dist/runtime/runtime-schema.d.ts +4056 -793
  224. package/dist/runtime/runtime-schema.d.ts.map +1 -1
  225. package/dist/runtime/runtime-schema.js +183 -46
  226. package/dist/runtime/runtime-schema.js.map +1 -1
  227. package/dist/runtime/runtime-version.d.ts +3 -6
  228. package/dist/runtime/runtime-version.d.ts.map +1 -1
  229. package/dist/runtime/runtime-version.js +3 -6
  230. package/dist/runtime/runtime-version.js.map +1 -1
  231. package/dist/runtime/runtime.d.ts +47 -0
  232. package/dist/runtime/runtime.d.ts.map +1 -1
  233. package/dist/runtime/runtime.js +517 -134
  234. package/dist/runtime/runtime.js.map +1 -1
  235. package/dist/runtime/scanner-registry.d.ts +1 -1
  236. package/dist/runtime/scanner-registry.d.ts.map +1 -1
  237. package/dist/runtime/scanner-registry.js +3 -12
  238. package/dist/runtime/scanner-registry.js.map +1 -1
  239. package/dist/runtime/strategy-lifecycle.d.ts +45 -0
  240. package/dist/runtime/strategy-lifecycle.d.ts.map +1 -0
  241. package/dist/runtime/strategy-lifecycle.js +117 -0
  242. package/dist/runtime/strategy-lifecycle.js.map +1 -0
  243. package/dist/runtime/strategy-registry.d.ts +6 -0
  244. package/dist/runtime/strategy-registry.d.ts.map +1 -1
  245. package/dist/runtime/strategy-registry.js +1 -0
  246. package/dist/runtime/strategy-registry.js.map +1 -1
  247. package/dist/runtime/supervisor/long-running-supervisor.d.ts +222 -0
  248. package/dist/runtime/supervisor/long-running-supervisor.d.ts.map +1 -0
  249. package/dist/runtime/supervisor/long-running-supervisor.js +625 -0
  250. package/dist/runtime/supervisor/long-running-supervisor.js.map +1 -0
  251. package/dist/runtime/supervisor/orphan-sweep.d.ts +36 -0
  252. package/dist/runtime/supervisor/orphan-sweep.d.ts.map +1 -0
  253. package/dist/runtime/supervisor/orphan-sweep.js +255 -0
  254. package/dist/runtime/supervisor/orphan-sweep.js.map +1 -0
  255. package/dist/runtime/supervisor/supervisor-utils.d.ts +37 -0
  256. package/dist/runtime/supervisor/supervisor-utils.d.ts.map +1 -0
  257. package/dist/runtime/supervisor/supervisor-utils.js +175 -0
  258. package/dist/runtime/supervisor/supervisor-utils.js.map +1 -0
  259. package/dist/runtime-api/handlers/ingest-signals.d.ts +3 -3
  260. package/dist/runtime-api/handlers/ingest-signals.js +3 -3
  261. package/dist/runtime-api/intake/acceptance-record.d.ts +103 -0
  262. package/dist/runtime-api/intake/acceptance-record.d.ts.map +1 -0
  263. package/dist/runtime-api/intake/acceptance-record.js +192 -0
  264. package/dist/runtime-api/intake/acceptance-record.js.map +1 -0
  265. package/dist/runtime-api/intake/intake-context.d.ts +31 -0
  266. package/dist/runtime-api/intake/intake-context.d.ts.map +1 -0
  267. package/dist/runtime-api/intake/intake-context.js +21 -0
  268. package/dist/runtime-api/intake/intake-context.js.map +1 -0
  269. package/dist/runtime-api/intake/intake-mount.d.ts +118 -0
  270. package/dist/runtime-api/intake/intake-mount.d.ts.map +1 -0
  271. package/dist/runtime-api/intake/intake-mount.js +193 -0
  272. package/dist/runtime-api/intake/intake-mount.js.map +1 -0
  273. package/dist/runtime-api/intake/liveness-store.d.ts +32 -0
  274. package/dist/runtime-api/intake/liveness-store.d.ts.map +1 -0
  275. package/dist/runtime-api/intake/liveness-store.js +31 -0
  276. package/dist/runtime-api/intake/liveness-store.js.map +1 -0
  277. package/dist/runtime-api/intake/process-error-post.d.ts +15 -0
  278. package/dist/runtime-api/intake/process-error-post.d.ts.map +1 -0
  279. package/dist/runtime-api/intake/process-error-post.js +19 -0
  280. package/dist/runtime-api/intake/process-error-post.js.map +1 -0
  281. package/dist/runtime-api/intake/process-signal-post.d.ts +73 -0
  282. package/dist/runtime-api/intake/process-signal-post.d.ts.map +1 -0
  283. package/dist/runtime-api/intake/process-signal-post.js +188 -0
  284. package/dist/runtime-api/intake/process-signal-post.js.map +1 -0
  285. package/dist/runtime-api/intake/scanner-launcher.d.ts +133 -0
  286. package/dist/runtime-api/intake/scanner-launcher.d.ts.map +1 -0
  287. package/dist/runtime-api/intake/scanner-launcher.js +204 -0
  288. package/dist/runtime-api/intake/scanner-launcher.js.map +1 -0
  289. package/dist/runtime-api/intake/scanner-registry.d.ts +36 -0
  290. package/dist/runtime-api/intake/scanner-registry.d.ts.map +1 -0
  291. package/dist/runtime-api/intake/scanner-registry.js +29 -0
  292. package/dist/runtime-api/intake/scanner-registry.js.map +1 -0
  293. package/dist/runtime-api/intake/types.d.ts +61 -0
  294. package/dist/runtime-api/intake/types.d.ts.map +1 -0
  295. package/dist/runtime-api/intake/types.js +8 -0
  296. package/dist/runtime-api/intake/types.js.map +1 -0
  297. package/dist/runtime-api/routes/signals.d.ts +20 -40
  298. package/dist/runtime-api/routes/signals.d.ts.map +1 -1
  299. package/dist/runtime-api/routes/signals.js +119 -75
  300. package/dist/runtime-api/routes/signals.js.map +1 -1
  301. package/dist/runtime-api/routes/signals.schema.d.ts +24 -86
  302. package/dist/runtime-api/routes/signals.schema.d.ts.map +1 -1
  303. package/dist/runtime-api/routes/signals.schema.js +35 -50
  304. package/dist/runtime-api/routes/signals.schema.js.map +1 -1
  305. package/dist/runtime-api/server.d.ts +15 -6
  306. package/dist/runtime-api/server.d.ts.map +1 -1
  307. package/dist/runtime-api/server.js +12 -12
  308. package/dist/runtime-api/server.js.map +1 -1
  309. package/dist/scanners/events.d.ts +6 -0
  310. package/dist/scanners/events.d.ts.map +1 -1
  311. package/dist/scanners/events.js.map +1 -1
  312. package/dist/scanners/external/scaffold/__init__.py +16 -0
  313. package/dist/scanners/external/scaffold/__main__.py +155 -0
  314. package/dist/scanners/external/scaffold/ctx.py +78 -0
  315. package/dist/scanners/external/scaffold/delivery.py +263 -0
  316. package/dist/scanners/external/scaffold/entrypoint_loader.py +151 -0
  317. package/dist/scanners/external/scaffold/http_post.py +70 -0
  318. package/dist/scanners/external/scaffold/journal.py +247 -0
  319. package/dist/scanners/external/scaffold/loop_primitives.py +65 -0
  320. package/dist/scanners/external/scaffold/requirements.txt +11 -0
  321. package/dist/scanners/external/scaffold/scaffold.py +361 -0
  322. package/dist/scanners/external/scaffold/scaffold_state.py +114 -0
  323. package/dist/scanners/external/scaffold/senpi_mcp.py +250 -0
  324. package/dist/scanners/external/scaffold/signal_envelope.py +220 -0
  325. package/dist/scanners/external/scaffold/state_manager.py +175 -0
  326. package/dist/scanners/external-scanner-receiver.d.ts +17 -1
  327. package/dist/scanners/external-scanner-receiver.d.ts.map +1 -1
  328. package/dist/scanners/external-scanner-receiver.js +16 -3
  329. package/dist/scanners/external-scanner-receiver.js.map +1 -1
  330. package/dist/scanners/implementations/external-scanner.d.ts.map +1 -1
  331. package/dist/scanners/implementations/external-scanner.js +7 -1
  332. package/dist/scanners/implementations/external-scanner.js.map +1 -1
  333. package/dist/scanners/implementations/momentum.d.ts.map +1 -1
  334. package/dist/scanners/implementations/momentum.js +16 -0
  335. package/dist/scanners/implementations/momentum.js.map +1 -1
  336. package/dist/scanners/runtime-module.d.ts.map +1 -1
  337. package/dist/scanners/runtime-module.js +9 -1
  338. package/dist/scanners/runtime-module.js.map +1 -1
  339. package/dist/scripts/run-dsl-standalone-live.d.ts +1 -1
  340. package/dist/scripts/run-dsl-standalone-live.js +5 -3
  341. package/dist/scripts/run-dsl-standalone-live.js.map +1 -1
  342. package/dist/senpi/client.d.ts +56 -4
  343. package/dist/senpi/client.d.ts.map +1 -1
  344. package/dist/senpi/client.js +123 -24
  345. package/dist/senpi/client.js.map +1 -1
  346. package/dist/senpi/index.d.ts +2 -1
  347. package/dist/senpi/index.d.ts.map +1 -1
  348. package/dist/senpi/index.js +1 -1
  349. package/dist/senpi/index.js.map +1 -1
  350. package/dist/senpi/types.d.ts +1 -2
  351. package/dist/senpi/types.d.ts.map +1 -1
  352. package/dist/state/state-manager.d.ts +17 -0
  353. package/dist/state/state-manager.d.ts.map +1 -1
  354. package/dist/state/state-manager.js +55 -4
  355. package/dist/state/state-manager.js.map +1 -1
  356. package/dist/strategy/strategy-state.d.ts +9 -1
  357. package/dist/strategy/strategy-state.d.ts.map +1 -1
  358. package/dist/strategy/strategy-state.js +62 -9
  359. package/dist/strategy/strategy-state.js.map +1 -1
  360. package/dist/tracking/build-rehydrate-items.d.ts +15 -0
  361. package/dist/tracking/build-rehydrate-items.d.ts.map +1 -0
  362. package/dist/tracking/build-rehydrate-items.js +19 -0
  363. package/dist/tracking/build-rehydrate-items.js.map +1 -0
  364. package/dist/tracking/constants.d.ts.map +1 -1
  365. package/dist/tracking/constants.js +2 -0
  366. package/dist/tracking/constants.js.map +1 -1
  367. package/dist/tracking/index.d.ts +3 -0
  368. package/dist/tracking/index.d.ts.map +1 -1
  369. package/dist/tracking/index.js +2 -0
  370. package/dist/tracking/index.js.map +1 -1
  371. package/dist/tracking/position-id-registry.d.ts +69 -0
  372. package/dist/tracking/position-id-registry.d.ts.map +1 -0
  373. package/dist/tracking/position-id-registry.js +139 -0
  374. package/dist/tracking/position-id-registry.js.map +1 -0
  375. package/dist/tracking/spans/fan-out-span-transport.d.ts +22 -0
  376. package/dist/tracking/spans/fan-out-span-transport.d.ts.map +1 -0
  377. package/dist/tracking/spans/fan-out-span-transport.js +49 -0
  378. package/dist/tracking/spans/fan-out-span-transport.js.map +1 -0
  379. package/dist/tracking/spans/otel/fit-row-budget.d.ts +22 -0
  380. package/dist/tracking/spans/otel/fit-row-budget.d.ts.map +1 -0
  381. package/dist/tracking/spans/otel/fit-row-budget.js +91 -0
  382. package/dist/tracking/spans/otel/fit-row-budget.js.map +1 -0
  383. package/dist/tracking/spans/otel/map-span-to-trace-row.d.ts +16 -0
  384. package/dist/tracking/spans/otel/map-span-to-trace-row.d.ts.map +1 -0
  385. package/dist/tracking/spans/otel/map-span-to-trace-row.js +227 -0
  386. package/dist/tracking/spans/otel/map-span-to-trace-row.js.map +1 -0
  387. package/dist/tracking/spans/otel/recording-span-transport.d.ts +43 -0
  388. package/dist/tracking/spans/otel/recording-span-transport.d.ts.map +1 -0
  389. package/dist/tracking/spans/otel/recording-span-transport.js +67 -0
  390. package/dist/tracking/spans/otel/recording-span-transport.js.map +1 -0
  391. package/dist/tracking/spans/otel/span-ids.d.ts +22 -0
  392. package/dist/tracking/spans/otel/span-ids.d.ts.map +1 -0
  393. package/dist/tracking/spans/otel/span-ids.js +32 -0
  394. package/dist/tracking/spans/otel/span-ids.js.map +1 -0
  395. package/dist/tracking/spans/plugin-span-tracker.d.ts +6 -0
  396. package/dist/tracking/spans/plugin-span-tracker.d.ts.map +1 -1
  397. package/dist/tracking/spans/plugin-span-tracker.js +82 -9
  398. package/dist/tracking/spans/plugin-span-tracker.js.map +1 -1
  399. package/dist/tracking/spans/redact-pii.d.ts +3 -1
  400. package/dist/tracking/spans/redact-pii.d.ts.map +1 -1
  401. package/dist/tracking/spans/redact-pii.js +5 -1
  402. package/dist/tracking/spans/redact-pii.js.map +1 -1
  403. package/dist/tracking/spans/span-transport.d.ts +6 -0
  404. package/dist/tracking/spans/span-transport.d.ts.map +1 -1
  405. package/dist/tracking/spans/span-transport.js +1 -1
  406. package/dist/tracking/spans/span-transport.js.map +1 -1
  407. package/dist/types/dsl/index.d.ts +24 -1
  408. package/dist/types/dsl/index.d.ts.map +1 -1
  409. package/dist/types/hooks.d.ts +1 -0
  410. package/dist/types/hooks.d.ts.map +1 -1
  411. package/dist/types/hooks.js +1 -0
  412. package/dist/types/hooks.js.map +1 -1
  413. package/dist/types/runtime.d.ts +6 -0
  414. package/dist/types/runtime.d.ts.map +1 -1
  415. package/dist/types/scanner.d.ts +7 -0
  416. package/dist/types/scanner.d.ts.map +1 -1
  417. package/dist/types/strategy.d.ts +3 -1
  418. package/dist/types/strategy.d.ts.map +1 -1
  419. package/dist/utils/keyed-mutex.d.ts +37 -0
  420. package/dist/utils/keyed-mutex.d.ts.map +1 -0
  421. package/dist/utils/keyed-mutex.js +77 -0
  422. package/dist/utils/keyed-mutex.js.map +1 -0
  423. package/dist/utils/safe-spawn.d.ts +6 -0
  424. package/dist/utils/safe-spawn.d.ts.map +1 -0
  425. package/dist/utils/safe-spawn.js +62 -0
  426. package/dist/utils/safe-spawn.js.map +1 -0
  427. package/examples/strategies/README.md +17 -12
  428. package/examples/strategies/iguana/README.md +135 -0
  429. package/examples/strategies/iguana/recipe.yaml +137 -0
  430. package/examples/strategies/iguana/scanners/scan.py +243 -0
  431. package/examples/strategies/iguana/scanners/scoring.py +152 -0
  432. package/examples/strategies/raptor/README.md +156 -0
  433. package/examples/strategies/raptor/recipe.yaml +154 -0
  434. package/examples/strategies/raptor/scanners/scan.py +349 -0
  435. package/examples/strategies/raptor/scanners/scoring.py +452 -0
  436. package/examples/strategies/spider/README.md +89 -0
  437. package/examples/strategies/spider/scalp/recipe.yaml +129 -0
  438. package/examples/strategies/spider/scalp/scanners/scan.py +219 -0
  439. package/examples/strategies/spider/scalp/scanners/scoring.py +179 -0
  440. package/examples/strategies/spider/swing/recipe.yaml +137 -0
  441. package/examples/strategies/spider/swing/scanners/scan.py +334 -0
  442. package/examples/strategies/spider/swing/scanners/scoring.py +184 -0
  443. package/examples/strategies/turbine/README.md +166 -0
  444. package/examples/strategies/turbine/recipe-runners.yaml +123 -0
  445. package/examples/strategies/turbine/recipe-volume.yaml +129 -0
  446. package/examples/strategies/turbine/scanners/scan.py +283 -0
  447. package/examples/strategies/turbine/scanners/scoring.py +190 -0
  448. package/openclaw.plugin.json +12 -1
  449. package/package.json +3 -3
  450. package/dist/runtime-api/handlers/group-by-scanner.d.ts +0 -43
  451. package/dist/runtime-api/handlers/group-by-scanner.d.ts.map +0 -1
  452. package/dist/runtime-api/handlers/group-by-scanner.js +0 -43
  453. package/dist/runtime-api/handlers/group-by-scanner.js.map +0 -1
  454. package/dist/scanners/external/liquidation-watchdog/README.md +0 -107
  455. package/dist/scanners/external/liquidation-watchdog/liquidation-watchdog.yaml +0 -48
  456. package/dist/scanners/external/liquidation-watchdog/producer.mjs +0 -336
  457. package/dist/scanners/external/momentum/README.md +0 -148
  458. package/dist/scanners/external/momentum/momentum.yaml +0 -116
  459. package/dist/scanners/external/momentum/producer.mjs +0 -251
  460. package/dist/scanners/external/shared/ingest.mjs +0 -112
  461. package/examples/README.md +0 -89
  462. package/examples/scanners-consumer-quickstart.mjs +0 -134
  463. package/examples/scanners-emerging-movers-v4.mjs +0 -287
  464. package/examples/scanners-liquidation-watchdog.mjs +0 -341
  465. package/examples/scanners-live-mcp.mjs +0 -208
  466. package/examples/scanners-multi-strategy.mjs +0 -165
  467. package/examples/scanners-position-tracker-e2e.mjs +0 -225
  468. package/examples/scanners-scheduled-events.mjs +0 -96
  469. package/examples/scanners-senpi-provider-client.mjs +0 -182
  470. package/examples/scanners-single-strategy.mjs +0 -198
  471. package/examples/strategies/dsl-showcase.yaml +0 -68
  472. package/examples/strategies/dsl.yaml +0 -51
  473. package/examples/strategies/fox-minimal-loosened.yaml +0 -240
  474. package/examples/strategies/fox-minimal.yaml +0 -242
  475. package/examples/strategies/minimal.yaml +0 -46
  476. package/examples/strategies/momentum/how-it-works.md +0 -48
  477. package/examples/strategies/momentum/momentum-guarded.yaml +0 -161
  478. package/examples/strategies/risk-showcase.yaml +0 -93
  479. package/examples/strategies/viper.yaml +0 -67
  480. package/examples/strategies/wolf.yaml +0 -72
  481. package/examples/yamls/sample-with-dsl-and-emerging-movers.yaml +0 -123
@@ -1 +1 @@
1
- {"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/scanners/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAEzE,yDAAyD;AACzD,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,sFAAsF;AACtF,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,qFAAqF;AACrF,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,6EAA6E;AAC7E,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,yCAAyC;AACzC,MAAM,WAAW,sBAAsB;IACrC,mBAAmB,EAAE,oBAAoB,CAAC;IAC1C,sBAAsB,EAAE,uBAAuB,CAAC;IAChD,kBAAkB,EAAE,mBAAmB,CAAC;IACxC,mBAAmB,EAAE,oBAAoB,CAAC;CAC3C;AAED,qEAAqE;AACrE,MAAM,MAAM,uBAAuB,GAAG,MAAM,sBAAsB,CAAC;AAEnE,sFAAsF;AACtF,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,CAAC,SAAS,EAAE,uBAAuB,EAAE,KAAK,EAAE,sBAAsB,CAAC,uBAAuB,CAAC,KAAK,IAAI,EAC1G,MAAM,EAAE,UAAU,GACjB,IAAI,CAiCN"}
1
+ {"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/scanners/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAEzE,yDAAyD;AACzD,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,sFAAsF;AACtF,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;IACnB,qGAAqG;IACrG,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qFAAqF;AACrF,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,qGAAqG;IACrG,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,6EAA6E;AAC7E,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,qGAAqG;IACrG,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,yCAAyC;AACzC,MAAM,WAAW,sBAAsB;IACrC,mBAAmB,EAAE,oBAAoB,CAAC;IAC1C,sBAAsB,EAAE,uBAAuB,CAAC;IAChD,kBAAkB,EAAE,mBAAmB,CAAC;IACxC,mBAAmB,EAAE,oBAAoB,CAAC;CAC3C;AAED,qEAAqE;AACrE,MAAM,MAAM,uBAAuB,GAAG,MAAM,sBAAsB,CAAC;AAEnE,sFAAsF;AACtF,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,CAAC,SAAS,EAAE,uBAAuB,EAAE,KAAK,EAAE,sBAAsB,CAAC,uBAAuB,CAAC,KAAK,IAAI,EAC1G,MAAM,EAAE,UAAU,GACjB,IAAI,CAiCN"}
@@ -1 +1 @@
1
- {"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/scanners/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAmC,MAAM,YAAY,CAAC;AA6CzE,sFAAsF;AACtF,MAAM,UAAU,2BAA2B,CACzC,IAA0G,EAC1G,MAAkB;IAElB,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;IACnC,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU,CAAC,KAAK,EAAE,CAAC;QACvC,IAAI,CAAC,mBAAmB,EAAE;YACxB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,SAAS;YACT,KAAK,EAAE,MAAM,CAAC,MAAM,IAAI,wBAAwB;SACjD,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IAED,IACE,MAAM,CAAC,MAAM,KAAK,UAAU,CAAC,OAAO;QACpC,MAAM,CAAC,MAAM,KAAK,UAAU,CAAC,MAAM;QACnC,MAAM,CAAC,MAAM,KAAK,UAAU,CAAC,QAAQ,EACrC,CAAC;QACD,IAAI,CAAC,kBAAkB,EAAE;YACvB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,SAAS;YACT,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,sBAAsB;SAChD,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IAED,IAAI,CAAC,sBAAsB,EAAE;QAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,SAAS;QACT,MAAM;KACP,CAAC,CAAC;AACL,CAAC"}
1
+ {"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/scanners/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAmC,MAAM,YAAY,CAAC;AAmDzE,sFAAsF;AACtF,MAAM,UAAU,2BAA2B,CACzC,IAA0G,EAC1G,MAAkB;IAElB,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;IACnC,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU,CAAC,KAAK,EAAE,CAAC;QACvC,IAAI,CAAC,mBAAmB,EAAE;YACxB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,SAAS;YACT,KAAK,EAAE,MAAM,CAAC,MAAM,IAAI,wBAAwB;SACjD,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IAED,IACE,MAAM,CAAC,MAAM,KAAK,UAAU,CAAC,OAAO;QACpC,MAAM,CAAC,MAAM,KAAK,UAAU,CAAC,MAAM;QACnC,MAAM,CAAC,MAAM,KAAK,UAAU,CAAC,QAAQ,EACrC,CAAC;QACD,IAAI,CAAC,kBAAkB,EAAE;YACvB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,SAAS;YACT,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,sBAAsB;SAChD,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IAED,IAAI,CAAC,sBAAsB,EAAE;QAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,SAAS;QACT,MAAM;KACP,CAAC,CAAC;AACL,CAAC"}
@@ -0,0 +1,16 @@
1
+ """scaffold — the system-owned harness that runs a scan() function on an interval.
2
+
3
+ Public API:
4
+ run_scaffold(...) — the main entry point; loads and drives the scan loop.
5
+ ScanEntrypointError — import failure, scan missing or not callable.
6
+ ScanSignatureError — scan call-shape incompatible with the scaffold contract.
7
+ """
8
+
9
+ from .entrypoint_loader import ScanEntrypointError, ScanSignatureError
10
+ from .scaffold import run_scaffold
11
+
12
+ __all__ = [
13
+ "run_scaffold",
14
+ "ScanEntrypointError",
15
+ "ScanSignatureError",
16
+ ]
@@ -0,0 +1,155 @@
1
+ """Process entry for the scaffold core (v2).
2
+
3
+ Usage: python3 -m scaffold <launch-config.json>
4
+
5
+ The launch config JSON is the FROZEN launcher<->scaffold contract (design §4a).
6
+ This side READS every §4a key the B1 launcher writes and threads them into
7
+ run_scaffold. Hard cut: old key names are gone (`interval` -> `interval_seconds`,
8
+ `params` -> `inputs`).
9
+
10
+ Required keys (missing => fail loud, non-zero exit):
11
+ path — directory added to sys.path (scanner working dir).
12
+ entrypoint — module name to import from `path`.
13
+ interval_seconds — tick cadence in seconds (was `interval`).
14
+ default_signal_validity_seconds — fallback signal TTL (seconds); no magic default.
15
+ wallet — strategy wallet (-> ctx.wallet).
16
+ scanner_name — this scanner's recipe name (-> ctx.scanner_name).
17
+
18
+ Optional keys:
19
+ timeout_seconds — per-tick wall-clock budget (default: interval_seconds).
20
+ state_path — JSON state file path (None => no persistence).
21
+ inputs — tunables dict for scan() (was `params`); default {}.
22
+ state_history_max_count — state series bound; default 0 = history disabled.
23
+
24
+ Delivery sink is wired when EXTERNAL_SCANNER_ID and SIGNAL_INGESTION_URL are set in
25
+ the environment. If either is absent the scaffold runs with the default no-op sink
26
+ and logs a warning — scanners can still operate without a live runtime.
27
+ """
28
+
29
+ import json
30
+ import os
31
+ import sys
32
+
33
+
34
+ def _main(argv=None) -> int:
35
+ if argv is None:
36
+ argv = sys.argv
37
+
38
+ if len(argv) < 2:
39
+ print(
40
+ "Usage: python3 -m scaffold <launch-config.json>",
41
+ file=sys.stderr,
42
+ )
43
+ return 1
44
+
45
+ config_path = argv[1]
46
+ try:
47
+ with open(config_path, "r", encoding="utf-8") as fh:
48
+ config = json.load(fh)
49
+ except (OSError, json.JSONDecodeError) as exc:
50
+ print(f"[scaffold] launch config error: {exc}", file=sys.stderr)
51
+ return 1
52
+
53
+ # ---- Required §4a keys: missing => fail loud (no magic default) ----
54
+ try:
55
+ path = config["path"]
56
+ entrypoint = config["entrypoint"]
57
+ interval = float(config["interval_seconds"])
58
+ default_signal_validity_seconds = int(config["default_signal_validity_seconds"])
59
+ wallet = config["wallet"]
60
+ scanner_name = config["scanner_name"]
61
+ except (KeyError, TypeError, ValueError) as exc:
62
+ print(
63
+ f"[scaffold] launch config missing/invalid required field: {exc}",
64
+ file=sys.stderr,
65
+ )
66
+ return 1
67
+
68
+ # ---- Optional §4a keys ----
69
+ timeout_seconds = config.get("timeout_seconds")
70
+ # Hard cut: only `inputs` is read. The legacy `params` key is NOT honored.
71
+ inputs = config.get("inputs") or {}
72
+ state_path = config.get("state_path")
73
+ state_history_max_count = config.get("state_history_max_count") or 0
74
+ # Per-signal data{} schema (§4a). None / absent => no scaffold-side validation
75
+ # (intake still validates authoritatively). A dict turns on early, loud
76
+ # scaffold-side validation that POSTs a violation to /errors.
77
+ signal_data_schema = config.get("signal_data_schema")
78
+ if signal_data_schema is not None and not isinstance(signal_data_schema, dict):
79
+ signal_data_schema = None
80
+ max_ticks = config.get("max_ticks")
81
+
82
+ import scaffold as scaffold_pkg
83
+ from scaffold import ScanEntrypointError, ScanSignatureError
84
+ from scaffold.loop_primitives import log_event
85
+
86
+ # Resolve run_scaffold via the package symbol so a test stub patched onto the
87
+ # package (or this module) is picked up.
88
+ run_scaffold = globals().get("run_scaffold") or scaffold_pkg.run_scaffold
89
+
90
+ # Build the delivery sink when scanner_id and intake URL are available.
91
+ sink = None
92
+ scanner_id = os.environ.get("EXTERNAL_SCANNER_ID", "").strip()
93
+ intake_url = os.environ.get("SIGNAL_INGESTION_URL", "").strip()
94
+
95
+ if scanner_id and intake_url:
96
+ try:
97
+ from scaffold.delivery import build_delivery_sink
98
+
99
+ post_timeout = float(os.environ.get("SIGNAL_POST_TIMEOUT_SECONDS", "5"))
100
+
101
+ # Derive journal path from the state file directory when available.
102
+ journal_path = None
103
+ if state_path:
104
+ journal_path = os.path.join(
105
+ os.path.dirname(os.path.abspath(state_path)),
106
+ "delivery-journal.jsonl",
107
+ )
108
+
109
+ # §4a threads the per-data-key schema (`signal_data_schema`) to the
110
+ # scaffold so the envelope validates each signal's `data` scaffold-side
111
+ # and POSTs a violation to /errors (early, loud feedback). None ⇒ no
112
+ # scaffold-side validation. The intake still performs authoritative
113
+ # server-side schema validation regardless (this is additive).
114
+ sink = build_delivery_sink(
115
+ scanner_id=scanner_id,
116
+ intake_url=intake_url,
117
+ journal_path=journal_path,
118
+ signal_data_schema=signal_data_schema,
119
+ default_signal_validity_seconds=default_signal_validity_seconds,
120
+ timeout=post_timeout,
121
+ )
122
+ log_event("delivery_sink_enabled", scanner_id=scanner_id, intake_url=intake_url)
123
+ except Exception as exc: # noqa: BLE001
124
+ log_event("delivery_sink_error", error=str(exc))
125
+ sink = None
126
+ else:
127
+ log_event(
128
+ "delivery_sink_disabled",
129
+ reason="EXTERNAL_SCANNER_ID or SIGNAL_INGESTION_URL not set; running with no-op sink",
130
+ )
131
+
132
+ try:
133
+ run_scaffold(
134
+ path,
135
+ entrypoint,
136
+ interval=interval,
137
+ timeout_seconds=timeout_seconds,
138
+ inputs=inputs,
139
+ state_path=state_path,
140
+ scanner_name=scanner_name,
141
+ wallet=wallet,
142
+ default_signal_validity_seconds=default_signal_validity_seconds,
143
+ state_history_max_count=state_history_max_count,
144
+ sink=sink,
145
+ max_ticks=max_ticks,
146
+ )
147
+ except (ScanEntrypointError, ScanSignatureError, ValueError) as exc:
148
+ print(f"[scaffold] launch failed: {exc}", file=sys.stderr)
149
+ return 1
150
+
151
+ return 0
152
+
153
+
154
+ if __name__ == "__main__":
155
+ sys.exit(_main())
@@ -0,0 +1,78 @@
1
+ """The author-facing `ctx` object handed to scan(inputs, ctx).
2
+
3
+ `ScanContext` is the second argument to the author's `scan(inputs, ctx)`. It is
4
+ two tiers (design §2.1):
5
+
6
+ Capabilities you CALL:
7
+ state — the StateManager (B2): a disk-persisted, bounded, transactional
8
+ series. Passed in AS-IS (never wrapped/copied) so author mutations
9
+ and the scaffold's commit/rollback hit the SAME object. May be None
10
+ when history is disabled (state_history_max_count 0/unset).
11
+ senpi_mcp — the MCP client capability. PRESENT but EMPTY this block (None);
12
+ B5 fills it. The slot exists now so B5 is purely additive — no
13
+ structural change to ctx later.
14
+
15
+ Read-only metadata you READ:
16
+ wallet — str, the strategy wallet (routing identity).
17
+ scanner_name — str, this scanner's recipe name.
18
+ interval_seconds — int, tick cadence in seconds.
19
+
20
+ The metadata is FROZEN: mutating, deleting, or adding any attribute raises. The
21
+ author can read `ctx.wallet` but cannot rebind it (or scribble a backdoor onto
22
+ ctx). `state` and `senpi_mcp` are likewise immutable bindings on ctx — the author
23
+ uses them through their own APIs, never by reassigning the slot.
24
+ """
25
+
26
+ from __future__ import annotations
27
+
28
+ from typing import Any, Optional
29
+
30
+
31
+ class ScanContext:
32
+ """Frozen, read-only metadata + capability handles for scan(inputs, ctx).
33
+
34
+ Construction seam the scaffold uses:
35
+
36
+ ScanContext(
37
+ *,
38
+ state, # a StateManager instance (or None when history disabled)
39
+ wallet: str,
40
+ scanner_name: str,
41
+ interval_seconds: int,
42
+ senpi_mcp=None, # B5 fills this; None/absent this block
43
+ )
44
+ """
45
+
46
+ # Lock the attribute set: no __dict__, so any unknown attribute (mutate / add /
47
+ # delete) raises AttributeError. The five documented slots are the only ones.
48
+ __slots__ = ("state", "senpi_mcp", "wallet", "scanner_name", "interval_seconds")
49
+
50
+ def __init__(
51
+ self,
52
+ *,
53
+ state: Any,
54
+ wallet: str,
55
+ scanner_name: str,
56
+ interval_seconds: int,
57
+ senpi_mcp: Optional[Any] = None,
58
+ ) -> None:
59
+ # Bypass our own frozen __setattr__ to populate the slots once at
60
+ # construction. object.__setattr__ writes the slot directly.
61
+ object.__setattr__(self, "state", state)
62
+ object.__setattr__(self, "senpi_mcp", senpi_mcp)
63
+ object.__setattr__(self, "wallet", wallet)
64
+ object.__setattr__(self, "scanner_name", scanner_name)
65
+ object.__setattr__(self, "interval_seconds", interval_seconds)
66
+
67
+ # -- frozen: block every post-construction mutation --------------------
68
+
69
+ def __setattr__(self, name: str, value: Any) -> None:
70
+ raise AttributeError(
71
+ f"ctx is read-only: cannot set {name!r}. The metadata "
72
+ "(wallet/scanner_name/interval_seconds) is frozen, and the "
73
+ "capability slots (state/senpi_mcp) are used through their own APIs, "
74
+ "never reassigned."
75
+ )
76
+
77
+ def __delattr__(self, name: str) -> None:
78
+ raise AttributeError(f"ctx is read-only: cannot delete {name!r}.")
@@ -0,0 +1,263 @@
1
+ """Journal-backed delivery sink factory.
2
+
3
+ build_delivery_sink(
4
+ *,
5
+ scanner_id: str,
6
+ intake_url: str,
7
+ journal_path: str | None,
8
+ signal_data_schema: dict | None, # per-data-key {type, required?}; None = no validation
9
+ default_signal_validity_seconds: int, # fallback signal TTL (seconds)
10
+ timeout: float = 5.0,
11
+ clock: Callable[[], float] = time.time,
12
+ ) -> sink
13
+
14
+ The returned sink is a callable: sink(candidates)
15
+ On each call it:
16
+ 1. Replays journal on first call (if file-backed), re-queuing valid undelivered entries
17
+ 2. Flushes still-valid undelivered entries from prior ticks (retry)
18
+ 3. Wraps this tick's candidates into wire signals (skips invalid ones)
19
+ 4. Drops locally superseded / expired entries
20
+ 5. POSTs {scanner_id, signals:[...]} to <intake_url>/signals
21
+ 6. Interprets the response: accepted/expired/superseded/rejected = delivered;
22
+ transport failure or non-success envelope leaves entry queued for retry
23
+
24
+ sink.post_error(error: dict) -> None
25
+ POSTs {scanner_id, error} to <intake_url>/errors. Fire-and-forget.
26
+
27
+ Module constants:
28
+ SIGNALS_PATH = "/signals"
29
+ ERRORS_PATH = "/errors"
30
+ """
31
+
32
+ from __future__ import annotations
33
+
34
+ import sys
35
+ import time
36
+ import uuid
37
+ from typing import Any, Callable
38
+
39
+ from .http_post import ERRORS_PATH, SIGNALS_PATH, TransportError, post_json
40
+ from .journal import Journal
41
+ from .loop_primitives import log_event
42
+ from .signal_envelope import candidate_to_signal
43
+
44
+ # Terminal statuses from the intake — all mean "the runtime decided, no retry"
45
+ _TERMINAL_STATUSES = {"accepted", "expired", "superseded", "rejected"}
46
+
47
+
48
+ def build_delivery_sink(
49
+ *,
50
+ scanner_id: str,
51
+ intake_url: str,
52
+ journal_path: str | None,
53
+ signal_data_schema: dict | None,
54
+ default_signal_validity_seconds: int,
55
+ timeout: float = 5.0,
56
+ clock: Callable[[], float] = time.time,
57
+ ):
58
+ """Factory: build and return the delivery sink callable."""
59
+
60
+ journal = Journal(journal_path)
61
+ replayed = [False] # mutable cell; replay runs once on first invocation
62
+
63
+ # ------------------------------------------------------------------
64
+ # Internal helpers
65
+ # ------------------------------------------------------------------
66
+
67
+ def _now_ms() -> int:
68
+ return int(clock() * 1000)
69
+
70
+ def _flush_prior_pending(now_ms: int) -> list[tuple]:
71
+ """Return still-valid pending entries; drop expired ones with journal line.
72
+
73
+ Returns list of (_Entry, produced_id) to include in the next POST.
74
+ """
75
+ to_send = []
76
+ to_drop = []
77
+ for entry in list(journal.pending()):
78
+ # Belt-and-braces: guard against a non-numeric valid_until that survived
79
+ # into the in-memory queue (e.g. re-queued by a future code path or a
80
+ # replay edge case). Drop it instead of crashing with TypeError.
81
+ if not isinstance(entry.valid_until, (int, float)) or isinstance(entry.valid_until, bool):
82
+ to_drop.append(entry)
83
+ elif now_ms < entry.valid_until:
84
+ to_send.append(entry)
85
+ else:
86
+ to_drop.append(entry)
87
+ for entry in to_drop:
88
+ journal.record_outcome(entry.id, "dropped_expired")
89
+ log_event("delivery_dropped_expired", entry_id=entry.id, asset=entry.asset)
90
+ return to_send
91
+
92
+ def _on_reject(reason: dict) -> None:
93
+ """Loud rejection: log AND POST to /errors (design §4 — never a silent drop)."""
94
+ log_event("delivery_candidate_invalid", **reason)
95
+ _post_error({"type": "candidate_rejected", **reason})
96
+
97
+ def _wrap_candidates(candidates, produced_at_ms: int) -> list[tuple]:
98
+ """Wrap candidates into (signal, entry_id) pairs, skipping invalid ones.
99
+
100
+ Schema-rejected candidates are NOT silently dropped: candidate_to_signal
101
+ calls _on_reject, which logs AND POSTs to /errors.
102
+ """
103
+ result = []
104
+ for c in candidates:
105
+ # Mint the stable signal_id (the journal eid) up front and thread it
106
+ # through the envelope so the POSTed signal carries it. record_produced
107
+ # re-uses this same id as the entry id, so wire signal_id == journal eid.
108
+ eid = uuid.uuid4().hex
109
+ sig = candidate_to_signal(
110
+ c,
111
+ produced_at_ms,
112
+ signal_id=eid,
113
+ signal_data_schema=signal_data_schema,
114
+ default_signal_validity_seconds=default_signal_validity_seconds,
115
+ on_reject=_on_reject,
116
+ )
117
+ if sig is None:
118
+ continue
119
+ entry_id = journal.record_produced(sig, now_ms=produced_at_ms)
120
+ result.append((sig, entry_id))
121
+ return result
122
+
123
+ def _post_signals(signals: list[dict]) -> tuple[int, Any]:
124
+ """POST the signals list to the intake."""
125
+ body = {"scanner_id": scanner_id, "signals": signals}
126
+ # Log the exact wire shape so a 400 can be matched to the field that broke.
127
+ if signals:
128
+ log_event(
129
+ "delivery_post_signals",
130
+ scanner_id=scanner_id,
131
+ count=len(signals),
132
+ first_signal_keys=sorted(signals[0].keys()),
133
+ first_signal=signals[0],
134
+ )
135
+ url = intake_url.rstrip("/") + SIGNALS_PATH
136
+ return post_json(url, body, timeout)
137
+
138
+ def _interpret_response(status: int, parsed: Any, pending_eids: list[str], pending_entries: list) -> bool:
139
+ """Interpret POST response; journal outcomes. Returns True if successful envelope."""
140
+ if status != 200 or parsed is None:
141
+ if isinstance(parsed, dict):
142
+ err = parsed.get("error") or {}
143
+ body_code = err.get("code")
144
+ if body_code == "UNKNOWN_SCANNER":
145
+ log_event("delivery_unknown_scanner", scanner_id=scanner_id, status=status)
146
+ # Surface the intake's actual reject code+message (e.g. INVALID_SHAPE)
147
+ # instead of burying every non-200 under "unparseable".
148
+ log_event(
149
+ "delivery_rejected",
150
+ scanner_id=scanner_id,
151
+ status=status,
152
+ code=body_code,
153
+ message=err.get("message"),
154
+ body=repr(parsed)[:300],
155
+ )
156
+ else:
157
+ log_event("delivery_response_unparseable", status=status, raw=repr(parsed)[:300])
158
+ return False
159
+
160
+ if not isinstance(parsed, dict) or not parsed.get("success"):
161
+ log_event("delivery_response_unparseable", status=status, parsed=repr(parsed)[:200])
162
+ return False
163
+
164
+ # success: true -- read per-signal statuses
165
+ data = parsed.get("data") or {}
166
+ per_signal = data.get("signals") if isinstance(data, dict) else None
167
+ if not isinstance(per_signal, list):
168
+ per_signal = []
169
+
170
+ # Match per-signal outcomes BY signal_id, NEVER by array position. The wire
171
+ # signal_id IS the journal entry id, so a pending eid set is the lookup key.
172
+ # Index-matching would cross-attribute outcomes (asset A's "accepted"
173
+ # recorded against asset B) under out-of-order or partial responses —
174
+ # capital-sensitive. Robust to: out-of-order, partial (fewer statuses than
175
+ # signals), and unknown/missing signal_id (ignored safely, never applied by
176
+ # position). An unmatched entry stays pending and is retried.
177
+ pending = set(pending_eids)
178
+ for sig_status in per_signal:
179
+ if not isinstance(sig_status, dict):
180
+ continue
181
+ eid = sig_status.get("signal_id")
182
+ # Missing or unknown signal_id: cannot be matched -> ignore safely.
183
+ if not isinstance(eid, str) or eid not in pending:
184
+ log_event("delivery_status_unmatched", signal_id=eid)
185
+ continue
186
+ st = sig_status.get("status")
187
+ if st == "accepted":
188
+ journal.record_outcome(eid, "delivered", correlationId=sig_status.get("correlationId", ""))
189
+ elif st == "rejected":
190
+ journal.record_outcome(eid, "rejected", reason=sig_status.get("reason", ""))
191
+ elif st in ("expired", "superseded"):
192
+ journal.record_outcome(eid, st)
193
+ else:
194
+ # Unknown status — treat as undelivered (no outcome written)
195
+ log_event("delivery_unknown_status", entry_id=eid, status=st)
196
+ # Entries with no matching status returned stay pending (retry next tick).
197
+
198
+ return True
199
+
200
+ # ------------------------------------------------------------------
201
+ # The sink callable
202
+ # ------------------------------------------------------------------
203
+
204
+ def _sink(candidates) -> None:
205
+ # Replay journal on very first invocation
206
+ if not replayed[0]:
207
+ replayed[0] = True
208
+ journal.replay(_now_ms())
209
+
210
+ now_ms = _now_ms()
211
+ produced_at_ms = now_ms # single timestamp for the whole tick
212
+
213
+ # 1. Flush prior pending (retry candidates from older ticks)
214
+ prior_entries = _flush_prior_pending(now_ms)
215
+
216
+ # 2. Wrap new candidates into signals
217
+ new_signal_pairs = _wrap_candidates(candidates, produced_at_ms)
218
+
219
+ # Build the ordered signal list and corresponding entry-id list:
220
+ # prior entries first (retry), then new ones.
221
+ # But: if a new candidate for the same asset was just produced, the
222
+ # journal.record_produced already dropped the prior entry (dropped_superseded).
223
+ # We need to filter out prior entries that are now settled.
224
+ all_signals: list[dict] = []
225
+ all_eids: list[str] = []
226
+
227
+ for entry in prior_entries:
228
+ if not journal.is_settled(entry.id):
229
+ all_signals.append(entry.signal)
230
+ all_eids.append(entry.id)
231
+
232
+ for sig, eid in new_signal_pairs:
233
+ if not journal.is_settled(eid):
234
+ all_signals.append(sig)
235
+ all_eids.append(eid)
236
+
237
+ # 3. POST (always, even when signals==[])
238
+ try:
239
+ status, parsed = _post_signals(all_signals)
240
+ except TransportError as exc:
241
+ log_event("delivery_transport_error", error=str(exc))
242
+ # All signals remain undelivered -> retry on next tick
243
+ # Empty-list no-ops: nothing to retry (no produced lines were written)
244
+ return
245
+
246
+ # 4. Interpret response
247
+ # The response per-signal list corresponds only to all_signals that have
248
+ # produced entries (all_eids). Empty no-ops: no eids.
249
+ _interpret_response(status, parsed, all_eids, [])
250
+
251
+ def _post_error(error: dict) -> None:
252
+ """POST an error dict. Fire-and-forget."""
253
+ body = {"scanner_id": scanner_id, "error": error}
254
+ url = intake_url.rstrip("/") + ERRORS_PATH
255
+ try:
256
+ post_json(url, body, timeout)
257
+ except TransportError as exc:
258
+ log_event("delivery_error_post_failed", error=str(exc))
259
+ except Exception as exc: # noqa: BLE001
260
+ log_event("delivery_error_post_failed", error=str(exc))
261
+
262
+ _sink.post_error = _post_error # type: ignore[attr-defined]
263
+ return _sink
@@ -0,0 +1,151 @@
1
+ """Entrypoint loading and scan() compatibility verification.
2
+
3
+ Pure, unit-testable helpers — no side effects beyond sys.path mutation and imports.
4
+
5
+ Exported error types:
6
+ ScanEntrypointError — import failure, missing/non-callable scan.
7
+ ScanSignatureError — scan call-shape incompatible with the scaffold contract.
8
+
9
+ Both are importable from here AND from the package root (scaffold).
10
+ """
11
+
12
+ import importlib
13
+ import inspect
14
+ import sys
15
+ from typing import Any, Callable
16
+
17
+
18
+ class ScanEntrypointError(Exception):
19
+ """Import failure, or scan is missing / not callable."""
20
+
21
+
22
+ class ScanSignatureError(Exception):
23
+ """scan's call shape is incompatible with scan(inputs, ctx)."""
24
+
25
+
26
+ def add_path_to_sys_path(path: str) -> None:
27
+ """Insert `path` at sys.path[0]. Idempotent — never inserts a duplicate."""
28
+ if path not in sys.path:
29
+ sys.path.insert(0, path)
30
+
31
+
32
+ def import_entrypoint(path: str, entrypoint: str):
33
+ """Put `path` on sys.path, then import `entrypoint` by module name.
34
+
35
+ The recipe expresses `entrypoint` as a FILENAME (e.g. `scan.py`, the shape the
36
+ B1 launcher writes verbatim into the launch config and the §4a entrypoint FS
37
+ check validates). importlib needs a MODULE name, so a trailing `.py` is
38
+ stripped here — the only place the filename<->module-name bridge lives.
39
+
40
+ Raises ScanEntrypointError on any import/syntax/missing-sibling failure,
41
+ chaining the underlying exception.
42
+ """
43
+ add_path_to_sys_path(path)
44
+ module_name = entrypoint[:-3] if entrypoint.endswith(".py") else entrypoint
45
+ try:
46
+ # Force re-import when the module has been previously imported so that
47
+ # tests can write fresh modules to tmp_path without cache collisions.
48
+ if module_name in sys.modules:
49
+ del sys.modules[module_name]
50
+ return importlib.import_module(module_name)
51
+ except Exception as exc:
52
+ raise ScanEntrypointError(
53
+ f"Failed to import entrypoint '{entrypoint}' from '{path}': {exc}"
54
+ ) from exc
55
+
56
+
57
+ def locate_scan(module) -> Callable:
58
+ """Return the module's `scan` callable.
59
+
60
+ Raises ScanEntrypointError if scan is missing, None, or not callable.
61
+ """
62
+ scan = getattr(module, "scan", _MISSING)
63
+ if scan is _MISSING:
64
+ raise ScanEntrypointError(
65
+ f"Module '{getattr(module, '__name__', module)}' has no 'scan' attribute."
66
+ )
67
+ if scan is None or not callable(scan):
68
+ raise ScanEntrypointError(
69
+ f"'scan' in module '{getattr(module, '__name__', module)}' is not callable "
70
+ f"(got {type(scan).__name__!r})."
71
+ )
72
+ return scan
73
+
74
+
75
+ def verify_scan_signature(scan: Callable) -> None:
76
+ """Verify scan's call shape is compatible with the v2 contract scan(inputs, ctx).
77
+
78
+ v2 calls scan with EXACTLY two positionals (inputs, ctx). A signature must be
79
+ callable that way.
80
+
81
+ Accepted shapes:
82
+ scan(inputs, ctx) — 2 required (the canonical shape)
83
+ scan(inputs, ctx, extra=None) — 2 required + defaulted extra
84
+ scan(inputs, ctx, *args) — variadic absorbs nothing extra here
85
+ scan(*args, **kwargs) — fully variadic, accepts anything
86
+
87
+ Rejected shapes:
88
+ scan() — 0 required
89
+ scan(inputs) — 1 required
90
+ scan(params, state, client) — 3 required (the OLD v1 client shape)
91
+ scan(a, b, c, d) — >=4 required
92
+
93
+ The contract is now EXACTLY two positionals: a 3rd REQUIRED positional cannot
94
+ be satisfied by scan(inputs, ctx) and is rejected.
95
+
96
+ Raises ScanSignatureError naming the found arity on mismatch.
97
+ """
98
+ try:
99
+ sig = inspect.signature(scan)
100
+ except (ValueError, TypeError):
101
+ # Builtins or C extensions without introspectable signatures: accept.
102
+ return
103
+
104
+ params = list(sig.parameters.values())
105
+
106
+ has_var_positional = any(
107
+ p.kind == inspect.Parameter.VAR_POSITIONAL for p in params
108
+ )
109
+
110
+ # Required (non-defaulted) fixed positional params.
111
+ required_fixed = [
112
+ p for p in params
113
+ if p.kind in (
114
+ inspect.Parameter.POSITIONAL_ONLY,
115
+ inspect.Parameter.POSITIONAL_OR_KEYWORD,
116
+ )
117
+ and p.default is inspect.Parameter.empty
118
+ ]
119
+ n_required = len(required_fixed)
120
+
121
+ # A *args (or *args/**kwargs) signature accepts the 2-positional call as long
122
+ # as it has no MORE than 2 required fixed positionals ahead of *args.
123
+ if has_var_positional:
124
+ if n_required > 2:
125
+ raise ScanSignatureError(
126
+ f"scan requires {n_required} fixed positional params; the v2 "
127
+ f"contract calls scan(inputs, ctx) — exactly 2. Found arity: {n_required}."
128
+ )
129
+ return
130
+
131
+ if n_required < 2:
132
+ raise ScanSignatureError(
133
+ f"scan has {n_required} required positional param(s); the v2 contract "
134
+ f"requires exactly 2 (inputs, ctx). Found arity: {n_required}."
135
+ )
136
+
137
+ if n_required > 2:
138
+ raise ScanSignatureError(
139
+ f"scan has {n_required} required positional params; the v2 contract "
140
+ f"calls scan(inputs, ctx) — exactly 2. A 3rd required positional "
141
+ f"(the old v1 client shape) is no longer accepted. Found arity: {n_required}."
142
+ )
143
+
144
+
145
+ # Private sentinel — distinct from None so getattr(..., None) doesn't hide a
146
+ # real `scan = None` attribute.
147
+ class _MissingSentinel:
148
+ pass
149
+
150
+
151
+ _MISSING = _MissingSentinel()