@arcforge/platform 2.0.166

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 (207) hide show
  1. package/README.md +31 -0
  2. package/package.json +69 -0
  3. package/src/bin/supervisor.ts +102 -0
  4. package/src/bin/test-api.ts +30 -0
  5. package/src/bin/test-preload.ts +308 -0
  6. package/src/bin/update-helper.ts +32 -0
  7. package/src/build/bench/CLAUDE.md +106 -0
  8. package/src/build/bench/SPEC.md +209 -0
  9. package/src/build/bench/agents.ts +105 -0
  10. package/src/build/bench/axes.ts +84 -0
  11. package/src/build/bench/bench.ts +96 -0
  12. package/src/build/bench/discover.ts +147 -0
  13. package/src/build/bench/index.ts +7 -0
  14. package/src/build/bench/log.ts +47 -0
  15. package/src/build/bench/matrix.ts +23 -0
  16. package/src/build/bench/preload.ts +440 -0
  17. package/src/build/bench/prepare.ts +61 -0
  18. package/src/build/bench/projection.ts +112 -0
  19. package/src/build/bench/resolve.ts +54 -0
  20. package/src/build/bench/runner.ts +309 -0
  21. package/src/build/bench/schema/extract.ts +148 -0
  22. package/src/build/bench/schema/index.ts +2 -0
  23. package/src/build/bench/schema/schema.ts +95 -0
  24. package/src/build/bench/schema/worker.ts +30 -0
  25. package/src/build/bench/typegen.ts +119 -0
  26. package/src/build/bench/workspace/files.ts +139 -0
  27. package/src/build/bench/workspace/handle.ts +133 -0
  28. package/src/build/bench/workspace/index.ts +11 -0
  29. package/src/build/bench/workspace/workspace.ts +14 -0
  30. package/src/build/blueprint/blueprint.ts +398 -0
  31. package/src/build/blueprint/cognet/abi.ts +207 -0
  32. package/src/build/blueprint/cognet/bundle-worker.ts +93 -0
  33. package/src/build/blueprint/cognet/bundle.ts +664 -0
  34. package/src/build/blueprint/cognet/cognet.ts +249 -0
  35. package/src/build/blueprint/cognet/index.ts +10 -0
  36. package/src/build/blueprint/cognet/manifest.ts +38 -0
  37. package/src/build/blueprint/cognet/resolve.ts +113 -0
  38. package/src/build/blueprint/collisions.ts +51 -0
  39. package/src/build/blueprint/index.ts +29 -0
  40. package/src/build/blueprint/modules/entries.ts +117 -0
  41. package/src/build/blueprint/modules/index.ts +300 -0
  42. package/src/build/blueprint/modules/meta.ts +174 -0
  43. package/src/build/blueprint/scan/boot.ts +34 -0
  44. package/src/build/blueprint/scan/cognetImports.ts +56 -0
  45. package/src/build/blueprint/scan/components.ts +45 -0
  46. package/src/build/blueprint/scan/config.ts +234 -0
  47. package/src/build/blueprint/scan/configImports.ts +232 -0
  48. package/src/build/blueprint/scan/declare-worker.ts +61 -0
  49. package/src/build/blueprint/scan/declare.ts +393 -0
  50. package/src/build/blueprint/scan/h3-globals.ts +137 -0
  51. package/src/build/blueprint/scan/knowledge.ts +101 -0
  52. package/src/build/blueprint/scan/middleware.ts +110 -0
  53. package/src/build/blueprint/scan/moduleImports.ts +79 -0
  54. package/src/build/blueprint/scan/plugins.ts +93 -0
  55. package/src/build/blueprint/scan/promptPackages.ts +45 -0
  56. package/src/build/blueprint/scan/prompts.ts +164 -0
  57. package/src/build/blueprint/scan/published.ts +131 -0
  58. package/src/build/blueprint/scan/resolve.ts +398 -0
  59. package/src/build/blueprint/scan/routes.ts +109 -0
  60. package/src/build/blueprint/scan/scripts.ts +119 -0
  61. package/src/build/blueprint/scan/tool-bundle-worker.ts +69 -0
  62. package/src/build/blueprint/scan/tools.ts +610 -0
  63. package/src/build/blueprint/types.ts +28 -0
  64. package/src/build/extensions/config.ts +261 -0
  65. package/src/build/extensions/edit.ts +684 -0
  66. package/src/build/extensions/extensions.ts +731 -0
  67. package/src/build/extensions/index.ts +10 -0
  68. package/src/build/extensions/load.ts +350 -0
  69. package/src/build/extensions/registrations.ts +189 -0
  70. package/src/build/extensions/store.ts +200 -0
  71. package/src/build/frame/frame.ts +145 -0
  72. package/src/build/frame/index.ts +5 -0
  73. package/src/build/frame/migrate.ts +246 -0
  74. package/src/build/project/bundle/agent.ts +382 -0
  75. package/src/build/project/bundle/artifacts.ts +88 -0
  76. package/src/build/project/bundle/assets.ts +385 -0
  77. package/src/build/project/bundle/bundle.ts +160 -0
  78. package/src/build/project/bundle/imports.ts +102 -0
  79. package/src/build/project/bundle/index.ts +16 -0
  80. package/src/build/project/bundle/module.ts +130 -0
  81. package/src/build/project/bundle/source.ts +136 -0
  82. package/src/build/project/bundle/stage.ts +97 -0
  83. package/src/build/project/bundle/types.ts +111 -0
  84. package/src/build/project/cognet.ts +156 -0
  85. package/src/build/project/create/agent.ts +52 -0
  86. package/src/build/project/create/bench.ts +81 -0
  87. package/src/build/project/create/cognet.ts +102 -0
  88. package/src/build/project/create/extension.ts +63 -0
  89. package/src/build/project/create/module.ts +43 -0
  90. package/src/build/project/create/profile.ts +102 -0
  91. package/src/build/project/create/prompt.ts +68 -0
  92. package/src/build/project/create/templates.ts +88 -0
  93. package/src/build/project/deploy.ts +96 -0
  94. package/src/build/project/index.ts +40 -0
  95. package/src/build/project/installer.ts +616 -0
  96. package/src/build/project/kinds.ts +374 -0
  97. package/src/build/project/links.ts +33 -0
  98. package/src/build/project/manifest/bunfig.ts +139 -0
  99. package/src/build/project/manifest/config.ts +246 -0
  100. package/src/build/project/manifest/env.ts +184 -0
  101. package/src/build/project/manifest/index.ts +9 -0
  102. package/src/build/project/manifest/manifest.ts +49 -0
  103. package/src/build/project/manifest/model.ts +124 -0
  104. package/src/build/project/manifest/package.ts +386 -0
  105. package/src/build/project/manifest/text.ts +19 -0
  106. package/src/build/project/models/fetch.ts +123 -0
  107. package/src/build/project/models/index.ts +8 -0
  108. package/src/build/project/models/models.ts +111 -0
  109. package/src/build/project/models/specifier.ts +106 -0
  110. package/src/build/project/models/store.ts +202 -0
  111. package/src/build/project/modules/hash.ts +31 -0
  112. package/src/build/project/modules/index.ts +5 -0
  113. package/src/build/project/modules/lock.ts +78 -0
  114. package/src/build/project/modules/modules.ts +155 -0
  115. package/src/build/project/prepare.ts +709 -0
  116. package/src/build/project/project.ts +253 -0
  117. package/src/build/project/projects.ts +164 -0
  118. package/src/build/project/propagation.ts +120 -0
  119. package/src/build/project/publish/verify.ts +312 -0
  120. package/src/build/project/publish.ts +155 -0
  121. package/src/build/project/reconcile.ts +93 -0
  122. package/src/build/project/specifier.ts +42 -0
  123. package/src/build/project/tree.ts +615 -0
  124. package/src/build/project/treecache.ts +356 -0
  125. package/src/build/project/typegen/axon-dts.ts +362 -0
  126. package/src/build/project/typegen/cognet-dts.ts +91 -0
  127. package/src/build/project/typegen/components.ts +45 -0
  128. package/src/build/project/typegen/env.ts +59 -0
  129. package/src/build/project/typegen/generators.ts +108 -0
  130. package/src/build/project/typegen/hooks.ts +71 -0
  131. package/src/build/project/typegen/index.ts +137 -0
  132. package/src/build/project/typegen/prompt-dts.ts +40 -0
  133. package/src/build/project/typegen/prompts.ts +36 -0
  134. package/src/build/project/typegen/registry-dts.ts +109 -0
  135. package/src/build/project/typegen/scripts.ts +37 -0
  136. package/src/build/project/typegen/tools.ts +31 -0
  137. package/src/build/project/typegen/tsconfig.ts +243 -0
  138. package/src/build/project/typegen/tui-dts.ts +120 -0
  139. package/src/build/project/typegen/write.ts +40 -0
  140. package/src/build/project/verify.ts +268 -0
  141. package/src/build/project/watcher.ts +266 -0
  142. package/src/build/runtime/agent.ts +550 -0
  143. package/src/build/runtime/escalations.ts +159 -0
  144. package/src/build/runtime/index.ts +15 -0
  145. package/src/build/runtime/instances.ts +604 -0
  146. package/src/build/runtime/profile.ts +91 -0
  147. package/src/build/runtime/progress.ts +143 -0
  148. package/src/build/runtime/requests.ts +167 -0
  149. package/src/build/runtime/resolve.ts +159 -0
  150. package/src/build/runtime/runtime.ts +233 -0
  151. package/src/build/runtime/sessions/index.ts +5 -0
  152. package/src/build/runtime/sessions/record.ts +145 -0
  153. package/src/build/runtime/sessions/sessions.ts +240 -0
  154. package/src/build/runtime/zeno.ts +120 -0
  155. package/src/index.ts +11 -0
  156. package/src/link/agent-main.ts +395 -0
  157. package/src/link/index.ts +70 -0
  158. package/src/link/services.ts +120 -0
  159. package/src/platform.ts +293 -0
  160. package/src/procs/index.ts +15 -0
  161. package/src/procs/tree.ts +177 -0
  162. package/src/services/cloud.ts +419 -0
  163. package/src/services/control/client.ts +126 -0
  164. package/src/services/control/dispatch.ts +156 -0
  165. package/src/services/control/index.ts +17 -0
  166. package/src/services/control/protocol.ts +179 -0
  167. package/src/services/control/server.ts +241 -0
  168. package/src/services/deployments.ts +81 -0
  169. package/src/services/files.ts +329 -0
  170. package/src/services/index.ts +5 -0
  171. package/src/services/mic/capture.ts +248 -0
  172. package/src/services/mic/config.ts +109 -0
  173. package/src/services/mic/fft.ts +93 -0
  174. package/src/services/mic/index.ts +139 -0
  175. package/src/services/mic/visualizer.ts +46 -0
  176. package/src/services/ollama/catalog.ts +122 -0
  177. package/src/services/ollama/http.ts +124 -0
  178. package/src/services/ollama/index.ts +13 -0
  179. package/src/services/ollama/models.ts +153 -0
  180. package/src/services/ollama/ollama.ts +89 -0
  181. package/src/services/ollama/registry.ts +112 -0
  182. package/src/services/ollama/types.ts +72 -0
  183. package/src/services/prompts.ts +76 -0
  184. package/src/services/registry.ts +220 -0
  185. package/src/services/resources/hardware.ts +125 -0
  186. package/src/services/resources/index.ts +6 -0
  187. package/src/services/resources/reservations.ts +162 -0
  188. package/src/services/resources/resources.ts +156 -0
  189. package/src/services/running/index.ts +1 -0
  190. package/src/services/running/running.ts +200 -0
  191. package/src/services/store/disk.ts +97 -0
  192. package/src/services/store/index.ts +15 -0
  193. package/src/services/store/store.ts +729 -0
  194. package/src/services/store/types.ts +303 -0
  195. package/src/services/test/child.ts +150 -0
  196. package/src/services/test/events.ts +102 -0
  197. package/src/services/test/files.ts +26 -0
  198. package/src/services/test/frames.ts +39 -0
  199. package/src/services/test/index.ts +7 -0
  200. package/src/services/test/runner.ts +122 -0
  201. package/src/services/test/types.ts +26 -0
  202. package/src/services/update/contract.ts +77 -0
  203. package/src/services/update/index.ts +12 -0
  204. package/src/services/update/installer.ts +139 -0
  205. package/src/services/update/updates.ts +137 -0
  206. package/src/utils/fs.ts +148 -0
  207. package/src/utils/tsast.ts +102 -0
