@wildshard/sdk 0.0.0 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (687) hide show
  1. package/GUIDE.md +790 -0
  2. package/README.md +14 -4
  3. package/bin/wildshard.mjs +38 -0
  4. package/lint/declaration-config.d.mts +2 -0
  5. package/lint/declaration-config.mjs +19 -0
  6. package/lint/engine-plugin.d.mts +2 -0
  7. package/lint/engine-plugin.mjs +40 -0
  8. package/lint/host-callbacks.d.mts +6 -0
  9. package/lint/host-callbacks.mjs +123 -0
  10. package/lint/host-files.d.mts +1 -0
  11. package/lint/host-files.mjs +7 -0
  12. package/lint/layer-exports.d.mts +2 -0
  13. package/lint/layer-exports.mjs +21 -0
  14. package/lint/legacy-line-basis.json +995 -0
  15. package/lint/nine-tiling-baseline.json +35 -0
  16. package/lint/ratchet.json +11 -0
  17. package/lint/runtime-files.d.mts +12 -0
  18. package/lint/runtime-files.json +16 -0
  19. package/lint/runtime-files.mjs +69 -0
  20. package/lint/runtime-performance.d.mts +6 -0
  21. package/lint/runtime-performance.mjs +184 -0
  22. package/lint/sdk-plugin.d.mts +4 -0
  23. package/lint/sdk-plugin.mjs +134 -0
  24. package/lint/shardfile-boundaries.d.mts +10 -0
  25. package/lint/shardfile-boundaries.mjs +122 -0
  26. package/lint/tile-bake-debt.json +556 -0
  27. package/package.json +371 -4
  28. package/scripts/agent-parity.mjs +1524 -0
  29. package/scripts/agent-sync.mjs +518 -0
  30. package/scripts/apfs-clone.mjs +67 -0
  31. package/scripts/assert-store-layout.mjs +23 -0
  32. package/scripts/astc6-phone-cap.d.mts +3 -0
  33. package/scripts/astc6-phone-cap.mjs +137 -0
  34. package/scripts/audit-assets.d.mts +10 -0
  35. package/scripts/audit-assets.mjs +151 -0
  36. package/scripts/bake/coatFiles.d.mts +6 -0
  37. package/scripts/bake/coatFiles.mjs +37 -0
  38. package/scripts/bake/environment.d.mts +2 -0
  39. package/scripts/bake/environment.mjs +58 -0
  40. package/scripts/bake/far-proxies.mjs +45 -0
  41. package/scripts/bake/keyed-sky.d.mts +4 -0
  42. package/scripts/bake/keyed-sky.mjs +34 -0
  43. package/scripts/bake/movers.mjs +56 -0
  44. package/scripts/bake/nativeWorld.d.mts +6 -0
  45. package/scripts/bake/nativeWorld.mjs +43 -0
  46. package/scripts/bake/navmeshGround.ts +22 -0
  47. package/scripts/bake/near-placeholder.mjs +331 -0
  48. package/scripts/bake/placeholderShards.mjs +41 -0
  49. package/scripts/bake/skins.mjs +15 -0
  50. package/scripts/bake/template-skins.mjs +33 -0
  51. package/scripts/bake/viewmodelBytes.ts +26 -0
  52. package/scripts/bake/viewmodelPage.ts +11 -0
  53. package/scripts/bake/worldHost.d.mts +35 -0
  54. package/scripts/bake/worldHost.mjs +110 -0
  55. package/scripts/bake-astc6.cache.json +80 -0
  56. package/scripts/bake-astc6.far-reach.cache.json +23 -0
  57. package/scripts/bake-astc6.list.json +111 -0
  58. package/scripts/bake-astc6.mjs +279 -0
  59. package/scripts/bake-astc6.nalati-grasslands.cache.json +42 -0
  60. package/scripts/bake-catalogue.mjs +44 -0
  61. package/scripts/bake-check.mjs +54 -0
  62. package/scripts/bake-chunk.mjs +124 -0
  63. package/scripts/bake-cloud-field.mjs +24 -0
  64. package/scripts/bake-coats.mjs +110 -0
  65. package/scripts/bake-data-maps.d.mts +24 -0
  66. package/scripts/bake-data-maps.mjs +72 -0
  67. package/scripts/bake-entry-programs.mjs +117 -0
  68. package/scripts/bake-geometry.mjs +106 -0
  69. package/scripts/bake-hybrid-tiles.mjs +28 -0
  70. package/scripts/bake-ktx2.cache.json +276 -0
  71. package/scripts/bake-ktx2.list.json +365 -0
  72. package/scripts/bake-ktx2.mjs +477 -0
  73. package/scripts/bake-map-glb.mjs +127 -0
  74. package/scripts/bake-map-rest.d.mts +7 -0
  75. package/scripts/bake-map-rest.mjs +50 -0
  76. package/scripts/bake-maps.mjs +200 -0
  77. package/scripts/bake-navmesh.mjs +259 -0
  78. package/scripts/bake-packs.mjs +129 -0
  79. package/scripts/bake-pickups.mjs +102 -0
  80. package/scripts/bake-query-terrain.mjs +64 -0
  81. package/scripts/bake-recurve-pool.mjs +16 -0
  82. package/scripts/bake-section-schemas.d.mts +3 -0
  83. package/scripts/bake-template-shardfile.mjs +32 -0
  84. package/scripts/bake-textures.mjs +80 -0
  85. package/scripts/bake-viewmodel-sets.json +45 -0
  86. package/scripts/bake-viewmodel-sets.mjs +137 -0
  87. package/scripts/bake-voxel-ao.mjs +119 -0
  88. package/scripts/bake-water-ripples.mjs +25 -0
  89. package/scripts/blender/README.md +129 -0
  90. package/scripts/blender/build.sh +166 -0
  91. package/scripts/blender/lib/export-scene.mjs +129 -0
  92. package/scripts/blender/lib/glb-digest.mjs +188 -0
  93. package/scripts/blender/lib/glb.py +68 -0
  94. package/scripts/blender/lib/save_blend.py +17 -0
  95. package/scripts/blender/lib/world_fixture.py +55 -0
  96. package/scripts/blender/targets.json +591 -0
  97. package/scripts/build-sdk.mjs +95 -0
  98. package/scripts/build-shardfiles.d.mts +7 -0
  99. package/scripts/build-shardfiles.mjs +206 -0
  100. package/scripts/capture-hero.mjs +137 -0
  101. package/scripts/check-lift-review.mjs +23 -0
  102. package/scripts/chromium-keychain-check.mjs +139 -0
  103. package/scripts/chromium-keychain.d.mts +1 -0
  104. package/scripts/chromium-keychain.mjs +5 -0
  105. package/scripts/compile-script.d.mts +3 -0
  106. package/scripts/compile-script.mjs +8 -0
  107. package/scripts/creature-color.mjs +255 -0
  108. package/scripts/decide/calibrate.py +127 -0
  109. package/scripts/decide/calibration/2026-10-03/labels-s1.tsv +281 -0
  110. package/scripts/decide/calibration/2026-10-03/labels-s2.tsv +97 -0
  111. package/scripts/decide/calibration/2026-10-03/labels-s3.tsv +48 -0
  112. package/scripts/decide/calibration/2026-10-03/labels-s3b.tsv +26 -0
  113. package/scripts/decide/calibration/2026-10-03/res-capture-status-v1.jsonl +376 -0
  114. package/scripts/decide/calibration/2026-10-03/res-text-garbled-strings.jsonl +48 -0
  115. package/scripts/decide/calibration/2026-10-03/res-text-garbled-v1.jsonl +73 -0
  116. package/scripts/decide/decide.py +262 -0
  117. package/scripts/decide/decide.sh +50 -0
  118. package/scripts/decide/layer-purity-pilot.mjs +41 -0
  119. package/scripts/decide/sets/capture-status.json +46 -0
  120. package/scripts/decide/sets/layer-purity.json +28 -0
  121. package/scripts/decide/sets/text-garbled.json +17 -0
  122. package/scripts/decide/test_decide.py +37 -0
  123. package/scripts/docs.mjs +15 -0
  124. package/scripts/entry-reads/crawl.ts +152 -0
  125. package/scripts/entry-reads/tsconfig.json +25 -0
  126. package/scripts/gen-format-schema.d.mts +2 -0
  127. package/scripts/gen-format-schema.mjs +21 -0
  128. package/scripts/gen-host-catalogue.d.mts +14 -0
  129. package/scripts/gen-host-catalogue.mjs +108 -0
  130. package/scripts/gen-shard-layout-doc.d.mts +4 -0
  131. package/scripts/gen-shard-layout-doc.mjs +55 -0
  132. package/scripts/gen-shards.d.mts +17 -0
  133. package/scripts/gen-shards.mjs +311 -0
  134. package/scripts/goldens/capture-inputs.d.mts +4 -0
  135. package/scripts/goldens/capture-inputs.mjs +34 -0
  136. package/scripts/goldens/colour_shift.py +27 -0
  137. package/scripts/goldens/native-residency.d.mts +10 -0
  138. package/scripts/goldens/native-residency.mjs +104 -0
  139. package/scripts/goldens/plot-inputs.d.mts +12 -0
  140. package/scripts/goldens/plot-inputs.mjs +46 -0
  141. package/scripts/gpu-texmem.mjs +98 -0
  142. package/scripts/horizon-matte/config.py +24 -0
  143. package/scripts/horizon-matte/encode.py +91 -0
  144. package/scripts/horizon-matte/key.py +141 -0
  145. package/scripts/horizon-matte/mkjobs.py +33 -0
  146. package/scripts/horizon-matte/mkjobs_day2.py +11 -0
  147. package/scripts/horizon-matte/overlap.py +80 -0
  148. package/scripts/horizon-matte/run_codex.py +57 -0
  149. package/scripts/horizon-matte/stitch.py +133 -0
  150. package/scripts/img2mesh/CC0.md +105 -0
  151. package/scripts/img2mesh/README.md +209 -0
  152. package/scripts/img2mesh/ab_board.py +102 -0
  153. package/scripts/img2mesh/birds/birds.json +255 -0
  154. package/scripts/img2mesh/birds/birds_atlas.py +150 -0
  155. package/scripts/img2mesh/birds/birds_fix_preview.mjs +103 -0
  156. package/scripts/img2mesh/birds/birds_fix_render.py +75 -0
  157. package/scripts/img2mesh/birds/birds_pack.py +110 -0
  158. package/scripts/img2mesh/birds/birds_phone_b.py +112 -0
  159. package/scripts/img2mesh/birds/birds_post.py +550 -0
  160. package/scripts/img2mesh/birds/birds_render.py +125 -0
  161. package/scripts/img2mesh/birds/birds_sheet.py +33 -0
  162. package/scripts/img2mesh/birds/birds_view.py +60 -0
  163. package/scripts/img2mesh/board.py +100 -0
  164. package/scripts/img2mesh/build_cc0.sh +52 -0
  165. package/scripts/img2mesh/build_driftwood.sh +12 -0
  166. package/scripts/img2mesh/build_faces.sh +53 -0
  167. package/scripts/img2mesh/build_props.py +81 -0
  168. package/scripts/img2mesh/cc0_export.py +186 -0
  169. package/scripts/img2mesh/driftwood_post.py +571 -0
  170. package/scripts/img2mesh/e304_faces.sh +67 -0
  171. package/scripts/img2mesh/face_remaster.py +911 -0
  172. package/scripts/img2mesh/face_views.py +95 -0
  173. package/scripts/img2mesh/faces-e304.json +9 -0
  174. package/scripts/img2mesh/faces.json +30 -0
  175. package/scripts/img2mesh/head_cut.py +100 -0
  176. package/scripts/img2mesh/hi3d_paint.py +94 -0
  177. package/scripts/img2mesh/hi3d_refine.py +161 -0
  178. package/scripts/img2mesh/hunyuan_cpu_rasterizer.sh +42 -0
  179. package/scripts/img2mesh/pine_hollow_phone.sh +13 -0
  180. package/scripts/img2mesh/props/coral-arch.json +32 -0
  181. package/scripts/img2mesh/props/ember-furnace.json +30 -0
  182. package/scripts/img2mesh/props/night-market-gate.json +10 -0
  183. package/scripts/img2mesh/render_still.py +86 -0
  184. package/scripts/img2mesh/rig_strip.mjs +46 -0
  185. package/scripts/img2mesh/rig_transfer.mjs +104 -0
  186. package/scripts/img2mesh/split_sheet.py +48 -0
  187. package/scripts/img2mesh/trellis_batch.py +110 -0
  188. package/scripts/img2mesh/versus_board.py +114 -0
  189. package/scripts/import-bundle.d.mts +2 -0
  190. package/scripts/import-bundle.mjs +20 -0
  191. package/scripts/ktx2-ab-board.py +133 -0
  192. package/scripts/ktx2-ab.mjs +111 -0
  193. package/scripts/ktx2-settings.mjs +18 -0
  194. package/scripts/land.d.mts +14 -0
  195. package/scripts/land.mjs +809 -0
  196. package/scripts/lint-dispatch.mjs +14 -0
  197. package/scripts/map-bake-frames.d.mts +4 -0
  198. package/scripts/map-bake-frames.mjs +23 -0
  199. package/scripts/map-geometry.d.mts +9 -0
  200. package/scripts/map-geometry.mjs +29 -0
  201. package/scripts/map-world.mjs +162 -0
  202. package/scripts/mockup-local.sh +46 -0
  203. package/scripts/music/export-midi.mjs +68 -0
  204. package/scripts/music/gen/analyze.py +308 -0
  205. package/scripts/music/gen/audio_jobs.py +46 -0
  206. package/scripts/music/gen/briefs.json +51 -0
  207. package/scripts/music/gen/build_page.py +334 -0
  208. package/scripts/music/gen/folk.json +3187 -0
  209. package/scripts/music/gen/gen_ace_step.py +156 -0
  210. package/scripts/music/gen/gen_heartmula.py +187 -0
  211. package/scripts/music/gen/gen_minimax.py +143 -0
  212. package/scripts/music/gen/gen_sao.py +122 -0
  213. package/scripts/music/gen/gen_sao_small.py +104 -0
  214. package/scripts/music/gen/gen_sfx.py +98 -0
  215. package/scripts/music/gen/gen_sfx_ezaudio.py +112 -0
  216. package/scripts/music/gen/gen_sfx_moss.py +112 -0
  217. package/scripts/music/gen/models.json +61 -0
  218. package/scripts/music/gen/nalati-jobs.json +104 -0
  219. package/scripts/music/gen/nalati-score-build.json +119 -0
  220. package/scripts/music/gen/nalati-score.json +3448 -0
  221. package/scripts/music/gen/ob7-fit-decisions.json +38 -0
  222. package/scripts/music/gen/ob7-score-jobs.json +152 -0
  223. package/scripts/music/gen/ob7-sfx-jobs.json +897 -0
  224. package/scripts/music/gen/ob7_build.py +469 -0
  225. package/scripts/music/gen/ob7_generate.py +67 -0
  226. package/scripts/music/gen/ob7_run.sh +42 -0
  227. package/scripts/music/gen/orchestral.json +3187 -0
  228. package/scripts/music/gen/own_score.py +486 -0
  229. package/scripts/music/gen/ph-jobs.json +27 -0
  230. package/scripts/music/gen/ph_page.py +222 -0
  231. package/scripts/music/gen/piano.json +3175 -0
  232. package/scripts/music/gen/rank_v3.py +248 -0
  233. package/scripts/music/gen/sfx-best.json +2486 -0
  234. package/scripts/music/gen/sfx-ezaudio.json +4082 -0
  235. package/scripts/music/gen/sfx-jobs.json +57 -0
  236. package/scripts/music/gen/sfx-minimax-jobs.json +16 -0
  237. package/scripts/music/gen/sfx-minimax.json +289 -0
  238. package/scripts/music/gen/sfx-moss.json +4082 -0
  239. package/scripts/music/gen/sfx-nalati-b3-jobs.json +17 -0
  240. package/scripts/music/gen/sfx-nalati-jobs.json +338 -0
  241. package/scripts/music/gen/sfx-nalati.json +11202 -0
  242. package/scripts/music/gen/sfx-nd-jobs.json +57 -0
  243. package/scripts/music/gen/sfx-nd-moss.json +2097 -0
  244. package/scripts/music/gen/sfx-nd-sa3-medium.json +2097 -0
  245. package/scripts/music/gen/sfx-nd-summary.json +38 -0
  246. package/scripts/music/gen/sfx-peaks.json +7 -0
  247. package/scripts/music/gen/sfx-ph-jobs.json +169 -0
  248. package/scripts/music/gen/sfx-ph-moss.json +6564 -0
  249. package/scripts/music/gen/sfx-ph-sa3-medium.json +7239 -0
  250. package/scripts/music/gen/sfx-ph-summary.json +63 -0
  251. package/scripts/music/gen/sfx-sa3-medium.json +4082 -0
  252. package/scripts/music/gen/sfx-sa3.json +4082 -0
  253. package/scripts/music/gen/sfx-summary.json +107 -0
  254. package/scripts/music/gen/sfx_build.py +332 -0
  255. package/scripts/music/gen/sfx_merge.py +255 -0
  256. package/scripts/music/gen/sfx_minimax.py +61 -0
  257. package/scripts/music/gen/sfx_nalati.py +331 -0
  258. package/scripts/music/gen/sfx_sprite.py +424 -0
  259. package/scripts/music/gen/stems.py +539 -0
  260. package/scripts/music/gen/test_loop_meter.py +29 -0
  261. package/scripts/music/gen/test_ob7_provenance.py +77 -0
  262. package/scripts/music/gen/v3-folk-build.json +148 -0
  263. package/scripts/music/gen/v3-folk.json +1818 -0
  264. package/scripts/music/gen/v3-jobs.json +145 -0
  265. package/scripts/music/gen/v3-orchestral-build.json +148 -0
  266. package/scripts/music/gen/v3-orchestral.json +1813 -0
  267. package/scripts/music/gen/v3-ph-folk-build.json +94 -0
  268. package/scripts/music/gen/v3-ph-folk.json +1806 -0
  269. package/scripts/music/gen/v3-ph-orchestral-build.json +94 -0
  270. package/scripts/music/gen/v3-ph-orchestral.json +1824 -0
  271. package/scripts/music/gen/v3-ph-piano-build.json +94 -0
  272. package/scripts/music/gen/v3-ph-piano.json +1818 -0
  273. package/scripts/music/gen/v3-piano-build.json +148 -0
  274. package/scripts/music/gen/v3-piano.json +1813 -0
  275. package/scripts/music/wildshard-theme.mid +0 -0
  276. package/scripts/music/wildshard-trailer30.mid +0 -0
  277. package/scripts/named-blob-output.d.mts +8 -0
  278. package/scripts/named-blob-output.mjs +48 -0
  279. package/scripts/pack-all.mjs +15 -0
  280. package/scripts/pid-lock.d.mts +1 -0
  281. package/scripts/pid-lock.mjs +63 -0
  282. package/scripts/practice/bake_dummy.py +53 -0
  283. package/scripts/practice/build_dummies.sh +43 -0
  284. package/scripts/practice/dummy_parts.py +568 -0
  285. package/scripts/practice/dummy_rig_gate.py +139 -0
  286. package/scripts/practice/gate_sheet.py +36 -0
  287. package/scripts/practice/generate_dummy_unimate.py +132 -0
  288. package/scripts/practice/pack_dummy.mjs +59 -0
  289. package/scripts/practice/repair_dummy_weights.mjs +68 -0
  290. package/scripts/practice/rig_dummy.py +828 -0
  291. package/scripts/practice/verify_unimate_skin.mjs +356 -0
  292. package/scripts/preparation-seed.mjs +15 -0
  293. package/scripts/prepare-basis-tool.mjs +6 -0
  294. package/scripts/prepare-product.d.mts +14 -0
  295. package/scripts/prepare-product.mjs +101 -0
  296. package/scripts/product-build-tools.d.mts +3 -0
  297. package/scripts/product-build-tools.json +3 -0
  298. package/scripts/product-build-tools.mjs +31 -0
  299. package/scripts/publish-public.mjs +7 -0
  300. package/scripts/push-tables.d.mts +1 -0
  301. package/scripts/push-tables.mjs +28 -0
  302. package/scripts/record-shard-mounts.mjs +133 -0
  303. package/scripts/sdk-externals.d.mts +2 -0
  304. package/scripts/sdk-externals.mjs +2 -0
  305. package/scripts/section-inventory.ts +209 -0
  306. package/scripts/select-candidate.mjs +15 -0
  307. package/scripts/shard-build-pool.d.mts +4 -0
  308. package/scripts/shard-build-pool.mjs +53 -0
  309. package/scripts/shard-line-baseline.json +17 -0
  310. package/scripts/shard-milestones.d.mts +15 -0
  311. package/scripts/shard-milestones.mjs +105 -0
  312. package/scripts/shard-output-report.d.mts +9 -0
  313. package/scripts/shard-output-report.mjs +85 -0
  314. package/scripts/shard-platform-cli.mjs +93 -0
  315. package/scripts/shard-progress.mjs +212 -0
  316. package/scripts/shard-timelapse.py +102 -0
  317. package/scripts/shardfile-cold-boot.mjs +79 -0
  318. package/scripts/shardfile-vite.d.mts +4 -0
  319. package/scripts/shardfile-vite.mjs +20 -0
  320. package/scripts/simplify-models.mjs +24 -0
  321. package/scripts/site-facts.mjs +88 -0
  322. package/scripts/test-template-gate.mjs +44 -0
  323. package/scripts/test_golden_compare.py +68 -0
  324. package/scripts/tex-tiers.cache.json +181 -0
  325. package/scripts/tex-tiers.mjs +240 -0
  326. package/scripts/texmem-probe.mjs +184 -0
  327. package/scripts/unused-assets.mjs +173 -0
  328. package/scripts/vite-tmp.d.mts +23 -0
  329. package/scripts/vite-tmp.mjs +157 -0
  330. package/scripts/wave-line-baselines.json +32 -0
  331. package/scripts/wildshard.d.mts +4 -0
  332. package/scripts/wildshard.mjs +105 -0
  333. package/scripts/witness-checkpoints.d.mts +10 -0
  334. package/scripts/witness-checkpoints.mjs +84 -0
  335. package/scripts/witness-generation.d.mts +10 -0
  336. package/scripts/witness-generation.mjs +45 -0
  337. package/scripts/witness-manifests.d.mts +8 -0
  338. package/scripts/witness-manifests.mjs +157 -0
  339. package/scripts/worktree-ignore.d.mts +4 -0
  340. package/scripts/worktree-ignore.mjs +36 -0
  341. package/scripts/worktree-reap.mjs +214 -0
  342. package/scripts/worktree.mjs +396 -0
  343. package/scripts/worldclaw/capture-front.sh +28 -0
  344. package/scripts/worldclaw/design-template.md +62 -0
  345. package/scripts/worldclaw/spec-map.py +92 -0
  346. package/scripts/worldclaw/spec.ts +96 -0
  347. package/skills/wildshard/SKILL.md +50 -0
  348. package/skills/wildshard-goldens/SKILL.md +54 -0
  349. package/skills/wildshard-mockup-to-model/SKILL.md +56 -0
  350. package/skills/wildshard-upgrade/SKILL.md +46 -0
  351. package/src/.oxfmtrc.json +50 -0
  352. package/src/.oxlintrc.json +173 -0
  353. package/src/cli/account/account.ts +199 -0
  354. package/src/cli/account/command.ts +193 -0
  355. package/src/cli/account/key.ts +154 -0
  356. package/src/cli/args.ts +97 -0
  357. package/src/cli/audio/audio.ts +24 -0
  358. package/src/cli/bin.mjs +8 -0
  359. package/src/cli/delete/delete.ts +258 -0
  360. package/src/cli/help.ts +196 -0
  361. package/src/cli/hero/adopt.ts +103 -0
  362. package/src/cli/hero/hero.ts +112 -0
  363. package/src/cli/hero/stamp.ts +298 -0
  364. package/src/cli/main.ts +292 -0
  365. package/src/cli/report.ts +16 -0
  366. package/src/cli/shardfile/command.ts +50 -0
  367. package/src/cli/shardfile/shardfile.ts +192 -0
  368. package/src/cli/upload/api.ts +246 -0
  369. package/src/cli/upload/compress.ts +55 -0
  370. package/src/cli/upload/hero.ts +62 -0
  371. package/src/cli/upload/placement.ts +115 -0
  372. package/src/cli/upload/provenance.ts +192 -0
  373. package/src/cli/upload/signature.ts +30 -0
  374. package/src/cli/upload/upload.ts +269 -0
  375. package/src/cli/upload/validate.ts +74 -0
  376. package/src/cli/upload/wire.ts +147 -0
  377. package/src/cli/version.ts +63 -0
  378. package/src/commons/bake/portableMath.ts +187 -0
  379. package/src/commons/catalogue.ts +10 -0
  380. package/src/commons/courseProgram.ts +32 -0
  381. package/src/commons/practiceCourse.ts +16 -0
  382. package/src/commons/scripts/abi.as +14 -0
  383. package/src/commons/scripts/bridge.as +14 -0
  384. package/src/commons/scripts/course.as +63 -0
  385. package/src/scripts/ask-new.sh +29 -0
  386. package/src/scripts/asks.mjs +141 -0
  387. package/src/scripts/herdr-prompt.sh +34 -0
  388. package/src/scripts/herdr-question-open.sh +67 -0
  389. package/src/scripts/md-wrap.mjs +229 -0
  390. package/src/server/app.ts +19 -0
  391. package/src/server/serve.ts +49 -0
  392. package/src/sharddev/admission.ts +7 -0
  393. package/src/sharddev/arenaView.ts +15 -0
  394. package/src/sharddev/as/groupBankV2.ts +36 -0
  395. package/src/sharddev/as/groupStepV2.ts +13 -0
  396. package/src/sharddev/as/ws.ts +30 -0
  397. package/src/sharddev/as/wsV2.ts +180 -0
  398. package/src/sharddev/assemblyscriptCompiler.d.mts +5 -0
  399. package/src/sharddev/assemblyscriptCompiler.mjs +14 -0
  400. package/src/sharddev/assetHandle.ts +84 -0
  401. package/src/sharddev/assetOwner.ts +70 -0
  402. package/src/sharddev/assetScope.ts +30 -0
  403. package/src/sharddev/assets.ts +21 -0
  404. package/src/sharddev/audio.ts +9 -0
  405. package/src/sharddev/audioEncode.ts +211 -0
  406. package/src/sharddev/author.ts +3 -0
  407. package/src/sharddev/authorError.ts +28 -0
  408. package/src/sharddev/authorManifest.ts +39 -0
  409. package/src/sharddev/bake/annulus.ts +19 -0
  410. package/src/sharddev/bake/assemblyscriptMemo.ts +76 -0
  411. package/src/sharddev/bake/assemblyscriptMemoPort.ts +4 -0
  412. package/src/sharddev/bake/authoredWorld.ts +201 -0
  413. package/src/sharddev/bake/basisEncoder.ts +95 -0
  414. package/src/sharddev/bake/basisGlb.ts +85 -0
  415. package/src/sharddev/bake/basisTool.ts +74 -0
  416. package/src/sharddev/bake/basisToolInputs.ts +476 -0
  417. package/src/sharddev/bake/byteCodec.ts +33 -0
  418. package/src/sharddev/bake/canvasAtlas.ts +406 -0
  419. package/src/sharddev/bake/coarseCopy.ts +59 -0
  420. package/src/sharddev/bake/colliders.ts +87 -0
  421. package/src/sharddev/bake/compactGlb.ts +224 -0
  422. package/src/sharddev/bake/compileScript.ts +119 -0
  423. package/src/sharddev/bake/compileScriptV2.ts +75 -0
  424. package/src/sharddev/bake/contactRows.ts +84 -0
  425. package/src/sharddev/bake/creaturePlacement.ts +117 -0
  426. package/src/sharddev/bake/export.ts +67 -0
  427. package/src/sharddev/bake/facetedGeometry.ts +379 -0
  428. package/src/sharddev/bake/farImpostor.ts +120 -0
  429. package/src/sharddev/bake/forest.ts +100 -0
  430. package/src/sharddev/bake/format-hook.mjs +2 -0
  431. package/src/sharddev/bake/generatorGlb.ts +23 -0
  432. package/src/sharddev/bake/geometryBounds.ts +77 -0
  433. package/src/sharddev/bake/geometryError.ts +48 -0
  434. package/src/sharddev/bake/glb.ts +355 -0
  435. package/src/sharddev/bake/glbCompression.ts +143 -0
  436. package/src/sharddev/bake/gltfSource.ts +59 -0
  437. package/src/sharddev/bake/groundMap.ts +142 -0
  438. package/src/sharddev/bake/image.ts +20 -0
  439. package/src/sharddev/bake/isleMap.ts +64 -0
  440. package/src/sharddev/bake/json.mjs +84 -0
  441. package/src/sharddev/bake/keyedSky.ts +47 -0
  442. package/src/sharddev/bake/keyedSkyMemo.ts +39 -0
  443. package/src/sharddev/bake/kinds.ts +137 -0
  444. package/src/sharddev/bake/lightSources.ts +31 -0
  445. package/src/sharddev/bake/mapAssembly.ts +84 -0
  446. package/src/sharddev/bake/mapRaster.ts +173 -0
  447. package/src/sharddev/bake/mapRest.ts +57 -0
  448. package/src/sharddev/bake/mapScenes.ts +234 -0
  449. package/src/sharddev/bake/materialGraph.ts +32 -0
  450. package/src/sharddev/bake/meadow.ts +27 -0
  451. package/src/sharddev/bake/meshoptChoiceMemo.ts +34 -0
  452. package/src/sharddev/bake/nativeInteractionFacts.ts +5 -0
  453. package/src/sharddev/bake/nativeLattice.ts +178 -0
  454. package/src/sharddev/bake/nativeRaster.ts +106 -0
  455. package/src/sharddev/bake/nativeTerrainField.ts +11 -0
  456. package/src/sharddev/bake/navigation-json.mjs +38 -0
  457. package/src/sharddev/bake/navigation.ts +113 -0
  458. package/src/sharddev/bake/navigationAsset.ts +18 -0
  459. package/src/sharddev/bake/nearPlaceholder.ts +206 -0
  460. package/src/sharddev/bake/normalizeRig.ts +80 -0
  461. package/src/sharddev/bake/phoneAstc.ts +93 -0
  462. package/src/sharddev/bake/placeholders.ts +581 -0
  463. package/src/sharddev/bake/placement.ts +80 -0
  464. package/src/sharddev/bake/portableBytes.ts +18 -0
  465. package/src/sharddev/bake/portableBytesMemo.ts +50 -0
  466. package/src/sharddev/bake/practiceCourse.ts +49 -0
  467. package/src/sharddev/bake/primitives.ts +96 -0
  468. package/src/sharddev/bake/props.ts +443 -0
  469. package/src/sharddev/bake/questPlacement.ts +98 -0
  470. package/src/sharddev/bake/rawTexture.ts +26 -0
  471. package/src/sharddev/bake/riderArms.ts +97 -0
  472. package/src/sharddev/bake/rig.ts +95 -0
  473. package/src/sharddev/bake/riggedHullRecipes.ts +40 -0
  474. package/src/sharddev/bake/signPlacements.ts +25 -0
  475. package/src/sharddev/bake/simplifier.ts +52 -0
  476. package/src/sharddev/bake/skinned.ts +312 -0
  477. package/src/sharddev/bake/slabChunks.ts +149 -0
  478. package/src/sharddev/bake/slabs.ts +263 -0
  479. package/src/sharddev/bake/source-loader.mjs +55 -0
  480. package/src/sharddev/bake/sourceMetadata.ts +54 -0
  481. package/src/sharddev/bake/species.ts +368 -0
  482. package/src/sharddev/bake/specimenCatalogue.ts +47 -0
  483. package/src/sharddev/bake/splatGround.ts +141 -0
  484. package/src/sharddev/bake/staticMaterials.ts +171 -0
  485. package/src/sharddev/bake/terrain.ts +195 -0
  486. package/src/sharddev/bake/texture.ts +33 -0
  487. package/src/sharddev/bake/textureWasm.ts +81 -0
  488. package/src/sharddev/bake/tileEncoder.ts +11 -0
  489. package/src/sharddev/bake/tileGrid.ts +62 -0
  490. package/src/sharddev/bake/v2Finite.ts +160 -0
  491. package/src/sharddev/bake/v2Fuel.ts +71 -0
  492. package/src/sharddev/bake/wholePartition.ts +74 -0
  493. package/src/sharddev/bake/wholePieceJoin.ts +147 -0
  494. package/src/sharddev/bake/world.ts +173 -0
  495. package/src/sharddev/bake/worldCollision.ts +128 -0
  496. package/src/sharddev/bake/worldGeometry.ts +237 -0
  497. package/src/sharddev/bake/worldGlb.ts +123 -0
  498. package/src/sharddev/bake/worldImage.ts +12 -0
  499. package/src/sharddev/bake/worldLod.ts +128 -0
  500. package/src/sharddev/bake/worldRows.ts +102 -0
  501. package/src/sharddev/bake/worldTextureMemo.ts +63 -0
  502. package/src/sharddev/bake/zstdBytesMemo.ts +52 -0
  503. package/src/sharddev/bake.ts +193 -0
  504. package/src/sharddev/bakePublication.ts +31 -0
  505. package/src/sharddev/behaviourSource.ts +94 -0
  506. package/src/sharddev/bin/wildshard.mjs +7 -0
  507. package/src/sharddev/blobBytes.ts +65 -0
  508. package/src/sharddev/blobs.ts +138 -0
  509. package/src/sharddev/bootInventory.ts +129 -0
  510. package/src/sharddev/bossProfiles.ts +18 -0
  511. package/src/sharddev/buildBehaviour.ts +77 -0
  512. package/src/sharddev/buildCacheMetrics.ts +17 -0
  513. package/src/sharddev/buildDecisionScripts.ts +122 -0
  514. package/src/sharddev/check.ts +117 -0
  515. package/src/sharddev/checkProject.ts +126 -0
  516. package/src/sharddev/cli.ts +191 -0
  517. package/src/sharddev/clientChannels.ts +169 -0
  518. package/src/sharddev/clientScripts.ts +10 -0
  519. package/src/sharddev/commons.ts +77 -0
  520. package/src/sharddev/commonsCosts.ts +11 -0
  521. package/src/sharddev/compileMovers.ts +11 -0
  522. package/src/sharddev/configBoundary.ts +6 -0
  523. package/src/sharddev/cookInput.ts +40 -0
  524. package/src/sharddev/crowds.ts +6 -0
  525. package/src/sharddev/decisionBindingMap.ts +11 -0
  526. package/src/sharddev/decisionScriptBindings.ts +117 -0
  527. package/src/sharddev/decisionScripts.ts +28 -0
  528. package/src/sharddev/decisionSource.ts +51 -0
  529. package/src/sharddev/dev.ts +113 -0
  530. package/src/sharddev/director.ts +26 -0
  531. package/src/sharddev/directorAbi.ts +77 -0
  532. package/src/sharddev/discoveryDocument.ts +97 -0
  533. package/src/sharddev/draft.ts +11 -0
  534. package/src/sharddev/eliteEntryRows.ts +29 -0
  535. package/src/sharddev/entries.ts +76 -0
  536. package/src/sharddev/entryReads.ts +73 -0
  537. package/src/sharddev/executeBundle.ts +55 -0
  538. package/src/sharddev/finds.ts +5 -0
  539. package/src/sharddev/formatJsonSchema.ts +3 -0
  540. package/src/sharddev/generationCache.ts +257 -0
  541. package/src/sharddev/generationRecipe.ts +94 -0
  542. package/src/sharddev/handwritten.ts +110 -0
  543. package/src/sharddev/immutable.ts +14 -0
  544. package/src/sharddev/interactions.ts +38 -0
  545. package/src/sharddev/kit/bakedGeometry.ts +16 -0
  546. package/src/sharddev/kit/geometryPack.ts +110 -0
  547. package/src/sharddev/ledger.ts +13 -0
  548. package/src/sharddev/looks/tileField.ts +67 -0
  549. package/src/sharddev/materialGraphFiles.ts +57 -0
  550. package/src/sharddev/materials.ts +574 -0
  551. package/src/sharddev/measure.ts +18 -0
  552. package/src/sharddev/modes.ts +115 -0
  553. package/src/sharddev/moverPrograms.ts +213 -0
  554. package/src/sharddev/movers.ts +75 -0
  555. package/src/sharddev/nativePopulationRows.ts +46 -0
  556. package/src/sharddev/newProject.ts +247 -0
  557. package/src/sharddev/noise.ts +54 -0
  558. package/src/sharddev/outputProduct.ts +188 -0
  559. package/src/sharddev/outputRuntime.ts +66 -0
  560. package/src/sharddev/performancePolicy.ts +18 -0
  561. package/src/sharddev/phasedBoss.ts +34 -0
  562. package/src/sharddev/physics.ts +194 -0
  563. package/src/sharddev/platformSections.ts +42 -0
  564. package/src/sharddev/plumbing.ts +8 -0
  565. package/src/sharddev/productOutput.ts +128 -0
  566. package/src/sharddev/project.ts +337 -0
  567. package/src/sharddev/projectCompilerIdentity.ts +94 -0
  568. package/src/sharddev/projectDecisions.ts +66 -0
  569. package/src/sharddev/projectEntryProof.ts +32 -0
  570. package/src/sharddev/projectGeneration.ts +219 -0
  571. package/src/sharddev/projectInputFiles.ts +47 -0
  572. package/src/sharddev/projectManifest.ts +108 -0
  573. package/src/sharddev/projectMap.ts +35 -0
  574. package/src/sharddev/projectOutput.ts +242 -0
  575. package/src/sharddev/projectPolicy.ts +17 -0
  576. package/src/sharddev/projectSections.ts +27 -0
  577. package/src/sharddev/questGraph.ts +25 -0
  578. package/src/sharddev/quests.ts +65 -0
  579. package/src/sharddev/random.ts +61 -0
  580. package/src/sharddev/refusals.ts +234 -0
  581. package/src/sharddev/reportCard.ts +13 -0
  582. package/src/sharddev/returnProjectionV2.ts +81 -0
  583. package/src/sharddev/rows.ts +192 -0
  584. package/src/sharddev/runtimeImports.ts +38 -0
  585. package/src/sharddev/runtimeMirrors.ts +39 -0
  586. package/src/sharddev/runtimePerformance.ts +38 -0
  587. package/src/sharddev/scene.ts +321 -0
  588. package/src/sharddev/sceneAnimation.ts +54 -0
  589. package/src/sharddev/sceneAudio.ts +64 -0
  590. package/src/sharddev/sceneDeclarations.ts +100 -0
  591. package/src/sharddev/sceneGraph.ts +139 -0
  592. package/src/sharddev/sceneTransform.ts +12 -0
  593. package/src/sharddev/schemaValidation.ts +61 -0
  594. package/src/sharddev/sections.ts +47 -0
  595. package/src/sharddev/shardSource.ts +59 -0
  596. package/src/sharddev/sourceReader.ts +26 -0
  597. package/src/sharddev/spawns.ts +38 -0
  598. package/src/sharddev/species/clips.ts +24 -0
  599. package/src/sharddev/species.ts +29 -0
  600. package/src/sharddev/speciesBrains.ts +19 -0
  601. package/src/sharddev/synth.ts +66 -0
  602. package/src/sharddev/test/compileDualScriptV2.ts +71 -0
  603. package/src/sharddev/test/compileSimV2.ts +21 -0
  604. package/src/sharddev/test/diskScriptScenario.ts +86 -0
  605. package/src/sharddev/test/scriptScenario.ts +249 -0
  606. package/src/sharddev/test/scriptSource.ts +12 -0
  607. package/src/sharddev/version.ts +4 -0
  608. package/src/sharddev/weapons/bowProfile.ts +20 -0
  609. package/src/sharddev/weapons/firearmRows.ts +11 -0
  610. package/src/sharddev/weapons/meleeProfile.ts +71 -0
  611. package/src/sharddev/weapons/thrownProfile.ts +10 -0
  612. package/src/sharddev/worldScenes.ts +308 -0
  613. package/src/sharddev/worldSource.ts +82 -0
  614. package/src/shards/_template/README.md +78 -0
  615. package/src/shards/_template/assets/2bf489fdb15f1734ddb4c4f32d500ec6da85c765ec7a4eb28dc6781160e7ec8c +0 -0
  616. package/src/shards/_template/assets/97ec4d8f75f5fa6239ee919444d6dc19fd35896bb305930c1f050ac6e0e0e6a6 +1 -0
  617. package/src/shards/_template/assets/a6a587a31327f936b1b04c05ade818c73fc8964260918662db43539465e27586 +0 -0
  618. package/src/shards/_template/assets/b4fbde0422e125b498c3dc8b9a5cc2516c8598f09e9d0e5f6b639b32f98179e6 +0 -0
  619. package/src/shards/_template/assets/bfa4dfc9c18979f904557ee8deab0058b8a399be10266f5fb1578b403f482fd4 +1 -0
  620. package/src/shards/_template/assets/ef3b7ff4fd22715771cb7d68a3977a903c5e7c3dc293542687d04b3ef3ace2cb +0 -0
  621. package/src/shards/_template/assets/f2db05998615ce1cb79ea96be32c168842eb6a2b34ec01feb86d36404603ee54 +0 -0
  622. package/src/shards/_template/assets/fef98ebb7fce6f66b26e78ac699e5c90f9bdcfaf8cabeb2b58125347eea8b4ab +0 -0
  623. package/src/shards/_template/behaviour/boss.as +39 -0
  624. package/src/shards/_template/behaviour/door.as +32 -0
  625. package/src/shards/_template/behaviour/hooks.json +129 -0
  626. package/src/shards/_template/behaviour/idle.as +75 -0
  627. package/src/shards/_template/behaviour/items.as +22 -0
  628. package/src/shards/_template/card/landscape.jpg +0 -0
  629. package/src/shards/_template/card/portrait.jpg +0 -0
  630. package/src/shards/_template/card/thumb.jpg +0 -0
  631. package/src/shards/_template/data/audio.json +45 -0
  632. package/src/shards/_template/data/bossDecision.json +83 -0
  633. package/src/shards/_template/data/budgets.json +70 -0
  634. package/src/shards/_template/data/card.json +281 -0
  635. package/src/shards/_template/data/clientScripts.json +987 -0
  636. package/src/shards/_template/data/creatures.json +65 -0
  637. package/src/shards/_template/data/director.json +39 -0
  638. package/src/shards/_template/data/encounters.json +96 -0
  639. package/src/shards/_template/data/items.json +172 -0
  640. package/src/shards/_template/data/layout.json +66 -0
  641. package/src/shards/_template/data/ledger.json +32 -0
  642. package/src/shards/_template/data/look.json +521 -0
  643. package/src/shards/_template/data/map.json +64 -0
  644. package/src/shards/_template/data/moves.json +16 -0
  645. package/src/shards/_template/data/placeholder.json +8 -0
  646. package/src/shards/_template/data/plumbing.json +32 -0
  647. package/src/shards/_template/data/quests.json +223 -0
  648. package/src/shards/_template/data/rows.json +423 -0
  649. package/src/shards/_template/data/skins.json +66 -0
  650. package/src/shards/_template/data/spawn.json +6 -0
  651. package/src/shards/_template/data/targets.json +150 -0
  652. package/src/shards/_template/data/text.json +12 -0
  653. package/src/shards/_template/data/ui.json +33 -0
  654. package/src/shards/_template/data/water.json +13 -0
  655. package/src/shards/_template/generators/behaviour.ts +34 -0
  656. package/src/shards/_template/generators/boss.ts +29 -0
  657. package/src/shards/_template/generators/buildOptions.ts +2 -0
  658. package/src/shards/_template/generators/cell.ts +224 -0
  659. package/src/shards/_template/generators/districts.ts +215 -0
  660. package/src/shards/_template/generators/farLook.ts +15 -0
  661. package/src/shards/_template/generators/generate.ts +27 -0
  662. package/src/shards/_template/generators/ground.ts +15 -0
  663. package/src/shards/_template/generators/kit.ts +69 -0
  664. package/src/shards/_template/generators/landscape.ts +59 -0
  665. package/src/shards/_template/generators/landscapeNoise.ts +62 -0
  666. package/src/shards/_template/generators/mapInputs.ts +10 -0
  667. package/src/shards/_template/generators/product.ts +100 -0
  668. package/src/shards/_template/generators/productOutput.ts +18 -0
  669. package/src/shards/_template/generators/props.ts +9 -0
  670. package/src/shards/_template/generators/templatePropsSource.ts +58 -0
  671. package/src/shards/_template/generators/terrain.ts +17 -0
  672. package/src/shards/_template/generators/world.ts +630 -0
  673. package/src/shards/_template/hero.json +10 -0
  674. package/src/shards/_template/look/entry-reads.json +20 -0
  675. package/src/shards/_template/manifest.json +281 -0
  676. package/src/shards/_template/shard.config.ts +10 -0
  677. package/src/shared/health.ts +10 -0
  678. package/src/tools/build-web.ts +59 -0
  679. package/src/tsconfig.json +30 -0
  680. package/src/web/app.tsx +53 -0
  681. package/src/web/index.html +12 -0
  682. package/src/web/main.tsx +10 -0
  683. package/src/web/tsconfig.json +13 -0
  684. package/tsconfig.author.json +23 -0
  685. package/tsconfig.commons.json +21 -0
  686. package/tsconfig.json +47 -0
  687. package/tsconfig.sharddev.json +20 -0
