@arcforge/platform 2.0.219 → 2.0.245

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 (127) hide show
  1. package/package.json +27 -19
  2. package/src/build/blueprint/blueprint.ts +48 -64
  3. package/src/build/blueprint/cognet/abi.ts +3 -257
  4. package/src/build/blueprint/cognet/bundle-worker.ts +11 -0
  5. package/src/build/blueprint/cognet/bundle.ts +294 -89
  6. package/src/build/blueprint/cognet/cognet.ts +8 -7
  7. package/src/build/blueprint/cognet/config/config.ts +52 -0
  8. package/src/build/blueprint/cognet/config/index.ts +4 -0
  9. package/src/build/blueprint/cognet/config/literal.ts +83 -0
  10. package/src/build/blueprint/cognet/config/provider.ts +43 -0
  11. package/src/build/blueprint/cognet/config/shape.ts +183 -0
  12. package/src/build/blueprint/cognet/index.ts +4 -2
  13. package/src/build/blueprint/cognet/native/cargo.ts +31 -0
  14. package/src/build/blueprint/cognet/native/crate.ts +126 -0
  15. package/src/build/blueprint/cognet/native/index.ts +2 -0
  16. package/src/build/blueprint/cognet/native/library.ts +125 -0
  17. package/src/build/blueprint/cognet/native/manifest.ts +137 -0
  18. package/src/build/blueprint/cognet/python/index.ts +1 -0
  19. package/src/build/blueprint/cognet/python/project.ts +119 -0
  20. package/src/build/blueprint/cognet/schema/arrays.ts +23 -0
  21. package/src/build/blueprint/cognet/schema/authored.ts +273 -0
  22. package/src/build/blueprint/cognet/schema/compile.ts +78 -0
  23. package/src/build/blueprint/cognet/schema/components/external.ts +15 -0
  24. package/src/build/blueprint/cognet/schema/components/index.ts +3 -0
  25. package/src/build/blueprint/cognet/schema/components/lock.ts +58 -0
  26. package/src/build/blueprint/cognet/schema/components/model.ts +34 -0
  27. package/src/build/blueprint/cognet/schema/components/python.ts +15 -0
  28. package/src/build/blueprint/cognet/schema/components/python_source.py +69 -0
  29. package/src/build/blueprint/cognet/schema/components/rust.ts +33 -0
  30. package/src/build/blueprint/cognet/schema/components/rust_source/Cargo.lock +117 -0
  31. package/src/build/blueprint/cognet/schema/components/rust_source/Cargo.toml +11 -0
  32. package/src/build/blueprint/cognet/schema/components/rust_source/src/main.rs +104 -0
  33. package/src/build/blueprint/cognet/schema/components/source.ts +220 -0
  34. package/src/build/blueprint/cognet/schema/components/tags.ts +66 -0
  35. package/src/build/blueprint/cognet/schema/components/typescript.ts +157 -0
  36. package/src/build/blueprint/cognet/schema/index.ts +5 -0
  37. package/src/build/blueprint/cognet/schema/interfaces/index.ts +3 -0
  38. package/src/build/blueprint/cognet/schema/interfaces/source.ts +218 -0
  39. package/src/build/blueprint/cognet/schema/python.ts +260 -0
  40. package/src/build/blueprint/cognet/schema/rust.ts +316 -0
  41. package/src/build/blueprint/cognet/schema/schema.ts +248 -0
  42. package/src/build/blueprint/cognet/schema/typescript.ts +352 -0
  43. package/src/build/blueprint/index.ts +1 -1
  44. package/src/build/blueprint/modules/index.ts +7 -5
  45. package/src/build/blueprint/modules/meta.ts +47 -3
  46. package/src/build/blueprint/scan/config.ts +22 -16
  47. package/src/build/blueprint/scan/provider-globals.ts +46 -0
  48. package/src/build/blueprint/scan/providers.ts +25 -0
  49. package/src/build/blueprint/scan/tools.ts +21 -15
  50. package/src/build/extensions/edit.ts +66 -2
  51. package/src/build/extensions/extensions.ts +16 -3
  52. package/src/build/extensions/index.ts +1 -1
  53. package/src/build/project/bundle/agent.ts +26 -17
  54. package/src/build/project/bundle/source.ts +2 -2
  55. package/src/build/project/create/cognet.ts +84 -33
  56. package/src/build/project/create/profile.ts +13 -3
  57. package/src/build/project/index.ts +1 -1
  58. package/src/build/project/installer.ts +6 -5
  59. package/src/build/project/kinds.ts +4 -0
  60. package/src/build/project/manifest/env.ts +10 -0
  61. package/src/build/project/models/blobs/blobs.ts +57 -0
  62. package/src/build/project/models/blobs/index.ts +1 -0
  63. package/src/build/project/models/fetch.ts +46 -51
  64. package/src/build/project/models/index.ts +2 -1
  65. package/src/build/project/models/models.ts +12 -38
  66. package/src/build/project/models/onnx.ts +82 -0
  67. package/src/build/project/models/specifier.ts +9 -3
  68. package/src/build/project/models/storage/index-store.ts +27 -0
  69. package/src/build/project/models/storage/index.ts +1 -0
  70. package/src/build/project/models/store.ts +21 -16
  71. package/src/build/project/prepare.ts +82 -27
  72. package/src/build/project/project.ts +8 -14
  73. package/src/build/project/projects.ts +12 -1
  74. package/src/build/project/tree.ts +13 -3
  75. package/src/build/project/treecache.ts +8 -4
  76. package/src/build/project/typegen/axon-dts.ts +18 -0
  77. package/src/build/project/typegen/cognet-dts.ts +248 -59
  78. package/src/build/project/typegen/prompt-dts.ts +2 -3
  79. package/src/build/project/typegen/registry-dts.ts +2 -2
  80. package/src/build/project/typegen/tsconfig.ts +13 -13
  81. package/src/build/project/typegen/tui-dts.ts +3 -4
  82. package/src/build/project/typegen/workspace-scripts.ts +8 -7
  83. package/src/build/project/typegen/write.ts +15 -2
  84. package/src/build/project/watcher.ts +27 -0
  85. package/src/build/runtime/agent.ts +102 -63
  86. package/src/build/runtime/conformance.ts +25 -0
  87. package/src/build/runtime/escalations.ts +3 -8
  88. package/src/build/runtime/index.ts +2 -0
  89. package/src/build/runtime/instances.ts +7 -4
  90. package/src/build/runtime/progress.ts +6 -2
  91. package/src/build/runtime/reload-watch.ts +11 -8
  92. package/src/debug/README.md +398 -0
  93. package/src/debug/debug.ts +101 -0
  94. package/src/debug/events.ts +156 -0
  95. package/src/debug/graph.ts +94 -0
  96. package/src/debug/index.ts +5 -0
  97. package/src/debug/indexer.ts +286 -0
  98. package/src/debug/inference.ts +53 -0
  99. package/src/debug/log.ts +68 -0
  100. package/src/debug/overview.ts +78 -0
  101. package/src/debug/perf.ts +75 -0
  102. package/src/debug/resources.ts +125 -0
  103. package/src/debug/ring.ts +31 -0
  104. package/src/debug/sessions.ts +90 -0
  105. package/src/debug/signs.ts +119 -0
  106. package/src/debug/tally.ts +44 -0
  107. package/src/debug/types.ts +146 -0
  108. package/src/index.ts +9 -0
  109. package/src/link/agent-main.ts +36 -10
  110. package/src/link/index.ts +1 -1
  111. package/src/link/services.ts +88 -57
  112. package/src/platform.ts +17 -25
  113. package/src/services/cloud.ts +1 -4
  114. package/src/services/control/client.ts +1 -1
  115. package/src/services/control/server.ts +1 -1
  116. package/src/services/index.ts +1 -0
  117. package/src/services/ollama/daemon.ts +23 -0
  118. package/src/services/ollama/http.ts +7 -1
  119. package/src/services/ollama/ollama.ts +8 -14
  120. package/src/services/probe/ask.ts +139 -0
  121. package/src/services/probe/index.ts +3 -0
  122. package/src/services/providers.ts +18 -0
  123. package/src/services/resources/hardware.ts +15 -18
  124. package/src/services/resources/resources.ts +4 -5
  125. package/src/services/store/types.ts +3 -0
  126. package/src/services/running/index.ts +0 -1
  127. package/src/services/running/running.ts +0 -216
