xithead 1.4.0 → 1.5.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 (661) hide show
  1. package/.actrc +14 -0
  2. package/.actrc.local.example +15 -0
  3. package/.changelog.md +2 -0
  4. package/.claude/agents/academic-anthropologist.md +125 -0
  5. package/.claude/agents/academic-geographer.md +127 -0
  6. package/.claude/agents/academic-historian.md +123 -0
  7. package/.claude/agents/academic-narratologist.md +118 -0
  8. package/.claude/agents/academic-psychologist.md +118 -0
  9. package/.claude/agents/academic-statistician.md +144 -0
  10. package/.claude/agents/accounts-payable-agent.md +205 -0
  11. package/.claude/agents/agentic-identity-trust.md +394 -0
  12. package/.claude/agents/agents-orchestrator.md +367 -0
  13. package/.claude/agents/automation-governance-architect.md +216 -0
  14. package/.claude/agents/blender-addon-engineer.md +243 -0
  15. package/.claude/agents/business-strategist.md +488 -0
  16. package/.claude/agents/change-management-consultant.md +497 -0
  17. package/.claude/agents/chief-financial-officer.md +388 -0
  18. package/.claude/agents/corporate-training-designer.md +192 -0
  19. package/.claude/agents/customer-service.md +398 -0
  20. package/.claude/agents/customer-success-manager.md +460 -0
  21. package/.claude/agents/data-consolidation-agent.md +60 -0
  22. package/.claude/agents/data-privacy-officer.md +412 -0
  23. package/.claude/agents/design-brand-guardian.md +322 -0
  24. package/.claude/agents/design-image-prompt-engineer.md +236 -0
  25. package/.claude/agents/design-inclusive-visuals-specialist.md +73 -0
  26. package/.claude/agents/design-persona-walkthrough.md +272 -0
  27. package/.claude/agents/design-ui-designer.md +386 -0
  28. package/.claude/agents/design-ui-finish-gate-reviewer.md +217 -0
  29. package/.claude/agents/design-ux-architect.md +482 -0
  30. package/.claude/agents/design-ux-researcher.md +329 -0
  31. package/.claude/agents/design-visual-storyteller.md +149 -0
  32. package/.claude/agents/design-whimsy-injector.md +460 -0
  33. package/.claude/agents/economy-designer.md +156 -0
  34. package/.claude/agents/engineering-ai-data-remediation-engineer.md +211 -0
  35. package/.claude/agents/engineering-ai-engineer.md +146 -0
  36. package/.claude/agents/engineering-api-platform-engineer.md +181 -0
  37. package/.claude/agents/engineering-ats-validator-architect.md +383 -0
  38. package/.claude/agents/engineering-autonomous-optimization-architect.md +121 -0
  39. package/.claude/agents/engineering-backend-architect.md +255 -0
  40. package/.claude/agents/engineering-china-network-engineer.md +252 -0
  41. package/.claude/agents/engineering-cms-developer.md +536 -0
  42. package/.claude/agents/engineering-code-reviewer.md +76 -0
  43. package/.claude/agents/engineering-codebase-onboarding-engineer.md +173 -0
  44. package/.claude/agents/engineering-data-engineer.md +349 -0
  45. package/.claude/agents/engineering-data-visualization-engineer.md +151 -0
  46. package/.claude/agents/engineering-database-optimizer.md +188 -0
  47. package/.claude/agents/engineering-database-reliability-engineer.md +201 -0
  48. package/.claude/agents/engineering-desktop-app-engineer.md +209 -0
  49. package/.claude/agents/engineering-developer-tooling-engineer.md +153 -0
  50. package/.claude/agents/engineering-devops-automator.md +385 -0
  51. package/.claude/agents/engineering-drupal-performance.md +347 -0
  52. package/.claude/agents/engineering-drupal-shopping-cart.md +360 -0
  53. package/.claude/agents/engineering-electrical-engineer.md +575 -0
  54. package/.claude/agents/engineering-email-intelligence-engineer.md +390 -0
  55. package/.claude/agents/engineering-embedded-firmware-engineer.md +196 -0
  56. package/.claude/agents/engineering-feishu-integration-developer.md +606 -0
  57. package/.claude/agents/engineering-filament-optimization-specialist.md +283 -0
  58. package/.claude/agents/engineering-finops-engineer.md +164 -0
  59. package/.claude/agents/engineering-frontend-developer.md +257 -0
  60. package/.claude/agents/engineering-gaussdb-expert.md +334 -0
  61. package/.claude/agents/engineering-git-workflow-master.md +98 -0
  62. package/.claude/agents/engineering-i18n-engineer.md +214 -0
  63. package/.claude/agents/engineering-identity-access-engineer.md +217 -0
  64. package/.claude/agents/engineering-incident-response-commander.md +444 -0
  65. package/.claude/agents/engineering-iot-fleet-engineer.md +148 -0
  66. package/.claude/agents/engineering-it-service-manager.md +561 -0
  67. package/.claude/agents/engineering-knowledge-graph-engineer.md +372 -0
  68. package/.claude/agents/engineering-llm-post-training-engineer.md +166 -0
  69. package/.claude/agents/engineering-minimal-change-engineer.md +207 -0
  70. package/.claude/agents/engineering-mobile-app-builder.md +493 -0
  71. package/.claude/agents/engineering-mobile-release-engineer.md +164 -0
  72. package/.claude/agents/engineering-multi-agent-systems-architect.md +600 -0
  73. package/.claude/agents/engineering-network-engineer.md +245 -0
  74. package/.claude/agents/engineering-orgscript-engineer.md +113 -0
  75. package/.claude/agents/engineering-payments-billing-engineer.md +228 -0
  76. package/.claude/agents/engineering-pdf-engine-architect.md +696 -0
  77. package/.claude/agents/engineering-platform-engineer.md +270 -0
  78. package/.claude/agents/engineering-privacy-engineer.md +152 -0
  79. package/.claude/agents/engineering-prompt-engineer.md +209 -0
  80. package/.claude/agents/engineering-rag-pipeline-engineer.md +450 -0
  81. package/.claude/agents/engineering-rapid-prototyper.md +466 -0
  82. package/.claude/agents/engineering-realtime-collaboration-engineer.md +200 -0
  83. package/.claude/agents/engineering-rust-refactoring-specialist.md +313 -0
  84. package/.claude/agents/engineering-search-relevance-engineer.md +237 -0
  85. package/.claude/agents/engineering-section-508-specialist.md +339 -0
  86. package/.claude/agents/engineering-senior-developer.md +176 -0
  87. package/.claude/agents/engineering-servicenow-developer-mentor.md +180 -0
  88. package/.claude/agents/engineering-software-architect.md +112 -0
  89. package/.claude/agents/engineering-solidity-smart-contract-engineer.md +522 -0
  90. package/.claude/agents/engineering-sre.md +90 -0
  91. package/.claude/agents/engineering-technical-writer.md +393 -0
  92. package/.claude/agents/engineering-universal-document-compiler.md +370 -0
  93. package/.claude/agents/engineering-uswds-developer.md +340 -0
  94. package/.claude/agents/engineering-video-streaming-engineer.md +151 -0
  95. package/.claude/agents/engineering-voice-ai-integration-engineer.md +584 -0
  96. package/.claude/agents/engineering-webassembly-engineer.md +153 -0
  97. package/.claude/agents/engineering-wechat-mini-program-developer.md +356 -0
  98. package/.claude/agents/engineering-wordpress-performance.md +346 -0
  99. package/.claude/agents/engineering-wordpress-shopping-cart.md +346 -0
  100. package/.claude/agents/esg-sustainability-officer.md +396 -0
  101. package/.claude/agents/finance-bookkeeper-controller.md +260 -0
  102. package/.claude/agents/finance-financial-analyst.md +234 -0
  103. package/.claude/agents/finance-fpa-analyst.md +263 -0
  104. package/.claude/agents/finance-investment-researcher.md +272 -0
  105. package/.claude/agents/finance-tax-strategist.md +239 -0
  106. package/.claude/agents/game-audio-engineer.md +264 -0
  107. package/.claude/agents/game-designer.md +167 -0
  108. package/.claude/agents/gis-3d-scene-developer.md +111 -0
  109. package/.claude/agents/gis-analyst.md +91 -0
  110. package/.claude/agents/gis-bim-specialist.md +108 -0
  111. package/.claude/agents/gis-cartography-designer.md +150 -0
  112. package/.claude/agents/gis-drone-reality-mapping.md +120 -0
  113. package/.claude/agents/gis-geoai-ml-engineer.md +105 -0
  114. package/.claude/agents/gis-geoprocessing-specialist.md +97 -0
  115. package/.claude/agents/gis-qa-engineer.md +133 -0
  116. package/.claude/agents/gis-solution-engineer.md +101 -0
  117. package/.claude/agents/gis-spatial-data-engineer.md +97 -0
  118. package/.claude/agents/gis-spatial-data-scientist.md +111 -0
  119. package/.claude/agents/gis-technical-consultant.md +86 -0
  120. package/.claude/agents/gis-web-gis-developer.md +108 -0
  121. package/.claude/agents/godot-gameplay-scripter.md +338 -0
  122. package/.claude/agents/godot-multiplayer-engineer.md +301 -0
  123. package/.claude/agents/godot-shader-developer.md +267 -0
  124. package/.claude/agents/government-digital-presales-consultant.md +363 -0
  125. package/.claude/agents/grant-writer.md +511 -0
  126. package/.claude/agents/healthcare-aging-parent-care-companion.md +414 -0
  127. package/.claude/agents/healthcare-clinical-evidence-agent.md +231 -0
  128. package/.claude/agents/healthcare-customer-service.md +389 -0
  129. package/.claude/agents/healthcare-innovation-strategist.md +433 -0
  130. package/.claude/agents/healthcare-marketing-compliance.md +395 -0
  131. package/.claude/agents/healthcare-sovereign-health-systems-agent.md +312 -0
  132. package/.claude/agents/hospitality-guest-services.md +603 -0
  133. package/.claude/agents/hr-onboarding.md +451 -0
  134. package/.claude/agents/identity-graph-operator.md +303 -0
  135. package/.claude/agents/language-translator.md +264 -0
  136. package/.claude/agents/legal-billing-time-tracking.md +569 -0
  137. package/.claude/agents/legal-client-intake.md +492 -0
  138. package/.claude/agents/legal-document-review.md +454 -0
  139. package/.claude/agents/level-designer.md +208 -0
  140. package/.claude/agents/loan-officer-assistant.md +555 -0
  141. package/.claude/agents/lsp-index-engineer.md +320 -0
  142. package/.claude/agents/ma-integration-manager.md +427 -0
  143. package/.claude/agents/macos-spatial-metal-engineer.md +337 -0
  144. package/.claude/agents/marketing-aeo-foundations.md +264 -0
  145. package/.claude/agents/marketing-agentic-search-optimizer.md +279 -0
  146. package/.claude/agents/marketing-ai-citation-strategist.md +172 -0
  147. package/.claude/agents/marketing-app-store-optimizer.md +321 -0
  148. package/.claude/agents/marketing-baidu-seo-specialist.md +226 -0
  149. package/.claude/agents/marketing-bilibili-content-strategist.md +199 -0
  150. package/.claude/agents/marketing-book-co-author.md +110 -0
  151. package/.claude/agents/marketing-carousel-growth-engine.md +204 -0
  152. package/.claude/agents/marketing-china-ecommerce-operator.md +283 -0
  153. package/.claude/agents/marketing-china-market-localization-strategist.md +283 -0
  154. package/.claude/agents/marketing-content-creator.md +54 -0
  155. package/.claude/agents/marketing-cross-border-ecommerce.md +259 -0
  156. package/.claude/agents/marketing-developer-community-builder.md +285 -0
  157. package/.claude/agents/marketing-douyin-strategist.md +149 -0
  158. package/.claude/agents/marketing-email-strategist.md +249 -0
  159. package/.claude/agents/marketing-global-podcast-strategist.md +206 -0
  160. package/.claude/agents/marketing-growth-hacker.md +54 -0
  161. package/.claude/agents/marketing-instagram-curator.md +113 -0
  162. package/.claude/agents/marketing-kuaishou-strategist.md +223 -0
  163. package/.claude/agents/marketing-linkedin-content-creator.md +214 -0
  164. package/.claude/agents/marketing-livestream-commerce-coach.md +305 -0
  165. package/.claude/agents/marketing-multi-platform-publisher.md +217 -0
  166. package/.claude/agents/marketing-podcast-strategist.md +277 -0
  167. package/.claude/agents/marketing-pr-communications-manager.md +473 -0
  168. package/.claude/agents/marketing-private-domain-operator.md +308 -0
  169. package/.claude/agents/marketing-reddit-community-builder.md +123 -0
  170. package/.claude/agents/marketing-seo-specialist.md +370 -0
  171. package/.claude/agents/marketing-short-video-editing-coach.md +412 -0
  172. package/.claude/agents/marketing-social-media-strategist.md +125 -0
  173. package/.claude/agents/marketing-tiktok-strategist.md +125 -0
  174. package/.claude/agents/marketing-twitter-engager.md +126 -0
  175. package/.claude/agents/marketing-video-optimization-specialist.md +119 -0
  176. package/.claude/agents/marketing-wechat-official-account.md +145 -0
  177. package/.claude/agents/marketing-weibo-strategist.md +240 -0
  178. package/.claude/agents/marketing-x-twitter-intelligence-analyst.md +161 -0
  179. package/.claude/agents/marketing-xiaohongshu-specialist.md +138 -0
  180. package/.claude/agents/marketing-zhihu-strategist.md +162 -0
  181. package/.claude/agents/medical-billing-coding-specialist.md +491 -0
  182. package/.claude/agents/narrative-designer.md +243 -0
  183. package/.claude/agents/operations-manager.md +399 -0
  184. package/.claude/agents/organizational-psychologist.md +391 -0
  185. package/.claude/agents/paid-media-auditor.md +71 -0
  186. package/.claude/agents/paid-media-creative-strategist.md +71 -0
  187. package/.claude/agents/paid-media-paid-social-strategist.md +71 -0
  188. package/.claude/agents/paid-media-ppc-strategist.md +71 -0
  189. package/.claude/agents/paid-media-programmatic-buyer.md +71 -0
  190. package/.claude/agents/paid-media-search-query-analyst.md +71 -0
  191. package/.claude/agents/paid-media-tracking-specialist.md +71 -0
  192. package/.claude/agents/personal-growth-mentor.md +159 -0
  193. package/.claude/agents/product-behavioral-nudge-engine.md +83 -0
  194. package/.claude/agents/product-dx-engineer.md +332 -0
  195. package/.claude/agents/product-feedback-synthesizer.md +119 -0
  196. package/.claude/agents/product-manager.md +469 -0
  197. package/.claude/agents/product-sprint-prioritizer.md +154 -0
  198. package/.claude/agents/product-trend-researcher.md +159 -0
  199. package/.claude/agents/project-management-experiment-tracker.md +198 -0
  200. package/.claude/agents/project-management-jira-workflow-steward.md +233 -0
  201. package/.claude/agents/project-management-meeting-notes-specialist.md +95 -0
  202. package/.claude/agents/project-management-project-shepherd.md +194 -0
  203. package/.claude/agents/project-management-studio-operations.md +200 -0
  204. package/.claude/agents/project-management-studio-producer.md +203 -0
  205. package/.claude/agents/project-manager-senior.md +135 -0
  206. package/.claude/agents/real-estate-buyer-seller.md +596 -0
  207. package/.claude/agents/recruitment-specialist.md +515 -0
  208. package/.claude/agents/report-distribution-agent.md +65 -0
  209. package/.claude/agents/research-synthesist.md +136 -0
  210. package/.claude/agents/resume-tailor.md +230 -0
  211. package/.claude/agents/retail-customer-returns.md +566 -0
  212. package/.claude/agents/roblox-avatar-creator.md +297 -0
  213. package/.claude/agents/roblox-experience-designer.md +306 -0
  214. package/.claude/agents/roblox-systems-scripter.md +332 -0
  215. package/.claude/agents/sales-account-strategist.md +227 -0
  216. package/.claude/agents/sales-coach.md +271 -0
  217. package/.claude/agents/sales-data-extraction-agent.md +67 -0
  218. package/.claude/agents/sales-deal-strategist.md +180 -0
  219. package/.claude/agents/sales-discovery-coach.md +225 -0
  220. package/.claude/agents/sales-engineer.md +182 -0
  221. package/.claude/agents/sales-offer-lead-gen-strategist.md +257 -0
  222. package/.claude/agents/sales-outbound-strategist.md +201 -0
  223. package/.claude/agents/sales-outreach.md +425 -0
  224. package/.claude/agents/sales-pipeline-analyst.md +267 -0
  225. package/.claude/agents/sales-proposal-strategist.md +217 -0
  226. package/.claude/agents/security-ai-generated-code-auditor.md +207 -0
  227. package/.claude/agents/security-appsec-engineer.md +536 -0
  228. package/.claude/agents/security-architect.md +307 -0
  229. package/.claude/agents/security-blockchain-security-auditor.md +482 -0
  230. package/.claude/agents/security-cloud-security-architect.md +576 -0
  231. package/.claude/agents/security-compliance-auditor.md +158 -0
  232. package/.claude/agents/security-incident-responder.md +450 -0
  233. package/.claude/agents/security-penetration-tester.md +399 -0
  234. package/.claude/agents/security-secrets-credential-engineer.md +189 -0
  235. package/.claude/agents/security-senior-secops.md +760 -0
  236. package/.claude/agents/security-threat-detection-engineer.md +553 -0
  237. package/.claude/agents/security-threat-intelligence-analyst.md +661 -0
  238. package/.claude/agents/specialized-chief-of-staff.md +279 -0
  239. package/.claude/agents/specialized-civil-engineer.md +356 -0
  240. package/.claude/agents/specialized-codebase-archaeologist.md +341 -0
  241. package/.claude/agents/specialized-cultural-intelligence-strategist.md +88 -0
  242. package/.claude/agents/specialized-developer-advocate.md +317 -0
  243. package/.claude/agents/specialized-document-generator.md +55 -0
  244. package/.claude/agents/specialized-fedramp-rmf-compliance.md +378 -0
  245. package/.claude/agents/specialized-focus-music-architect.md +175 -0
  246. package/.claude/agents/specialized-french-consulting-market.md +194 -0
  247. package/.claude/agents/specialized-korean-business-navigator.md +216 -0
  248. package/.claude/agents/specialized-master-plan-architect.md +157 -0
  249. package/.claude/agents/specialized-mcp-builder.md +260 -0
  250. package/.claude/agents/specialized-model-qa.md +528 -0
  251. package/.claude/agents/specialized-pricing-analyst.md +243 -0
  252. package/.claude/agents/specialized-salesforce-architect.md +182 -0
  253. package/.claude/agents/specialized-strategy-duel-agent.md +130 -0
  254. package/.claude/agents/specialized-workflow-architect.md +597 -0
  255. package/.claude/agents/study-abroad-advisor.md +282 -0
  256. package/.claude/agents/supply-chain-strategist.md +591 -0
  257. package/.claude/agents/support-analytics-reporter.md +387 -0
  258. package/.claude/agents/support-executive-summary-generator.md +212 -0
  259. package/.claude/agents/support-finance-tracker.md +480 -0
  260. package/.claude/agents/support-infrastructure-maintainer.md +628 -0
  261. package/.claude/agents/support-legal-compliance-checker.md +591 -0
  262. package/.claude/agents/support-support-responder.md +607 -0
  263. package/.claude/agents/technical-artist.md +233 -0
  264. package/.claude/agents/terminal-integration-specialist.md +70 -0
  265. package/.claude/agents/testing-accessibility-auditor.md +327 -0
  266. package/.claude/agents/testing-api-tester.md +334 -0
  267. package/.claude/agents/testing-evidence-collector.md +210 -0
  268. package/.claude/agents/testing-performance-benchmarker.md +283 -0
  269. package/.claude/agents/testing-reality-checker.md +249 -0
  270. package/.claude/agents/testing-test-automation-engineer.md +196 -0
  271. package/.claude/agents/testing-test-results-analyzer.md +330 -0
  272. package/.claude/agents/testing-tool-evaluator.md +416 -0
  273. package/.claude/agents/testing-workflow-optimizer.md +463 -0
  274. package/.claude/agents/unity-architect.md +271 -0
  275. package/.claude/agents/unity-editor-tool-developer.md +310 -0
  276. package/.claude/agents/unity-multiplayer-engineer.md +323 -0
  277. package/.claude/agents/unity-shader-graph-artist.md +269 -0
  278. package/.claude/agents/unreal-multiplayer-architect.md +364 -0
  279. package/.claude/agents/unreal-systems-engineer.md +322 -0
  280. package/.claude/agents/unreal-technical-artist.md +256 -0
  281. package/.claude/agents/unreal-world-builder.md +273 -0
  282. package/.claude/agents/visionos-spatial-engineer.md +54 -0
  283. package/.claude/agents/xr-cockpit-interaction-specialist.md +32 -0
  284. package/.claude/agents/xr-immersive-developer.md +32 -0
  285. package/.claude/agents/xr-interface-architect.md +32 -0
  286. package/.claude/agents/zk-steward.md +211 -0
  287. package/.claude-plugin/marketplace.json +30 -0
  288. package/.commitlintrc.json +26 -0
  289. package/.devcontainer/Dockerfile +24 -0
  290. package/.devcontainer/devcontainer.json +70 -0
  291. package/.devcontainer/docker-compose.memory.yml +42 -0
  292. package/.devcontainer/memory-stack/devcontainer.json +84 -0
  293. package/.devcontainer/post-create.sh +83 -0
  294. package/.dockerignore +23 -0
  295. package/.env.act.example +15 -0
  296. package/.env.example +171 -0
  297. package/.eslintrc.json +16 -0
  298. package/.git-blame-ignore-revs +10 -0
  299. package/.gitattributes +2 -0
  300. package/.gitguardian.yaml +50 -0
  301. package/.githooks/pre-commit +6 -0
  302. package/.pre-commit-config.yaml +30 -0
  303. package/.release-please-config-xithead.json +22 -0
  304. package/.release-please-config.json +44 -0
  305. package/.release-please-manifest-xithead.json +3 -0
  306. package/.release-please-manifest.json +3 -0
  307. package/CODE_OF_CONDUCT.md +133 -0
  308. package/CONTRIBUTING.md +133 -0
  309. package/Cargo.lock +5557 -0
  310. package/Cargo.toml +121 -0
  311. package/Dockerfile +38 -0
  312. package/Dockerfile.proxy +48 -0
  313. package/ENTERPRISE.md +5 -0
  314. package/FEATURES_ADVANCED.md +311 -0
  315. package/Headroom-2.gif +0 -0
  316. package/HeadroomDemo-Fast.gif +0 -0
  317. package/MANIFEST.in +4 -0
  318. package/MODERNIZATION_GUIDE.md +358 -0
  319. package/Makefile +140 -0
  320. package/NOTICE +43 -0
  321. package/NPM_TOKEN_SETUP.md +81 -0
  322. package/PR.md +170 -0
  323. package/PUBLISH.md +77 -0
  324. package/README.md +108 -72
  325. package/README_FRONTEND.md +196 -0
  326. package/REALIGNMENT/00-overview.md +53 -0
  327. package/REALIGNMENT/01-bug-list.md +421 -0
  328. package/REALIGNMENT/02-architecture.md +322 -0
  329. package/REALIGNMENT/03-phase-A-lockdown.md +420 -0
  330. package/REALIGNMENT/04-phase-B-live-zone.md +470 -0
  331. package/REALIGNMENT/05-phase-C-rust-proxy.md +329 -0
  332. package/REALIGNMENT/06-phase-D-bedrock-vertex.md +222 -0
  333. package/REALIGNMENT/07-phase-E-cache-stabilization.md +338 -0
  334. package/REALIGNMENT/08-phase-F-auth-mode.md +254 -0
  335. package/REALIGNMENT/09-phase-G-rtk-observability.md +194 -0
  336. package/REALIGNMENT/10-phase-H-python-retirement.md +214 -0
  337. package/REALIGNMENT/11-phase-I-test-infra.md +385 -0
  338. package/REALIGNMENT/12-decisions-needed.md +196 -0
  339. package/REALIGNMENT/INDEX.md +82 -0
  340. package/REFACTORING_CAMPAIGN.md +277 -0
  341. package/RESTRUCTURE_PLAN.md +100 -0
  342. package/RUST_DEV.md +361 -0
  343. package/SECURITY.md +65 -0
  344. package/SETUP_AUTO_PUBLISH.md +164 -0
  345. package/TESTING-copilot-subscription.md +153 -0
  346. package/app/api/config/route.ts +22 -0
  347. package/app/api/export/route.ts +83 -0
  348. package/app/api/models/route.ts +12 -0
  349. package/app/api/stats/route.ts +46 -0
  350. package/app/dashboard/page.tsx +445 -0
  351. package/app/globals.css +35 -0
  352. package/app/installation/page.tsx +293 -0
  353. package/app/layout.tsx +35 -0
  354. package/app/master-design-system.css +2076 -0
  355. package/app/master-design-system.source.css +8 -0
  356. package/app/page.tsx +187 -0
  357. package/app/rechtliches/agb/page.tsx +165 -0
  358. package/app/rechtliches/datenschutz/page.tsx +128 -0
  359. package/app/rechtliches/impressum/page.tsx +122 -0
  360. package/app/rechtliches/widerruf/page.tsx +185 -0
  361. package/bin/xithead.js +264 -0
  362. package/codecov.yml +34 -0
  363. package/components/layout/AppShell.tsx +25 -0
  364. package/components/layout/Footer.tsx +120 -0
  365. package/components/layout/Header.tsx +145 -0
  366. package/components/marketing/LegalHighlights.tsx +45 -0
  367. package/components/marketing/LegalPageShell.tsx +49 -0
  368. package/components/marketing/LegalPanel.tsx +41 -0
  369. package/components/marketing/index.ts +3 -0
  370. package/crates/headroom-core/Cargo.toml +165 -0
  371. package/crates/headroom-core/benches/auth_mode.rs +74 -0
  372. package/crates/headroom-core/benches/ccr_store.rs +224 -0
  373. package/crates/headroom-core/benches/tokenizer.rs +52 -0
  374. package/crates/headroom-core/config/pipeline.toml +151 -0
  375. package/crates/headroom-core/proptest-regressions/transforms/tag_protector.txt +9 -0
  376. package/crates/headroom-core/src/auth_mode.rs +250 -0
  377. package/crates/headroom-core/src/cache_control.rs +414 -0
  378. package/crates/headroom-core/src/ccr/backends/in_memory.rs +317 -0
  379. package/crates/headroom-core/src/ccr/backends/mod.rs +152 -0
  380. package/crates/headroom-core/src/ccr/backends/redis.rs +146 -0
  381. package/crates/headroom-core/src/ccr/backends/sqlite.rs +205 -0
  382. package/crates/headroom-core/src/ccr/mod.rs +119 -0
  383. package/crates/headroom-core/src/compression_policy.rs +505 -0
  384. package/crates/headroom-core/src/lib.rs +33 -0
  385. package/crates/headroom-core/src/relevance/base.rs +139 -0
  386. package/crates/headroom-core/src/relevance/bm25.rs +385 -0
  387. package/crates/headroom-core/src/relevance/embedding.rs +354 -0
  388. package/crates/headroom-core/src/relevance/hybrid.rs +364 -0
  389. package/crates/headroom-core/src/relevance/mod.rs +64 -0
  390. package/crates/headroom-core/src/signals/keyword_detector.rs +433 -0
  391. package/crates/headroom-core/src/signals/line_importance.rs +84 -0
  392. package/crates/headroom-core/src/signals/mod.rs +61 -0
  393. package/crates/headroom-core/src/signals/tiered.rs +141 -0
  394. package/crates/headroom-core/src/tokenizer/estimator.rs +152 -0
  395. package/crates/headroom-core/src/tokenizer/hf_impl.rs +314 -0
  396. package/crates/headroom-core/src/tokenizer/mod.rs +56 -0
  397. package/crates/headroom-core/src/tokenizer/registry.rs +342 -0
  398. package/crates/headroom-core/src/tokenizer/tiktoken_impl.rs +265 -0
  399. package/crates/headroom-core/src/transforms/adaptive_sizer.rs +610 -0
  400. package/crates/headroom-core/src/transforms/anchor_selector.rs +1189 -0
  401. package/crates/headroom-core/src/transforms/content_detector.rs +769 -0
  402. package/crates/headroom-core/src/transforms/detection.rs +222 -0
  403. package/crates/headroom-core/src/transforms/diff_compressor.rs +1685 -0
  404. package/crates/headroom-core/src/transforms/live_zone.rs +2967 -0
  405. package/crates/headroom-core/src/transforms/log_compressor.rs +1295 -0
  406. package/crates/headroom-core/src/transforms/magika_detector.rs +395 -0
  407. package/crates/headroom-core/src/transforms/mod.rs +64 -0
  408. package/crates/headroom-core/src/transforms/pipeline/config.rs +331 -0
  409. package/crates/headroom-core/src/transforms/pipeline/mod.rs +103 -0
  410. package/crates/headroom-core/src/transforms/pipeline/offloads/diff_noise.rs +524 -0
  411. package/crates/headroom-core/src/transforms/pipeline/offloads/diff_offload.rs +279 -0
  412. package/crates/headroom-core/src/transforms/pipeline/offloads/json_offload.rs +400 -0
  413. package/crates/headroom-core/src/transforms/pipeline/offloads/log_offload.rs +284 -0
  414. package/crates/headroom-core/src/transforms/pipeline/offloads/mod.rs +34 -0
  415. package/crates/headroom-core/src/transforms/pipeline/offloads/search_offload.rs +331 -0
  416. package/crates/headroom-core/src/transforms/pipeline/orchestrator.rs +848 -0
  417. package/crates/headroom-core/src/transforms/pipeline/reformats/json_minifier.rs +175 -0
  418. package/crates/headroom-core/src/transforms/pipeline/reformats/log_template.rs +545 -0
  419. package/crates/headroom-core/src/transforms/pipeline/reformats/mod.rs +12 -0
  420. package/crates/headroom-core/src/transforms/pipeline/traits.rs +338 -0
  421. package/crates/headroom-core/src/transforms/recommendations.rs +329 -0
  422. package/crates/headroom-core/src/transforms/safety.rs +215 -0
  423. package/crates/headroom-core/src/transforms/search_compressor.rs +902 -0
  424. package/crates/headroom-core/src/transforms/smart_crusher/analyzer.rs +1262 -0
  425. package/crates/headroom-core/src/transforms/smart_crusher/anchors.rs +407 -0
  426. package/crates/headroom-core/src/transforms/smart_crusher/builder.rs +263 -0
  427. package/crates/headroom-core/src/transforms/smart_crusher/classifier.rs +214 -0
  428. package/crates/headroom-core/src/transforms/smart_crusher/compaction/classifier.rs +283 -0
  429. package/crates/headroom-core/src/transforms/smart_crusher/compaction/compactor.rs +733 -0
  430. package/crates/headroom-core/src/transforms/smart_crusher/compaction/formatter.rs +961 -0
  431. package/crates/headroom-core/src/transforms/smart_crusher/compaction/ir.rs +252 -0
  432. package/crates/headroom-core/src/transforms/smart_crusher/compaction/mod.rs +127 -0
  433. package/crates/headroom-core/src/transforms/smart_crusher/compaction/walker.rs +397 -0
  434. package/crates/headroom-core/src/transforms/smart_crusher/config.rs +173 -0
  435. package/crates/headroom-core/src/transforms/smart_crusher/constraints.rs +159 -0
  436. package/crates/headroom-core/src/transforms/smart_crusher/crusher.rs +1665 -0
  437. package/crates/headroom-core/src/transforms/smart_crusher/crushers.rs +865 -0
  438. package/crates/headroom-core/src/transforms/smart_crusher/error_keywords.rs +77 -0
  439. package/crates/headroom-core/src/transforms/smart_crusher/field_detect.rs +393 -0
  440. package/crates/headroom-core/src/transforms/smart_crusher/hashing.rs +72 -0
  441. package/crates/headroom-core/src/transforms/smart_crusher/mod.rs +81 -0
  442. package/crates/headroom-core/src/transforms/smart_crusher/observer.rs +66 -0
  443. package/crates/headroom-core/src/transforms/smart_crusher/orchestration.rs +459 -0
  444. package/crates/headroom-core/src/transforms/smart_crusher/outliers.rs +507 -0
  445. package/crates/headroom-core/src/transforms/smart_crusher/planning.rs +904 -0
  446. package/crates/headroom-core/src/transforms/smart_crusher/statistics.rs +510 -0
  447. package/crates/headroom-core/src/transforms/smart_crusher/stats_math.rs +287 -0
  448. package/crates/headroom-core/src/transforms/smart_crusher/traits.rs +203 -0
  449. package/crates/headroom-core/src/transforms/smart_crusher/types.rs +263 -0
  450. package/crates/headroom-core/src/transforms/tag_protector.rs +1272 -0
  451. package/crates/headroom-core/src/transforms/unidiff_detector.rs +232 -0
  452. package/crates/headroom-parity/Cargo.toml +26 -0
  453. package/crates/headroom-parity/examples/diff_fixture.rs +66 -0
  454. package/crates/headroom-parity/src/bin/parity_run.rs +78 -0
  455. package/crates/headroom-parity/src/lib.rs +613 -0
  456. package/crates/headroom-proxy/Cargo.toml +119 -0
  457. package/crates/headroom-proxy/data/model_prices_and_context_window.json +39767 -0
  458. package/crates/headroom-proxy/src/bedrock/auth_mode_layer.rs +192 -0
  459. package/crates/headroom-proxy/src/bedrock/envelope.rs +239 -0
  460. package/crates/headroom-proxy/src/bedrock/eventstream.rs +769 -0
  461. package/crates/headroom-proxy/src/bedrock/eventstream_to_sse.rs +459 -0
  462. package/crates/headroom-proxy/src/bedrock/invoke.rs +735 -0
  463. package/crates/headroom-proxy/src/bedrock/invoke_streaming.rs +1098 -0
  464. package/crates/headroom-proxy/src/bedrock/mod.rs +66 -0
  465. package/crates/headroom-proxy/src/bedrock/sigv4.rs +324 -0
  466. package/crates/headroom-proxy/src/bedrock/vendor.rs +82 -0
  467. package/crates/headroom-proxy/src/cache_stabilization/anthropic_cache_control.rs +698 -0
  468. package/crates/headroom-proxy/src/cache_stabilization/drift_detector.rs +683 -0
  469. package/crates/headroom-proxy/src/cache_stabilization/mod.rs +61 -0
  470. package/crates/headroom-proxy/src/cache_stabilization/openai_cache_key.rs +600 -0
  471. package/crates/headroom-proxy/src/cache_stabilization/tool_def_normalize.rs +514 -0
  472. package/crates/headroom-proxy/src/cache_stabilization/volatile_detector.rs +720 -0
  473. package/crates/headroom-proxy/src/compression/anthropic.rs +92 -0
  474. package/crates/headroom-proxy/src/compression/live_zone_anthropic.rs +1311 -0
  475. package/crates/headroom-proxy/src/compression/live_zone_openai.rs +660 -0
  476. package/crates/headroom-proxy/src/compression/live_zone_responses.rs +678 -0
  477. package/crates/headroom-proxy/src/compression/mod.rs +127 -0
  478. package/crates/headroom-proxy/src/compression/model_limits.rs +211 -0
  479. package/crates/headroom-proxy/src/config.rs +646 -0
  480. package/crates/headroom-proxy/src/error.rs +69 -0
  481. package/crates/headroom-proxy/src/handlers/chat_completions.rs +100 -0
  482. package/crates/headroom-proxy/src/handlers/conversations.rs +241 -0
  483. package/crates/headroom-proxy/src/handlers/mod.rs +13 -0
  484. package/crates/headroom-proxy/src/handlers/responses.rs +256 -0
  485. package/crates/headroom-proxy/src/headers.rs +288 -0
  486. package/crates/headroom-proxy/src/health.rs +41 -0
  487. package/crates/headroom-proxy/src/lib.rs +21 -0
  488. package/crates/headroom-proxy/src/main.rs +141 -0
  489. package/crates/headroom-proxy/src/observability/cache_hit_rate.rs +340 -0
  490. package/crates/headroom-proxy/src/observability/compression_ratio.rs +158 -0
  491. package/crates/headroom-proxy/src/observability/metric_names.rs +174 -0
  492. package/crates/headroom-proxy/src/observability/mod.rs +68 -0
  493. package/crates/headroom-proxy/src/observability/prometheus.rs +394 -0
  494. package/crates/headroom-proxy/src/observability/proxy_metrics.rs +368 -0
  495. package/crates/headroom-proxy/src/proxy.rs +1619 -0
  496. package/crates/headroom-proxy/src/responses_items.rs +565 -0
  497. package/crates/headroom-proxy/src/sse/anthropic.rs +415 -0
  498. package/crates/headroom-proxy/src/sse/framing.rs +366 -0
  499. package/crates/headroom-proxy/src/sse/mod.rs +40 -0
  500. package/crates/headroom-proxy/src/sse/openai_chat.rs +231 -0
  501. package/crates/headroom-proxy/src/sse/openai_responses.rs +458 -0
  502. package/crates/headroom-proxy/src/vertex/adc.rs +315 -0
  503. package/crates/headroom-proxy/src/vertex/envelope.rs +167 -0
  504. package/crates/headroom-proxy/src/vertex/mod.rs +277 -0
  505. package/crates/headroom-proxy/src/vertex/raw_predict.rs +490 -0
  506. package/crates/headroom-proxy/src/vertex/stream_raw_predict.rs +49 -0
  507. package/crates/headroom-proxy/src/websocket.rs +246 -0
  508. package/crates/headroom-py/Cargo.toml +37 -0
  509. package/crates/headroom-py/build.rs +77 -0
  510. package/crates/headroom-py/glibc_compat.c +170 -0
  511. package/crates/headroom-py/src/lib.rs +1655 -0
  512. package/deny.toml +32 -0
  513. package/design-system/base.css +127 -0
  514. package/design-system/components.css +1943 -0
  515. package/design-system/fonts.css +17 -0
  516. package/design-system/tailwind-preset.js +95 -0
  517. package/design-system/tokens.css +48 -0
  518. package/design-system/utilities.css +53 -0
  519. package/docker/differential-network-capture/Dockerfile.runner +14 -0
  520. package/docker/differential-network-capture/docker-compose.yml +142 -0
  521. package/docker/differential-network-capture/run-claude-lane.sh +24 -0
  522. package/docker/docker-compose.native.yml +44 -0
  523. package/docker-bake.hcl +88 -0
  524. package/docker-compose.yml +80 -0
  525. package/e2e/_lib/make_shim.ps1 +24 -0
  526. package/e2e/_lib/make_shim.sh +28 -0
  527. package/e2e/docker-native-install.sh +120 -0
  528. package/e2e/init/Dockerfile +79 -0
  529. package/e2e/wrap/Dockerfile +115 -0
  530. package/examples/07-context-compression.ipynb +279 -0
  531. package/examples/deployment/macos-launchagent/com.headroom.proxy.plist.template +65 -0
  532. package/examples/deployment/macos-launchagent/install.sh +227 -0
  533. package/examples/deployment/macos-launchagent/shell-integration.sh +74 -0
  534. package/examples/deployment/macos-launchagent/uninstall.sh +145 -0
  535. package/headroom-savings.png +0 -0
  536. package/headroom_learn.gif +0 -0
  537. package/lib/config/index.ts +12 -0
  538. package/lib/hooks/index.ts +4 -0
  539. package/lib/hooks/use-mounted.ts +13 -0
  540. package/lib/hooks/use-session.ts +34 -0
  541. package/lib/hooks/use-settings.ts +49 -0
  542. package/lib/utils/index.ts +1 -0
  543. package/lib/utils/settings.ts +162 -0
  544. package/lib/utils/utils.ts +6 -0
  545. package/llms.txt +67 -0
  546. package/middleware.ts +26 -0
  547. package/mkdocs.yml +136 -0
  548. package/next-env.d.ts +7 -0
  549. package/next.config.ts +12 -0
  550. package/npm/bin/xithead.js +366 -366
  551. package/npm/bin/xtream-head.js +366 -0
  552. package/npm/index.d.ts +57 -57
  553. package/npm/index.js +139 -139
  554. package/npm/package.json +55 -54
  555. package/npm/postinstall.js +43 -43
  556. package/package.json +58 -36
  557. package/plugins/headroom-agent-hooks/.claude-plugin/plugin.json +17 -0
  558. package/plugins/headroom-agent-hooks/hooks/hooks.json +29 -0
  559. package/plugins/headroom-oauth2/LICENSE +3 -0
  560. package/plugins/headroom-oauth2/SPEC.md +115 -0
  561. package/plugins/headroom-oauth2/pyproject.toml +48 -0
  562. package/plugins/hermes/headroom_retrieve/plugin.yaml +6 -0
  563. package/plugins/openclaw/hook-shim/HOOK.md +21 -0
  564. package/plugins/openclaw/hook-shim/handler.js +3 -0
  565. package/plugins/openclaw/openclaw.plugin.json +98 -0
  566. package/plugins/openclaw/package-lock.json +2692 -0
  567. package/plugins/openclaw/package.json +54 -0
  568. package/plugins/openclaw/prepare-dist.mjs +56 -0
  569. package/plugins/openclaw/src/convert.ts +418 -0
  570. package/plugins/openclaw/src/engine.ts +284 -0
  571. package/plugins/openclaw/src/gateway-config.ts +143 -0
  572. package/plugins/openclaw/src/index.ts +11 -0
  573. package/plugins/openclaw/src/plugin/index.ts +98 -0
  574. package/plugins/openclaw/src/proxy-manager.ts +477 -0
  575. package/plugins/openclaw/src/tools/headroom-retrieve.ts +76 -0
  576. package/plugins/openclaw/test/convert.test.ts +96 -0
  577. package/plugins/openclaw/test/engine-normalization.test.ts +21 -0
  578. package/plugins/openclaw/test/engine.test.ts +101 -0
  579. package/plugins/openclaw/test/gateway-config.test.ts +278 -0
  580. package/plugins/openclaw/test/plugin-runtime-routing.test.ts +141 -0
  581. package/plugins/openclaw/test/proxy-manager.test.ts +343 -0
  582. package/plugins/openclaw/tsup.config.ts +9 -0
  583. package/postcss.config.mjs +7 -0
  584. package/pyproject.toml +438 -0
  585. package/rust-toolchain.toml +16 -0
  586. package/sdk/typescript/examples/basic-compress.ts +64 -0
  587. package/sdk/typescript/examples/ccr-retrieve.ts +80 -0
  588. package/sdk/typescript/examples/hooks-custom-compression.ts +117 -0
  589. package/sdk/typescript/examples/middleware-composition.ts +59 -0
  590. package/sdk/typescript/examples/multi-provider.ts +53 -0
  591. package/sdk/typescript/examples/openai-anthropic-adapters.ts +73 -0
  592. package/sdk/typescript/examples/shared-context-multi-agent.ts +74 -0
  593. package/sdk/typescript/examples/simulation-dry-run.ts +80 -0
  594. package/sdk/typescript/examples/streaming-chat.ts +71 -0
  595. package/sdk/typescript/examples/structured-output.ts +99 -0
  596. package/sdk/typescript/examples/tool-calling-agent.ts +86 -0
  597. package/sdk/typescript/examples/with-headroom-vercel.ts +57 -0
  598. package/sdk/typescript/package-lock.json +3437 -0
  599. package/sdk/typescript/package.json +108 -0
  600. package/sdk/typescript/src/adapters/anthropic.ts +218 -0
  601. package/sdk/typescript/src/adapters/gemini.ts +83 -0
  602. package/sdk/typescript/src/adapters/openai.ts +77 -0
  603. package/sdk/typescript/src/adapters/vercel-ai.ts +131 -0
  604. package/sdk/typescript/src/client.ts +632 -0
  605. package/sdk/typescript/src/compress.ts +87 -0
  606. package/sdk/typescript/src/errors.ts +114 -0
  607. package/sdk/typescript/src/hooks.ts +113 -0
  608. package/sdk/typescript/src/index.ts +140 -0
  609. package/sdk/typescript/src/paths.ts +272 -0
  610. package/sdk/typescript/src/shared-context.ts +188 -0
  611. package/sdk/typescript/src/simulate.ts +52 -0
  612. package/sdk/typescript/src/types/config.ts +183 -0
  613. package/sdk/typescript/src/types/models.ts +314 -0
  614. package/sdk/typescript/src/types.ts +139 -0
  615. package/sdk/typescript/src/utils/case.ts +34 -0
  616. package/sdk/typescript/src/utils/format.ts +480 -0
  617. package/sdk/typescript/src/utils/stream.ts +50 -0
  618. package/sdk/typescript/test/adapters/anthropic.test.ts +217 -0
  619. package/sdk/typescript/test/adapters/gemini.test.ts +131 -0
  620. package/sdk/typescript/test/adapters/openai.test.ts +174 -0
  621. package/sdk/typescript/test/adapters/vercel-ai.test.ts +306 -0
  622. package/sdk/typescript/test/client-expanded.test.ts +333 -0
  623. package/sdk/typescript/test/client.test.ts +266 -0
  624. package/sdk/typescript/test/compress.test.ts +118 -0
  625. package/sdk/typescript/test/config.test.ts +275 -0
  626. package/sdk/typescript/test/errors.test.ts +169 -0
  627. package/sdk/typescript/test/format-integration.test.ts +252 -0
  628. package/sdk/typescript/test/hooks.test.ts +265 -0
  629. package/sdk/typescript/test/integration.test.ts +249 -0
  630. package/sdk/typescript/test/mdx-examples.test.ts +253 -0
  631. package/sdk/typescript/test/models.test.ts +318 -0
  632. package/sdk/typescript/test/parity.test.ts +337 -0
  633. package/sdk/typescript/test/paths.test.ts +447 -0
  634. package/sdk/typescript/test/shared-context.test.ts +245 -0
  635. package/sdk/typescript/test/simulate.test.ts +84 -0
  636. package/sdk/typescript/test/types.test.ts +244 -0
  637. package/sdk/typescript/test/utils/case.test.ts +129 -0
  638. package/sdk/typescript/test/utils/detect-format.test.ts +133 -0
  639. package/sdk/typescript/test/utils/format.test.ts +434 -0
  640. package/sdk/typescript/test/vercel-ai-e2e.test.ts +179 -0
  641. package/sdk/typescript/tsup.config.ts +17 -0
  642. package/tailwind.master.config.cjs +47 -0
  643. package/types/api.ts +12 -0
  644. package/types/config.ts +9 -0
  645. package/types/index.ts +2 -0
  646. package/uv.lock +6951 -0
  647. package/xithead.egg-info/PKG-INFO +22 -0
  648. package/xithead.egg-info/SOURCES.txt +16 -0
  649. package/xithead.egg-info/dependency_links.txt +1 -0
  650. package/xithead.egg-info/entry_points.txt +2 -0
  651. package/xithead.egg-info/requires.txt +10 -0
  652. package/xithead.egg-info/top_level.txt +2 -0
  653. package/xithead.ps1 +136 -0
  654. package/xithead.sh +129 -0
  655. package/xithead_dist/pyproject.toml +39 -0
  656. package/xithead_dist/xithead.egg-info/PKG-INFO +22 -0
  657. package/xithead_dist/xithead.egg-info/SOURCES.txt +16 -0
  658. package/xithead_dist/xithead.egg-info/dependency_links.txt +1 -0
  659. package/xithead_dist/xithead.egg-info/entry_points.txt +3 -0
  660. package/xithead_dist/xithead.egg-info/requires.txt +10 -0
  661. package/xithead_dist/xithead.egg-info/top_level.txt +2 -0
