@ruverd/julius 0.0.0-stage → 0.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (704) hide show
  1. package/CHANGELOG.md +31 -0
  2. package/CREDITS.md +25 -0
  3. package/LICENSE +21 -0
  4. package/PROVENANCE.md +9 -0
  5. package/README.md +225 -2
  6. package/dist/ai/crux.d.ts +60 -0
  7. package/dist/ai/crux.d.ts.map +1 -0
  8. package/dist/ai/crux.js +141 -0
  9. package/dist/ai/crux.js.map +1 -0
  10. package/dist/ai/failure.d.ts +60 -0
  11. package/dist/ai/failure.d.ts.map +1 -0
  12. package/dist/ai/failure.js +86 -0
  13. package/dist/ai/failure.js.map +1 -0
  14. package/dist/ai/llm/anthropic.d.ts +37 -0
  15. package/dist/ai/llm/anthropic.d.ts.map +1 -0
  16. package/dist/ai/llm/anthropic.js +144 -0
  17. package/dist/ai/llm/anthropic.js.map +1 -0
  18. package/dist/ai/llm/factory.d.ts +28 -0
  19. package/dist/ai/llm/factory.d.ts.map +1 -0
  20. package/dist/ai/llm/factory.js +36 -0
  21. package/dist/ai/llm/factory.js.map +1 -0
  22. package/dist/ai/llm/litellm.d.ts +34 -0
  23. package/dist/ai/llm/litellm.d.ts.map +1 -0
  24. package/dist/ai/llm/litellm.js +45 -0
  25. package/dist/ai/llm/litellm.js.map +1 -0
  26. package/dist/ai/llm/openai.d.ts +44 -0
  27. package/dist/ai/llm/openai.d.ts.map +1 -0
  28. package/dist/ai/llm/openai.js +239 -0
  29. package/dist/ai/llm/openai.js.map +1 -0
  30. package/dist/ai/llm/orcarouter.d.ts +34 -0
  31. package/dist/ai/llm/orcarouter.d.ts.map +1 -0
  32. package/dist/ai/llm/orcarouter.js +45 -0
  33. package/dist/ai/llm/orcarouter.js.map +1 -0
  34. package/dist/ai/llm/recover-tool.d.ts +19 -0
  35. package/dist/ai/llm/recover-tool.d.ts.map +1 -0
  36. package/dist/ai/llm/recover-tool.js +109 -0
  37. package/dist/ai/llm/recover-tool.js.map +1 -0
  38. package/dist/ai/llm/types.d.ts +122 -0
  39. package/dist/ai/llm/types.d.ts.map +1 -0
  40. package/dist/ai/llm/types.js +33 -0
  41. package/dist/ai/llm/types.js.map +1 -0
  42. package/dist/ai/providers.d.ts +59 -0
  43. package/dist/ai/providers.d.ts.map +1 -0
  44. package/dist/ai/providers.js +54 -0
  45. package/dist/ai/providers.js.map +1 -0
  46. package/dist/ai/summarize.d.ts +25 -0
  47. package/dist/ai/summarize.d.ts.map +1 -0
  48. package/dist/ai/summarize.js +34 -0
  49. package/dist/ai/summarize.js.map +1 -0
  50. package/dist/ai/synthesize.d.ts +40 -0
  51. package/dist/ai/synthesize.d.ts.map +1 -0
  52. package/dist/ai/synthesize.js +131 -0
  53. package/dist/ai/synthesize.js.map +1 -0
  54. package/dist/app/checkout.d.ts +46 -0
  55. package/dist/app/checkout.d.ts.map +1 -0
  56. package/dist/app/checkout.js +223 -0
  57. package/dist/app/checkout.js.map +1 -0
  58. package/dist/app/events.d.ts +44 -0
  59. package/dist/app/events.d.ts.map +1 -0
  60. package/dist/app/events.js +64 -0
  61. package/dist/app/events.js.map +1 -0
  62. package/dist/app/identity.d.ts +54 -0
  63. package/dist/app/identity.d.ts.map +1 -0
  64. package/dist/app/identity.js +96 -0
  65. package/dist/app/identity.js.map +1 -0
  66. package/dist/app/main.d.ts +2 -0
  67. package/dist/app/main.d.ts.map +1 -0
  68. package/dist/app/main.js +62 -0
  69. package/dist/app/main.js.map +1 -0
  70. package/dist/app/pages.d.ts +56 -0
  71. package/dist/app/pages.d.ts.map +1 -0
  72. package/dist/app/pages.js +193 -0
  73. package/dist/app/pages.js.map +1 -0
  74. package/dist/app/queue.d.ts +40 -0
  75. package/dist/app/queue.d.ts.map +1 -0
  76. package/dist/app/queue.js +68 -0
  77. package/dist/app/queue.js.map +1 -0
  78. package/dist/app/review-process.d.ts +66 -0
  79. package/dist/app/review-process.d.ts.map +1 -0
  80. package/dist/app/review-process.js +200 -0
  81. package/dist/app/review-process.js.map +1 -0
  82. package/dist/app/review-worker.d.ts +2 -0
  83. package/dist/app/review-worker.d.ts.map +1 -0
  84. package/dist/app/review-worker.js +108 -0
  85. package/dist/app/review-worker.js.map +1 -0
  86. package/dist/app/review.d.ts +23 -0
  87. package/dist/app/review.d.ts.map +1 -0
  88. package/dist/app/review.js +142 -0
  89. package/dist/app/review.js.map +1 -0
  90. package/dist/app/server.d.ts +49 -0
  91. package/dist/app/server.d.ts.map +1 -0
  92. package/dist/app/server.js +123 -0
  93. package/dist/app/server.js.map +1 -0
  94. package/dist/ask/ask.d.ts +195 -0
  95. package/dist/ask/ask.d.ts.map +1 -0
  96. package/dist/ask/ask.js +1252 -0
  97. package/dist/ask/ask.js.map +1 -0
  98. package/dist/ask/file-rank.d.ts +72 -0
  99. package/dist/ask/file-rank.d.ts.map +1 -0
  100. package/dist/ask/file-rank.js +160 -0
  101. package/dist/ask/file-rank.js.map +1 -0
  102. package/dist/ask/file-selection.d.ts +22 -0
  103. package/dist/ask/file-selection.d.ts.map +1 -0
  104. package/dist/ask/file-selection.js +66 -0
  105. package/dist/ask/file-selection.js.map +1 -0
  106. package/dist/ask/fuse.d.ts +195 -0
  107. package/dist/ask/fuse.d.ts.map +1 -0
  108. package/dist/ask/fuse.js +344 -0
  109. package/dist/ask/fuse.js.map +1 -0
  110. package/dist/ask/graphrank.d.ts +61 -0
  111. package/dist/ask/graphrank.d.ts.map +1 -0
  112. package/dist/ask/graphrank.js +130 -0
  113. package/dist/ask/graphrank.js.map +1 -0
  114. package/dist/ask/index-file.d.ts +44 -0
  115. package/dist/ask/index-file.d.ts.map +1 -0
  116. package/dist/ask/index-file.js +128 -0
  117. package/dist/ask/index-file.js.map +1 -0
  118. package/dist/bin/julius.d.ts +3 -0
  119. package/dist/bin/julius.d.ts.map +1 -0
  120. package/dist/bin/julius.js +4 -0
  121. package/dist/bin/julius.js.map +1 -0
  122. package/dist/blast/blast-cli.d.ts +35 -0
  123. package/dist/blast/blast-cli.d.ts.map +1 -0
  124. package/dist/blast/blast-cli.js +155 -0
  125. package/dist/blast/blast-cli.js.map +1 -0
  126. package/dist/blast/blast.d.ts +128 -0
  127. package/dist/blast/blast.d.ts.map +1 -0
  128. package/dist/blast/blast.js +383 -0
  129. package/dist/blast/blast.js.map +1 -0
  130. package/dist/blast/diff.d.ts +53 -0
  131. package/dist/blast/diff.d.ts.map +1 -0
  132. package/dist/blast/diff.js +193 -0
  133. package/dist/blast/diff.js.map +1 -0
  134. package/dist/blast/evidence.d.ts +51 -0
  135. package/dist/blast/evidence.d.ts.map +1 -0
  136. package/dist/blast/evidence.js +162 -0
  137. package/dist/blast/evidence.js.map +1 -0
  138. package/dist/blast/modules.d.ts +33 -0
  139. package/dist/blast/modules.d.ts.map +1 -0
  140. package/dist/blast/modules.js +83 -0
  141. package/dist/blast/modules.js.map +1 -0
  142. package/dist/blast/name.d.ts +74 -0
  143. package/dist/blast/name.d.ts.map +1 -0
  144. package/dist/blast/name.js +269 -0
  145. package/dist/blast/name.js.map +1 -0
  146. package/dist/blast/owners.d.ts +85 -0
  147. package/dist/blast/owners.d.ts.map +1 -0
  148. package/dist/blast/owners.js +272 -0
  149. package/dist/blast/owners.js.map +1 -0
  150. package/dist/blast/render.d.ts +46 -0
  151. package/dist/blast/render.d.ts.map +1 -0
  152. package/dist/blast/render.js +422 -0
  153. package/dist/blast/render.js.map +1 -0
  154. package/dist/blast/viz.d.ts +37 -0
  155. package/dist/blast/viz.d.ts.map +1 -0
  156. package/dist/blast/viz.js +180 -0
  157. package/dist/blast/viz.js.map +1 -0
  158. package/dist/brand.d.ts +13 -0
  159. package/dist/brand.d.ts.map +1 -0
  160. package/dist/brand.js +43 -0
  161. package/dist/brand.js.map +1 -0
  162. package/dist/check/learning-edits.d.ts +9 -0
  163. package/dist/check/learning-edits.d.ts.map +1 -0
  164. package/dist/check/learning-edits.js +62 -0
  165. package/dist/check/learning-edits.js.map +1 -0
  166. package/dist/check/local-check.d.ts +104 -0
  167. package/dist/check/local-check.d.ts.map +1 -0
  168. package/dist/check/local-check.js +830 -0
  169. package/dist/check/local-check.js.map +1 -0
  170. package/dist/check/types.d.ts +31 -0
  171. package/dist/check/types.d.ts.map +1 -0
  172. package/dist/check/types.js +2 -0
  173. package/dist/check/types.js.map +1 -0
  174. package/dist/claude/build-progress.d.ts +29 -0
  175. package/dist/claude/build-progress.d.ts.map +1 -0
  176. package/dist/claude/build-progress.js +76 -0
  177. package/dist/claude/build-progress.js.map +1 -0
  178. package/dist/claude/format.d.ts +131 -0
  179. package/dist/claude/format.d.ts.map +1 -0
  180. package/dist/claude/format.js +328 -0
  181. package/dist/claude/format.js.map +1 -0
  182. package/dist/claude/hook-layers.d.ts +8 -0
  183. package/dist/claude/hook-layers.d.ts.map +1 -0
  184. package/dist/claude/hook-layers.js +74 -0
  185. package/dist/claude/hook-layers.js.map +1 -0
  186. package/dist/claude/hooks.d.ts +101 -0
  187. package/dist/claude/hooks.d.ts.map +1 -0
  188. package/dist/claude/hooks.js +849 -0
  189. package/dist/claude/hooks.js.map +1 -0
  190. package/dist/claude/init.d.ts +70 -0
  191. package/dist/claude/init.d.ts.map +1 -0
  192. package/dist/claude/init.js +207 -0
  193. package/dist/claude/init.js.map +1 -0
  194. package/dist/claude/note-signals.d.ts +28 -0
  195. package/dist/claude/note-signals.d.ts.map +1 -0
  196. package/dist/claude/note-signals.js +325 -0
  197. package/dist/claude/note-signals.js.map +1 -0
  198. package/dist/claude/paths.d.ts +9 -0
  199. package/dist/claude/paths.d.ts.map +1 -0
  200. package/dist/claude/paths.js +22 -0
  201. package/dist/claude/paths.js.map +1 -0
  202. package/dist/claude/session-metrics.d.ts +73 -0
  203. package/dist/claude/session-metrics.d.ts.map +1 -0
  204. package/dist/claude/session-metrics.js +209 -0
  205. package/dist/claude/session-metrics.js.map +1 -0
  206. package/dist/claude/settings-merge.d.ts +66 -0
  207. package/dist/claude/settings-merge.d.ts.map +1 -0
  208. package/dist/claude/settings-merge.js +249 -0
  209. package/dist/claude/settings-merge.js.map +1 -0
  210. package/dist/claude/shim-template.d.ts +18 -0
  211. package/dist/claude/shim-template.d.ts.map +1 -0
  212. package/dist/claude/shim-template.js +226 -0
  213. package/dist/claude/shim-template.js.map +1 -0
  214. package/dist/claude/skill-template.d.ts +12 -0
  215. package/dist/claude/skill-template.d.ts.map +1 -0
  216. package/dist/claude/skill-template.js +294 -0
  217. package/dist/claude/skill-template.js.map +1 -0
  218. package/dist/claude/state.d.ts +73 -0
  219. package/dist/claude/state.d.ts.map +1 -0
  220. package/dist/claude/state.js +33 -0
  221. package/dist/claude/state.js.map +1 -0
  222. package/dist/claude/stats.d.ts +5 -0
  223. package/dist/claude/stats.d.ts.map +1 -0
  224. package/dist/claude/stats.js +24 -0
  225. package/dist/claude/stats.js.map +1 -0
  226. package/dist/claude/statusline.d.ts +14 -0
  227. package/dist/claude/statusline.d.ts.map +1 -0
  228. package/dist/claude/statusline.js +45 -0
  229. package/dist/claude/statusline.js.map +1 -0
  230. package/dist/claude/sync-run.d.ts +3 -0
  231. package/dist/claude/sync-run.d.ts.map +1 -0
  232. package/dist/claude/sync-run.js +46 -0
  233. package/dist/claude/sync-run.js.map +1 -0
  234. package/dist/claude/tally.d.ts +50 -0
  235. package/dist/claude/tally.d.ts.map +1 -0
  236. package/dist/claude/tally.js +211 -0
  237. package/dist/claude/tally.js.map +1 -0
  238. package/dist/cli-epilogue.d.ts +12 -0
  239. package/dist/cli-epilogue.d.ts.map +1 -0
  240. package/dist/cli-epilogue.js +55 -0
  241. package/dist/cli-epilogue.js.map +1 -0
  242. package/dist/cli-meta.d.ts +45 -0
  243. package/dist/cli-meta.d.ts.map +1 -0
  244. package/dist/cli-meta.js +145 -0
  245. package/dist/cli-meta.js.map +1 -0
  246. package/dist/cli-picker.d.ts +129 -0
  247. package/dist/cli-picker.d.ts.map +1 -0
  248. package/dist/cli-picker.js +432 -0
  249. package/dist/cli-picker.js.map +1 -0
  250. package/dist/cli.d.ts +3 -0
  251. package/dist/cli.d.ts.map +1 -0
  252. package/dist/cli.js +2213 -0
  253. package/dist/cli.js.map +1 -0
  254. package/dist/cloud/diff.d.ts +20 -0
  255. package/dist/cloud/diff.d.ts.map +1 -0
  256. package/dist/cloud/diff.js +59 -0
  257. package/dist/cloud/diff.js.map +1 -0
  258. package/dist/cloud/nudge.d.ts +66 -0
  259. package/dist/cloud/nudge.d.ts.map +1 -0
  260. package/dist/cloud/nudge.js +268 -0
  261. package/dist/cloud/nudge.js.map +1 -0
  262. package/dist/cloud/workspace-sync.d.ts +58 -0
  263. package/dist/cloud/workspace-sync.d.ts.map +1 -0
  264. package/dist/cloud/workspace-sync.js +268 -0
  265. package/dist/cloud/workspace-sync.js.map +1 -0
  266. package/dist/cloud/workspace.d.ts +159 -0
  267. package/dist/cloud/workspace.d.ts.map +1 -0
  268. package/dist/cloud/workspace.js +134 -0
  269. package/dist/cloud/workspace.js.map +1 -0
  270. package/dist/context/build.d.ts +52 -0
  271. package/dist/context/build.d.ts.map +1 -0
  272. package/dist/context/build.js +362 -0
  273. package/dist/context/build.js.map +1 -0
  274. package/dist/context/check.d.ts +42 -0
  275. package/dist/context/check.d.ts.map +1 -0
  276. package/dist/context/check.js +162 -0
  277. package/dist/context/check.js.map +1 -0
  278. package/dist/context/map-dir.d.ts +4 -0
  279. package/dist/context/map-dir.d.ts.map +1 -0
  280. package/dist/context/map-dir.js +6 -0
  281. package/dist/context/map-dir.js.map +1 -0
  282. package/dist/context/node-file.d.ts +109 -0
  283. package/dist/context/node-file.d.ts.map +1 -0
  284. package/dist/context/node-file.js +362 -0
  285. package/dist/context/node-file.js.map +1 -0
  286. package/dist/context/price.d.ts +49 -0
  287. package/dist/context/price.d.ts.map +1 -0
  288. package/dist/context/price.js +83 -0
  289. package/dist/context/price.js.map +1 -0
  290. package/dist/context/savings.d.ts +26 -0
  291. package/dist/context/savings.d.ts.map +1 -0
  292. package/dist/context/savings.js +59 -0
  293. package/dist/context/savings.js.map +1 -0
  294. package/dist/economy/cli.d.ts +3 -0
  295. package/dist/economy/cli.d.ts.map +1 -0
  296. package/dist/economy/cli.js +52 -0
  297. package/dist/economy/cli.js.map +1 -0
  298. package/dist/economy/delivery.d.ts +49 -0
  299. package/dist/economy/delivery.d.ts.map +1 -0
  300. package/dist/economy/delivery.js +176 -0
  301. package/dist/economy/delivery.js.map +1 -0
  302. package/dist/economy/index.d.ts +67 -0
  303. package/dist/economy/index.d.ts.map +1 -0
  304. package/dist/economy/index.js +519 -0
  305. package/dist/economy/index.js.map +1 -0
  306. package/dist/engine.d.ts +83 -0
  307. package/dist/engine.d.ts.map +1 -0
  308. package/dist/engine.js +122 -0
  309. package/dist/engine.js.map +1 -0
  310. package/dist/evaluation/index.d.ts +41 -0
  311. package/dist/evaluation/index.d.ts.map +1 -0
  312. package/dist/evaluation/index.js +61 -0
  313. package/dist/evaluation/index.js.map +1 -0
  314. package/dist/graph/bindings.d.ts +64 -0
  315. package/dist/graph/bindings.d.ts.map +1 -0
  316. package/dist/graph/bindings.js +713 -0
  317. package/dist/graph/bindings.js.map +1 -0
  318. package/dist/graph/build.d.ts +88 -0
  319. package/dist/graph/build.d.ts.map +1 -0
  320. package/dist/graph/build.js +375 -0
  321. package/dist/graph/build.js.map +1 -0
  322. package/dist/graph/cards.d.ts +46 -0
  323. package/dist/graph/cards.d.ts.map +1 -0
  324. package/dist/graph/cards.js +280 -0
  325. package/dist/graph/cards.js.map +1 -0
  326. package/dist/graph/check.d.ts +25 -0
  327. package/dist/graph/check.d.ts.map +1 -0
  328. package/dist/graph/check.js +192 -0
  329. package/dist/graph/check.js.map +1 -0
  330. package/dist/graph/container.d.ts +63 -0
  331. package/dist/graph/container.d.ts.map +1 -0
  332. package/dist/graph/container.js +190 -0
  333. package/dist/graph/container.js.map +1 -0
  334. package/dist/graph/enrich.d.ts +62 -0
  335. package/dist/graph/enrich.d.ts.map +1 -0
  336. package/dist/graph/enrich.js +253 -0
  337. package/dist/graph/enrich.js.map +1 -0
  338. package/dist/graph/extract-cache.d.ts +101 -0
  339. package/dist/graph/extract-cache.d.ts.map +1 -0
  340. package/dist/graph/extract-cache.js +199 -0
  341. package/dist/graph/extract-cache.js.map +1 -0
  342. package/dist/graph/extract.d.ts +85 -0
  343. package/dist/graph/extract.d.ts.map +1 -0
  344. package/dist/graph/extract.js +2376 -0
  345. package/dist/graph/extract.js.map +1 -0
  346. package/dist/graph/fingerprint.d.ts +76 -0
  347. package/dist/graph/fingerprint.d.ts.map +1 -0
  348. package/dist/graph/fingerprint.js +160 -0
  349. package/dist/graph/fingerprint.js.map +1 -0
  350. package/dist/graph/generic.d.ts +74 -0
  351. package/dist/graph/generic.d.ts.map +1 -0
  352. package/dist/graph/generic.js +580 -0
  353. package/dist/graph/generic.js.map +1 -0
  354. package/dist/graph/invariants.d.ts +33 -0
  355. package/dist/graph/invariants.d.ts.map +1 -0
  356. package/dist/graph/invariants.js +52 -0
  357. package/dist/graph/invariants.js.map +1 -0
  358. package/dist/graph/load.d.ts +29 -0
  359. package/dist/graph/load.d.ts.map +1 -0
  360. package/dist/graph/load.js +97 -0
  361. package/dist/graph/load.js.map +1 -0
  362. package/dist/graph/lsp/client.d.ts +43 -0
  363. package/dist/graph/lsp/client.d.ts.map +1 -0
  364. package/dist/graph/lsp/client.js +179 -0
  365. package/dist/graph/lsp/client.js.map +1 -0
  366. package/dist/graph/lsp/enrich.d.ts +11 -0
  367. package/dist/graph/lsp/enrich.d.ts.map +1 -0
  368. package/dist/graph/lsp/enrich.js +155 -0
  369. package/dist/graph/lsp/enrich.js.map +1 -0
  370. package/dist/graph/lsp/registry.d.ts +15 -0
  371. package/dist/graph/lsp/registry.d.ts.map +1 -0
  372. package/dist/graph/lsp/registry.js +46 -0
  373. package/dist/graph/lsp/registry.js.map +1 -0
  374. package/dist/graph/map.d.ts +107 -0
  375. package/dist/graph/map.d.ts.map +1 -0
  376. package/dist/graph/map.js +239 -0
  377. package/dist/graph/map.js.map +1 -0
  378. package/dist/graph/native.d.ts +38 -0
  379. package/dist/graph/native.d.ts.map +1 -0
  380. package/dist/graph/native.js +169 -0
  381. package/dist/graph/native.js.map +1 -0
  382. package/dist/graph/queries/c.scm +13 -0
  383. package/dist/graph/queries/c_sharp.scm +19 -0
  384. package/dist/graph/queries/clojure.scm +58 -0
  385. package/dist/graph/queries/cpp.scm +23 -0
  386. package/dist/graph/queries/dart.scm +42 -0
  387. package/dist/graph/queries/elixir.scm +54 -0
  388. package/dist/graph/queries/java.scm +20 -0
  389. package/dist/graph/queries/kotlin.scm +43 -0
  390. package/dist/graph/queries/lua.scm +36 -0
  391. package/dist/graph/queries/nix.scm +32 -0
  392. package/dist/graph/queries/php.scm +40 -0
  393. package/dist/graph/queries/ruby.scm +65 -0
  394. package/dist/graph/queries/rust.scm +41 -0
  395. package/dist/graph/queries/scala.scm +66 -0
  396. package/dist/graph/queries/solidity.scm +43 -0
  397. package/dist/graph/queries/swift.scm +51 -0
  398. package/dist/graph/refresh.d.ts +49 -0
  399. package/dist/graph/refresh.d.ts.map +1 -0
  400. package/dist/graph/refresh.js +255 -0
  401. package/dist/graph/refresh.js.map +1 -0
  402. package/dist/graph/relations.d.ts +14 -0
  403. package/dist/graph/relations.d.ts.map +1 -0
  404. package/dist/graph/relations.js +8 -0
  405. package/dist/graph/relations.js.map +1 -0
  406. package/dist/graph/resolve.d.ts +17 -0
  407. package/dist/graph/resolve.d.ts.map +1 -0
  408. package/dist/graph/resolve.js +654 -0
  409. package/dist/graph/resolve.js.map +1 -0
  410. package/dist/graph/root.d.ts +11 -0
  411. package/dist/graph/root.d.ts.map +1 -0
  412. package/dist/graph/root.js +40 -0
  413. package/dist/graph/root.js.map +1 -0
  414. package/dist/graph/scopes.d.ts +42 -0
  415. package/dist/graph/scopes.d.ts.map +1 -0
  416. package/dist/graph/scopes.js +342 -0
  417. package/dist/graph/scopes.js.map +1 -0
  418. package/dist/graph/seed.d.ts +38 -0
  419. package/dist/graph/seed.d.ts.map +1 -0
  420. package/dist/graph/seed.js +226 -0
  421. package/dist/graph/seed.js.map +1 -0
  422. package/dist/graph/source-files.d.ts +40 -0
  423. package/dist/graph/source-files.d.ts.map +1 -0
  424. package/dist/graph/source-files.js +85 -0
  425. package/dist/graph/source-files.js.map +1 -0
  426. package/dist/graph/traverse-cli.d.ts +55 -0
  427. package/dist/graph/traverse-cli.d.ts.map +1 -0
  428. package/dist/graph/traverse-cli.js +189 -0
  429. package/dist/graph/traverse-cli.js.map +1 -0
  430. package/dist/graph/traverse.d.ts +112 -0
  431. package/dist/graph/traverse.d.ts.map +1 -0
  432. package/dist/graph/traverse.js +192 -0
  433. package/dist/graph/traverse.js.map +1 -0
  434. package/dist/graph/types.d.ts +78 -0
  435. package/dist/graph/types.d.ts.map +1 -0
  436. package/dist/graph/types.js +14 -0
  437. package/dist/graph/types.js.map +1 -0
  438. package/dist/graph/workspace-cli.d.ts +48 -0
  439. package/dist/graph/workspace-cli.d.ts.map +1 -0
  440. package/dist/graph/workspace-cli.js +102 -0
  441. package/dist/graph/workspace-cli.js.map +1 -0
  442. package/dist/graph/workspace.d.ts +135 -0
  443. package/dist/graph/workspace.d.ts.map +1 -0
  444. package/dist/graph/workspace.js +598 -0
  445. package/dist/graph/workspace.js.map +1 -0
  446. package/dist/graph/write.d.ts +13 -0
  447. package/dist/graph/write.d.ts.map +1 -0
  448. package/dist/graph/write.js +86 -0
  449. package/dist/graph/write.js.map +1 -0
  450. package/dist/hosts/antigravity.d.ts +8 -0
  451. package/dist/hosts/antigravity.d.ts.map +1 -0
  452. package/dist/hosts/antigravity.js +42 -0
  453. package/dist/hosts/antigravity.js.map +1 -0
  454. package/dist/hosts/claude-global.d.ts +36 -0
  455. package/dist/hosts/claude-global.d.ts.map +1 -0
  456. package/dist/hosts/claude-global.js +153 -0
  457. package/dist/hosts/claude-global.js.map +1 -0
  458. package/dist/hosts/codex-hooks.d.ts +11 -0
  459. package/dist/hosts/codex-hooks.d.ts.map +1 -0
  460. package/dist/hosts/codex-hooks.js +80 -0
  461. package/dist/hosts/codex-hooks.js.map +1 -0
  462. package/dist/hosts/config-write.d.ts +36 -0
  463. package/dist/hosts/config-write.d.ts.map +1 -0
  464. package/dist/hosts/config-write.js +64 -0
  465. package/dist/hosts/config-write.js.map +1 -0
  466. package/dist/hosts/cursor-hooks.d.ts +21 -0
  467. package/dist/hosts/cursor-hooks.d.ts.map +1 -0
  468. package/dist/hosts/cursor-hooks.js +103 -0
  469. package/dist/hosts/cursor-hooks.js.map +1 -0
  470. package/dist/hosts/init.d.ts +26 -0
  471. package/dist/hosts/init.d.ts.map +1 -0
  472. package/dist/hosts/init.js +82 -0
  473. package/dist/hosts/init.js.map +1 -0
  474. package/dist/hosts/install.d.ts +12 -0
  475. package/dist/hosts/install.d.ts.map +1 -0
  476. package/dist/hosts/install.js +347 -0
  477. package/dist/hosts/install.js.map +1 -0
  478. package/dist/hosts/instructions.d.ts +7 -0
  479. package/dist/hosts/instructions.d.ts.map +1 -0
  480. package/dist/hosts/instructions.js +71 -0
  481. package/dist/hosts/instructions.js.map +1 -0
  482. package/dist/hosts/investigation-instructions.d.ts +2 -0
  483. package/dist/hosts/investigation-instructions.d.ts.map +1 -0
  484. package/dist/hosts/investigation-instructions.js +2 -0
  485. package/dist/hosts/investigation-instructions.js.map +1 -0
  486. package/dist/hosts/mcp-config.d.ts +59 -0
  487. package/dist/hosts/mcp-config.d.ts.map +1 -0
  488. package/dist/hosts/mcp-config.js +229 -0
  489. package/dist/hosts/mcp-config.js.map +1 -0
  490. package/dist/hosts/plan.d.ts +32 -0
  491. package/dist/hosts/plan.d.ts.map +1 -0
  492. package/dist/hosts/plan.js +77 -0
  493. package/dist/hosts/plan.js.map +1 -0
  494. package/dist/hosts/registry.d.ts +35 -0
  495. package/dist/hosts/registry.d.ts.map +1 -0
  496. package/dist/hosts/registry.js +157 -0
  497. package/dist/hosts/registry.js.map +1 -0
  498. package/dist/hosts/retract.d.ts +47 -0
  499. package/dist/hosts/retract.d.ts.map +1 -0
  500. package/dist/hosts/retract.js +541 -0
  501. package/dist/hosts/retract.js.map +1 -0
  502. package/dist/hosts/sections.d.ts +46 -0
  503. package/dist/hosts/sections.d.ts.map +1 -0
  504. package/dist/hosts/sections.js +126 -0
  505. package/dist/hosts/sections.js.map +1 -0
  506. package/dist/index.d.ts +43 -0
  507. package/dist/index.d.ts.map +1 -0
  508. package/dist/index.js +33 -0
  509. package/dist/index.js.map +1 -0
  510. package/dist/ingest/fs.d.ts +79 -0
  511. package/dist/ingest/fs.d.ts.map +1 -0
  512. package/dist/ingest/fs.js +307 -0
  513. package/dist/ingest/fs.js.map +1 -0
  514. package/dist/init-guard.d.ts +11 -0
  515. package/dist/init-guard.d.ts.map +1 -0
  516. package/dist/init-guard.js +21 -0
  517. package/dist/init-guard.js.map +1 -0
  518. package/dist/investigation/index.d.ts +57 -0
  519. package/dist/investigation/index.d.ts.map +1 -0
  520. package/dist/investigation/index.js +315 -0
  521. package/dist/investigation/index.js.map +1 -0
  522. package/dist/mcp/compact.d.ts +9 -0
  523. package/dist/mcp/compact.d.ts.map +1 -0
  524. package/dist/mcp/compact.js +133 -0
  525. package/dist/mcp/compact.js.map +1 -0
  526. package/dist/mcp/instructions.d.ts +5 -0
  527. package/dist/mcp/instructions.d.ts.map +1 -0
  528. package/dist/mcp/instructions.js +57 -0
  529. package/dist/mcp/instructions.js.map +1 -0
  530. package/dist/mcp/server.d.ts +7 -0
  531. package/dist/mcp/server.d.ts.map +1 -0
  532. package/dist/mcp/server.js +128 -0
  533. package/dist/mcp/server.js.map +1 -0
  534. package/dist/mcp/tool-names.d.ts +20 -0
  535. package/dist/mcp/tool-names.d.ts.map +1 -0
  536. package/dist/mcp/tool-names.js +36 -0
  537. package/dist/mcp/tool-names.js.map +1 -0
  538. package/dist/mcp/tools.d.ts +22 -0
  539. package/dist/mcp/tools.d.ts.map +1 -0
  540. package/dist/mcp/tools.js +300 -0
  541. package/dist/mcp/tools.js.map +1 -0
  542. package/dist/notes/ask-notes.d.ts +8 -0
  543. package/dist/notes/ask-notes.d.ts.map +1 -0
  544. package/dist/notes/ask-notes.js +19 -0
  545. package/dist/notes/ask-notes.js.map +1 -0
  546. package/dist/notes/branches.d.ts +102 -0
  547. package/dist/notes/branches.d.ts.map +1 -0
  548. package/dist/notes/branches.js +304 -0
  549. package/dist/notes/branches.js.map +1 -0
  550. package/dist/notes/cold-start.d.ts +177 -0
  551. package/dist/notes/cold-start.d.ts.map +1 -0
  552. package/dist/notes/cold-start.js +537 -0
  553. package/dist/notes/cold-start.js.map +1 -0
  554. package/dist/notes/edit-overlap.d.ts +62 -0
  555. package/dist/notes/edit-overlap.d.ts.map +1 -0
  556. package/dist/notes/edit-overlap.js +202 -0
  557. package/dist/notes/edit-overlap.js.map +1 -0
  558. package/dist/notes/git-facts.d.ts +21 -0
  559. package/dist/notes/git-facts.d.ts.map +1 -0
  560. package/dist/notes/git-facts.js +121 -0
  561. package/dist/notes/git-facts.js.map +1 -0
  562. package/dist/notes/home.d.ts +87 -0
  563. package/dist/notes/home.d.ts.map +1 -0
  564. package/dist/notes/home.js +430 -0
  565. package/dist/notes/home.js.map +1 -0
  566. package/dist/notes/learning-fields.d.ts +102 -0
  567. package/dist/notes/learning-fields.d.ts.map +1 -0
  568. package/dist/notes/learning-fields.js +217 -0
  569. package/dist/notes/learning-fields.js.map +1 -0
  570. package/dist/notes/note-gate.d.ts +42 -0
  571. package/dist/notes/note-gate.d.ts.map +1 -0
  572. package/dist/notes/note-gate.js +181 -0
  573. package/dist/notes/note-gate.js.map +1 -0
  574. package/dist/notes/notes.d.ts +214 -0
  575. package/dist/notes/notes.d.ts.map +1 -0
  576. package/dist/notes/notes.js +591 -0
  577. package/dist/notes/notes.js.map +1 -0
  578. package/dist/notes/pr-reviews.d.ts +108 -0
  579. package/dist/notes/pr-reviews.d.ts.map +1 -0
  580. package/dist/notes/pr-reviews.js +325 -0
  581. package/dist/notes/pr-reviews.js.map +1 -0
  582. package/dist/notes/repo-julius.d.ts +18 -0
  583. package/dist/notes/repo-julius.d.ts.map +1 -0
  584. package/dist/notes/repo-julius.js +111 -0
  585. package/dist/notes/repo-julius.js.map +1 -0
  586. package/dist/notes/session-cost.d.ts +35 -0
  587. package/dist/notes/session-cost.d.ts.map +1 -0
  588. package/dist/notes/session-cost.js +276 -0
  589. package/dist/notes/session-cost.js.map +1 -0
  590. package/dist/search/grep-cli.d.ts +35 -0
  591. package/dist/search/grep-cli.d.ts.map +1 -0
  592. package/dist/search/grep-cli.js +115 -0
  593. package/dist/search/grep-cli.js.map +1 -0
  594. package/dist/search/grep.d.ts +60 -0
  595. package/dist/search/grep.d.ts.map +1 -0
  596. package/dist/search/grep.js +176 -0
  597. package/dist/search/grep.js.map +1 -0
  598. package/dist/search/ignored-code.d.ts +9 -0
  599. package/dist/search/ignored-code.d.ts.map +1 -0
  600. package/dist/search/ignored-code.js +73 -0
  601. package/dist/search/ignored-code.js.map +1 -0
  602. package/dist/skills/skills.d.ts +118 -0
  603. package/dist/skills/skills.d.ts.map +1 -0
  604. package/dist/skills/skills.js +370 -0
  605. package/dist/skills/skills.js.map +1 -0
  606. package/dist/telemetry/contract.d.ts +103 -0
  607. package/dist/telemetry/contract.d.ts.map +1 -0
  608. package/dist/telemetry/contract.js +270 -0
  609. package/dist/telemetry/contract.js.map +1 -0
  610. package/dist/telemetry/flush.d.ts +21 -0
  611. package/dist/telemetry/flush.d.ts.map +1 -0
  612. package/dist/telemetry/flush.js +85 -0
  613. package/dist/telemetry/flush.js.map +1 -0
  614. package/dist/telemetry/gate.d.ts +30 -0
  615. package/dist/telemetry/gate.d.ts.map +1 -0
  616. package/dist/telemetry/gate.js +81 -0
  617. package/dist/telemetry/gate.js.map +1 -0
  618. package/dist/telemetry/identity.d.ts +40 -0
  619. package/dist/telemetry/identity.d.ts.map +1 -0
  620. package/dist/telemetry/identity.js +80 -0
  621. package/dist/telemetry/identity.js.map +1 -0
  622. package/dist/telemetry/index.d.ts +18 -0
  623. package/dist/telemetry/index.d.ts.map +1 -0
  624. package/dist/telemetry/index.js +16 -0
  625. package/dist/telemetry/index.js.map +1 -0
  626. package/dist/telemetry/key.d.ts +4 -0
  627. package/dist/telemetry/key.d.ts.map +1 -0
  628. package/dist/telemetry/key.js +4 -0
  629. package/dist/telemetry/key.js.map +1 -0
  630. package/dist/telemetry/notice.d.ts +19 -0
  631. package/dist/telemetry/notice.d.ts.map +1 -0
  632. package/dist/telemetry/notice.js +93 -0
  633. package/dist/telemetry/notice.js.map +1 -0
  634. package/dist/telemetry/queue.d.ts +35 -0
  635. package/dist/telemetry/queue.d.ts.map +1 -0
  636. package/dist/telemetry/queue.js +162 -0
  637. package/dist/telemetry/queue.js.map +1 -0
  638. package/dist/telemetry/send.d.ts +19 -0
  639. package/dist/telemetry/send.d.ts.map +1 -0
  640. package/dist/telemetry/send.js +84 -0
  641. package/dist/telemetry/send.js.map +1 -0
  642. package/dist/telemetry/sessions.d.ts +25 -0
  643. package/dist/telemetry/sessions.d.ts.map +1 -0
  644. package/dist/telemetry/sessions.js +104 -0
  645. package/dist/telemetry/sessions.js.map +1 -0
  646. package/dist/telemetry/track.d.ts +62 -0
  647. package/dist/telemetry/track.d.ts.map +1 -0
  648. package/dist/telemetry/track.js +142 -0
  649. package/dist/telemetry/track.js.map +1 -0
  650. package/dist/upkeep-run.d.ts +15 -0
  651. package/dist/upkeep-run.d.ts.map +1 -0
  652. package/dist/upkeep-run.js +71 -0
  653. package/dist/upkeep-run.js.map +1 -0
  654. package/dist/upkeep.d.ts +125 -0
  655. package/dist/upkeep.d.ts.map +1 -0
  656. package/dist/upkeep.js +255 -0
  657. package/dist/upkeep.js.map +1 -0
  658. package/dist/util/browser.d.ts +3 -0
  659. package/dist/util/browser.d.ts.map +1 -0
  660. package/dist/util/browser.js +14 -0
  661. package/dist/util/browser.js.map +1 -0
  662. package/dist/util/front-matter.d.ts +19 -0
  663. package/dist/util/front-matter.d.ts.map +1 -0
  664. package/dist/util/front-matter.js +21 -0
  665. package/dist/util/front-matter.js.map +1 -0
  666. package/dist/util/id.d.ts +7 -0
  667. package/dist/util/id.d.ts.map +1 -0
  668. package/dist/util/id.js +14 -0
  669. package/dist/util/id.js.map +1 -0
  670. package/dist/util/paths.d.ts +29 -0
  671. package/dist/util/paths.d.ts.map +1 -0
  672. package/dist/util/paths.js +71 -0
  673. package/dist/util/paths.js.map +1 -0
  674. package/dist/util/source.d.ts +4 -0
  675. package/dist/util/source.d.ts.map +1 -0
  676. package/dist/util/source.js +12 -0
  677. package/dist/util/source.js.map +1 -0
  678. package/dist/util/spinner.d.ts +15 -0
  679. package/dist/util/spinner.d.ts.map +1 -0
  680. package/dist/util/spinner.js +52 -0
  681. package/dist/util/spinner.js.map +1 -0
  682. package/dist/util/state.d.ts +100 -0
  683. package/dist/util/state.d.ts.map +1 -0
  684. package/dist/util/state.js +186 -0
  685. package/dist/util/state.js.map +1 -0
  686. package/dist/viewer/app.js +2 -0
  687. package/dist/viewer/index.html +49 -0
  688. package/dist/viewer/style.css +154 -0
  689. package/dist/viz/assemble.d.ts +83 -0
  690. package/dist/viz/assemble.d.ts.map +1 -0
  691. package/dist/viz/assemble.js +101 -0
  692. package/dist/viz/assemble.js.map +1 -0
  693. package/dist/viz/export.d.ts +39 -0
  694. package/dist/viz/export.d.ts.map +1 -0
  695. package/dist/viz/export.js +98 -0
  696. package/dist/viz/export.js.map +1 -0
  697. package/dist/viz/serve.d.ts +12 -0
  698. package/dist/viz/serve.d.ts.map +1 -0
  699. package/dist/viz/serve.js +129 -0
  700. package/dist/viz/serve.js.map +1 -0
  701. package/docs/assets/context-benchmark.svg +31 -0
  702. package/docs/assets/julius-hero.png +0 -0
  703. package/docs/upstream-changelog.md +785 -0
  704. package/package.json +138 -4