@@ -1,16 +1,20 @@
1
1
  import { workerPath } from "../../../utils/packaged"
2
2
  import { createHash } from "node:crypto"
3
3
  import { readdir, rename, rm } from "node:fs/promises"
4
- import { existsSync, lstatSync, realpathSync } from "node:fs"
4
+ import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs"
5
5
  import { homedir } from "node:os"
6
- import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
6
+ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
7
7
  import { pathToFileURL } from "node:url"
8
8
  import { err } from "@arcforge/err"
9
9
  import { KERNEL_ABI_VERSION } from "@arcforge/types"
10
- import type { CognetBlueprint, CognetDefinition } from "@arcforge/types"
10
+ import type { CognetBlueprint, CognetDefinition, CognetUse, ServiceUse } from "@arcforge/types"
11
11
  import { fsx } from "../../../utils/fs"
12
12
  import { Frame } from "../../frame"
13
- import { readCognetAbi } from "./abi"
13
+ import { CognetConfigFile } from "./config"
14
+ import { Crate, NATIVE_DIR } from "./native"
15
+ import { PythonProject } from "./python"
16
+ import type { PythonSystem } from "@arcforge/cognet"
17
+ import { Schema, type Described } from "./schema"
14
18
 
15
19
  // The subprocess entry that actually runs Bun.build() — see runBundleWorker()
16
20
  // for why this isn't inline.
@@ -34,8 +38,8 @@ type BundleWorkerResult =
34
38
  * tree, so this is not a trivial burst). A subprocess moves that freeze
35
39
  * off the process that owns the terminal.
36
40
  */