@@ -0,0 +1,77 @@
1
+ //! Canonical error keyword set for item preservation.
2
+ //!
3
+ //! Direct port of `ERROR_KEYWORDS` from `headroom/transforms/error_detection.py:18-33`.
4
+ //! These are the **FALLBACK** preservation signal when TOIN field
5
+ //! semantics aren't available yet (per the Python module-level
6
+ //! comment). Intentionally broad — better to over-preserve than to
7
+ //! drop a real error item.
8
+ //!
9
+ //! Used by `detect_error_items_for_preservation`. The list is small
10
+ //! enough to keep as a `&[&str]`; if we ever cross ~50 keywords, switch
11
+ //! to a `phf::Set` or pre-built FST for sub-linear lookup.
12
+
13
+ /// 12 error/failure keywords. Order doesn't matter for correctness, but
14
+ /// matches Python's set-literal order so reading both side-by-side is
15
+ /// easier. Lowercase by construction; callers must lowercase the
16
+ /// haystack before substring-matching.
17
+ pub const ERROR_KEYWORDS: &[&str] = &[
18
+ "error",
19
+ "exception",
20
+ "failed",
21
+ "failure",
22
+ "critical",
23
+ "fatal",
24
+ "crash",
25
+ "panic",
26
+ "abort",
27
+ "timeout",
28
+ "denied",
29
+ "rejected",
30
+ ];
31
+
32
+ #[cfg(test)]
33
+ mod tests {
34
+ use super::*;
35
+
36
+ #[test]
37
+ fn matches_python_count() {
38
+ // Python `len(ERROR_KEYWORDS) == 12`. If this drifts, the
39
+ // Python set was edited and the Rust list needs a matching
40
+ // update.
41
+ assert_eq!(ERROR_KEYWORDS.len(), 12);
42
+ }
43
+
44
+ #[test]
45
+ fn all_lowercase_invariant() {
46
+ for &kw in ERROR_KEYWORDS {
47
+ assert_eq!(
48
+ kw,
49
+ kw.to_lowercase(),
50
+ "ERROR_KEYWORDS must all be lowercase"
51
+ );
52
+ }
53
+ }
54
+
55
+ #[test]
56
+ fn pinned_membership() {
57
+ // Pin the exact set so accidental edits surface in CI rather
58
+ // than silently changing item-preservation behavior.
59
+ let expected = [
60
+ "error",
61
+ "exception",
62
+ "failed",
63
+ "failure",
64
+ "critical",
65
+ "fatal",
66
+ "crash",
67
+ "panic",
68
+ "abort",
69
+ "timeout",
70
+ "denied",
71
+ "rejected",
72
+ ];
73
+ let actual: std::collections::BTreeSet<&str> = ERROR_KEYWORDS.iter().copied().collect();
74
+ let expected: std::collections::BTreeSet<&str> = expected.iter().copied().collect();
75
+ assert_eq!(actual, expected);
76
+ }
77
+ }
@@ -0,0 +1,393 @@
1
+ //! Statistical detectors for ID-like and score-like fields.
2
+ //!
3
+ //! Direct ports of `_detect_id_field_statistically` and
4
+ //! `_detect_score_field_statistically` from `smart_crusher.py:484-603`.
5
+ //!
6
+ //! These run *after* per-field statistics are computed and consume a
7
+ //! `FieldStats` plus the raw values. They're called by the analyzer's
8
+ //! crushability logic to decide whether a field carries a meaningful
9
+ //! ranking signal (score) or is just a unique identifier (ID) that
10
+ //! shouldn't drive compression decisions.
11
+
12
+ use serde_json::Value;
13
+
14
+ use super::statistics::{calculate_string_entropy, detect_sequential_pattern, is_uuid_format};
15
+ use super::types::FieldStats;
16
+
17
+ /// Detect whether a field is an "ID field" — high-uniqueness column
18
+ /// that doesn't carry semantic information.
19
+ ///
20
+ /// Direct port of `_detect_id_field_statistically` (Python
21
+ /// `smart_crusher.py:484-530`). Returns `(is_id, confidence)` where
22
+ /// confidence ∈ [0.0, 1.0]. The caller uses this to decide whether the
23
+ /// field is a strong enough signal to drive crushability analysis.
24
+ ///
25
+ /// # Detection rules (mirroring Python step-by-step)
26
+ ///
27
+ /// 1. Hard gate: `unique_ratio < 0.9` → not an ID field.
28
+ /// 2. String fields:
29
+ /// - >80% of first-20 sample values look like UUIDs → confidence 0.95.
30
+ /// - Average entropy >0.7 AND `unique_ratio > 0.95` → confidence 0.8.
31
+ /// 3. Numeric fields:
32
+ /// - Sequential pattern (via `detect_sequential_pattern`) AND
33
+ /// `unique_ratio > 0.95` → confidence 0.9.
34
+ /// - Has a value range AND `unique_ratio > 0.95` → confidence 0.85.
35
+ /// 4. Catch-all: very high uniqueness (`> 0.98`) → confidence 0.7.
36
+ pub fn detect_id_field_statistically(stats: &FieldStats, values: &[Value]) -> (bool, f64) {
37
+ // Hard gate matching Python line 494.
38
+ if stats.unique_ratio < 0.9 {
39
+ return (false, 0.0);
40
+ }
41
+
42
+ // String-field branches.
43
+ if stats.field_type == "string" {
44
+ // First 20 string-typed values for sampling. Python: `values[:20]`
45
+ // then filters by `isinstance(v, str)` — order-preserving slice
46
+ // before filter, so we mirror that.
47
+ let sample_values: Vec<&str> = values.iter().take(20).filter_map(|v| v.as_str()).collect();
48
+
49
+ if !sample_values.is_empty() {
50
+ let uuid_count = sample_values.iter().filter(|s| is_uuid_format(s)).count();
51
+ // Python: `uuid_count / len(sample_values) > 0.8`.
52
+ if (uuid_count as f64 / sample_values.len() as f64) > 0.8 {
53
+ return (true, 0.95);
54
+ }
55
+
56
+ // Python: average entropy across the sample.
57
+ let avg_entropy = sample_values
58
+ .iter()
59
+ .map(|s| calculate_string_entropy(s))
60
+ .sum::<f64>()
61
+ / sample_values.len() as f64;
62
+ if avg_entropy > 0.7 && stats.unique_ratio > 0.95 {
63
+ return (true, 0.8);
64
+ }
65
+ }
66
+ }
67
+
68
+ // Numeric-field branches.
69
+ if stats.field_type == "numeric" {
70
+ // Python: passes `values` (full list, may include strings) through
71
+ // `_detect_sequential_pattern` with default `check_order=True`.
72
+ if detect_sequential_pattern(values, true) && stats.unique_ratio > 0.95 {
73
+ return (true, 0.9);
74
+ }
75
+
76
+ // High-uniqueness numeric with non-trivial range — likely an ID
77
+ // even without sequential structure (e.g., random ints in a wide
78
+ // band).
79
+ if let (Some(min_v), Some(max_v)) = (stats.min_val, stats.max_val) {
80
+ let value_range = max_v - min_v;
81
+ if value_range > 0.0 && stats.unique_ratio > 0.95 {
82
+ return (true, 0.85);
83
+ }
84
+ }
85
+ }
86
+
87
+ // Catch-all: very high uniqueness alone is a signal.
88
+ if stats.unique_ratio > 0.98 {
89
+ return (true, 0.7);
90
+ }
91
+
92
+ (false, 0.0)
93
+ }
94
+
95
+ /// Detect whether a field is a "score field" — bounded-range numeric
96
+ /// where higher values mean "more relevant".
97
+ ///
98
+ /// Direct port of `_detect_score_field_statistically` (Python
99
+ /// `smart_crusher.py:533-603`). Returns `(is_score, confidence)`.
100
+ ///
101
+ /// # Detection rules (mirroring Python)
102
+ ///
103
+ /// 1. Field must be numeric AND have both `min_val` and `max_val`.
104
+ /// 2. Range must match a "common score range":
105
+ /// - `[0, 1]` (most common ML score range) → +0.4
106
+ /// - `[0, 10]` → +0.3
107
+ /// - `[0, 100]` → +0.25
108
+ /// - `[-1, 1]` (signed similarity) → +0.35
109
+ /// 3. Must NOT be a sequential pattern (IDs are sequential; scores aren't).
110
+ /// 4. If first-50 values appear sorted descending (>70% of pairs) → +0.3.
111
+ /// 5. If >30% of first-20 are non-integer floats → +0.1.
112
+ /// 6. Returns `(confidence >= 0.4, min(confidence, 0.95))`.
113
+ ///
114
+ /// `items` is the list of original-array dict items so we can pull the
115
+ /// field's values in array order for the descending-sort check.
116
+ pub fn detect_score_field_statistically(stats: &FieldStats, items: &[Value]) -> (bool, f64) {
117
+ if stats.field_type != "numeric" {
118
+ return (false, 0.0);
119
+ }
120
+
121
+ let (min_val, max_val) = match (stats.min_val, stats.max_val) {
122
+ (Some(min_v), Some(max_v)) => (min_v, max_v),
123
+ _ => return (false, 0.0),
124
+ };
125
+
126
+ let mut confidence: f64 = 0.0;
127
+
128
+ // Range check (Python lines 555-568). The conditions are arranged
129
+ // exactly as in Python — `if/elif` chain, first match wins.
130
+ let is_bounded = if (0.0..=1.0).contains(&min_val) && (0.0..=1.0).contains(&max_val) {
131
+ confidence += 0.4;
132
+ true
133
+ } else if (0.0..=10.0).contains(&min_val) && (0.0..=10.0).contains(&max_val) {
134
+ confidence += 0.3;
135
+ true
136
+ } else if (0.0..=100.0).contains(&min_val) && (0.0..=100.0).contains(&max_val) {
137
+ confidence += 0.25;
138
+ true
139
+ } else if min_val >= -1.0 && max_val <= 1.0 {
140
+ // Python: `elif -1 <= min_val and max_val <= 1`. Note Python's
141
+ // chained `<=` only on max_val side; min_val is checked
142
+ // separately. Pinned exactly.
143
+ confidence += 0.35;
144
+ true
145
+ } else {
146
+ false
147
+ };
148
+
149
+ if !is_bounded {
150
+ return (false, 0.0);
151
+ }
152
+
153
+ // Pull this field's values from the FIRST 50 items, dict-style.
154
+ // Python: `[item.get(stats.name) for item in items[:50] if stats.name in item]`.
155
+ let sample_values: Vec<&Value> = items
156
+ .iter()
157
+ .take(50)
158
+ .filter_map(|item| item.as_object().and_then(|m| m.get(&stats.name)))
159
+ .collect();
160
+
161
+ // Sequential check — IDs are sequential, scores aren't. We need
162
+ // owned `Value`s for `detect_sequential_pattern`; clone the sample.
163
+ let sample_owned: Vec<Value> = sample_values.iter().map(|v| (*v).clone()).collect();
164
+ if detect_sequential_pattern(&sample_owned, true) {
165
+ return (false, 0.0);
166
+ }
167
+
168
+ // Descending-sort check on the full items list (Python line 580-593).
169
+ // Filter to finite-numeric values, preserving array order.
170
+ let values_in_order: Vec<f64> = items
171
+ .iter()
172
+ .filter_map(|item| item.as_object().and_then(|m| m.get(&stats.name)))
173
+ .filter_map(|v| v.as_f64())
174
+ .filter(|f| f.is_finite())
175
+ .collect();
176
+
177
+ if values_in_order.len() >= 5 {
178
+ let num_pairs = values_in_order.len() - 1;
179
+ let descending_count = values_in_order.windows(2).filter(|w| w[0] >= w[1]).count();
180
+ if num_pairs > 0 && (descending_count as f64 / num_pairs as f64) > 0.7 {
181
+ confidence += 0.3;
182
+ }
183
+ }
184
+
185
+ // Float-fraction check on first 20 ordered values (Python line 597-601).
186
+ // "Not equal to its int-truncation" ≈ has a fractional part.
187
+ let first_20: &[f64] = if values_in_order.len() > 20 {
188
+ &values_in_order[..20]
189
+ } else {
190
+ &values_in_order[..]
191
+ };
192
+ let float_count = first_20
193
+ .iter()
194
+ .filter(|&&v| v.is_finite() && v != v.trunc())
195
+ .count();
196
+ if !first_20.is_empty() && (float_count as f64) > (first_20.len() as f64 * 0.3) {
197
+ confidence += 0.1;
198
+ }
199
+
200
+ let is_score = confidence >= 0.4;
201
+ let bounded_confidence = confidence.min(0.95);
202
+ (is_score, bounded_confidence)
203
+ }
204
+
205
+ #[cfg(test)]
206
+ mod tests {
207
+ use super::*;
208
+ use serde_json::json;
209
+
210
+ fn stats(name: &str, field_type: &str, unique_ratio: f64) -> FieldStats {
211
+ FieldStats {
212
+ name: name.to_string(),
213
+ field_type: field_type.to_string(),
214
+ count: 100,
215
+ unique_count: (100.0 * unique_ratio) as usize,
216
+ unique_ratio,
217
+ is_constant: false,
218
+ constant_value: None,
219
+ min_val: None,
220
+ max_val: None,
221
+ mean_val: None,
222
+ variance: None,
223
+ change_points: Vec::new(),
224
+ avg_length: None,
225
+ top_values: Vec::new(),
226
+ }
227
+ }
228
+
229
+ fn stats_with_range(name: &str, min_v: f64, max_v: f64) -> FieldStats {
230
+ let mut s = stats(name, "numeric", 1.0);
231
+ s.min_val = Some(min_v);
232
+ s.max_val = Some(max_v);
233
+ s
234
+ }
235
+
236
+ // ---------- detect_id_field_statistically ----------
237
+
238
+ #[test]
239
+ fn id_field_low_uniqueness_rejected() {
240
+ let s = stats("status", "string", 0.5);
241
+ let values: Vec<Value> = vec![json!("ok"), json!("error"), json!("ok"), json!("ok")];
242
+ assert_eq!(detect_id_field_statistically(&s, &values), (false, 0.0));
243
+ }
244
+
245
+ #[test]
246
+ fn id_field_uuid_strings_high_confidence() {
247
+ let s = stats("uid", "string", 1.0);
248
+ let values: Vec<Value> = (0..20)
249
+ .map(|i| json!(format!("550e8400-e29b-41d4-a716-{:012x}", i)))
250
+ .collect();
251
+ let (is_id, conf) = detect_id_field_statistically(&s, &values);
252
+ assert!(is_id);
253
+ assert_eq!(conf, 0.95);
254
+ }
255
+
256
+ #[test]
257
+ fn id_field_high_entropy_strings() {
258
+ let mut s = stats("uid", "string", 1.0);
259
+ s.unique_ratio = 0.96;
260
+ // 20 random-looking hex-ish strings — high entropy.
261
+ let values: Vec<Value> = (0..20)
262
+ .map(|i| json!(format!("a3f7b2c{:06x}d8e1f4a7", i)))
263
+ .collect();
264
+ let (is_id, conf) = detect_id_field_statistically(&s, &values);
265
+ assert!(is_id);
266
+ assert!((conf - 0.8).abs() < 1e-9);
267
+ }
268
+
269
+ #[test]
270
+ fn id_field_sequential_numeric() {
271
+ let mut s = stats("id", "numeric", 1.0);
272
+ s.unique_ratio = 0.96;
273
+ s.min_val = Some(1.0);
274
+ s.max_val = Some(100.0);
275
+ let values: Vec<Value> = (1..=100).map(|i| json!(i)).collect();
276
+ let (is_id, conf) = detect_id_field_statistically(&s, &values);
277
+ assert!(is_id);
278
+ assert!((conf - 0.9).abs() < 1e-9);
279
+ }
280
+
281
+ #[test]
282
+ fn id_field_high_uniqueness_alone_triggers_catchall() {
283
+ // Numeric field with unique_ratio = 0.99 but no other signal.
284
+ // Falls through to the 0.98 catch-all.
285
+ let mut s = stats("misc", "numeric", 0.99);
286
+ s.min_val = Some(0.0);
287
+ s.max_val = Some(0.0); // zero range → numeric range branch fails
288
+ let values: Vec<Value> = (0..100).map(|_| json!(0)).collect();
289
+ let (is_id, conf) = detect_id_field_statistically(&s, &values);
290
+ assert!(is_id);
291
+ assert!((conf - 0.7).abs() < 1e-9);
292
+ }
293
+
294
+ // ---------- detect_score_field_statistically ----------
295
+
296
+ #[test]
297
+ fn score_field_unit_range_with_descending_sort() {
298
+ // Range [0, 1] (+0.4) + descending sort (+0.3) = 0.7, which
299
+ // exceeds the 0.4 threshold and is below the 0.95 cap.
300
+ let s = stats_with_range("score", 0.0, 1.0);
301
+ let items: Vec<Value> = (0..10)
302
+ .rev()
303
+ .map(|i| json!({"score": (i as f64) / 10.0}))
304
+ .collect();
305
+ let (is_score, conf) = detect_score_field_statistically(&s, &items);
306
+ assert!(is_score);
307
+ assert!(conf >= 0.7);
308
+ assert!(conf <= 0.95);
309
+ }
310
+
311
+ #[test]
312
+ fn score_field_sequential_rejected() {
313
+ // Bounded but sequential — must NOT be a score.
314
+ let s = stats_with_range("score", 1.0, 10.0);
315
+ let items: Vec<Value> = (1..=10).map(|i| json!({"score": i})).collect();
316
+ let (is_score, _) = detect_score_field_statistically(&s, &items);
317
+ assert!(!is_score);
318
+ }
319
+
320
+ #[test]
321
+ fn score_field_unbounded_range_rejected() {
322
+ // Range [0, 1000] doesn't match any of the bounded-range cases.
323
+ let s = stats_with_range("metric", 0.0, 1000.0);
324
+ let items: Vec<Value> = (0..10).map(|i| json!({"metric": i * 100})).collect();
325
+ let (is_score, _) = detect_score_field_statistically(&s, &items);
326
+ assert!(!is_score);
327
+ }
328
+
329
+ #[test]
330
+ fn score_field_signed_similarity_range() {
331
+ // Range [-1, 1] is the cosine-similarity bucket (+0.35).
332
+ let s = stats_with_range("similarity", -0.9, 0.95);
333
+ let items: Vec<Value> = (0..10)
334
+ .rev()
335
+ .map(|i| json!({"similarity": (i as f64) / 10.0 - 0.5}))
336
+ .collect();
337
+ let (is_score, _) = detect_score_field_statistically(&s, &items);
338
+ assert!(is_score);
339
+ }
340
+
341
+ #[test]
342
+ fn score_field_below_threshold_rejected() {
343
+ // Range [0, 100] alone (+0.25) is below the 0.4 threshold.
344
+ // No descending sort, no float fraction → stays below 0.4.
345
+ let s = stats_with_range("metric", 0.0, 100.0);
346
+ // Random unsorted ints — no descending hint.
347
+ let items: Vec<Value> = vec![
348
+ json!({"metric": 50}),
349
+ json!({"metric": 10}),
350
+ json!({"metric": 80}),
351
+ json!({"metric": 20}),
352
+ json!({"metric": 90}),
353
+ ];
354
+ let (is_score, _) = detect_score_field_statistically(&s, &items);
355
+ assert!(!is_score);
356
+ }
357
+
358
+ #[test]
359
+ fn score_field_non_numeric_rejected() {
360
+ let s = stats("name", "string", 0.5);
361
+ let items: Vec<Value> = vec![
362
+ json!({"name": "alice"}),
363
+ json!({"name": "bob"}),
364
+ json!({"name": "alice"}),
365
+ ];
366
+ let (is_score, _) = detect_score_field_statistically(&s, &items);
367
+ assert!(!is_score);
368
+ }
369
+
370
+ #[test]
371
+ fn score_field_missing_min_max_rejected() {
372
+ let s = stats("score", "numeric", 1.0); // no min/max set
373
+ let items: Vec<Value> = vec![json!({"score": 0.5})];
374
+ let (is_score, _) = detect_score_field_statistically(&s, &items);
375
+ assert!(!is_score);
376
+ }
377
+
378
+ #[test]
379
+ fn score_field_confidence_capped_at_95() {
380
+ // Range [0, 1] (+0.4) + descending sort (+0.3) + float fraction
381
+ // (+0.1) = 0.8. Below cap. To exceed 0.95 we'd need >0.55 from
382
+ // bonuses, which isn't possible with current rules. Pin the cap
383
+ // anyway by constructing the highest-scoring case and confirming
384
+ // it doesn't go above 0.95.
385
+ let s = stats_with_range("score", 0.0, 1.0);
386
+ let items: Vec<Value> = (0..50)
387
+ .rev()
388
+ .map(|i| json!({"score": (i as f64) / 50.0}))
389
+ .collect();
390
+ let (_, conf) = detect_score_field_statistically(&s, &items);
391
+ assert!(conf <= 0.95);
392
+ }
393
+ }
@@ -0,0 +1,72 @@
1
+ //! Field-name hashing for cache keys.
2
+ //!
3
+ //! Direct port of `_hash_field_name` (Python `smart_crusher.py:171-177`).
4
+ //! Used to look up TOIN-anonymized `preserve_fields` — TOIN stores
5
+ //! field names as **SHA-256[:8]** for privacy (per Python doc-comment
6
+ //! at `smart_crusher.py:174-175`), so cache lookups will silently miss
7
+ //! if the truncation length drifts.
8
+ //!
9
+ //! # 16 vs 8 — got it wrong once, now pinned
10
+ //!
11
+ //! The first version of this file used `[:16]` based on a misread of
12
+ //! the Python source. Code review caught the discrepancy: Python uses
13
+ //! `[:8]`. Cache lookups against TOIN's 8-char hashes would have
14
+ //! silently missed every field, defeating the entire `use_feedback_hints`
15
+ //! path. Fixed here; the tests now pin against Python `[:8]` reference
16
+ //! values verified via `python3 -c "...hexdigest()[:8]"`.
17
+
18
+ use sha2::{Digest, Sha256};
19
+
20
+ /// SHA-256 of the UTF-8 bytes, hex-encoded, truncated to **8** chars.
21
+ ///
22
+ /// Python equivalent: `hashlib.sha256(field_name.encode()).hexdigest()[:8]`.
23
+ /// Lowercase hex — both Python `hexdigest()` and Rust's `sha2` default
24
+ /// to lowercase, so this is consistent without manual case-coercion.
25
+ pub fn hash_field_name(field_name: &str) -> String {
26
+ let mut hasher = Sha256::new();
27
+ hasher.update(field_name.as_bytes());
28
+ let digest = hasher.finalize();
29
+ // Truncate to first 8 hex chars (4 bytes of digest). MUST match
30
+ // Python's `[:8]` — see module-level note above.
31
+ let hex = format!("{:x}", digest);
32
+ hex[..8].to_string()
33
+ }
34
+
35
+ #[cfg(test)]
36
+ mod tests {
37
+ use super::*;
38
+
39
+ #[test]
40
+ fn matches_python_sha256_truncated_to_8() {
41
+ // Verified against Python: hashlib.sha256(b"customer_id").hexdigest()[:8]
42
+ assert_eq!(hash_field_name("customer_id"), "1e38d67d");
43
+ }
44
+
45
+ #[test]
46
+ fn empty_string() {
47
+ // Verified against Python: hashlib.sha256(b"").hexdigest()[:8]
48
+ assert_eq!(hash_field_name(""), "e3b0c442");
49
+ }
50
+
51
+ #[test]
52
+ fn unicode_field_name() {
53
+ // Verified against Python: hashlib.sha256("café".encode()).hexdigest()[:8]
54
+ // UTF-8 bytes for "café" are 63 61 66 c3 a9 — must encode same way.
55
+ assert_eq!(hash_field_name("café"), "850f7dc4");
56
+ }
57
+
58
+ #[test]
59
+ fn deterministic() {
60
+ // Same input → same output across calls.
61
+ assert_eq!(hash_field_name("test"), hash_field_name("test"));
62
+ }
63
+
64
+ #[test]
65
+ fn output_length_is_8() {
66
+ // Always exactly 8 hex chars regardless of input length.
67
+ // This must match Python's `[:8]`; if you change it, every TOIN
68
+ // preserve-field lookup silently misses.
69
+ assert_eq!(hash_field_name("a").len(), 8);
70
+ assert_eq!(hash_field_name(&"x".repeat(1000)).len(), 8);
71
+ }
72
+ }
@@ -0,0 +1,81 @@
1
+ //! Smart statistical tool output compression — Rust port of
2
+ //! `headroom/transforms/smart_crusher.py`.
3
+ //!
4
+ //! # Stage 3c.1: like-for-like parity port
5
+ //!
6
+ //! This module is a literal Rust port of the Python `SmartCrusher`
7
+ //! implementation. The goal of Stage 3c.1 is **byte-equal output parity** for
8
+ //! every fixture in `tests/parity/fixtures/smart_crusher/`. Architectural
9
+ //! improvements (lossless-first, unified saliency score, structured CCR
10
+ //! markers, token budget) are deferred to Stage 3c.2 and tracked in
11
+ //! `~/Desktop/SmartCrusher-Architecture-Improvements.md`.
12
+ //!
13
+ //! # Bugs fixed in BOTH Python and Rust during 3c.1
14
+ //!
15
+ //! Four defects in the Python source (`headroom/transforms/smart_crusher.py`)
16
+ //! were caught during port review. They're fixed in both languages
17
+ //! simultaneously so the parity fixtures continue to byte-match:
18
+ //!
19
+ //! - **k-split overshoot** (line 2722): `_compute_k_split` keeps 2 items when
20
+ //! `k_total = 1` because `max(1, round(k_total * fraction))` floors both
21
+ //! first and last to 1. Violates `max_items_after_crush`.
22
+ //! - **sequential-pattern false positive** (line 444): `_detect_sequential_pattern`
23
+ //! does `int("001")` and silently loses zero padding. Padded string IDs
24
+ //! misclassified as sequential numeric IDs.
25
+ //! - **rare-status detection short-circuit** (line 674): `_detect_rare_status_values`
26
+ //! exits early at >10 distinct values. Datasets with 50+ error codes lose
27
+ //! rare-error preservation.
28
+ //! - **percentile off-by-one** (line 2844): For `len < 8`, integer-division
29
+ //! percentile indices are off by one. Cosmetic — only affects strategy
30
+ //! debug strings.
31
+ //!
32
+ //! Each fix has a fixture entry in the parity harness and a corresponding
33
+ //! test in `tests/test_transforms/test_smart_crusher_bugs.py`.
34
+
35
+ mod analyzer;
36
+ mod anchors;
37
+ mod builder;
38
+ mod classifier;
39
+ pub mod compaction;
40
+ mod config;
41
+ mod constraints;
42
+ mod crusher;
43
+ mod crushers;
44
+ mod error_keywords;
45
+ mod field_detect;
46
+ mod hashing;
47
+ mod observer;
48
+ mod orchestration;
49
+ mod outliers;
50
+ mod planning;
51
+ mod statistics;
52
+ mod stats_math;
53
+ mod traits;
54
+ mod types;
55
+
56
+ pub use analyzer::SmartAnalyzer;
57
+ pub use anchors::{extract_query_anchors, item_matches_anchors};
58
+ pub use builder::SmartCrusherBuilder;
59
+ pub use classifier::{classify_array, ArrayType};
60
+ pub use config::SmartCrusherConfig;
61
+ pub use constraints::{
62
+ default_oss_constraints, KeepErrorsConstraint, KeepStructuralOutliersConstraint,
63
+ };
64
+ pub use crusher::{CrushArrayResult, SmartCrusher};
65
+ pub use crushers::{compute_k_split, crush_number_array, crush_object, crush_string_array};
66
+ pub use error_keywords::ERROR_KEYWORDS;
67
+ pub use field_detect::{detect_id_field_statistically, detect_score_field_statistically};
68
+ pub use hashing::hash_field_name;
69
+ pub use observer::TracingObserver;
70
+ pub use orchestration::{deduplicate_indices_by_content, fill_remaining_slots, prioritize_indices};
71
+ pub use outliers::{
72
+ detect_error_items_for_preservation, detect_rare_status_values, detect_structural_outliers,
73
+ };
74
+ pub use planning::{item_has_preserve_field_match, map_to_anchor_pattern, SmartCrusherPlanner};
75
+ pub use statistics::{calculate_string_entropy, detect_sequential_pattern, is_uuid_format};
76
+ pub use stats_math::{format_g, mean, median, sample_stdev, sample_variance};
77
+ pub use traits::{Constraint, CrushEvent, Observer, Scorer};
78
+ pub use types::{
79
+ ArrayAnalysis, CompressionPlan, CompressionStrategy, CrushResult, CrushabilityAnalysis,
80
+ FieldStats,
81
+ };
@@ -0,0 +1,66 @@
1
+ //! OSS default `Observer` implementation.
2
+ //!
3
+ //! Ships [`TracingObserver`] which writes each `CrushEvent` to the
4
+ //! `tracing` crate at `debug` level. Subscribers that filter `debug`
5
+ //! out (typical production config) pay nothing — `tracing` stops
6
+ //! evaluation at the level check before constructing the event
7
+ //! fields. Subscribers that retain `debug` get a structured per-crush
8
+ //! event suitable for log analytics.
9
+ //!
10
+ //! Enterprise consumers ship richer observers — `AuditObserver` for
11
+ //! SOC2/HIPAA decision logs, `MetricsObserver` for Datadog/Atlas
12
+ //! gauges, `LoopTrainingObserver` to stream events to Headroom Loop —
13
+ //! all on the same trait.
14
+
15
+ use super::traits::{CrushEvent, Observer};
16
+
17
+ /// Writes each `CrushEvent` to the `tracing` crate at `debug` level.
18
+ /// Zero-cost when the subscriber filters `debug` out.
19
+ #[derive(Debug, Default, Clone, Copy)]
20
+ pub struct TracingObserver;
21
+
22
+ impl Observer for TracingObserver {
23
+ fn name(&self) -> &str {
24
+ "tracing"
25
+ }
26
+
27
+ fn on_event(&self, event: &CrushEvent) {
28
+ // `tracing::debug!` is a macro; the level check happens before
29
+ // the fields are evaluated, so this is essentially free at
30
+ // higher log levels.
31
+ tracing::debug!(
32
+ target: "headroom::smart_crusher",
33
+ strategy = %event.strategy,
34
+ input_bytes = event.input_bytes,
35
+ output_bytes = event.output_bytes,
36
+ elapsed_ns = event.elapsed_ns,
37
+ was_modified = event.was_modified,
38
+ "smart_crusher.crush emitted",
39
+ );
40
+ }
41
+ }
42
+
43
+ #[cfg(test)]
44
+ mod tests {
45
+ use super::*;
46
+
47
+ #[test]
48
+ fn tracing_observer_does_not_panic_on_event() {
49
+ // We can't easily assert what `tracing` did without a
50
+ // subscriber set up — but the call must not panic, and the
51
+ // event fields must be readable.
52
+ let event = CrushEvent {
53
+ strategy: "passthrough".to_string(),
54
+ input_bytes: 100,
55
+ output_bytes: 100,
56
+ elapsed_ns: 0,
57
+ was_modified: false,
58
+ };
59
+ TracingObserver.on_event(&event);
60
+ }
61
+
62
+ #[test]
63
+ fn tracing_observer_name_is_stable() {
64
+ assert_eq!(TracingObserver.name(), "tracing");
65
+ }
66
+ }