@@ -0,0 +1,709 @@
1
+ import type { FrameworkSource } from "./manifest/package"
2
+ import { join } from "node:path"
3
+ import { err } from "@arcforge/err"
4
+ import type { ProviderEntry } from "@arcforge/types"
5
+ import { resolveDefaultBaseUrl } from "@arcforge/cloud"
6
+ import { KERNEL_ABI_VERSION } from "@arcforge/types"
7
+ import { Blueprint, Config, cognetAbi, cognetName, cognetSourceOf, readCognetModels, flatten, DEFAULT_COGNET, type CognetSource, type ScanWarning } from "../blueprint"
8
+ import { reconcile } from "./reconcile"
9
+ import { describeFaults } from "./verify"
10
+ import { Models } from "./models"
11
+
12
+ import type { InstallerT, InstallResult } from "./installer"
13
+ import type { ManifestT } from "./manifest"
14
+ import type { TreeT } from "./tree"
15
+ import type { LinkResult, SourceModulesT } from "./modules"
16
+ import type { TypegenResult, TypegenT } from "./typegen"
17
+ import { fsx } from "../../utils/fs"
18
+ import { migrateFrame } from "../frame"
19
+ import { KINDS, type ProjectKind } from "./kinds"
20
+
21
+ export type PrepareResult = {
22
+ modules: InstallResult[]
23
+ sourceModules: LinkResult[]
24
+ typegen: TypegenResult
25
+ warnings: ScanWarning[]
26
+ }
27
+
28
+ type PrepareOpts = {
29
+ root: string
30
+ kind: ProjectKind
31
+ installer: InstallerT
32
+ manifest: ManifestT
33
+ modules: SourceModulesT
34
+ tree: TreeT
35
+ typegen: TypegenT
36
+ /** CLI version — the framework deps prepare declares/repairs are pinned to it. */
37
+ frameworkVersion: string
38
+ /** Where framework deps resolve from — "workspace" links this repo's tree (tests). */
39
+ frameworkSource?: FrameworkSource
40
+ /** Repo root, required when frameworkSource is "workspace". */
41
+ repoRoot?: string
42
+ /**
43
+ * Kind-specific work that runs after the shared frame is written. Benches
44
+ * use it to generate declarations from their own config; nothing else has
45
+ * needed it yet.
46
+ */
47
+ extend?: () => Promise<void>
48
+ /**
49
+ * Where this prepare reports its phases.
50
+ *
51
+ * A plain callback rather than a session handle: prepare is the stage
52
+ * that RUNS before a runtime exists, so it must not know what a session
53
+ * is. The caller that has one (Agent(), via BuildRecorder) supplies a
54
+ * sink that writes there; a caller that does not — `axon prepare` on
55
+ * its own — passes nothing and the spans cost nothing.
56
+ */
57
+ report?: BuildReporter
58
+ /**
59
+ * The active profile's declared inference sources.
60
+ *
61
+ * Read at load and carried onto the blueprint, never baked into the
62
+ * project: a blueprint travels (it is what `axon deploy` ships) and a
63
+ * deployed agent has no profile at all, so a user's local Ollama daemon
64
+ * must not become an artifact's dependency.
65
+ */
66
+ profileProviders?: () => Promise<readonly ProviderEntry[] | undefined>
67
+ }
68
+
69
+ /**
70
+ * Runs one build span, or just the work when nobody is listening.
71
+ *
72
+ * Mirrors @arcforge/session's `span()` deliberately rather than importing
73
+ * it: this package must not depend on the session package to be
74
+ * instrumented, and the contract here is two lines. The `finally`-shaped
75
+ * guarantee is the point — a span opened is always closed, with the error
76
+ * attached, because a flame graph with an unclosed bracket shows a phantom
77
+ * bar running to the end of the log.
78
+ */
79
+ async function phase<T>(
80
+ report: BuildReporter | undefined,
81
+ name: "build:framework" | "build:modules" | "build:cognet" | "build:tree" | "build:typegen",
82
+ start: Record<string, unknown>,
83
+ run: () => Promise<T>,
84
+ complete?: (value: T) => Record<string, unknown>,
85
+ ): Promise<T> {
86
+ if (!report) return run()
87
+
88
+ const began = Date.now()
89
+ report(`${name}:start`, start)
90
+ try {
91
+ const value = await run()
92
+ report(`${name}:complete`, { ...start, ...(complete ? complete(value) : {}), durationMs: Date.now() - began })
93
+ return value
94
+ } catch (cause) {
95
+ report(`${name}:failed`, { ...start, error: cause, durationMs: Date.now() - began })
96
+ throw cause
97
+ }
98
+ }
99
+
100
+ /**
101
+ * Where a build phase reports itself. See PrepareOpts.report.
102
+ *
103
+ * `unknown` payloads rather than the typed BuildEventMap: that map lives in
104
+ * @arcforge/types alongside the session, and prepare stays free of both.
105
+ * The caller supplying the sink is the one that knows the event shapes.
106
+ */
107
+ export type BuildReporter = (type: string, data: unknown) => void
108
+
109
+ /**
110
+ * Prepare — the sequence that makes a project bootable. One sentence:
111
+ * install what's declared, compile the brain, then generate types from
112
+ * what's there.
113
+ *
114
+ * Agents: read declared modules (Config throws on a broken config — no
115
+ * agent), install registry specifiers, load the blueprint AFTER install so
116
+ * fresh modules are scanned, typegen from its surfaces.
117
+ *
118
+ * Modules: the static typegen frame only.
119
+ *
120
+ * Per-module install failures and scan warnings are returned, not thrown —
121
+ * the caller decides severity.
122
+ */
123
+ export function Prepare(opts: PrepareOpts) {
124
+ const { root, kind, installer, manifest, modules, tree, typegen, frameworkVersion, frameworkSource, repoRoot, extend } = opts
125
+
126
+ const blueprint = Blueprint({ root: root })
127
+ // Named `weights` locally: `modules` is already the source-module
128
+ // manager here, and two different things called models/modules in one
129
+ // function is exactly the kind of near-collision that reads fine and
130
+ // debugs badly.
131
+ const weights = Models()
132
+
133
+ /**
134
+ * True when everything the installed cognet needs to compile is
135
+ * materialized in a node_modules tree the agent can see.
136
+ *
137
+ * The cognet is compiled by bundling its import graph out of the AGENT's
138
+ * tree, so what it imports must be present THERE — not merely declared by
139
+ * it. A cognet that gained a requirement between versions is the case this
140
+ * catches: the agent's own manifest is unchanged, so nothing else would
141
+ * trigger an install, and the failure would otherwise surface as an
142
+ * unresolvable import inside the bundler.
143
+ *
144
+ * PEER dependencies are checked alongside regular ones, and are the reason
145
+ * this still has a job. `@arcforge/cognet` is a peer of every cognet — the
146
+ * host provides exactly one copy, which is what stops Bun from nesting a
147
+ * second runtime — and Bun does not install a peer it cannot already
148
+ * satisfy. So a peer is precisely the kind of requirement that can be
149
+ * declared and absent, which is the condition the bundler cannot recover
150
+ * from.
151
+ *
152
+ * Absent cognet, unreadable manifest, or nothing declared → true (nothing
153
+ * to install); the resolve step that follows reports a missing cognet
154
+ * properly.
155
+ */
156
+ async function cognetDependenciesPresent(source: CognetSource): Promise<boolean> {
157
+ let sourceDir: string
158
+ try {
159
+ sourceDir = blueprint.cognet.sourceDir(source)
160
+ } catch {
161
+ return true // not installed yet — the install above is what fixes that
162
+ }
163
+
164
+ const cognetManifest = await fsx.readJson<{
165
+ dependencies?: Record<string, string>
166
+ peerDependencies?: Record<string, string>
167
+ }>(join(sourceDir, "package.json"))
168
+
169
+ return tree.allResolve([
170
+ ...Object.keys(cognetManifest?.dependencies ?? {}),
171
+ ...Object.keys(cognetManifest?.peerDependencies ?? {}),
172
+ ])
173
+ }
174
+
175
+ /**
176
+ * The cognet's own non-framework dependencies, at the ranges IT declares.
177
+ *
178
+ * These become the agent's, because the compiled bundle runs from the
179
+ * agent and imports them by bare specifier. `@arcforge/*` is excluded:
180
+ * the host must be the one copy the agent already has, and a second
181
+ * nested runtime would give the brain a different ambient scope than the
182
+ * kernel bound.
183
+ *
184
+ * Ranges are copied rather than re-pinned, so the cognet author's own
185
+ * constraint is what governs — the agent is carrying a dependency on
186
+ * behalf of a brain it did not write.
187
+ */
188
+ async function cognetDependencyRanges(source: CognetSource): Promise<Record<string, string>> {
189
+ let sourceDir: string
190
+ try {
191
+ sourceDir = blueprint.cognet.sourceDir(source)
192
+ } catch {
193
+ return {} // not installed yet; the install below is what fixes that
194
+ }
195
+
196
+ const pkg = await fsx.readJson<{ dependencies?: Record<string, string> }>(
197
+ join(sourceDir, "package.json"),
198
+ )
199
+
200
+ return Object.fromEntries(
201
+ Object.entries(pkg?.dependencies ?? {}).filter(([name]) => !name.startsWith("@arcforge/")),
202
+ )
203
+ }
204
+
205
+ /**
206
+ * Installed packages that are cognets but are NOT the one now selected.
207
+ *
208
+ * A cognet is the only dependency an agent acquires without declaring it
209
+ * in `modules: [...]`, so nothing else would ever clean one up — switching
210
+ * `cognet:` used to leave the previous brain in package.json forever.
211
+ *
212
+ * Identified by PROOF, not by name: a package is a cognet when the thing
213
+ * installed at that name carries a cognet.config.ts. Guessing from a
214
+ * scope or a naming convention would eventually delete a user's own
215
+ * dependency, which is far worse than leaving a stale one behind.
216
+ */
217
+ async function cognetDependencies(
218
+ declared: Record<string, string>,
219
+ selected: string | null,
220
+ ): Promise<Set<string>> {
221
+ const found = new Set<string>()
222
+ for (const name of Object.keys(declared)) {
223
+ if (name === selected) continue
224
+ const dir = tree.locate(name)
225
+ if (dir && fsx.exists(join(dir, "cognet.config.ts"))) found.add(name)
226
+ }
227
+ return found
228
+ }
229
+
230
+ /**
231
+ * @param options.frozen Assert that the manifest and the installed tree
232
+ * already agree, instead of making them agree. Throws on any drift and
233
+ * never writes.
234
+ *
235
+ * The reproducible counterpart to prepare's normal reconciling behaviour,
236
+ * for CI and deploy — where "the build quietly upgraded something" is a
237
+ * worse outcome than "the build failed and told you what moved".
238
+ */
239
+ return async function prepare(options: { frozen?: boolean; report?: BuildReporter } = {}): Promise<PrepareResult> {
240
+ // Per call, not per construction: the project is opened long before
241
+ // anything knows where its build should report. Agent() supplies a
242
+ // session-backed sink at boot; `axon prepare` on its own supplies
243
+ // nothing and every span below is a no-op.
244
+ const report = options.report ?? opts.report
245
+
246
+ /**
247
+ * A just-published version has not reached this npm edge yet.
248
+ *
249
+ * Reported as a build event rather than swallowed: the wait is real
250
+ * seconds, and a caller watching a step list needs to see WHY it is
251
+ * still going. Without it a legitimate backoff reads as a hang against
252
+ * a registry doing exactly what it should.
253
+ */
254
+ const notePropagation = (delayMs: number, attempt: number): void => {
255
+ report?.("build:warning", {
256
+ domain: "install",
257
+ error: `a just-published version has not reached this npm edge yet — retrying in ${delayMs / 1_000}s (attempt ${attempt})`,
258
+ })
259
+ }
260
+
261
+ // Convert a pre-grouping frame before anything reads or writes one.
262
+ //
263
+ // FIRST, ahead of even the prompt early-return below, because every
264
+ // kind has a frame and every kind's is affected. It discards the
265
+ // regenerable files (types, caches, build output) that the rest of
266
+ // this function is about to rewrite anyway, and physically moves the
267
+ // runtime output that nothing can rebuild. Idempotent — on an
268
+ // already-current project it stats a few paths and returns.
269
+ const migration = await migrateFrame(root, kind)
270
+ if (migration.migrated) {
271
+ report?.("build:frame:migrated", {
272
+ root: root,
273
+ kind: kind,
274
+ discarded: migration.discarded,
275
+ dataMoved: migration.dataMoved,
276
+ })
277
+ }
278
+
279
+ // A prompt package is text: it declares no dependencies, so there is
280
+ // nothing to install and its frame is self-contained. It still gets
281
+ // one — definePrompt() is a global, and prompt.config.ts calls it.
282
+ //
283
+ // This returns BEFORE framework.ensure(): declaring @arcforge/types in
284
+ // a package that never installs would put a dependency in package.json
285
+ // that is guaranteed absent from disk, and package.json is published
286
+ // verbatim, so every consumer would inherit the phantom.
287
+ if (!KINDS[kind].installs) {
288
+ return { modules: [], sourceModules: [], typegen: await typegen.write(), warnings: [] }
289
+ }
290
+
291
+ // Ensure @arcforge/types + @arcforge/engines + h3 are declared and on
292
+ // disk before typegen runs — its generated tsconfig `extends`
293
+ // @arcforge/types/tsconfig.base.json and the .d.ts references those
294
+ // packages. This also self-heals older agents that declared none of
295
+ // them (their types used to come from machine-local tsconfig paths).
296
+ const frameworkChanged = await phase(
297
+ report,
298
+ "build:framework",
299
+ { version: frameworkVersion },
300
+ () => manifest.package.framework.ensure(frameworkVersion, frameworkSource, repoRoot, KINDS[kind].framework),
301
+ changed => ({ version: frameworkVersion, changed }),
302
+ )
303
+
304
+ // "Declared" is not "installed": a fresh scaffold writes the deps into
305
+ // package.json but has no node_modules, so frameworkChanged is false
306
+ // (nothing to add) yet an install is still required. Key off actual
307
+ // resolvability, not just a manifest edit.
308
+ // ── The pre-install gate ──────────────────────────────────────────
309
+ //
310
+ // Verification runs BEFORE the installs, and that ordering is the
311
+ // whole point of this block. It used to run last (see `reconcile`
312
+ // below), which meant every install that could fail ran first — so
313
+ // each new breakage got its own repair bolted to the front of this
314
+ // function, one incident at a time.
315
+ //
316
+ // Only manifest-level faults can be judged this early: `managed` is
317
+ // not known until the installers have declared their ranges. That is
318
+ // exactly enough, because these are the faults that kill `bun install`
319
+ // itself. Bun resolves the WHOLE manifest at once, so one unresolvable
320
+ // range fails every other package with it — a poisoned cognet range
321
+ // killed the modules install long before the cognet step that would
322
+ // have re-resolved it.
323
+ const repairedRanges = await installer.repairForeignRanges()
324
+
325
+ // The registry bunfig.toml FETCHES from, corrected here for the same
326
+ // reason ranges are: bun reads this file, not our env, so a stale
327
+ // mapping fails the install before anything downstream can repair it.
328
+ //
329
+ // This ran only AFTER the installs at first, which made it useless in
330
+ // exactly the case it exists for — an agent whose ranges came from
331
+ // production while bunfig pointed at local staging failed on every
332
+ // package at once, and the repair sat two hundred lines past the
333
+ // throw. A repair that runs after the thing it repairs is not a repair.
334
+ //
335
+ // The lockfile goes with it: bun.lock pins fully-qualified tarball
336
+ // URLs, so replaying one written against the other registry re-fetches
337
+ // everything from there regardless of what bunfig now says.
338
+ const registryOrigin = resolveDefaultBaseUrl()
339
+ const staleScopes = Object.entries(await manifest.bunfig.scopes())
340
+ .filter(([, mapped]) => !mapped.startsWith(registryOrigin))
341
+ if (staleScopes.length > 0) {
342
+ for (const [scope] of staleScopes) {
343
+ await manifest.bunfig.ensure(scope, `${registryOrigin}/api/registry/npm/-`)
344
+ }
345
+ await tree.clearLock()
346
+ await tree.clearModules()
347
+ }
348
+
349
+ // A node_modules of dangling symlinks is a real, recoverable state:
350
+ // the project was grafted onto a shared cache tree that has since been
351
+ // evicted. The stale directory must be REMOVED rather than installed
352
+ // over — bun writes what it resolves and does not audit what it did
353
+ // not touch, so the dangling links would survive the reinstall.
354
+ if (tree.graftBroken()) await tree.clearModules()
355
+
356
+ const needsFrameworkInstall = frameworkChanged || !tree.frameworkInstalled()
357
+
358
+ // Every installing kind installs its dependencies and writes its
359
+ // frame. Only an agent goes further: it resolves modules, compiles a
360
+ // cognet, and loads a blueprint, because only an agent has those.
361
+ if (kind !== "agent") {
362
+ if (needsFrameworkInstall) await tree.install({ onPropagationRetry: notePropagation })
363
+ const written = await typegen.write()
364
+ // Kinds whose declarations come from their own config generate
365
+ // them here, on top of the shared frame — a bench's axes and
366
+ // measurement schema are the only case today.
367
+ await extend?.()
368
+ return { modules: [], sourceModules: [], typegen: written, warnings: [] }
369
+ }
370
+
371
+ const config = await Config(root)
372
+ const entries = await flatten(config.modules, config.modulePaths)
373
+
374
+ // Hard-imported (source) modules become `file:` dependencies, so Bun
375
+ // links them and resolves their deps exactly as it does a registry
376
+ // package — origin must never change how a module's deps resolve.
377
+ // Their content hash stands in for a semver they don't have.
378
+ const declaredSources = []
379
+ for (const entry of entries) {
380
+ if (entry.kind !== "source") continue
381
+ declaredSources.push(await modules.resolve(entry.configPath))
382
+ }
383
+
384
+ // Prune BEFORE installing: a module that moved from a source import
385
+ // to a registry install still holds its `file:` dependency, and Bun
386
+ // would keep linking the local copy over whatever the registry
387
+ // serves. Removing it first frees the name.
388
+ const pruned = await modules.prune(declaredSources)
389
+
390
+ const specifiers = entries.filter(e => e.kind === "registry").map(e => e.name)
391
+ const installed = await phase(
392
+ report,
393
+ "build:modules",
394
+ { specifiers },
395
+ () => installer.install(specifiers),
396
+ results => ({
397
+ specifiers,
398
+ installed: results.filter(r => r.status === "installed").map(r => r.name),
399
+ alreadyPresent: results.filter(r => r.status !== "installed").map(r => r.name),
400
+ }),
401
+ )
402
+
403
+ // The cognet is a registry artifact installed like any other package,
404
+ // but it is NOT a module: it is selected by `cognet:`, so it must not
405
+ // be written into the config's modules array.
406
+ // Choosing nothing is not the same as choosing the default. An agent
407
+ // that never named a cognet tracks the registry's latest zero, so the
408
+ // brain nobody selected keeps up to date on its own; an agent that
409
+ // named one — with or without a version — keeps what it asked for.
410
+ //
411
+ // This also makes an unresolvable range unable to survive: dave's
412
+ // package.json acquired "@axon/zero": "^2.0.100" from a workspace
413
+ // sibling whose version is a framework version, and because the
414
+ // installer honoured a declared range as a deliberate pin, every
415
+ // prepare re-asserted a version that exists nowhere but this machine.
416
+ // `abi` is what makes "latest" safe to track. A cognet bundle is fused
417
+ // to one kernel contract, so the newest published version is not
418
+ // automatically one this runtime can load — asking the registry for the
419
+ // newest version targeting THIS kernel means an incompatible bundle is
420
+ // never installed, instead of being installed and then rejected by
421
+ // cognetAbi() after the fact.
422
+ //
423
+ // A SOURCE cognet skips all of this. It is a directory on disk — one
424
+ // the author pointed at with an import, or wrote inline at `cognet/` —
425
+ // not a package to fetch, so there is no registry lookup, no version to
426
+ // resolve, and no ABI negotiation: the source is whatever they have
427
+ // checked out. The ABI is still verified below, from the same
428
+ // cognet.config.ts every origin ends at.
429
+ const cognetSource = cognetSourceOf(config) ?? { kind: "registry" as const, specifier: DEFAULT_COGNET }
430
+
431
+ // Whether the agent CHOSE its brain, which an inline cognet/ does just
432
+ // as much as a `cognet:` line — the folder is the declaration. Only an
433
+ // agent that chose nothing tracks the registry's latest, and this flag
434
+ // is read solely on the registry path, where an inline cognet never
435
+ // arrives.
436
+ const declaredCognet = config.value.cognet !== undefined || cognetSource.kind === "source"
437
+
438
+ const cognetInstall = cognetSource.kind === "source"
439
+ ? []
440
+ : await installer.install([cognetSource.specifier], {
441
+ declare: false,
442
+ abi: KERNEL_ABI_VERSION,
443
+ ...(declaredCognet ? {} : { track: "latest" as const }),
444
+ })
445
+
446
+ const cognetSpecifier = cognetSource.kind === "source" ? cognetSource.dir : cognetSource.specifier
447
+ const cognetFailure = cognetInstall.find(result => result.status === "not-found" || result.status === "error")
448
+ if (cognetFailure) {
449
+ // "Published, but nothing built for this kernel" is a DIFFERENT
450
+ // failure from "no such cognet", and the registry answers 409 to
451
+ // say so — with the ABIs it does have. Reporting it as
452
+ // COGNET_NOT_FOUND would tell the user to check their spelling
453
+ // when the real answer is to update Axon or pin an older version.
454
+ // Matched on the registry's own phrasing for the ABI case, and
455
+ // ONLY that phrasing. A 404 for a range that matched nothing also
456
+ // mentions the ABI ("...satisfies ^0.1.0 for kernel ABI 9"), and
457
+ // reading that as an ABI mismatch told the user to update Axon
458
+ // when the real answer was that no version satisfied their range.
459
+ const abiRejected = cognetFailure.status === "error"
460
+ && cognetFailure.error?.includes(`targets kernel ABI ${KERNEL_ABI_VERSION}`)
461
+ if (abiRejected) {
462
+ throw err("COGNET_ABI_MISMATCH", {
463
+ detail: `${cognetFailure.error}`,
464
+ context: { specifier: cognetSpecifier, kernelAbi: KERNEL_ABI_VERSION },
465
+ })
466
+ }
467
+ // Name the registry that answered. "not published in the
468
+ // registry" is a claim about the world made from one endpoint's
469
+ // 404 — and when that endpoint is local staging while the cognet
470
+ // lives in production, the message sends the reader looking for a
471
+ // publishing bug that does not exist.
472
+ const registry = resolveDefaultBaseUrl()
473
+ throw err("COGNET_NOT_FOUND", {
474
+ detail: cognetFailure.status === "not-found"
475
+ ? `cognet "${cognetSpecifier}" was not found in the registry at ${registry}`
476
+ : `cognet "${cognetSpecifier}" failed to install from ${registry}: ${cognetFailure.error}`,
477
+ context: { specifier: cognetSpecifier, registry },
478
+ })
479
+ }
480
+
481
+ const sourceModules: LinkResult[] = []
482
+ for (const module of declaredSources) {
483
+ sourceModules.push(await modules.link(module))
484
+ }
485
+
486
+ // A cognet brings its OWN dependencies (zero depends on @arcforge/cognet),
487
+ // and unlike a module those are not resolvable until node_modules is
488
+ // materialized — the bundler resolves the cognet's import graph from
489
+ // the agent's tree. `already-installed` is not sufficient evidence
490
+ // they are present: a cognet version that GAINED a dependency leaves
491
+ // the agent's manifest unchanged while its own deps are missing, which
492
+ // fails at bundle time with an unresolvable import rather than here.
493
+ const cognetNeedsInstall = !(await cognetDependenciesPresent(cognetSource))
494
+
495
+ // Reconcile: compare what is DECLARED against what is INSTALLED, and
496
+ // repair the manifest where the two disagree. This is the step whose
497
+ // absence produced every dependency failure worth fixing — a present-
498
+ // but-wrong package reading as installed, a published fix unable to
499
+ // reach an agent holding the broken version, and a replaced cognet
500
+ // lingering in package.json forever.
501
+ //
502
+ // Runs AFTER the installers have declared their ranges (so `managed`
503
+ // reflects this run's intent) and BEFORE the install decision below,
504
+ // which is the thing it informs.
505
+ // A cognet's own runtime dependencies must be declared by the AGENT.
506
+ // The compiled brain leaves them external (a 259MB native ONNX
507
+ // runtime cannot be inlined, and should not be even if it could), so
508
+ // the bare import in the bundle resolves from the agent's tree — the
509
+ // bundle lives in the agent's .agent/cognet/, not the cognet's.
510
+ //
511
+ // Without this the compile succeeds and the agent fails at boot with
512
+ // "Cannot find package", naming a dependency the agent never declared
513
+ // and the author only wrote in the cognet.
514
+ const cognetRuntimeDeps = await cognetDependencyRanges(cognetSource)
515
+ if (Object.keys(cognetRuntimeDeps).length > 0) {
516
+ await manifest.package.dependencies.set(cognetRuntimeDeps)
517
+ }
518
+
519
+ const declaredNow = await manifest.package.dependencies.all()
520
+ const managed: Record<string, string> = {}
521
+
522
+ // The FRAMEWORK packages, first — they were missing from this set
523
+ // entirely, and that was a hole straight through "the one gate".
524
+ //
525
+ // Their only disk-side check was `tree.frameworkInstalled()`, which
526
+ // is `resolves("@arcforge/types")`: a bare directory-presence test
527
+ // that cannot see a version. So an agent declaring a framework
528
+ // version it did not have on disk — a stale pin, a hand-edit, a
529
+ // node_modules left behind by a different checkout — passed prepare
530
+ // and reported `✓ ready`, then failed at runtime with whatever the
531
+ // wrong copy happened to do. Verified: pinning @arcforge/types to a
532
+ // version that cannot exist still printed `✓ ready`.
533
+ //
534
+ // verify() already answers this correctly for everything in
535
+ // `managed`, including exempting local `workspace:`/`file:` ranges,
536
+ // so the fix is to stop hiding these from it rather than to add a
537
+ // second check beside it.
538
+ for (const name of Object.keys(manifest.package.framework.dependencies(frameworkVersion, frameworkSource, repoRoot, KINDS[kind].framework))) {
539
+ const range = declaredNow[name]
540
+ if (range !== undefined) managed[name] = range
541
+ }
542
+
543
+ if (cognetSource.kind === "registry") {
544
+ const name = cognetName(cognetSource.specifier)
545
+ const range = declaredNow[name]
546
+ if (range !== undefined) managed[name] = range
547
+ }
548
+ for (const result of installed) {
549
+ if (result.status === "not-found" || result.status === "error") continue
550
+ const range = declaredNow[result.name]
551
+ if (range !== undefined) managed[result.name] = range
552
+ }
553
+
554
+ // What Axon may prune. Ownership must be PROVEN, never guessed: a
555
+ // dependency the user added by hand is not Axon's to remove, and a
556
+ // wrong guess deletes something the agent needs.
557
+ //
558
+ // A dependency is Axon's when it is a COGNET — the one kind of package
559
+ // an agent installs without ever declaring it in `modules: [...]`,
560
+ // and therefore the one that nothing else would ever clean up.
561
+ // Registry modules are already pruned against the config's own
562
+ // modules array by Modules.prune(); this closes the cognet gap that
563
+ // left @axon/zero declared long after the agent switched brains.
564
+ const selectedCognet = cognetSource.kind === "registry" ? cognetName(cognetSource.specifier) : null
565
+ const staleCognets = await cognetDependencies(declaredNow, selectedCognet)
566
+
567
+ // Reconcile owns the MANIFEST half: prune what is no longer declared,
568
+ // write the ranges this run intends. It no longer judges the tree —
569
+ // that is verify's job, and having two answers to "is the tree right"
570
+ // is how they drift apart.
571
+ const reconciled = await reconcile({
572
+ manifest,
573
+ tree,
574
+ managed,
575
+ owned: name => name in managed || staleCognets.has(name),
576
+ ...(options.frozen ? { dryRun: true } : {}),
577
+ })
578
+
579
+ // Verify owns the DISK half, through the one gate every dependency
580
+ // question resolves to. Run here (rather than only at the top) because
581
+ // `managed` is not knowable until the installers have declared their
582
+ // ranges — this is the first moment the full question can be asked.
583
+ const verified = await tree.verify({ manifest, managed, registryOrigin })
584
+
585
+ // --frozen asserts agreement rather than creating it. Anything
586
+ // reconcile had to change, or verify says is incoherent, is drift —
587
+ // and a deploy that silently resolves drift is a deploy that ships
588
+ // something other than what was committed.
589
+ if (options.frozen && (reconciled.changed || !verified.coherent)) {
590
+ throw err("PREPARE_FROZEN_DRIFT", {
591
+ detail: verified.faults.length
592
+ ? describeFaults(verified.faults)
593
+ : `package.json was out of sync with axon.config.ts (${reconciled.pruned.join(", ")} no longer declared)`,
594
+ context: { faults: verified.faults, pruned: reconciled.pruned },
595
+ })
596
+ }
597
+
598
+ if (
599
+ needsFrameworkInstall
600
+ || cognetNeedsInstall
601
+ || reconciled.changed
602
+ || verified.needsInstall
603
+ || pruned.length > 0
604
+ || installed.some(r => r.status === "installed")
605
+ || cognetInstall.some(r => r.status === "installed")
606
+ || sourceModules.some(r => r.dependenciesChanged)
607
+ ) {
608
+ // A stale package needs its range re-resolved, not merely
609
+ // replayed: the lockfile pin is exactly what is holding it back.
610
+ const refresh = verified.faults.filter(f => f.kind === "stale").map(f => f.name)
611
+
612
+ // A dangling graft cannot be installed OVER — bun writes what it
613
+ // resolves and leaves what it did not touch, so the dead links
614
+ // survive. The tree has to go first. Re-checked here as well as at
615
+ // the top because an install earlier in this run can evict the
616
+ // very tree this project was grafted onto.
617
+ if (verified.faults.some(f => f.kind === "dangling")) await tree.clearModules()
618
+
619
+ await phase(
620
+ report,
621
+ "build:tree",
622
+ { reason: "reconcile" },
623
+ () => tree.install({
624
+ ...(refresh.length ? { refresh } : {}),
625
+ onPropagationRetry: notePropagation,
626
+ }),
627
+ )
628
+ }
629
+
630
+ // Cognets version independently of the CLI now, so an agent can pin one
631
+ // built against a kernel ABI this runtime no longer provides. Fail
632
+ // HERE, naming both versions, rather than at agent boot with a mismatch
633
+ // buried inside the compiled bundle.
634
+ // The cognet stage: the ABI gate, then its weights. Bracketed
635
+ // together because they are one question — "can this brain run
636
+ // here" — and because the ABI mismatch is the single most common
637
+ // way a build dies. It threw straight to the terminal before this
638
+ // existed, which is what made a failed boot invisible.
639
+ const resolvedModels = await phase(
640
+ report,
641
+ "build:cognet",
642
+ { specifier: cognetSpecifier },
643
+ async () => {
644
+ const cognetDir = blueprint.cognet.sourceDir(cognetSource)
645
+ await cognetAbi(cognetDir, cognetSpecifier)
646
+
647
+ // Weights, before the compile that will carry their paths. A
648
+ // declared model that cannot be fetched fails HERE — a brain
649
+ // without its weights is broken rather than degraded, and
650
+ // finding that out at first inference is far worse than
651
+ // finding it at prepare.
652
+ const declaredModels = await readCognetModels(blueprint.cognet.sourceDir(cognetSource))
653
+ return weights.resolve(declaredModels, {
654
+ ...(options.frozen ? { frozen: true } : {}),
655
+ onDownload: model => console.log(` fetching ${model.key} — ${model.repo}/${model.file}`),
656
+ })
657
+ },
658
+ models => ({
659
+ specifier: cognetSpecifier,
660
+ models: Object.keys(models.paths).length,
661
+ }),
662
+ )
663
+
664
+ // compile: true — load() compiles the brain before scanning, because
665
+ // the scan reads the manifest compilation writes. A broken build throws:
666
+ // no brain, no agent.
667
+ const profileProviders = await opts.profileProviders?.()
668
+ const { blueprint: loaded, warnings } = await blueprint.load({
669
+ compile: true,
670
+ ...(Object.keys(resolvedModels.paths).length ? { models: resolvedModels.paths } : {}),
671
+ ...(profileProviders ? { profileProviders: [...profileProviders] } : {}),
672
+ })
673
+
674
+ return {
675
+ modules: installed,
676
+ sourceModules,
677
+ typegen: await phase(
678
+ report,
679
+ "build:typegen",
680
+ {},
681
+ () => typegen.write(loaded),
682
+ written => ({ files: Array.isArray(written) ? written : [] }),
683
+ ),
684
+ warnings: [
685
+ ...warnings,
686
+ // A local shadow makes THIS machine disagree with a fresh
687
+ // clone, silently and in the direction that always works
688
+ // here. Surfaced every prepare, because the moment it stops
689
+ // being visible is the moment it starts costing someone a
690
+ // day of debugging a bug only they can't reproduce.
691
+ ...verified.faults.filter(fault => fault.kind === "shadowed").map(fault => ({
692
+ domain: "dependencies",
693
+ error: `${fault.name} is pinned to a local workspace copy, not the registry — this agent will not behave like a fresh clone. `
694
+ + `Set it back to a version range in package.json if that was not deliberate.`,
695
+ })),
696
+ // A range this tool wrote against one registry and then had to
697
+ // rewrite for another. Always surfaced: the manifest changed
698
+ // underneath the user, and the reason (two registries, one
699
+ // package.json) is not something they can infer from the diff.
700
+ ...repairedRanges.map(fixed => ({
701
+ domain: "dependencies",
702
+ error: `${fixed.name} was ${fixed.from}, auto-resolved against ${fixed.origin}. `
703
+ + `That version does not exist here, so it was re-resolved to ${fixed.to}. `
704
+ + `Switching between registries rewrites this range each time.`,
705
+ })),
706
+ ],
707
+ }
708
+ }
709
+ }