37
- async function runBundleWorker(entryPath: string, external: string[]): Promise<BundleWorkerResult> {
38
- const proc = Bun.spawn(["bun", "run", BUNDLE_WORKER_PATH, entryPath, external.join(",")], {
41
+ async function runBundleWorker(entryPath: string, external: string[], schemaDir: string): Promise<BundleWorkerResult> {
42
+ const proc = Bun.spawn(["bun", "run", BUNDLE_WORKER_PATH, entryPath, external.join(","), schemaDir], {
39
43
  stdout: "pipe",
40
44
  stderr: "pipe",
41
45
  })
@@ -57,6 +61,15 @@ export type CognetArtifact = {
57
61
  blueprint: CognetBlueprint & { path: string; hash: string }
58
62
  }
59
63
 
64
+ /**
65
+ * Where, in the agent frame's `cognet/`, a cognet's schemas are generated —
66
+ * and the specifier cognet source imports them by: `#schema/control/control`
67
+ * is `<frame>/cognet/schema/control/control.ts`. The bundle worker resolves
68
+ * it; the agent's cognet tsconfig maps it for the editor, tsc and bun test.
69
+ */
70
+ export const SCHEMA_DIR = "schema"
71
+ export const SCHEMA_SPECIFIER = "#schema/"
72
+
60
73
  /**
61
74
  * The host module the generated entry composes with — a BARE SPECIFIER,
62
75
  * resolved by the bundler from the agent's own node_modules.
@@ -147,7 +160,7 @@ async function linkedHostIdentity(hostDir: string): Promise<string | null> {
147
160
  const hash = createHash("sha256")
148
161
  const walked = await fsx.walk(join(real, "src"), { skipDirs: ["node_modules"] })
149
162
  const files = walked
150
- .filter(({ relPath }) => /\.(ts|tsx|js|mjs|json)$/.test(relPath))
163
+ .filter(({ relPath }) => /\.(ts|tsx|js|mjs|json|rs|toml|lock|proto)$/.test(relPath))
151
164
  .sort((a, b) => a.relPath.localeCompare(b.relPath))
152
165
 
153
166
  for (const { absPath, relPath } of files) {
@@ -179,19 +192,21 @@ async function isDeclared(agentRoot: string): Promise<boolean> {
179
192
  * <agent>/.agent/cognet/cognet.mjs.map — sourcemap (debuggability)
180
193
  * <agent>/.agent/cognet/manifest.json — { name, version, abi, hash, wakeOn }
181
194
  *
182
- * The authoring surface is two clutter-free files — cognet.config.ts
183
- * (declaration via defineCognet) and src/main.ts (a raw script declaring
184
- * loop() against ambient globals). This step is the desugar:
195
+ * The authoring surface is plain files against ambient globals —
196
+ * cognet.config.ts (defineCognet), `*.system.ts` files anywhere under the
197
+ * cognet, and an optional main.ts (a raw script that may declare loop()).
198
+ * This step is the desugar:
185
199
  *
186
- * 1. WRAP main.ts — hoist its import statements out, defer its body into
187
- * an exported async function. The script becomes callable; the host
188
- * runs it once at load(), after the kernel global is bound.
189
- * 2. GENERATE an entry that imports the host FIRST (module evaluation
190
- * order — installing the globals before config/main evaluate), then
191
- * composes: `export default CognetHost({ ...config, ...identity }, main)`,
192
- * with identity resolved here from package.json + the kernel's ABI.
193
- * 3. BUNDLE the entry (Bun.build) — host, config, main, and their whole
194
- * import graph inlined into one file the runtime imports and verifies.
200
+ * 1. DISCOVER every `*.system.ts`, and every file defining components or
201
+ * queries. WRAP main.ts — hoist its imports, defer its body into an
202
+ * exported async function the host runs once at load().
203
+ * 2. GENERATE an entry that imports the host FIRST (installing the globals
204
+ * before anything else evaluates), then plugins, config, the discovered
205
+ * files and the script, and composes them — `Discovered()` names every
206
+ * definition from where it is defined, and `CognetHost` receives the
207
+ * systems with identity resolved from package.json + the kernel's ABI.
208
+ * 3. BUNDLE the entry (Bun.build) — host, config, systems, main, and their
209
+ * whole import graph inlined into one file the runtime imports.
195
210
  *
196
211
  * The blueprint's identity is then read back off the ARTIFACT: we import the
197
212
  * fresh bundle once here and read the composed definition's own fields, so
@@ -204,32 +219,25 @@ async function isDeclared(agentRoot: string): Promise<boolean> {
204
219
  * compile skip straight to the existing manifest instead of rebuilding.
205
220
  */
206
221
  /**
207
- * The brain's entry file — `src/main.ts`, or `main.ts` at the cognet root.
222
+ * The brain's script — `src/main.ts`, or `main.ts` at the cognet root — or
223
+ * null when it has none.
208
224
  *
209
- * Both, because both are natural at their own scale. A published cognet with
210
- * plugins, state and several modules wants `src/`; a brain inlined in an agent
211
- * is often one file, and making it sit alone inside a `src/` directory is
212
- * ceremony with nothing to organize. The layout is the author's call.
225
+ * Optional since systems: a brain made only of `*.system.ts` files needs no
226
+ * script, and the host runs its systems every tick. Whether a brain has
227
+ * ANYTHING to run is checked once discovery is done, where both are known.
213
228
  *
214
- * `src/` wins when both exist rather than erroring: it is the conventional
215
- * layout, so a stray top-level `main.ts` beside a real `src/main.ts` is far
216
- * more likely to be a leftover than an intentional second entry.
217
- *
218
- * Throws with both candidates named — a cognet with no entry compiles to
219
- * nothing, and the ENOENT this used to raise pointed only at `src/main.ts`,
220
- * which was actively misleading for a flat layout.
229
+ * `src/` wins when both exist: it is the conventional layout, so a stray
230
+ * top-level `main.ts` beside a real `src/main.ts` is far more likely to be a
231
+ * leftover than an intentional second entry.
221
232
  */
222
- function resolveCognetMain(sourceDir: string): string {
233
+ function resolveCognetMain(sourceDir: string): string | null {
223
234
  const nested = join(sourceDir, "src", "main.ts")
224
235
  if (fsx.isFile(nested)) return nested
225
236
 
226
237
  const flat = join(sourceDir, "main.ts")
227
238
  if (fsx.isFile(flat)) return flat
228
239
 
229
- throw err("COGNET_INVALID", {
230
- detail: `no brain entry in ${sourceDir} — expected src/main.ts or main.ts`,
231
- context: { sourceDir, candidates: [nested, flat] },
232
- })
240
+ return null
233
241
  }
234
242
 
235
243
  /**
@@ -312,7 +320,6 @@ export async function bundleCognet(opts: {
312
320
  const outFile = join(outDir, "cognet.mjs")
313
321
  const manifestFile = join(outDir, "manifest.json")
314
322
 
315
- const mainSource = await Bun.file(mainPath).text()
316
323
 
317
324
  // A cognet.config.ts is OPTIONAL for every brain, published or inline.
318
325
  //
@@ -328,8 +335,34 @@ export async function bundleCognet(opts: {
328
335
  // author who wants a non-default schedule, a wake mask or engine
329
336
  // requirements writes the file and gets the full surface.
330
337
  const hasConfig = await Bun.file(configPath).exists()
331
-
332
- const inputHash = await hashCognetInputs(opts.sourceDir, opts.agentRoot)
338
+ const declared = CognetConfigFile({ sourceDir: opts.sourceDir }).read()
339
+ const named = await cognetIdentity({ sourceDir: opts.sourceDir, agentRoot: opts.agentRoot, inline: opts.inline })
340
+
341
+ // The schemas first: what they generate — into this agent's frame, never the source — is an input
342
+ // the hash below must see, and a module the discovery below must name.
343
+ const schemaDir = join(outDir, SCHEMA_DIR)
344
+ // Its Rust systems, compiled into the one module the entry loads — with the schemas' Rust, when there are any.
345
+ const crate = Crate({ sourceDir: opts.sourceDir, agentRoot: opts.agentRoot, out: join(outDir, "native"), owned: !opts.sourceDir.split(sep).includes("node_modules") })
346
+ const rust = await crate.sources()
347
+ const native = rust.some(source => source.system !== null)
348
+ const hasRustProject = native || (rust.length > 0 && existsSync(join(opts.sourceDir, "Cargo.toml")))
349
+ const python = PythonProject({ sourceDir: opts.sourceDir, agentRoot: opts.agentRoot, out: join(outDir, "python"), owned: !opts.sourceDir.split(sep).includes("node_modules") })
350
+ const pythonSources = await python.sources()
351
+ // A hot reload's copy (see core's cognet resolve), left behind by a process that never swapped it out.
352
+ for (const left of existsSync(outDir) ? (await readdir(outDir)).filter(entry => /^cognet\.[0-9a-f]+\.mjs$/.test(entry)) : []) await rm(join(outDir, left), { force: true })
353
+ // An inline brain's own interfaces are its agent's: `@cody/terry/features@1`, not the synthetic `terry-brain`'s.
354
+ const scope = opts.inline ? (await fsx.readJson<{ name?: string }>(join(opts.agentRoot, "package.json")))?.name ?? named.name : named.name
355
+ const schema = await Schema({ sourceDir: opts.sourceDir, agentRoot: opts.agentRoot, cognet: scope, uses: declared?.uses ?? {}, out: schemaDir, rust: hasRustProject ? crate.schema() : null, python: pythonSources.length > 0 ? join(outDir, "python", "generated") : null, stage: join(outDir, ".schema") }).generate()
356
+ // Each use joined to the interface it names, as compiled: what the kernel grants and serves by, and what each
357
+ // run's `services` calls through.
358
+ const uses = declared?.uses && Object.keys(declared.uses).length > 0 ? joined(declared.uses, schema.interfaces) : null
359
+ const builtNative = hasRustProject ? await crate.build(rust) : null
360
+ if (!builtNative) crate.clear()
361
+ const nativeModule = native ? builtNative : null
362
+ const pythonProject = pythonSources.length > 0 ? await python.prepare(pythonSources) : null
363
+ if (!pythonProject) python.clear()
364
+
365
+ const inputHash = await hashCognetInputs(opts.sourceDir, opts.agentRoot, schemaDir, nativeModule ? basename(nativeModule) : null)
333
366
  const cached = await readCachedArtifact(manifestFile, outFile, inputHash)
334
367
  if (cached) return cached
335
368
 
@@ -340,31 +373,33 @@ export async function bundleCognet(opts: {
340
373
  // project-specific, so only the .mjs travels).
341
374
  const shared = await readSharedArtifact(inputHash)
342
375
  if (shared) {
376
+ // `uses` names where each interface's cases are on THIS machine, for THIS project: never the cached copy's.
377
+ const { uses: _, ...identified } = shared.blueprint
378
+ const blueprint = { ...identified, ...(uses ? { uses: uses } : {}), path: outFile }
343
379
  await Bun.write(outFile, shared.code)
344
- await Bun.write(
345
- manifestFile,
346
- JSON.stringify({ ...shared.blueprint, path: outFile, inputHash, sourceDir: opts.sourceDir }, null, 4),
347
- )
348
- return { blueprint: { ...shared.blueprint, path: outFile } }
380
+ await Bun.write(manifestFile, JSON.stringify({ ...blueprint, inputHash, sourceDir: opts.sourceDir }, null, 4))
381
+ return { blueprint: blueprint }
349
382
  }
350
383
 
351
- // 1. wrap the raw script — imports hoisted, body deferred
352
- const { imports, body } = splitImports(mainSource, dirname(mainPath))
353
- const wrapped = [
354
- `// generated by axon — the raw script ${relative(opts.sourceDir, mainPath)}, made callable.`,
355
- "// imports hoisted; body runs once at load(), after kernel binds.",
356
- imports,
357
- "export default async function __cognet_main(): Promise<void> {",
358
- body,
359
- "}",
360
- ].join("\n")
384
+ // 1. what the brain is made of: its systems, the files defining the
385
+ // components and queries they use, and its optional script.
386
+ const systems = await discover.systems(opts.sourceDir)
387
+ const definitions = [...await discover.definitions(opts.sourceDir, naming(opts.sourceDir)), ...await discover.definitions(schemaDir, relPath => relPath)]
388
+ if (!mainPath && systems.length === 0 && !native && !pythonProject) {
389
+ throw err("COGNET_NO_LOOP", {
390
+ detail: `no brain in ${opts.sourceDir} — expected *.system.ts, *.system.rs, *.system.py, src/main.ts, or main.ts`,
391
+ context: { sourceDir: opts.sourceDir },
392
+ })
393
+ }
394
+
395
+ const wrapped = mainPath ? script(mainPath, opts.sourceDir) : NO_SCRIPT
361
396
  await Bun.write(join(buildDir, "main.ts"), wrapped)
362
397
 
363
398
  // 2. the composed entry — import order IS the wiring:
364
399
  // host first (installs the ambient globals, incl. definePlugin),
365
400
  // then plugins (their definePlugin(...) calls register hooks at import
366
401
  // time — before load() fires "boot"), then config, then main.
367
- const plugins = await discoverPlugins(opts.sourceDir)
402
+ const plugins = await discover.plugins(opts.sourceDir)
368
403
 
369
404
  // An inline brain with no config file gets one written into the build
370
405
  // scratch, so the composition below stays identical for every cognet —
@@ -381,10 +416,8 @@ export async function bundleCognet(opts: {
381
416
  // config. The ABI a config may pin is honoured; absent, this compile's own
382
417
  // kernel is stamped in, which is the truthful answer — the bundle really
383
418
  // was built against it.
384
- const identity = {
385
- ...(await cognetIdentity({ sourceDir: opts.sourceDir, agentRoot: opts.agentRoot, inline: opts.inline })),
386
- abi: (hasConfig ? await readCognetAbi(opts.sourceDir) : null) ?? KERNEL_ABI_VERSION,
387
- }
419
+ // The host is given what it calls by — never where the cases are, which is this machine's and not the brain's.
420
+ const identity = { ...named, abi: declared?.abi ?? KERNEL_ABI_VERSION, ...(uses ? { uses: Object.fromEntries(Object.entries(uses).map(([name, { conformance: _, ...use }]) => [name, use])) } : {}) }
388
421
 
389
422
  // Identity is MERGED INTO the config object rather than passed as its own
390
423
  // argument. CognetHost is a published package's public surface, and a
@@ -395,12 +428,8 @@ export async function bundleCognet(opts: {
395
428
  // resolved fact, and a config that somehow still carries a stale name
396
429
  // must not win over it.
397
430
  const entry = [
398
- "// generated by axon — composes identity + plugins + script into the definition.",
399
- `import { CognetHost } from ${JSON.stringify(HOST_SPECIFIER)}`,
400
- ...plugins.map((p, i) => `import ${specifier(p)} // plugin ${i}`),
401
- `import config from ${configImport}`,
402
- `import main from "./main.ts"`,
403
- `export default CognetHost({ ...config, ...${JSON.stringify(identity)} }, main)`,
431
+ "// generated by axon — composes identity + plugins + systems + script into the definition.",
432
+ ...composition({ plugins: plugins, configImport: configImport, identity: identity, systems: systems, definitions: definitions, native: nativeModule ? `./${NATIVE_DIR}/${basename(nativeModule)}` : null, python: pythonProject, sourceDir: opts.sourceDir }),
404
433
  ].join("\n")
405
434
  const entryPath = join(buildDir, "entry.ts")
406
435
  await Bun.write(entryPath, entry)
@@ -418,7 +447,7 @@ export async function bundleCognet(opts: {
418
447
  const external = Object.keys(cognetPkg?.dependencies ?? {})
419
448
  .filter(name => !name.startsWith("@arcforge/"))
420
449
 
421
- const result = await runBundleWorker(entryPath, external)
450
+ const result = await runBundleWorker(entryPath, external, schemaDir)
422
451
  if (!result.ok) {
423
452
  throw err("COGNET_BUILD_FAILED", { detail: result.message, context: { sourceDir: opts.sourceDir } })
424
453
  }
@@ -441,8 +470,10 @@ export async function bundleCognet(opts: {
441
470
  name: definition.name,
442
471
  version: definition.version,
443
472
  abi: definition.abi,
473
+ mode: definition.mode,
444
474
  ...(definition.wakeOn ? { wakeOn: definition.wakeOn } : {}),
445
475
  ...(definition.stimuli ? { stimuli: definition.stimuli } : {}),
476
+ ...(uses ? { uses: uses } : {}),
446
477
  path: outFile,
447
478
  hash,
448
479
  }
@@ -459,6 +490,15 @@ export async function bundleCognet(opts: {
459
490
  return { blueprint }
460
491
  }
461
492
 
493
+ /** Each use the config declares, with the interface it names as compiled — what the kernel grants and serves by. */
494
+ function joined(uses: Readonly<Record<string, ServiceUse>>, interfaces: readonly Described[]): Record<string, CognetUse> {
495
+ return Object.fromEntries(Object.entries(uses).map(([name, use]) => {
496
+ const compiled = interfaces.find(one => one.written === use.interface)
497
+ if (!compiled) throw err("INTERFACE_NOT_FOUND", { detail: `uses.${name}: ${use.interface} was not compiled`, context: { use: name, interface: use.interface } })
498
+ return [name, { ...use, named: compiled.name, methods: compiled.methods, ...(compiled.conformance ? { conformance: compiled.conformance } : {}) }]
499
+ }))
500
+ }
501
+
462
502
  // ── machine-wide artifact cache ───────────────────────────────────────────────
463
503
 
464
504
  /**
@@ -513,10 +553,11 @@ async function publishSharedArtifact(
513
553
  const pending = `${final}.pending-${crypto.randomUUID().slice(0, 8)}`
514
554
  try {
515
555
  await Bun.write(join(pending, "cognet.mjs"), Bun.file(outFile))
516
- // `path` is deliberately dropped — it names the frame of whichever
517
- // project happened to compile first, and every consumer overwrites it
518
- // with its own. Storing it would invite someone to trust it.
519
- const { path: _local, ...portable } = blueprint
556
+ // `path` and `uses` are deliberately dropped — they name the frame and
557
+ // the conformance cases of whichever project happened to compile
558
+ // first, and every consumer writes its own. Storing them would invite
559
+ // someone to trust them.
560
+ const { path: _local, uses: _uses, ...portable } = blueprint
520
561
  await Bun.write(join(pending, "blueprint.json"), JSON.stringify(portable))
521
562
  await rename(pending, final)
522
563
  } catch {
@@ -544,8 +585,21 @@ async function publishSharedArtifact(
544
585
  * graph would be tighter, but a false MISS only costs a recompile while a
545
586
  * false HIT ships the wrong brain — so when in doubt, rebuild.
546
587
  */
547
- async function hashCognetInputs(sourceDir: string, agentRoot: string): Promise<string> {
588
+ /**
589
+ * The shape of a cached artifact's blueprint. Bump it whenever a field is
590
+ * added to, or removed from, what the bundle writes: every entry written
591
+ * before then is then a miss, rebuilt, rather than read without the field.
592
+ *
593
+ * 2 — `mode`, so a client knows what kind of mind it is talking to
594
+ */
595
+ const ARTIFACT_FORMAT = "artifact/2"
596
+
597
+ async function hashCognetInputs(sourceDir: string, agentRoot: string, schemaDir: string, native: string | null): Promise<string> {
548
598
  const hash = createHash("sha256")
599
+ // What a cached entry HOLDS is an input too: an entry written in an older shape is a miss, never a blueprint missing a field.
600
+ hash.update(`${ARTIFACT_FORMAT}\0`)
601
+ // The entry loads its native module by name, and the name is the module's content: a new one is a new bundle.
602
+ hash.update(`native\0${native ?? ""}\0`)
549
603
 
550
604
  hash.update(`${HOST_SPECIFIER}@${await hostVersion(agentRoot)}\0`)
551
605
 
@@ -554,10 +608,16 @@ async function hashCognetInputs(sourceDir: string, agentRoot: string): Promise<s
554
608
  // version above, not on their bytes).
555
609
  const walked = await fsx.walk(sourceDir, { skipDirs: ["node_modules", ".cognet", ".git"] })
556
610
  const files = walked
557
- .filter(({ relPath }) => /\.(ts|tsx|js|mjs|json)$/.test(relPath))
611
+ .filter(({ relPath }) => /\.(ts|tsx|js|mjs|json|rs|py|toml|lock|proto)$/.test(relPath))
558
612
  .map(({ absPath }) => absPath)
559
613
  .sort()
560
614
 
615
+ // What the schemas generated is compiled too — and differs whenever the generator does, whatever the schemas say.
616
+ for (const file of existsSync(schemaDir) ? (await fsx.walk(schemaDir)).map(({ absPath }) => absPath).sort() : []) {
617
+ const text = await Bun.file(file).text()
618
+ hash.update(`${SCHEMA_SPECIFIER}${relative(schemaDir, file)}\0${text}`)
619
+ }
620
+
561
621
  for (const file of files) {
562
622
  const text = await Bun.file(file).text().catch(() => null)
563
623
  // Path RELATIVE to the cognet root, never absolute: the same brain
@@ -591,6 +651,25 @@ async function readCachedArtifact(manifestFile: string, outFile: string, inputHa
591
651
 
592
652
  // ── the wrap transform ────────────────────────────────────────────────────────
593
653
 
654
+ /** The script of a brain that has none: its systems are the whole program. */
655
+ const NO_SCRIPT = [
656
+ "// generated by axon — this brain has no main.ts; its systems are the whole program.",
657
+ "export default async function __cognet_main(): Promise<void> {}",
658
+ ].join("\n")
659
+
660
+ /** The raw script, made callable — imports hoisted, body deferred to load(). */
661
+ function script(mainPath: string, sourceDir: string): string {
662
+ const { imports, body } = splitImports(readFileSync(mainPath, "utf8"), dirname(mainPath))
663
+ return [
664
+ `// generated by axon — the raw script ${relative(sourceDir, mainPath)}, made callable.`,
665
+ "// imports hoisted; body runs once at load(), after kernel binds.",
666
+ imports,
667
+ "export default async function __cognet_main(): Promise<void> {",
668
+ body,
669
+ "}",
670
+ ].join("\n")
671
+ }
672
+
594
673
  /**
595
674
  * Split a raw script into its top-level import statements and everything
596
675
  * else. Relative specifiers are re-anchored to the script's own directory
@@ -639,25 +718,151 @@ function reanchor(statement: string, sourceDir: string): string {
639
718
  })
640
719
  }
641
720
 
642
- // ── plugin discovery ──────────────────────────────────────────────────────────
721
+ // ── discovery ─────────────────────────────────────────────────────────────────
722
+
723
+ /** Directories no discovered file lives under: installed code and build output. */
724
+ const SKIP_DIRS = ["node_modules", ".git", ".cognet", ".agent"]
725
+
726
+ /** `export const flow = component<Flow>(...)` / `export const tracked = query({...})` / `export const world = frame({...})` */
727
+ const DEFINITION = /^export\s+const\s+([A-Za-z_$][\w$]*)\s*(?::[^=\n]+)?=\s*(?:component|query|frame)\s*[<(]/gm
728
+
729
+ /** A file under the cognet root that defines components or queries, and the exports it defines. */
730
+ type DefinitionFile = { absPath: string; relPath: string; names: string[]; named: string }
731
+
732
+ /** A `*.system.ts` file under the cognet root. */
733
+ type SystemFile = { absPath: string; relPath: string }
734
+
735
+ const discover = {
736
+ /**
737
+ * Absolute paths of the cognet's lifecycle plugins — plugins/*.ts, sorted
738
+ * for deterministic import order. Imported AFTER the host (so definePlugin
739
+ * exists) and BEFORE main (so hooks register before "boot" fires).
740
+ *
741
+ * No plugins folder is an ordinary brain. Any OTHER failure to read it —
742
+ * permissions, a file where the folder should be — throws: returning
743
+ * "no plugins" there compiles a brain silently missing its tick driver.
744
+ */
745
+ async plugins(sourceDir: string): Promise<string[]> {
746
+ const dir = join(sourceDir, "plugins")
747
+ if (!existsSync(dir)) return []
748
+ const names = await readdir(dir)
749
+ return names
750
+ .filter(n => n.endsWith(".ts") && !n.endsWith(".d.ts") && !n.endsWith(".test.ts"))
751
+ .sort()
752
+ .map(n => join(dir, n))
753
+ },
754
+
755
+ /**
756
+ * Every `*.system.ts` under the cognet, wherever it sits. Convention over
757
+ * config: the suffix IS the registration, and the schedule orders them
758
+ * from their data, so where a system lives is the author's choice.
759
+ */
760
+ async systems(sourceDir: string): Promise<SystemFile[]> {
761
+ const walked = await fsx.walk(sourceDir, { skipDirs: SKIP_DIRS })
762
+ return walked.filter(({ relPath }) => relPath.endsWith(".system.ts"))
763
+ },
764
+
765
+ /**
766
+ * Every file defining components or queries, with the exports it defines.
767
+ *
768
+ * Read as text, not executed: a definition's NAME is its folder plus its
769
+ * export name, which is a fact about the source. The generated entry
770
+ * imports each file and names exactly these exports; a handle defined any
771
+ * other way stays unnamed and throws the first time a system uses it.
772
+ */
773
+ async definitions(sourceDir: string, named: (relPath: string) => string): Promise<DefinitionFile[]> {
774
+ if (!existsSync(sourceDir)) return []
775
+ const walked = await fsx.walk(sourceDir, { skipDirs: SKIP_DIRS })
776
+ const found: DefinitionFile[] = []
777
+ for (const file of walked) {
778
+ if (!file.relPath.endsWith(".ts") || file.relPath.endsWith(".d.ts") || file.relPath.endsWith(".test.ts")) continue
779
+ const source = readFileSync(file.absPath, "utf8")
780
+ const names = [...source.matchAll(DEFINITION)].map(match => match[1]!)
781
+ if (names.length > 0) found.push({ ...file, names: names, named: named(file.relPath) })
782
+ }
783
+ return found
784
+ },
785
+ }
786
+
787
+ /**
788
+ * The path a file is NAMED by. A cognet that keeps its code under `src/`
789
+ * names everything from there — `L0/sense/vestibular/velocity`, not
790
+ * `src/L0/…` — because `src/` is where the code lives, not part of what it
791
+ * means. Files outside `src/` keep their path from the cognet root; a clash
792
+ * between the two is refused by `Discovered` like any other.
793
+ */
794
+ function naming(sourceDir: string): (relPath: string) => string {
795
+ const hasSource = existsSync(join(sourceDir, "src"))
796
+ return relPath => hasSource && relPath.startsWith("src/") ? relPath.slice("src/".length) : relPath
797
+ }
643
798
 
644
799
  /**
645
- * Absolute paths of the cognet's lifecycle plugins — plugins/*.ts, sorted
646
- * for deterministic import order. Each is imported into the entry AFTER the
647
- * host (so definePlugin exists) and BEFORE main (so hooks are registered
648
- * before "boot" fires). Convention over config: no manifest, the folder IS
649
- * the registry — same as agents/modules.
800
+ * The generated entry's body — import order IS the wiring.
801
+ *
802
+ * Host first (installs the ambient globals — definePlugin, component, query,
803
+ * defineSystem), then plugins, config, the definition and system files, the
804
+ * script, and finally the composition. `Discovered` is imported only when
805
+ * there are systems: it exists only in hosts that can run them, so a new CLI
806
+ * against an old installed host fails HERE, at build, instead of shipping a
807
+ * brain whose systems never run. A loop-only brain stays buildable against
808
+ * either.
650
809
  */
651
- async function discoverPlugins(sourceDir: string): Promise<string[]> {
652
- const dir = join(sourceDir, "plugins")
653
- let names: string[]
654
- try {
655
- names = await readdir(dir)
656
- } catch {
657
- return []
810
+ function composition(opts: {
811
+ plugins: string[]
812
+ configImport: string
813
+ identity: Record<string, unknown>
814
+ systems: SystemFile[]
815
+ definitions: DefinitionFile[]
816
+ /** Where the cognet's Rust systems' module sits, relative to the bundle; null when it has none. */
817
+ native: string | null
818
+ python: { systems: PythonSystem[]; executable: string } | null
819
+ sourceDir: string
820
+ }): string[] {
821
+ const hasSystems = opts.systems.length > 0 || opts.native !== null || opts.python !== null
822
+
823
+ // One namespace import per file, shared when a system file also defines.
824
+ const namespaces = new Map<string, string>()
825
+ for (const file of [...opts.definitions, ...opts.systems]) {
826
+ if (!namespaces.has(file.absPath)) namespaces.set(file.absPath, `__m${namespaces.size}`)
658
827
  }
659
- return names
660
- .filter(n => n.endsWith(".ts") && !n.endsWith(".d.ts") && !n.endsWith(".test.ts"))
661
- .sort()
662
- .map(n => join(dir, n))
828
+
829
+ const lines = [
830
+ `import { CognetHost${hasSystems ? ", Discovered" : ""}${opts.python ? ", Python" : ""} } from ${JSON.stringify(HOST_SPECIFIER)}`,
831
+ ...opts.plugins.map((p, i) => `import ${specifier(p)} // plugin ${i}`),
832
+ `import config from ${opts.configImport}`,
833
+ ...[...namespaces].map(([path, name]) => `import * as ${name} from ${specifier(path)}`),
834
+ `import main from "./main.ts"`,
835
+ // Loaded beside the bundle, relative to it — on the main thread and in every worker the bundle becomes.
836
+ ...(opts.native ? [`import { createRequire } from "node:module"`, `const native = createRequire(import.meta.url)(${JSON.stringify(opts.native)})`] : []),
837
+ ...(opts.python ? [
838
+ `import { fileURLToPath } from "node:url"`,
839
+ `const python = Python({ project: fileURLToPath(new URL("./python/", import.meta.url)), executable: ${JSON.stringify(opts.python.executable)}, systems: ${JSON.stringify(opts.python.systems)} })`,
840
+ `definePlugin(({ hooks }) => { hooks.on("shutdown", () => python.close()) })`,
841
+ ] : []),
842
+ ]
843
+
844
+ if (!hasSystems) {
845
+ return [...lines, `export default CognetHost({ ...config, ...${JSON.stringify(opts.identity)} }, main)`]
846
+ }
847
+
848
+ const named = naming(opts.sourceDir)
849
+ const definitions = opts.definitions.map(file =>
850
+ ` { file: ${JSON.stringify(file.named)}, module: ${namespaces.get(file.absPath)}, names: ${JSON.stringify(file.names)} },`)
851
+ const systems = opts.systems.map(file =>
852
+ ` { file: ${JSON.stringify(named(file.relPath))}, module: ${namespaces.get(file.absPath)} },`)
853
+
854
+ return [
855
+ ...lines,
856
+ "const discovered = Discovered({",
857
+ " definitions: [",
858
+ ...definitions,
859
+ " ],",
860
+ " systems: [",
861
+ ...systems,
862
+ " ],",
863
+ ...(opts.native ? [" native: native,"] : []),
864
+ ...(opts.python ? [" python: python,"] : []),
865
+ "})",
866
+ `export default CognetHost({ ...config, ...${JSON.stringify(opts.identity)}, systems: discovered.systems }, main)`,
867
+ ]
663
868
  }
@@ -59,16 +59,17 @@ export const INLINE_COGNET_DIR = "cognet"
59
59
  /**
60
60
  * The inline cognet's directory, if the agent has one.
61
61
  *
62
- * Recognized by its ENTRY, not by a config file: `cognet.config.ts` is
63
- * optional for an inline brain (identity comes from the agent — see
64
- * bundleCognet), so requiring it here would make the smallest possible
65
- * cognet, a lone `cognet/main.ts` holding a `loop()`, invisible to every
66
- * stage that asks this question.
62
+ * Recognized by a script OR a config: `cognet.config.ts` is optional for a
63
+ * brain with a script (the smallest possible cognet is a lone
64
+ * `cognet/main.ts` holding a `loop()`), and `main.ts` is optional for a brain
65
+ * made of systems — so either one marks the folder as a brain. A folder with
66
+ * neither is not claimed here; bundleCognet() is what refuses a brain with
67
+ * nothing to run.
67
68
  */
68
69
  export function inlineCognetDir(agentRoot: string): string | null {
69
70
  const dir = join(agentRoot, INLINE_COGNET_DIR)
70
- const hasEntry = fsx.isFile(join(dir, "main.ts")) || fsx.isFile(join(dir, "src", "main.ts"))
71
- return hasEntry ? dir : null
71
+ const marked = ["main.ts", join("src", "main.ts"), "cognet.config.ts"].some(file => fsx.isFile(join(dir, file)))
72
+ return marked ? dir : null
72
73
  }
73
74
 
74
75
  /**
@@ -0,0 +1,52 @@
1
+ import { existsSync, readFileSync } from "node:fs"
2
+ import { join } from "node:path"
3
+ import ts from "typescript"
4
+ import { err } from "@arcforge/err"
5
+ import type { CognetConfig } from "@arcforge/types"
6
+ import { Literal } from "./literal"
7
+ import { shape } from "./shape"
8
+
9
+ /**
10
+ * CognetConfigFile — a cognet's `cognet.config.ts`, read without running it.
11
+ *
12
+ * Read statically because it is needed before anything can run it: prepare
13
+ * checks the ABI, fetches what it suggests and grants what it uses before the
14
+ * cognet is compiled or its dependencies installed. So the file is parsed —
15
+ * `export default defineCognet({ … })` — and every value must be written out.
16
+ * One reader for every field: a field is read the same way everywhere, and a
17
+ * value that can't be known statically fails loudly rather than reading as
18
+ * absent.
19
+ */
20
+ export function CognetConfigFile(opts: { sourceDir: string }) {
21
+ const path = join(opts.sourceDir, "cognet.config.ts")
22
+
23
+ return {
24
+ path: path,
25
+ /** Whether the cognet has one. A cognet without one wakes on the defaults. */
26
+ exists(): boolean {
27
+ return existsSync(path)
28
+ },
29
+ /** The config, validated; null when the cognet has none. Throws COGNET_CONFIG_NOT_STATIC or COGNET_CONFIG_INVALID. */
30
+ read(): CognetConfig | null {
31
+ if (!existsSync(path)) return null
32
+ const source = ts.createSourceFile(path, readFileSync(path, "utf8"), ts.ScriptTarget.Latest, true)
33
+ return shape(Literal({ file: path, source: source }).read(declared(source, path), ""), path)
34
+ },
35
+ }
36
+ }
37
+
38
+ export type CognetConfigFileT = ReturnType<typeof CognetConfigFile>
39
+
40
+ /** The object handed to `defineCognet` in the default export. */
41
+ function declared(source: ts.SourceFile, path: string): ts.Expression {
42
+ const exported = source.statements.find(ts.isExportAssignment)
43
+ const call = exported && unwrap(exported.expression)
44
+ if (!call || !ts.isCallExpression(call) || !ts.isIdentifier(call.expression) || call.expression.text !== "defineCognet" || call.arguments.length !== 1) {
45
+ throw err("COGNET_CONFIG_INVALID", { detail: `${path}: the default export must be \`defineCognet({ … })\``, context: { file: path, field: "" } })
46
+ }
47
+ return call.arguments[0]!
48
+ }
49
+
50
+ function unwrap(node: ts.Expression): ts.Expression {
51
+ return ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node) ? unwrap(node.expression) : node
52
+ }
@@ -0,0 +1,4 @@
1
+ // config — the declaration files read statically: a cognet's cognet.config.ts, and the providers an agent writes.
2
+
3
+ export { CognetConfigFile, type CognetConfigFileT } from "./config"
4
+ export { ProviderFile } from "./provider"