package/CHANGELOG.md ADDED
@@ -0,0 +1,31 @@
1
+ # Changelog
2
+
3
+ Julius releases follow [Semantic Versioning](https://semver.org/).
4
+ The unchanged upstream history is in [upstream-changelog.md](docs/upstream-changelog.md).
5
+
6
+ ## [Unreleased]
7
+
8
+ ## 0.24.0
9
+
10
+ ### Added
11
+
12
+ - First public npm distribution of `@ruverd/julius`, with the `julius` executable and `Julius` API.
13
+ - Compact MCP discovery, local change-impact and failure-localization investigations.
14
+ - Recoverable context delivery with explicit budgets, literal focus and complete retrieval.
15
+ - Transactional MCP setup for Claude Code, Cursor, Codex and the native xAI Grok CLI.
16
+ - Tag-based release automation, npm trusted publishing, package installation smoke tests and release metadata checks.
17
+
18
+ ### Changed
19
+
20
+ - Keep runtime state under `.julius`, with local graph refresh and shared learnings.
21
+ - Preserve MIT licensing, upstream credits and the original changelog in every npm package.
22
+ - Publish stable versions to `latest` and alpha, beta or release candidates to `next`.
23
+ - Exclude development scripts, tests, local state and experiment traces from the npm archive.
24
+
25
+ ### Fixed
26
+
27
+ - Resolve the Node entry point for `vscode-jsonrpc` in packaged installations.
28
+ - Bound selective evidence delivery at UTF-8 boundaries and distinguish missing literals from oversized matches.
29
+
30
+ This release does not measure provider token usage or billing. Recorded benchmark
31
+ results refer to the historical revision identified in the README.
package/CREDITS.md ADDED
@@ -0,0 +1,25 @@
1
+ # Credits
2
+
3
+ ## Language support
4
+
5
+ The graft map's multi-language support was shaped by community contributors who opened
6
+ language pull requests. That wave of one-language-at-a-time PRs is exactly what
7
+ motivated the generic breadth tier (one tree-sitter grammar + `tags.scm` per
8
+ language) that now covers most of them. With gratitude to:
9
+
10
+ - **@muneebshere** (#38) — Dart & Kotlin. Both are now supported via the breadth tier.
11
+ - **@reinhardtb** (#46) — C#.
12
+ - **@jhouserizer** (#53) and **@dbianco** (#83) — Java.
13
+ - **@qoole** (#59) — Rust; (#58) — PowerShell; (#40) — the tree-sitter 0.25 runtime bump.
14
+ - **@williamdes** (#64) — PHP.
15
+ - **@edrethardo** (#67) — C/C++ and the "fail loudly on unsupported languages" idea (#66),
16
+ which the breadth tier addresses by routing unknown extensions to a generic
17
+ extractor instead of skipping them.
18
+ - **@kapelner** (#69) — C/C++; (#70) — R.
19
+ - **@CroissantEdit** (#187) — Lua.
20
+ - **@Ansh-Sonkusare** (#159) — Nix.
21
+ - **@shovelmn12** (#130) — Kotlin, promoted to full-fidelity depth extraction.
22
+ - **@mattstrayer** (#219) — Swift.
23
+
24
+ If you contributed a language PR and aren't listed here, please open an issue —
25
+ the omission is an oversight, not a slight.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Context Graph Engine contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/PROVENANCE.md ADDED
@@ -0,0 +1,9 @@
1
+ # Julius source provenance
2
+
3
+ Julius (`@ruverd/julius`) is an independent fork of [Trail-Code](https://github.com/trailhq/Trail-Code), previously also distributed as Graft.
4
+
5
+ The exact upstream source imported on October 21, 2026 is commit `b1211efd3eef0efa121b93800e5dd8e547aead77`. Import commit `6ecba95` records the exact upstream tree with both the previous Julius history and the upstream commit as parents. The MIT LICENSE and upstream CREDITS.md are preserved unchanged. [docs/upstream-changelog.md](docs/upstream-changelog.md) is the unchanged historical upstream changelog and retains its original names. [CHANGELOG.md](CHANGELOG.md) records Julius releases, starting at 0.24.0.
6
+
7
+ The previous Python/Rust Julius product was replaced with the user's approval. It remains available in the remote branch `archive/pre-trail-20261021`.
8
+
9
+ Julius changes the package, CLI, API, state directories and integration names; consolidates the former dual-brand behavior; and removes upstream deployment, publication and telemetry stamping machinery. It has no default hosted cloud service or telemetry endpoint. Its graph, code navigation, host integrations and local learning functionality originate in the pinned upstream source.
package/README.md CHANGED
@@ -1,3 +1,226 @@
1
- # Temporary Holding Version
1
+ <p align="center">
2
+ <img src="docs/assets/julius-hero.png" alt="Black-and-white ASCII portrait of Julius holding a floating data cube, with connected cubes, a thick white outline, and a transparent background." width="960">
3
+ </p>
2
4
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
5
+ <h1 align="center">Julius</h1>
6
+
7
+ <p align="center">
8
+ <strong>"That's 50,000 tokens of context. Do you think tokens grow on trees?"</strong><br>
9
+ Local code intelligence and recoverable context for coding agents.
10
+ </p>
11
+
12
+ <p align="center">
13
+ <a href="#install">Install</a> ·
14
+ <a href="#how-it-works">How it works</a> ·
15
+ <a href="#benchmarks">Benchmarks</a> ·
16
+ <a href="#documentation">Documentation</a>
17
+ </p>
18
+
19
+ Your agent needs to find a function, follow its callers, or locate a failure in a
20
+ long log. Julius builds a local repository graph and returns evidence within a
21
+ context budget. Omitted output stays on disk, ready to recover when the agent
22
+ needs it.
23
+
24
+ Structural indexing and context recovery run locally, without a model key.
25
+ After MCP setup, keep asking normal coding questions. The agent discovers and
26
+ calls Julius through two tools.
27
+
28
+ ## Install
29
+
30
+ Requires **Node.js 20+** and npm.
31
+
32
+ ```sh
33
+ npm install -g @ruverd/julius
34
+ julius install --dry-run
35
+ julius install
36
+ ```
37
+
38
+ To update an existing installation:
39
+
40
+ ```sh
41
+ npm install -g @ruverd/julius@latest
42
+ julius --version
43
+ ```
44
+
45
+ Restart or reconnect the client's MCP session after updating. Run `julius install`
46
+ again if the Node executable or installed package path changes. To select an
47
+ exact version, use `npm install -g @ruverd/julius@0.24.0`.
48
+
49
+ ### Install from source
50
+
51
+ ```sh
52
+ git clone https://github.com/ruverd/julius.git
53
+ cd julius
54
+ npm ci
55
+ npm run build
56
+ npm pack --pack-destination .
57
+ npm install -g ./ruverd-julius-0.24.0.tgz
58
+ julius install --dry-run
59
+ julius install
60
+ ```
61
+
62
+ Setup detects Claude Code, Cursor, Codex, and the native xAI Grok CLI. To select
63
+ hosts explicitly, use `julius install --hosts claude,cursor,codex,grok`.
64
+ Restart or reconnect the client's MCP session after setup.
65
+
66
+ Then open a repository in your coding client and ask:
67
+
68
+ ```text
69
+ What calls handleRequest, and what could this change affect?
70
+ Find the code near this failure: "expected 403 received 200".
71
+ ```
72
+
73
+ The host must start MCP in the repository's working directory. Julius indexes
74
+ that repository on demand. Tool selection and permissions belong to the host
75
+ agent; configuration and stdio tests do not establish live client compatibility.
76
+
77
+ Keep the installed Node executable and package path in place. If either moves,
78
+ run setup again. To undo global setup, run `julius uninstall --global`.
79
+ See [installation and migration](docs/installation.md) for rollback, ownership
80
+ conflicts, and repository-specific setup with `julius init`.
81
+
82
+ ## How it works
83
+
84
+ Julius gives agents a structural view of the code and control over how much
85
+ evidence enters the conversation.
86
+
87
+ | When the agent needs to… | Julius provides… |
88
+ | --- | --- |
89
+ | Find code | Ranked search, file signatures, and source locations |
90
+ | Understand dependencies | Call tracing, reference edges, and repository maps |
91
+ | Investigate a change or failure | Experimental change-impact and literal failure-localization reports |
92
+ | Read a large result | Bounded previews, literal focus, or explicit complete delivery |
93
+ | Recover omitted evidence | Local SHA-256 handles, byte ranges, and exact-text search |
94
+ | Keep repository knowledge | Shared learnings under `.julius/learnings/` |
95
+
96
+ The default MCP server advertises `julius_discover` and `julius_call`. The agent
97
+ discovers an operation's schema, invokes it, and retrieves more evidence as needed.
98
+ Results default to a 1,200-token text budget using the offline `cl100k_base`
99
+ encoding. Explicit complete delivery without a budget returns all captured bytes.
100
+
101
+ Graph evidence has limits. Dynamic calls, ignored files, and unsupported syntax
102
+ can be missing. A dependency is a candidate for investigation, not proof of a
103
+ breakage. See [investigations and limitations](docs/investigations.md).
104
+
105
+ ## Benchmarks
106
+
107
+ **25.3% fewer protocol tokens** in the recorded offline comparison with the
108
+ [pinned upstream executable](PROVENANCE.md). This is a result for a specific
109
+ synthetic task mix, not a prediction of your bill.
110
+
111
+ The measured Julius revision is `69945baf69a9f49ff68469283cb50d9c529ccf78`.
112
+ It predates the current `main`; these figures describe that historical revision,
113
+ not the current release.
114
+
115
+ ![Offline MCP comparison: pinned upstream uses 463,332 tokens; Julius uses 346,263, a 25.3% reduction. Local cl100k_base protocol counts, not provider usage.](docs/assets/context-benchmark.svg)
116
+
117
+ The experiment runs ten synthetic evidence tasks in TypeScript, Python, and Go,
118
+ with three repetitions per task and language. Each compared arm has 90 executions.
119
+ Counts include MCP initialization, discovery, invocation, and every recovery call.
120
+ The Julius arm uses the recorded selective/complete delivery policy.
121
+
122
+ The task determines the result. Smaller deliveries help selective reads, while
123
+ repeated recovery and extra investigation evidence can cost more:
124
+
125
+ | Task, summed across nine executions | Pinned upstream | Julius |
126
+ | --- | ---: | ---: |
127
+ | Retrieve one required fact | 78,903 | 18,129 |
128
+ | Request complete output explicitly | 78,903 | 75,495 |
129
+ | Recover all output without a hint | 78,903 | 113,472 |
130
+ | Investigate impact with a composed report | 15,186 | 63,048 |
131
+ | **All ten task types** | **463,332** | **346,263** |
132
+
133
+ These are offline `cl100k_base` counts over JSON-RPC NDJSON traffic. No model runs,
134
+ provider billing, or coding-task accuracy were measured. Local retrieval remained
135
+ slower than the pinned upstream in this experiment. The checks verify synthetic
136
+ evidence recovery, not the correctness of a code change.
137
+
138
+ Read the [method, all task results, limitations, and reproduction steps](docs/strategy/performance-comparison.md)
139
+ or inspect the [recorded JSON](docs/strategy/performance-comparison.json).
140
+ Regenerate this chart with `node scripts/render-readme-benchmark.mjs`.
141
+
142
+ ## Local navigation
143
+
144
+ The CLI also works directly, without an MCP client or a model key:
145
+
146
+ ```sh
147
+ julius build /path/to/repo
148
+ julius ask "Where is authentication checked?" --source /path/to/repo
149
+ julius map /path/to/repo
150
+ julius callers handleRequest /path/to/repo
151
+ julius skeleton src/index.ts /path/to/repo
152
+ julius build --check /path/to/repo
153
+ ```
154
+
155
+ Graph data lives in `.julius/cache/`, shared learnings in `.julius/learnings/`,
156
+ and machine state in `~/.julius`. `--deep` explicitly enables model-assisted
157
+ analysis. Run `julius --help` for the command list.
158
+
159
+ `julius grep` accepts JavaScript regular expressions, including lookbehind and
160
+ backreferences. Use `--fixed` for literal text. Compilation and matching each file
161
+ have a 1,000 ms limit; exceeding it aborts the search with an error.
162
+
163
+ ### Recoverable context economy
164
+
165
+ Keep noisy command output out of the conversation until you need it:
166
+
167
+ ```sh
168
+ julius run --budget 512 -- npm test
169
+ julius capture --file build.log --budget 512
170
+ julius read sha256:<digest> --search 'error' --budget 512
171
+ julius economy stats
172
+ ```
173
+
174
+ `run` executes its command once and preserves its exit status or signal. Handles
175
+ recover captured bytes exactly, up to the 8 MiB capture ceiling. Follow-up reads
176
+ add to delivery cost, so savings can become negative. Local payload counts are
177
+ not provider measurements. See [context economy](docs/context-economy.md) for
178
+ limits, retention, accounting, and the exported API.
179
+
180
+ ### Public API
181
+
182
+ ```ts
183
+ import { Julius } from '@ruverd/julius';
184
+
185
+ const engine = new Julius();
186
+ await engine.graph('/path/to/repo');
187
+ const drift = engine.check('/path/to/repo');
188
+ ```
189
+
190
+ ## Documentation
191
+
192
+ | Guide | What it covers |
193
+ | --- | --- |
194
+ | [Installation and migration](docs/installation.md) | Host setup, rollback, ownership, and migration |
195
+ | [Investigations](docs/investigations.md) | Change impact, failure localization, freshness, and coverage |
196
+ | [Compact MCP](docs/compact-mcp.md) | Discovery, budgets, delivery controls, and recovery |
197
+ | [Context economy](docs/context-economy.md) | Capture, command output, storage, accounting, and API |
198
+ | [Executable comparison](docs/strategy/performance-comparison.md) | Recorded benchmark results and counterexamples |
199
+ | [Fixture benchmark](docs/economy-benchmark.md) | Offline payload accounting and exact-byte recovery |
200
+ | [Research notes](docs/research.md) | Local context techniques and research boundaries |
201
+ | [External services](TELEMETRY.md) | Optional configuration and network behavior |
202
+
203
+ There is no default Julius cloud service, telemetry collector, or automatic npm
204
+ check. Optional external services require explicit configuration. A command you
205
+ explicitly run through Julius can access the network.
206
+
207
+ ## Development
208
+
209
+ ```sh
210
+ npm ci
211
+ npm run build
212
+ npm test
213
+ node dist/bin/julius.js --help
214
+ ```
215
+
216
+ Run `npm run benchmark:economy` after building for the separate offline fixture
217
+ experiment. See [releasing](docs/releasing.md) for versioning, release checks,
218
+ npm trusted publishing and recovery. Julius release notes live in
219
+ [CHANGELOG.md](CHANGELOG.md).
220
+
221
+ ## License and provenance
222
+
223
+ Julius is an independent TypeScript fork of Trail-Code, distributed under the
224
+ [MIT license](LICENSE). Upstream copyright and credits are preserved. See
225
+ [source provenance](PROVENANCE.md) for the pinned source, fork history, and the
226
+ archived earlier Julius product.
@@ -0,0 +1,60 @@
1
+ /**
2
+ * Tier-2 "meaning" call for the code graph — batched one request per file.
3
+ *
4
+ * Given a source file (with 1-based line numbers) and the list of definitions in
5
+ * it, one call returns, for each definition:
6
+ * 1. `summary` — one plain-English sentence: what the symbol is *for*, at the
7
+ * business-logic level, not a restatement of its signature.
8
+ * 2. `crux_start`/`crux_end` — the smallest contiguous range of FILE line
9
+ * numbers (inside that symbol's own span) that a reviewer must read to see
10
+ * the decision or rule the code encodes. `0/0` means there is no single
11
+ * crux (a trivial getter, a plain data holder).
12
+ *
13
+ * Batching per file means N definitions cost one request, not N — and the model
14
+ * sees each symbol's neighbours, which sharpens the summaries. Line numbers are
15
+ * consumed once, at write time, to slice the crux text verbatim from source.
16
+ */
17
+ import type { ChatModel, ChatResponse } from "./llm/types.js";
18
+ import type { Kind } from "../graph/types.js";
19
+ /** One definition we want described, located by its line span within the file. */
20
+ export interface NodeRef {
21
+ id: string;
22
+ kind: Kind;
23
+ signature: string | null;
24
+ startLine: number;
25
+ endLine: number;
26
+ }
27
+ export interface FileCruxInput {
28
+ path: string;
29
+ source: string;
30
+ nodes: NodeRef[];
31
+ }
32
+ export interface NodeCrux {
33
+ id: string;
34
+ summary: string;
35
+ crux_start: number;
36
+ crux_end: number;
37
+ }
38
+ export interface CruxSummarizer {
39
+ describeFile(input: FileCruxInput): Promise<NodeCrux[]>;
40
+ /** Set by {@link ChatCruxSummarizer} after each call; optional on fakes. */
41
+ lastMiss?: CruxMiss | null;
42
+ }
43
+ /** Why a crux call produced no usable summaries (#235). */
44
+ export type CruxMissKind = "empty-toolCalls" | "unparseable" | "truncated" | "empty-parsed";
45
+ export interface CruxMiss {
46
+ kind: CruxMissKind;
47
+ finishReason: string | null;
48
+ }
49
+ /** Classify an empty/unusable crux reply. `null` means at least one usable summary. */
50
+ export declare function classifyCruxMiss(res: ChatResponse, parsed: NodeCrux[]): CruxMiss | null;
51
+ /** Per-file error text: miss class + the provider's finish_reason (#235). */
52
+ export declare function formatCruxMiss(kind: CruxMissKind, finishReason: string | null): string;
53
+ /** Crux summarizer backed by any {@link ChatModel} via forced tool calling. */
54
+ export declare class ChatCruxSummarizer implements CruxSummarizer {
55
+ private model;
56
+ lastMiss: CruxMiss | null;
57
+ constructor(model: ChatModel);
58
+ describeFile(input: FileCruxInput): Promise<NodeCrux[]>;
59
+ }
60
+ //# sourceMappingURL=crux.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"crux.d.ts","sourceRoot":"","sources":["../../src/ai/crux.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAE9C,kFAAkF;AAClF,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,IAAI,CAAC;IACX,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,OAAO,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IACxD,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;CAC5B;AAED,2DAA2D;AAC3D,MAAM,MAAM,YAAY,GAAG,iBAAiB,GAAG,aAAa,GAAG,WAAW,GAAG,cAAc,CAAC;AAE5F,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,YAAY,CAAC;IACnB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAQD,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,QAAQ,GAAG,IAAI,CASvF;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAGtF;AA+FD,+EAA+E;AAC/E,qBAAa,kBAAmB,YAAW,cAAc;IAG3C,OAAO,CAAC,KAAK;IAFzB,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAQ;IAEjC,YAAoB,KAAK,EAAE,SAAS,EAAI;IAElC,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAsB5D;CACF"}
@@ -0,0 +1,141 @@
1
+ import { recoverToolArgsFromContent, warnToolChoiceIgnored } from "./llm/recover-tool.js";
2
+ function isTruncatedStop(reason) {
3
+ if (!reason)
4
+ return false;
5
+ const r = reason.toLowerCase();
6
+ return r === "length" || r === "max_tokens";
7
+ }
8
+ /** Classify an empty/unusable crux reply. `null` means at least one usable summary. */
9
+ export function classifyCruxMiss(res, parsed) {
10
+ const finishReason = res.stopReason;
11
+ if (parsed.some((p) => p.summary.trim()))
12
+ return null;
13
+ if (isTruncatedStop(finishReason))
14
+ return { kind: "truncated", finishReason };
15
+ if (parsed.length > 0)
16
+ return { kind: "empty-parsed", finishReason };
17
+ const emptyTools = res.toolCalls.length === 0;
18
+ const emptyText = !res.text?.trim();
19
+ if (emptyTools && emptyText)
20
+ return { kind: "empty-toolCalls", finishReason };
21
+ return { kind: "unparseable", finishReason };
22
+ }
23
+ /** Per-file error text: miss class + the provider's finish_reason (#235). */
24
+ export function formatCruxMiss(kind, finishReason) {
25
+ const fr = finishReason == null || finishReason === "" ? "null" : finishReason;
26
+ return `model returned no usable symbol summaries [${kind}, finish_reason=${fr}]`;
27
+ }
28
+ const SYSTEM_PROMPT = `You explain code definitions for a code graph that helps engineers navigate a codebase.
29
+
30
+ You are given ONE source file with 1-based line numbers, and a list of TARGET definitions in it. Describe EVERY target via the record_symbols tool.
31
+
32
+ Rules:
33
+ - Return EXACTLY ONE entry for EVERY target id, using that id verbatim. The number of entries you return MUST equal the number of targets. Never omit a target: a reply missing any id is invalid and will be re-requested.
34
+ - A trivial symbol is NOT an exception. You still return it — with a one-sentence summary and crux 0/0 (see below). "Skip" means "give it no crux span", NEVER "leave it out".
35
+ - summary: ONE sentence — what the symbol is FOR at the business-logic level (the problem it solves or the rule it enforces), not a restatement of its signature.
36
+ - crux_start / crux_end: FILE line numbers (as shown), inside that symbol's own line range. Pick the SINGLE most important contiguous span — the core branch, formula, guard, or state change — at most ~8 lines, and NEVER the whole function. When there is no single focal span (a trivial getter, a plain data holder, a one-line delegation, or logic spread evenly), use crux_start: 0 and crux_end: 0. That 0/0 IS the answer — do not drop the entry.`;
37
+ const RECORD_TOOL = "record_symbols";
38
+ const SYMBOLS_SCHEMA = {
39
+ type: "object",
40
+ properties: {
41
+ symbols: {
42
+ type: "array",
43
+ items: {
44
+ type: "object",
45
+ properties: {
46
+ id: { type: "string" },
47
+ summary: { type: "string" },
48
+ crux_start: { type: "number" },
49
+ crux_end: { type: "number" },
50
+ },
51
+ required: ["id", "summary", "crux_start", "crux_end"],
52
+ },
53
+ },
54
+ },
55
+ required: ["symbols"],
56
+ };
57
+ /** Cap the file text sent per request so one huge file can't blow the context. */
58
+ const MAX_CODE_CHARS = 18_000;
59
+ function numberLines(source) {
60
+ const clipped = source.length > MAX_CODE_CHARS ? `${source.slice(0, MAX_CODE_CHARS)}\n… (truncated)` : source;
61
+ return clipped
62
+ .split("\n")
63
+ .map((line, i) => `${i + 1}\t${line}`)
64
+ .join("\n");
65
+ }
66
+ function userContent(input) {
67
+ const targets = input.nodes
68
+ .map((n) => `- id=${n.id} | ${n.kind} | lines L${n.startLine}-L${n.endLine}` +
69
+ (n.signature ? ` | ${n.signature}` : ""))
70
+ .join("\n");
71
+ const n = input.nodes.length;
72
+ return `FILE: ${input.path}\n\n${numberLines(input.source)}\n\nTARGETS (${n} — return all ${n}, one entry per id):\n${targets}`;
73
+ }
74
+ /** Normalize the tool's parsed argument object into a {@link NodeCrux} list. */
75
+ function parseResults(obj) {
76
+ if (!obj || !Array.isArray(obj.symbols))
77
+ return [];
78
+ const num = (v) => (typeof v === "number" && Number.isFinite(v) ? Math.trunc(v) : 0);
79
+ return obj.symbols
80
+ .map((s) => s)
81
+ .filter((s) => typeof s.id === "string")
82
+ .map((s) => ({
83
+ id: s.id,
84
+ summary: typeof s.summary === "string" ? s.summary.trim() : "",
85
+ crux_start: num(s.crux_start),
86
+ crux_end: num(s.crux_end),
87
+ }));
88
+ }
89
+ /**
90
+ * Some OpenAI-compatible gateways ignore forced `tool_choice` and put the tool
91
+ * payload in `content` instead (plain `{symbols:…}`, fenced JSON, or an emulated
92
+ * `[{name, parameters}]` array). Without this recovery the meaning pass sees an
93
+ * empty `toolCalls` list, leaves every node `pending`, and `julius check` loops
94
+ * on "run --deep" forever (#172; same trigger as #129 for the crux path).
95
+ */
96
+ function argsFromResponse(res) {
97
+ const call = res.toolCalls.find((c) => c.name === RECORD_TOOL) ?? res.toolCalls[0];
98
+ if (call?.args && typeof call.args === "object" && !Array.isArray(call.args)) {
99
+ return call.args;
100
+ }
101
+ const recovered = recoverToolArgsFromContent(res.text, {
102
+ toolNames: [RECORD_TOOL, "emit_json"],
103
+ payloadKey: "symbols",
104
+ });
105
+ if (!recovered)
106
+ warnToolChoiceIgnored("crux", res.text?.trim() ? "unparsed" : "empty");
107
+ return recovered;
108
+ }
109
+ /** Crux summarizer backed by any {@link ChatModel} via forced tool calling. */
110
+ export class ChatCruxSummarizer {
111
+ model;
112
+ lastMiss = null;
113
+ constructor(model) {
114
+ this.model = model;
115
+ }
116
+ async describeFile(input) {
117
+ this.lastMiss = null;
118
+ if (input.nodes.length === 0)
119
+ return [];
120
+ const res = await this.model.create({
121
+ temperature: 0,
122
+ maxTokens: 8192,
123
+ tools: [
124
+ {
125
+ name: RECORD_TOOL,
126
+ description: "Record each target definition's purpose and crux line range.",
127
+ parameters: SYMBOLS_SCHEMA,
128
+ },
129
+ ],
130
+ responseFormat: { kind: "tool", name: RECORD_TOOL },
131
+ messages: [
132
+ { role: "system", content: SYSTEM_PROMPT },
133
+ { role: "user", content: userContent(input) },
134
+ ],
135
+ });
136
+ const parsed = parseResults(argsFromResponse(res));
137
+ this.lastMiss = classifyCruxMiss(res, parsed);
138
+ return parsed;
139
+ }
140
+ }
141
+ //# sourceMappingURL=crux.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"crux.js","sourceRoot":"","sources":["../../src/ai/crux.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,60 @@
1
+ /**
2
+ * When to stop calling a provider that is failing (#127).
3
+ *
4
+ * Both LLM passes of `build --deep` — the per-file concept summaries
5
+ * (`context/build.ts`) and the per-file crux pass (`graph/enrich.ts`) — used to
6
+ * catch every error per file, keep going, and finish with a clean exit. On an
7
+ * 884-file repo behind a gateway whose token quota was spent that produced 1,617
8
+ * failed calls, a normal success footer, and a graph whose meaning tier was
9
+ * missing; the degradation surfaced days later as bad `ask` results.
10
+ *
11
+ * One gate, shared by both passes, so they agree on what "the provider stopped
12
+ * working" means and a caller can report it once.
13
+ *
14
+ * Content-quality misses (empty/unusable crux, #235) still count as failed files
15
+ * so they are not cached as success (#177), but they do not increment the
16
+ * consecutive-failure cutoff — the provider is answering, just not usefully for
17
+ * those files. Quota/auth stay immediately terminal (#127).
18
+ */
19
+ /** Consecutive failures that end a pass. One flaky file is normal; five in a row is
20
+ * a provider that is not going to start working, and each further call is spend
21
+ * with no chance of a result. */
22
+ export declare const MAX_CONSECUTIVE_FAILURES = 5;
23
+ /**
24
+ * Errors no amount of retrying fixes: the key is wrong, or the account/quota is
25
+ * spent. Matched on the message because that is all a provider-neutral transport
26
+ * carries — over-matching costs a build that was going to fail anyway, while
27
+ * under-matching just falls back to the consecutive-failure cutoff.
28
+ */
29
+ export declare function terminalReason(message: string): string | null;
30
+ /**
31
+ * Failure bookkeeping for one LLM pass: how many units failed, how many were
32
+ * skipped once it gave up, and the human-readable reason it did.
33
+ *
34
+ * Single-threaded by construction — every mutation happens between awaits in the
35
+ * pass's own worker — so no locking is needed despite the concurrency above it.
36
+ */
37
+ export declare class LlmFailureGate {
38
+ /** Units (files) whose call failed. */
39
+ failed: number;
40
+ /** Units never attempted because the pass had already given up. */
41
+ skipped: number;
42
+ /** Why the pass stopped, when it did. */
43
+ fatal?: string;
44
+ private consecutive;
45
+ /** True once the pass should stop issuing calls. */
46
+ get stopped(): boolean;
47
+ /**
48
+ * Record a failed unit; sets {@link fatal} when this failure is the last straw.
49
+ * Pass `{ quality: true }` for a content-quality miss (#235): counted, not fatal,
50
+ * unless the message is quota/auth (those still stop immediately).
51
+ */
52
+ record(message: string, opts?: {
53
+ quality?: boolean;
54
+ }): void;
55
+ /** Record a success — a failure run only counts while it is unbroken. */
56
+ succeeded(): void;
57
+ /** Record a unit that was not attempted because the pass had stopped. */
58
+ skip(): void;
59
+ }
60
+ //# sourceMappingURL=failure.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"failure.d.ts","sourceRoot":"","sources":["../../src/ai/failure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;iCAEiC;AACjC,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS7D;AAED;;;;;;GAMG;AACH,qBAAa,cAAc;IACzB,uCAAuC;IACvC,MAAM,SAAK;IACX,mEAAmE;IACnE,OAAO,SAAK;IACZ,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,WAAW,CAAK;IAExB,oDAAoD;IACpD,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAY1D;IAED,yEAAyE;IACzE,SAAS,IAAI,IAAI,CAEhB;IAED,yEAAyE;IACzE,IAAI,IAAI,IAAI,CAEX;CACF"}