@@ -0,0 +1,76 @@
1
+ import { Matrix4, Object3D, Vector3 } from 'three';
2
+ import { updateAuthoringMatrix } from './sceneTransform';
3
+ import { parsePortalLink, type PortalLink as PortalLinkData } from '@wildshard/format/portalLink';
4
+ import { parseSocketLift, type SocketLift as SocketLiftData } from '@wildshard/format/socketLift';
5
+ import { CHUNK_HALF, ENTRY_WIDTH, ENTRY_ASPHALT } from '@wildshard/format/contentBounds';
6
+
7
+ /** Detached platform dimensions for authored midpoint sockets and their road reserve. */
8
+ export function roadSocketMetrics(): { half: number; width: 8; asphalt: 15 } {
9
+ return { half: CHUNK_HALF, width: ENTRY_WIDTH, asphalt: ENTRY_ASPHALT };
10
+ }
11
+ /** A road socket's boundary edge, with +Z north. */
12
+ export type EntryEdge = 'north' | 'east' | 'south' | 'west';
13
+ /** Authored entry row for the four road-height midpoint openings. */
14
+ export interface EntryData {
15
+ edge: EntryEdge;
16
+ at: [
17
+ number,
18
+ number,
19
+ number
20
+ ];
21
+ width: 8;
22
+ kind?: 'ground' | 'socketOverWater' | 'portalLink' | 'socketLift';
23
+ portal?: PortalLinkData;
24
+ lift?: SocketLiftData;
25
+ }
26
+ const MIDPOINTS = { north: [0, 0, 250], east: [250, 0, 0], south: [0, 0, -250], west: [-250, 0, 0] } as const;
27
+ /** A fixed 8 x 15 metre socket declaration; it does not create a floor or flatten authored ground. */
28
+ export class Entry extends Object3D {
29
+ /** The boundary edge this road socket occupies. */
30
+ edge: EntryEdge;
31
+ /** Optional floor admission kind; absent retains the host default. */
32
+ kind: EntryData['kind'];
33
+ private bindings: Pick<EntryData, 'portal' | 'lift'>;
34
+ constructor(edge: EntryEdge = 'north', kind?: EntryData['kind'], bindings: Pick<EntryData, 'portal' | 'lift'> = {}) {
35
+ super();
36
+ this.edge = edge; this.kind = kind; this.bindings = structuredClone(bindings);
37
+ this.name = `entry.${edge}`;
38
+ const at = MIDPOINTS[edge];
39
+ this.position.set(at[0], at[1], at[2]);
40
+ }
41
+ /** Clone the edge and kind with the normal scene transform and hierarchy. */
42
+ override copy(source: this, recursive = true): this { super.copy(source, recursive); this.edge = source.edge; this.kind = source.kind; this.bindings = structuredClone(source.bindings); return this; }
43
+ /** The four independent midpoint objects, in north/east/south/west order. */
44
+ static midpoints(): Entry[] { return (['north', 'east', 'south', 'west'] as const).map(edge => new Entry(edge)); }
45
+ /** Special entry subclasses supply their admitted link; a plain socket cannot guess one. */
46
+ protected entryBindings(): Pick<EntryData, 'portal' | 'lift'> {
47
+ if (this.kind === 'portalLink') { if (this.bindings.portal === undefined) throw new Error('Entry requires its matching portal link'); return { portal: parsePortalLink(this.bindings.portal) }; }
48
+ if (this.kind === 'socketLift') { if (this.bindings.lift === undefined) throw new Error('Entry requires its matching lift link'); return { lift: parseSocketLift(this.bindings.lift) }; }
49
+ return {};
50
+ }
51
+ /** Entries must retain their exact road-height world midpoint; geometry proof happens during validation. */
52
+ toEntryData(): EntryData {
53
+ updateAuthoringMatrix(this);
54
+ const at = new Vector3().setFromMatrixPosition(this.matrixWorld);
55
+ if (!at.equals(new Vector3(...MIDPOINTS[this.edge])))
56
+ throw new Error('Entry must remain at its road-height midpoint');
57
+ const expected = new Matrix4().makeTranslation(at.x, at.y, at.z);
58
+ if (this.matrixWorld.elements.some((value, index) => !Number.isFinite(value) || Math.abs(value - (expected.elements[index] ?? Infinity)) > 1e-8))
59
+ throw new Error('Entry socket frame cannot rotate, scale or shear');
60
+ return { edge: this.edge, at: [at.x, at.y, at.z], width: 8, ...(this.kind === undefined ? {} : { kind: this.kind }), ...this.entryBindings() };
61
+ }
62
+ }
63
+
64
+ /** A midpoint entry whose named mover/gate takes real feet from the road to its authored top stop. */
65
+ export class SocketLift extends Entry {
66
+ /** The bounded cell-local lift, approach and onward route; native mover ownership stays with the host. */
67
+ lift: SocketLiftData | undefined;
68
+ constructor(edge: EntryEdge = 'north', lift?: SocketLiftData) { super(edge, 'socketLift'); this.lift = lift === undefined ? undefined : structuredClone(parseSocketLift(lift)); }
69
+ /** Clone the lift declaration without sharing mutable author route rows. */
70
+ override copy(source: this, recursive = true): this { super.copy(source, recursive); this.lift = source.lift === undefined ? undefined : structuredClone(source.lift); return this; }
71
+ /** Emit exactly the existing entry wire shape, without guessing missing stops or floors. */
72
+ protected override entryBindings(): Pick<EntryData, 'lift'> {
73
+ if (this.lift === undefined || this.kind !== 'socketLift') throw new Error('SocketLift entry requires its lift link');
74
+ return { lift: parseSocketLift(this.lift) };
75
+ }
76
+ }
@@ -0,0 +1,73 @@
1
+ import * as v from 'valibot';
2
+ import { EntryReadUrlSchema, parseEntryReadSet, type EntryRead, type EntryReadSet, type RegionEntryReads } from '@wildshard/format/entryReads';
3
+ import { hashImmutableBytes } from './immutable';
4
+
5
+ /** Build-owned entry addresses. A crawl runs the same native entry read adapter
6
+ * for each tier, not a second runtime or an authored callback at prefetch time. */
7
+ export interface EntryCrawlRegion { readonly region: string; readonly at: readonly [number, number] }
8
+ export interface EntryCrawlPorts {
9
+ readonly read: (url: string) => Promise<Uint8Array>;
10
+ readonly visit: (entry: EntryCrawlRegion, tier: RegionEntryReads['tier'], read: EntryCrawlPorts['read']) => Promise<void>;
11
+ }
12
+
13
+ /** Observe actual entry demands at build time. Only immutable metadata escapes
14
+ * the crawl. Repeated reads retain their real behavior; first-demand order is
15
+ * recorded once, and a changing body at one URL refuses the product. Every
16
+ * started read drains even when entry construction or a sibling read refuses. */
17
+ export async function crawlEntryReadSet(entries: readonly EntryCrawlRegion[], ports: EntryCrawlPorts): Promise<EntryReadSet> {
18
+ const result: RegionEntryReads[] = [];
19
+ for (const entry of entries) for (const tier of ['phone', 'desktop'] as const) {
20
+ parseEntryReadSet([...result, { ...entry, tier, reads: [] }]);
21
+ const urls = new Map<string, number>(), rows: (EntryRead | undefined)[] = [], pending: Promise<void>[] = [];
22
+ const read = (url: string): Promise<Uint8Array> => {
23
+ const work = (async (): Promise<Uint8Array> => {
24
+ v.parse(EntryReadUrlSchema, url);
25
+ let index = urls.get(url);
26
+ if (index === undefined) {
27
+ if (urls.size >= 8192) throw new Error('Entry read set exceeds its URL bound');
28
+ index = rows.length; urls.set(url, index); rows.push(undefined);
29
+ }
30
+ const bytes = await ports.read(url), row = { url, hash: hashImmutableBytes(bytes), bytes: bytes.byteLength };
31
+ const previous = rows[index];
32
+ if (previous !== undefined && (previous.hash !== row.hash || previous.bytes !== row.bytes)) throw new Error('Entry URL changed during its crawl');
33
+ rows[index] = row;
34
+ return bytes;
35
+ })();
36
+ const observed = (async (): Promise<void> => { await work; })();
37
+ pending.push(observed);
38
+ // Attach an observer immediately; a native entry can demand a later read
39
+ // before awaiting an earlier one. The original rejection stays in work.
40
+ void observed.catch(() => undefined);
41
+ return work;
42
+ };
43
+ let failed = false, failure: unknown;
44
+ try { await ports.visit(entry, tier, read); } catch (error: unknown) { failed = true; failure = error; }
45
+ const finished = await Promise.allSettled(pending);
46
+ if (failed) throw failure;
47
+ for (const row of finished) if (row.status === 'rejected') throw row.reason;
48
+ const reads = rows.map(row => { if (row === undefined) throw new Error('Entry read did not settle'); return row; });
49
+ result.push({ ...entry, tier, reads });
50
+ }
51
+ return parseEntryReadSet(result);
52
+ }
53
+
54
+ export interface EntryCrawlDemand { readonly url: string; readonly range?: string }
55
+ export interface EntryCrawlInventory {
56
+ readonly files: readonly { readonly path: string; readonly hash: string; readonly compressed: number }[];
57
+ }
58
+
59
+ /** The product files and `/assets/` URLs an entry demanded, in first-demand order. Metadata sections are already
60
+ * acquired by admission. SHARD-SIZE S5: a product holds no packs, so every demand names one file. */
61
+ export function entryDemandUrls(slug: string, inventory: EntryCrawlInventory, demands: readonly EntryCrawlDemand[]): readonly string[] {
62
+ if (!/^[a-zA-Z0-9_-]+$/u.test(slug)) throw new Error('Canonical entry slug required');
63
+ const prefix = `/shardfiles/${slug}/`, result = new Set<string>();
64
+ for (const demand of demands) {
65
+ const url = v.parse(EntryReadUrlSchema, demand.url), path = url.split('?')[0] ?? '';
66
+ if (path.endsWith('/entry-reads.json') || /\.(?:js|css|wasm)$/u.test(path)) continue;
67
+ if (path.startsWith('/assets/')) { result.add(url); continue; }
68
+ if (!path.startsWith(prefix)) continue;
69
+ const relative = path.slice(prefix.length);
70
+ if (inventory.files.some(file => file.path === relative)) result.add(url);
71
+ }
72
+ return [...result];
73
+ }
@@ -0,0 +1,55 @@
1
+ // oxlint-disable-next-line import/no-nodejs-modules -- Trusted author execution owns and removes only its temporary module directory.
2
+ import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
3
+ // oxlint-disable-next-line import/no-nodejs-modules -- Keep execution scratch in the source workspace tmp, outside authored trees.
4
+ import { dirname, resolve } from 'node:path';
5
+ // oxlint-disable-next-line import/no-nodejs-modules -- Locate the enclosing source workspace without writing under src.
6
+ import { existsSync } from 'node:fs';
7
+ // oxlint-disable-next-line import/no-nodejs-modules -- Native ESM loads the original UTF-8 source as a file.
8
+ import { pathToFileURL } from 'node:url';
9
+ // oxlint-disable-next-line import/no-nodejs-modules -- Preserve native ESM's previous content-addressed namespace identity.
10
+ import { createHash } from 'node:crypto';
11
+ // oxlint-disable-next-line import/no-nodejs-modules -- Pin trusted bundle execution to Node ESM rather than a transforming test host.
12
+ import { Script, constants } from 'node:vm';
13
+
14
+ // A data URL was the same ESM identity for the same source, including rejected
15
+ // evaluations. Keep that identity without retaining its 4/3-sized encoded URL.
16
+ const namespaces = new Map<string, Promise<unknown>>();
17
+
18
+ /** Execute one trusted single-chunk build bundle. Its non-builtin imports must
19
+ * already be absolute, as for the previous data URL. The caller validates that
20
+ * boundary and retains source/input receipts. Only this module's own scratch
21
+ * is removed, after top-level await settles; exported closures remain usable. */
22
+ export function executeBundle(source: string, project: string): Promise<unknown> {
23
+ const key = createHash('sha256').update(source, 'utf8').digest('hex');
24
+ const present = namespaces.get(key);
25
+ if (present !== undefined) return present;
26
+ const pending = load(source, project);
27
+ namespaces.set(key, pending);
28
+ return pending;
29
+ }
30
+
31
+ async function load(source: string, project: string): Promise<unknown> {
32
+ let root = resolve(project);
33
+ for (let parent = root; ; parent = dirname(parent)) {
34
+ if (existsSync(resolve(parent, '.git'))) { root = parent; break; }
35
+ if (dirname(parent) === parent) break;
36
+ }
37
+ const scratch = resolve(root, 'tmp', 'sdk-execution');
38
+ await mkdir(scratch, { recursive: true });
39
+ const directory = await mkdtemp(resolve(scratch, 'module-'));
40
+ try {
41
+ const file = resolve(directory, 'bundle.mjs');
42
+ await writeFile(file, source, 'utf8');
43
+ // A host runner can rewrite import() and transform this multi-megabyte
44
+ // bundle a second time. Only the tiny import expression is compiled here;
45
+ // Node's native ESM loader evaluates the original file, just as the former
46
+ // data URL did. Never evaluate the bundle as a script or change its code.
47
+ const loader = new Script(`import(${JSON.stringify(pathToFileURL(file).href)})`, {
48
+ filename: file, importModuleDynamically: constants.USE_MAIN_CONTEXT_DEFAULT_LOADER,
49
+ });
50
+ const loaded: unknown = loader.runInThisContext();
51
+ return await loaded;
52
+ } finally {
53
+ await rm(directory, { recursive: true, force: true });
54
+ }
55
+ }
@@ -0,0 +1,5 @@
1
+ import { parseFindsCatalogue as parse, type FindsCatalogueData } from '@wildshard/format/findsCatalogue';
2
+
3
+ /** Admit bounded sticker counters, prize rows and saved-flag identities with the runtime's defining schema.
4
+ * Returns owned data only; installs no catalogue, live flag reader or world service. */
5
+ export function parseFindsCatalogue(input: unknown): FindsCatalogueData { return parse(input); }
@@ -0,0 +1,3 @@
1
+ // Engine's, coverage row 6: one copy, and this repo keeps the name.
2
+ // oxlint-disable-next-line wildshard/no-reexport, oxc/no-barrel-file -- Authors import this name, and engine owns the bytes.
3
+ export * from '@wildshard/engine/host/formatJsonSchema';
@@ -0,0 +1,257 @@
1
+ // oxlint-disable-next-line import/no-nodejs-modules -- Generation storage is a host-only filesystem capability.
2
+ import { existsSync, linkSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs';
3
+ // oxlint-disable-next-line import/no-nodejs-modules -- Content identities and private lease names never enter products.
4
+ import { createHash, randomUUID } from 'node:crypto';
5
+ // oxlint-disable-next-line import/no-nodejs-modules -- Cache paths contain only trusted roots and validated hashes.
6
+ import { basename, dirname, resolve } from 'node:path';
7
+ // oxlint-disable-next-line import/no-nodejs-modules -- Pruning runs as a low-priority background process on Mac and Linux.
8
+ import { execFileSync, spawn } from 'node:child_process';
9
+ // oxlint-disable-next-line import/no-nodejs-modules -- Resolve this installed worker even when the CLI itself is bundled.
10
+ import { createRequire } from 'node:module';
11
+ // oxlint-disable-next-line import/no-nodejs-modules -- The worker yields CPU priority to foreground builds.
12
+ import { setPriority } from 'node:os';
13
+ // oxlint-disable-next-line import/no-nodejs-modules -- Lock contention waits asynchronously, never busy-spins or recomputes a hit.
14
+ import { setTimeout as delay } from 'node:timers/promises';
15
+ // oxlint-disable-next-line import/no-nodejs-modules -- Native transactions release the shared cache mutex even after SIGKILL.
16
+ import { DatabaseSync } from 'node:sqlite';
17
+
18
+ const digest = (value: string | Uint8Array): string => createHash('sha256').update(value).digest('hex');
19
+ const hash = /^[a-f0-9]{64}$/u;
20
+ const day = 86_400_000;
21
+ interface FileRow { name: string; hash: string; bytes: number }
22
+ export interface GenerationManifest { key: string; files: FileRow[] }
23
+ interface Lease { pid: number; keys: string[] }
24
+ interface Receipt { keys: string[]; project?: string }
25
+ interface Entry { path: string; key: string; job: string; used: number; blobs: string[] }
26
+
27
+ function live(pid: number): boolean {
28
+ try { process.kill(pid, 0); return true; }
29
+ catch (error) { return !(error instanceof Error && 'code' in error && error.code === 'ESRCH'); }
30
+ }
31
+ function directories(path: string): string[] {
32
+ const top = lstatSync(path, { throwIfNoEntry: false });
33
+ if (top === undefined) return [];
34
+ if (top.isSymbolicLink()) throw new Error('Linked generation index tree');
35
+ const entries = readdirSync(path, { withFileTypes: true });
36
+ if (entries.some(row => row.isSymbolicLink())) throw new Error('Linked generation index tree');
37
+ return entries.filter(row => row.isDirectory()).map(row => row.name);
38
+ }
39
+ function json(path: string, value: unknown): void {
40
+ const temporary = `${path}.${randomUUID()}.tmp`;
41
+ try { writeFileSync(temporary, JSON.stringify(value), { flag: 'wx' }); renameSync(temporary, path); }
42
+ finally { rmSync(temporary, { force: true }); }
43
+ }
44
+ function locked<T>(root: string, work: () => T): T | undefined {
45
+ mkdirSync(root, { recursive: true });
46
+ if (lstatSync(root).isSymbolicLink()) throw new Error('Linked generation cache root');
47
+ const database = new DatabaseSync(resolve(root, '.mutex.sqlite'), { timeout: 0 });
48
+ try {
49
+ // This database is a filesystem mutex, with no SQL data. Take the read
50
+ // barrier before publishing files: IMMEDIATE can fail at COMMIT while a
51
+ // second connection still holds a schema read lock.
52
+ try { database.exec('BEGIN EXCLUSIVE'); }
53
+ catch (error) {
54
+ if (error instanceof Error && 'errcode' in error && (error.errcode === 5 || error.errcode === 6)) return undefined;
55
+ throw error;
56
+ }
57
+ try { const value = work(); database.exec('COMMIT'); return value; }
58
+ catch (error) { database.exec('ROLLBACK'); throw error; }
59
+ } finally { database.close(); }
60
+ }
61
+ async function waitLocked<T>(root: string, work: () => T): Promise<T> {
62
+ const deadline = Date.now() + 30_000;
63
+ for (;;) {
64
+ const result = locked(root, () => ({ value: work() }));
65
+ if (result !== undefined) return result.value;
66
+ if (Date.now() >= deadline) throw new Error('Generation cache lock held for 30 seconds');
67
+ await delay(10);
68
+ }
69
+ }
70
+
71
+ /** Versioned store: one immutable blob inode per SHA-256, index-only step keys.
72
+ * Every cache operation and collector uses the same lock. A busy collector
73
+ * yields briefly, preserving hits without a partially read build input.
74
+ * Active leases survive until completion/process death; successful receipts
75
+ * protect the current inputs even after the process exits. Legacy stores are
76
+ * deliberately outside this namespace: their writers do not take our lock. */
77
+ export function generationCache(base: string, project: string, scope: string): {
78
+ root: string;
79
+ blobs: string;
80
+ read: (step: string, key: string) => Promise<GenerationManifest | undefined>;
81
+ populate: (step: string, manifest: GenerationManifest, files: ReadonlyMap<string, Uint8Array>) => Promise<boolean>;
82
+ finish: (success: boolean) => Promise<void>;
83
+ } {
84
+ const root = resolve(base, 'v3'), blobs = resolve(base, 'blobs'), projectName = basename(project);
85
+ const leaseName = `${process.pid}-${randomUUID()}.json`, keys = new Set<string>();
86
+ const receiptName = `${digest(`${project}\0${scope}`)}.json`;
87
+ const pin = (key: string): void => {
88
+ keys.add(key); mkdirSync(resolve(root, 'leases'), { recursive: true });
89
+ json(resolve(root, 'leases', leaseName), { pid: process.pid, keys: [...keys] });
90
+ };
91
+ return {
92
+ root,
93
+ blobs,
94
+ read(step, key) {
95
+ return waitLocked(root, () => {
96
+ pin(key);
97
+ const path = resolve(root, 'keys', projectName, step, key);
98
+ if (!existsSync(resolve(path, 'index.json'))) return undefined;
99
+ const index = resolve(path, 'index.json');
100
+ if (statSync(index).size > 1_000_000) throw new Error('Generation cache index exceeds byte cap');
101
+ const saved = JSON.parse(readFileSync(index, 'utf8')) as GenerationManifest;
102
+ const now = new Date(); utimesSync(path, now, now);
103
+ return saved;
104
+ });
105
+ },
106
+ populate(step, manifest, files) {
107
+ return waitLocked(root, () => {
108
+ pin(manifest.key);
109
+ mkdirSync(blobs, { recursive: true });
110
+ for (const bytes of files.values()) {
111
+ const name = digest(bytes), target = resolve(blobs, name);
112
+ const verify = (): void => {
113
+ if (statSync(target).size !== bytes.byteLength) throw new Error('Generation cache byte mismatch');
114
+ const saved = readFileSync(target);
115
+ if (saved.byteLength !== bytes.byteLength || digest(saved) !== name) throw new Error('Generation cache byte mismatch');
116
+ };
117
+ if (existsSync(target)) { verify(); continue; }
118
+ const temporary = `${target}.${randomUUID()}.tmp`;
119
+ try {
120
+ writeFileSync(temporary, bytes, { flag: 'wx' });
121
+ // link is exclusive: even an unexpected concurrent writer cannot
122
+ // replace an already published content address.
123
+ try { linkSync(temporary, target); }
124
+ catch (error) {
125
+ if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST')) throw error;
126
+ verify();
127
+ }
128
+ } finally { rmSync(temporary, { force: true }); }
129
+ }
130
+ const parent = resolve(root, 'keys', projectName, step), target = resolve(parent, manifest.key);
131
+ mkdirSync(parent, { recursive: true });
132
+ if (existsSync(target)) return false;
133
+ const temporary = mkdtempSync(resolve(parent, '.writing-'));
134
+ try { writeFileSync(resolve(temporary, 'index.json'), JSON.stringify(manifest), { flag: 'wx' }); renameSync(temporary, target); }
135
+ finally { rmSync(temporary, { recursive: true, force: true }); }
136
+ return true;
137
+ });
138
+ },
139
+ finish(success) {
140
+ return waitLocked(root, () => {
141
+ if (success) {
142
+ mkdirSync(resolve(root, 'receipts'), { recursive: true });
143
+ json(resolve(root, 'receipts', receiptName), { project, keys: [...keys] });
144
+ }
145
+ rmSync(resolve(root, 'leases', leaseName), { force: true });
146
+ });
147
+ },
148
+ };
149
+ }
150
+
151
+ /** G430: retain the three most recently used keys per job, expire older history
152
+ * after a day, then evict LRU keys to 20 GB. Current receipts and live builds
153
+ * always win over the limit. Blobs are swept only after every remaining index
154
+ * is marked under the same lock; an incomplete inventory cannot sweep public keys or blobs. */
155
+ export function pruneGenerationCache(root: string, options: { now?: number; maxBytes?: number; maxAgeMs?: number; cacheOverheadBytes?: number } = {}): { removed: number; bytes: number; protected: number; cacheAllocatedBytes?: number } | undefined {
156
+ return locked(root, () => {
157
+ const now = options.now ?? Date.now(), maxBytes = options.maxBytes ?? 20_000_000_000;
158
+ const protectedKeys = new Set<string>();
159
+ for (const name of existsSync(resolve(root, 'leases')) ? readdirSync(resolve(root, 'leases')) : []) {
160
+ if (!name.endsWith('.json')) continue;
161
+ const path = resolve(root, 'leases', name), lease = JSON.parse(readFileSync(path, 'utf8')) as Lease;
162
+ if (!Number.isSafeInteger(lease.pid) || lease.pid <= 0 || !Array.isArray(lease.keys) || lease.keys.some(key => typeof key !== 'string' || !hash.test(key))) throw new Error('Invalid generation lease');
163
+ if (live(lease.pid)) for (const key of lease.keys) protectedKeys.add(key);
164
+ else rmSync(path);
165
+ }
166
+ for (const name of existsSync(resolve(root, 'receipts')) ? readdirSync(resolve(root, 'receipts')) : []) {
167
+ if (!hash.test(name.slice(0, -5)) || !name.endsWith('.json')) continue;
168
+ const path = resolve(root, 'receipts', name);
169
+ const receipt = JSON.parse(readFileSync(path, 'utf8')) as Receipt;
170
+ if (!Array.isArray(receipt.keys) || receipt.keys.some(key => typeof key !== 'string' || !hash.test(key))) throw new Error('Invalid generation receipt');
171
+ if (typeof receipt.project === 'string' && !existsSync(receipt.project)) { rmSync(path); continue; }
172
+ for (const key of receipt.keys) protectedKeys.add(key);
173
+ }
174
+ const entries: Entry[] = [];
175
+ for (const project of directories(resolve(root, 'keys'))) for (const step of directories(resolve(root, 'keys', project))) {
176
+ for (const key of directories(resolve(root, 'keys', project, step))) {
177
+ const path = resolve(root, 'keys', project, step, key);
178
+ if (/^\.writing-[a-zA-Z0-9]{6}$/u.test(key)) { rmSync(path, { recursive: true }); continue; }
179
+ if (!hash.test(key)) throw new Error('Invalid generation key directory');
180
+ const manifest = JSON.parse(readFileSync(resolve(path, 'index.json'), 'utf8')) as GenerationManifest;
181
+ if (manifest.key !== key || !Array.isArray(manifest.files) || manifest.files.some(row => !hash.test(row.hash))) throw new Error('Invalid generation index');
182
+ entries.push({ path, key, job: `${project}/${step}`, used: statSync(path).mtimeMs, blobs: manifest.files.map(row => row.hash) });
183
+ }
184
+ }
185
+ const blobs = resolve(root, '..', 'blobs'), blobSizes = new Map<string, number>(), blobAllocation = new Map<string, number>(), legacyLinks = new Set<string>();
186
+ if (lstatSync(blobs, { throwIfNoEntry: false })?.isSymbolicLink()) throw new Error('Linked generation blob pool');
187
+ const blobNames = existsSync(blobs) ? readdirSync(blobs) : [];
188
+ // No publisher can hold a private temporary while this mutex is held.
189
+ // Drop interrupted private links before classifying real legacy aliases.
190
+ for (const name of blobNames) if (/^[a-f0-9]{64}\.[a-f0-9-]{36}\.tmp$/u.test(name)) rmSync(resolve(blobs, name));
191
+ for (const name of blobNames) {
192
+ if (!hash.test(name)) continue;
193
+ const info = lstatSync(resolve(blobs, name));
194
+ if (!info.isFile() || info.isSymbolicLink()) throw new Error('Invalid generation blob');
195
+ blobSizes.set(name, info.size);
196
+ blobAllocation.set(name, info.blocks * 512);
197
+ if (info.nlink > 1) legacyLinks.add(name);
198
+ }
199
+ const counts = new Map<string, number>();
200
+ for (const entry of entries) for (const name of new Set(entry.blobs)) counts.set(name, (counts.get(name) ?? 0) + 1);
201
+ // Reclaim orphan publications before spending the budget on valid history.
202
+ for (const name of blobSizes.keys()) if (!counts.has(name) && !legacyLinks.has(name)) {
203
+ rmSync(resolve(blobs, name)); blobSizes.delete(name); blobAllocation.delete(name);
204
+ }
205
+ let bytes = [...blobSizes.values()].reduce((sum, size) => sum + size, 0), removed = 0;
206
+ let allocated = [...blobAllocation.values()].reduce((sum, size) => sum + size, 0) + (options.cacheOverheadBytes ?? 0);
207
+ const newest = new Map<string, number>(), candidates: Entry[] = [];
208
+ for (const entry of entries.sort((a, b) => b.used - a.used || a.key.localeCompare(b.key))) {
209
+ const rank = (newest.get(entry.job) ?? 0) + 1; newest.set(entry.job, rank);
210
+ newest.set(entry.path, rank);
211
+ if (!protectedKeys.has(entry.key)) candidates.push(entry);
212
+ }
213
+ for (const entry of candidates.reverse()) {
214
+ if (allocated <= maxBytes && (newest.get(entry.path) ?? 0) <= 3 && now - entry.used <= (options.maxAgeMs ?? day)) continue;
215
+ rmSync(entry.path, { recursive: true }); removed++;
216
+ for (const name of new Set(entry.blobs)) {
217
+ const count = (counts.get(name) ?? 0) - 1; counts.set(name, count);
218
+ if (count === 0 && !legacyLinks.has(name)) {
219
+ rmSync(resolve(blobs, name), { force: true }); bytes -= blobSizes.get(name) ?? 0;
220
+ allocated -= blobAllocation.get(name) ?? 0; blobSizes.delete(name); blobAllocation.delete(name);
221
+ }
222
+ }
223
+ }
224
+ const result = { removed, bytes, protected: protectedKeys.size, ...(options.cacheOverheadBytes === undefined ? {} : { cacheAllocatedBytes: allocated }) };
225
+ json(resolve(root, '.last-prune.json'), result); return result;
226
+ });
227
+ }
228
+
229
+ /** Rate-limited detached worker: generation latency never includes a cache scan. */
230
+ export function maybePruneGenerationCache(root: string): void {
231
+ const launch = locked(root, () => {
232
+ const stamp = resolve(root, '.prune-stamp');
233
+ if (existsSync(stamp) && Date.now() - statSync(stamp).mtimeMs < 600_000) return false;
234
+ writeFileSync(stamp, ''); return true;
235
+ });
236
+ if (!launch) return;
237
+ const entry = createRequire(resolve(import.meta.dirname, 'package.json')).resolve('@wildshard/sdk/projectGeneration');
238
+ const worker = spawn(process.execPath, [resolve(dirname(entry), 'generationCache.ts'), '--prune-generation-cache', root], { detached: true, stdio: 'ignore' });
239
+ worker.on('error', () => undefined); worker.unref();
240
+ }
241
+
242
+ if (process.argv[2] === '--prune-generation-cache') {
243
+ setPriority(19);
244
+ const root = process.argv[3];
245
+ if (root === undefined) throw new Error('Generation cache worker needs a root');
246
+ if (existsSync(root)) {
247
+ const base = resolve(root, '..'), blobs = resolve(base, 'blobs');
248
+ // Sample pool allocation before du: concurrent new blobs then reserve
249
+ // extra space conservatively. The potentially long walk takes no mutex.
250
+ let pooled = 0;
251
+ for (const name of existsSync(blobs) ? readdirSync(blobs) : []) if (hash.test(name)) pooled += lstatSync(resolve(blobs, name)).blocks * 512;
252
+ const usage = execFileSync('du', ['-sk', `${base}/`], { encoding: 'utf8', timeout: 30_000 });
253
+ const allocated = Number(usage.trim().split(/\s+/u)[0]) * 1024;
254
+ if (!Number.isSafeInteger(allocated) || allocated < 0) throw new Error('Invalid generation cache size census');
255
+ pruneGenerationCache(root, { cacheOverheadBytes: Math.max(0, allocated - pooled) });
256
+ }
257
+ }
@@ -0,0 +1,94 @@
1
+ import ts from '@typescript/typescript6';
2
+ import { hashImmutableBytes } from './immutable';
3
+
4
+ /** Bind each cached callback to its lexical source dependencies after bundling.
5
+ * The checker resolves bindings, so an unrelated imported constant/function is
6
+ * absent from the recipe. Captured declarations recursively include their own
7
+ * helpers, constants, default arguments and module initialization effects.
8
+ * Explicit byte inputs and the compiler/host are keyed by the cache itself. */
9
+ export function generationRecipes(code: string): string {
10
+ const file = ts.createSourceFile('generation.js', code, ts.ScriptTarget.Latest, true, ts.ScriptKind.JS);
11
+ const host: ts.CompilerHost = {
12
+ getSourceFile: name => name === file.fileName ? file : undefined,
13
+ getDefaultLibFileName: () => '', writeFile: () => undefined,
14
+ getCurrentDirectory: () => '', getDirectories: () => [],
15
+ fileExists: name => name === file.fileName,
16
+ readFile: name => name === file.fileName ? code : undefined,
17
+ getCanonicalFileName: name => name, useCaseSensitiveFileNames: () => true,
18
+ getNewLine: () => '\n',
19
+ };
20
+ const checker = ts.createProgram([file.fileName], { allowJs: true, noResolve: true, noLib: true }, host).getTypeChecker();
21
+ const effects = file.statements.filter(statement => ts.isExpressionStatement(statement)
22
+ || ts.isIfStatement(statement) || ts.isForStatement(statement) || ts.isForOfStatement(statement)
23
+ || ts.isWhileStatement(statement) || ts.isTryStatement(statement));
24
+ const edits: { at: number; value: string }[] = [];
25
+ const walk = (node: ts.Node): void => {
26
+ if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)
27
+ && node.expression.name.text === 'cached' && node.arguments.length === 2) {
28
+ const callback = node.arguments[1];
29
+ if (callback === undefined) throw new Error('Generation callback missing');
30
+ const seen = new Set<ts.Node>();
31
+ const sources = new Set<string>();
32
+ const collect = (dependency: ts.Node): void => {
33
+ if (seen.has(dependency)) return;
34
+ seen.add(dependency);
35
+ if (ts.isIdentifier(dependency)) {
36
+ const declarations = checker.getSymbolAtLocation(dependency)?.declarations ?? [];
37
+ for (const declaration of declarations) {
38
+ if (declaration.getSourceFile() !== file || seen.has(declaration)) continue;
39
+ // Parameters have no runtime value in source. Their defaults/types
40
+ // still enter the closure, as do local values computed from them.
41
+ sources.add(declaration.getText(file));
42
+ collect(declaration);
43
+ }
44
+ }
45
+ ts.forEachChild(dependency, collect);
46
+ };
47
+ sources.add(callback.getText(file));
48
+ collect(callback);
49
+ for (const effect of effects) { sources.add(effect.getText(file)); collect(effect); }
50
+ const receiver = node.expression.expression;
51
+ const context = ts.isIdentifier(receiver) ? checker.getSymbolAtLocation(receiver) : undefined;
52
+ // Initializers alone are insufficient: a captured local may be assigned
53
+ // later, or an object may be filled by a helper before cached() is called.
54
+ // Follow writes and calls using those bindings to a fixed point as well.
55
+ let previousSize = -1;
56
+ while (previousSize !== seen.size) {
57
+ previousSize = seen.size;
58
+ const refers = (target: ts.Node): boolean => {
59
+ if (ts.isIdentifier(target)) {
60
+ const symbol = checker.getSymbolAtLocation(target);
61
+ if (symbol !== context && symbol?.declarations?.some(declaration => seen.has(declaration))) return true;
62
+ }
63
+ return ts.forEachChild(target, child => refers(child) || undefined) === true;
64
+ };
65
+ const mutations = (target: ts.Node): void => {
66
+ let relevant = false;
67
+ if (ts.isBinaryExpression(target) && target.operatorToken.kind >= ts.SyntaxKind.FirstAssignment
68
+ && target.operatorToken.kind <= ts.SyntaxKind.LastAssignment) relevant = refers(target.left);
69
+ if (ts.isDeleteExpression(target)) relevant = refers(target.expression);
70
+ if (ts.isPostfixUnaryExpression(target)
71
+ || ts.isPrefixUnaryExpression(target) && (target.operator === ts.SyntaxKind.PlusPlusToken || target.operator === ts.SyntaxKind.MinusMinusToken)) relevant = refers(target.operand);
72
+ if (ts.isCallExpression(target) && !(ts.isPropertyAccessExpression(target.expression) && target.expression.name.text === 'cached')) relevant = refers(target);
73
+ if (relevant && !seen.has(target)) { sources.add(target.getText(file)); collect(target); }
74
+ ts.forEachChild(target, mutations);
75
+ };
76
+ mutations(file);
77
+ }
78
+ // A higher-order caller can pass a closure whose runtime captures are
79
+ // unavailable here. Keep the full program key in that case; guessing a
80
+ // function's identity from toString() would silently reuse stale bytes.
81
+ const dynamic = [...seen].some(dependency => ts.isParameter(dependency)
82
+ && !seen.has(dependency.parent)
83
+ && checker.getSymbolAtLocation(dependency.name) !== context);
84
+ if (dynamic) { ts.forEachChild(node, walk); return; }
85
+ const recipe = hashImmutableBytes(new TextEncoder().encode(JSON.stringify([...sources].sort())));
86
+ edits.push({ at: callback.end, value: `, ${JSON.stringify(recipe)}` });
87
+ }
88
+ ts.forEachChild(node, walk);
89
+ };
90
+ walk(file);
91
+ let output = code;
92
+ for (const edit of edits.sort((a, b) => b.at - a.at)) output = output.slice(0, edit.at) + edit.value + output.slice(edit.at);
93
+ return output;
94
+ }