@arcforge/platform 2.0.219 → 2.0.244

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
@@ -0,0 +1,83 @@
1
+ import ts from "typescript"
2
+ import { err } from "@arcforge/err"
3
+
4
+ /** A value written out in source: what a static config may hold. */
5
+ export type Literal = string | number | boolean | null | Literal[] | { [key: string]: Literal }
6
+
7
+ /**
8
+ * Literal — the value a TypeScript expression WRITES OUT, read without running
9
+ * it. Objects, arrays, strings, numbers (`100_000`, `-1`), booleans, `null`,
10
+ * and a top-level `const` holding one of those; `as const`, `satisfies` and
11
+ * parentheses are seen through. Anything else — a call, a spread, an import,
12
+ * a template with a substitution — throws COGNET_CONFIG_NOT_STATIC naming the
13
+ * field and the line, because a value that must be computed cannot be known
14
+ * before the code that computes it exists.
15
+ */
16
+ export function Literal(opts: { file: string; source: ts.SourceFile }) {
17
+ const consts = new Map<string, ts.Expression>()
18
+ for (const statement of opts.source.statements) {
19
+ if (!ts.isVariableStatement(statement) || !(statement.declarationList.flags & ts.NodeFlags.Const)) continue
20
+ for (const declaration of statement.declarationList.declarations) {
21
+ if (ts.isIdentifier(declaration.name) && declaration.initializer) consts.set(declaration.name.text, declaration.initializer)
22
+ }
23
+ }
24
+ const resolving = new Set<string>()
25
+
26
+ function read(node: ts.Expression, path: string): Literal {
27
+ if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node)) return read(node.expression, path)
28
+ if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text
29
+ if (ts.isNumericLiteral(node)) return Number(node.text)
30
+ if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.MinusToken && ts.isNumericLiteral(node.operand)) return -Number(node.operand.text)
31
+ if (node.kind === ts.SyntaxKind.TrueKeyword) return true
32
+ if (node.kind === ts.SyntaxKind.FalseKeyword) return false
33
+ if (node.kind === ts.SyntaxKind.NullKeyword) return null
34
+ if (ts.isArrayLiteralExpression(node)) return node.elements.map((element, index) => read(element, `${path}[${index}]`))
35
+ if (ts.isObjectLiteralExpression(node)) return object(node, path)
36
+ if (ts.isIdentifier(node)) return named(node, path)
37
+ return fail(node, path, `\`${node.getText(opts.source)}\``)
38
+ }
39
+
40
+ function object(node: ts.ObjectLiteralExpression, path: string): { [key: string]: Literal } {
41
+ const value: { [key: string]: Literal } = {}
42
+ for (const property of node.properties) {
43
+ if (ts.isShorthandPropertyAssignment(property)) {
44
+ value[property.name.text] = named(property.name, join(path, property.name.text))
45
+ continue
46
+ }
47
+ if (!ts.isPropertyAssignment(property)) return fail(property, path, `\`${property.getText(opts.source)}\``)
48
+ const key = ts.isIdentifier(property.name) || ts.isStringLiteral(property.name) || ts.isNumericLiteral(property.name)
49
+ ? property.name.text
50
+ : fail(property.name, path, `the computed key \`${property.name.getText(opts.source)}\``)
51
+ value[key] = read(property.initializer, join(path, key))
52
+ }
53
+ return value
54
+ }
55
+
56
+ function named(node: ts.Identifier, path: string): Literal {
57
+ if (node.text === "undefined") return fail(node, path, "`undefined` — leave the field out instead")
58
+ const initializer = consts.get(node.text)
59
+ if (!initializer) return fail(node, path, `\`${node.text}\`, which is not a top-level const of this file`)
60
+ if (resolving.has(node.text)) return fail(node, path, `\`${node.text}\`, which refers to itself`)
61
+ resolving.add(node.text)
62
+ const value = read(initializer, path)
63
+ resolving.delete(node.text)
64
+ return value
65
+ }
66
+
67
+ function fail(node: ts.Node, path: string, what: string): never {
68
+ const line = opts.source.getLineAndCharacterOfPosition(node.getStart(opts.source)).line + 1
69
+ throw err("COGNET_CONFIG_NOT_STATIC", {
70
+ detail: `${opts.file}:${line}: \`${path || "the config"}\` is ${what} — write the value out`,
71
+ context: { file: opts.file, line: line, field: path },
72
+ })
73
+ }
74
+
75
+ return {
76
+ /** The value `node` writes out, named `path` in errors. */
77
+ read: read,
78
+ }
79
+ }
80
+
81
+ function join(path: string, key: string): string {
82
+ return path ? `${path}.${key}` : key
83
+ }
@@ -0,0 +1,43 @@
1
+ import { readFileSync } from "node:fs"
2
+ import ts from "typescript"
3
+ import { err } from "@arcforge/err"
4
+ import type { EngineRequirements } from "@arcforge/types"
5
+ import { Literal } from "./literal"
6
+ import { engines } from "./shape"
7
+
8
+ /**
9
+ * ProviderFile — what a provider the agent wrote declares, read without
10
+ * running it: the interface it implements, and the engines it needs from the
11
+ * machine. Static for the reason cognet.config.ts is, and one more: a
12
+ * confined agent's supervisor resolves those engines, and must never run the
13
+ * agent's code outside its box to learn what they are.
14
+ */
15
+ export function ProviderFile(opts: { filePath: string }) {
16
+ return {
17
+ read(): { implements: string; engines: EngineRequirements } {
18
+ const source = ts.createSourceFile(opts.filePath, readFileSync(opts.filePath, "utf8"), ts.ScriptTarget.Latest, true)
19
+ const declared = definition(source, opts.filePath)
20
+ const literal = Literal({ file: opts.filePath, source: source })
21
+ const field = (name: string) => declared.properties.find(property => ts.isPropertyAssignment(property) && ts.isIdentifier(property.name) && property.name.text === name) as ts.PropertyAssignment | undefined
22
+ const implemented = field("implements")
23
+ const named = implemented ? literal.read(implemented.initializer, "implements") : undefined
24
+ if (typeof named !== "string") throw invalid(opts.filePath, "defineProvider({ implements: \"<interface>@<major>\", … }) — written out")
25
+ const needs = field("engines")
26
+ return { implements: named, engines: needs ? engines(literal.read(needs.initializer, "engines"), opts.filePath) : {} }
27
+ },
28
+ }
29
+ }
30
+
31
+ /** The object handed to `defineProvider` in the default export. */
32
+ function definition(source: ts.SourceFile, path: string): ts.ObjectLiteralExpression {
33
+ const exported = source.statements.find(ts.isExportAssignment)
34
+ let call = exported?.expression
35
+ while (call && (ts.isParenthesizedExpression(call) || ts.isAsExpression(call) || ts.isSatisfiesExpression(call))) call = call.expression
36
+ const argument = call && ts.isCallExpression(call) && ts.isIdentifier(call.expression) && call.expression.text === "defineProvider" ? call.arguments[0] : undefined
37
+ if (!argument || !ts.isObjectLiteralExpression(argument)) throw invalid(path, "the default export must be defineProvider({ … })")
38
+ return argument
39
+ }
40
+
41
+ function invalid(path: string, must: string) {
42
+ return err("SERVICE_INVALID", { detail: `${path}: ${must}`, context: { provider: path } })
43
+ }
@@ -0,0 +1,183 @@
1
+ import { err } from "@arcforge/err"
2
+ import type { CognetConfig, EngineRequirement, Modality, ModelRef, ServiceRequirement, ServiceUse } from "@arcforge/types"
3
+ import type { Literal } from "./literal"
4
+
5
+ type Field<K extends keyof CognetConfig> = (value: Literal, path: string) => NonNullable<CognetConfig[K]>
6
+
7
+ /**
8
+ * Every field a cognet config may hold, and the shape its value must have.
9
+ * One table: a field is valid because it is here, and a field not here is a
10
+ * mistake — a typo, or a field that moved — never something to skip.
11
+ */
12
+ const FIELDS: { [K in keyof Required<CognetConfig>]: Field<K> } = {
13
+ abi: (value, path) => is.string(value, path),
14
+ mode: (value, path) => {
15
+ const mode = is.object(value, path)
16
+ if (mode.kind === "invocation") return { kind: "invocation" }
17
+ if (mode.kind === "continuous") return { kind: "continuous", hz: is.positive(mode.hz, `${path}.hz`) }
18
+ return wrong(`${path}.kind`, `"continuous" or "invocation"`)
19
+ },
20
+ wakeOn: (value, path) => is.array(value, path).map((one, i) => is.string(one, `${path}[${i}]`)) as CognetConfig["wakeOn"] & {},
21
+ stimuli: (value, path) => is.object(value, path) as CognetConfig["stimuli"] & {},
22
+ maxTicksPerWake: (value, path) => is.positive(value, path),
23
+ threads: (value, path) => value === "auto" ? "auto" : is.count(value, path),
24
+ engines: (value, path) => record(value, path, (one, at) => engine(one, at)),
25
+ models: (value, path) => record(value, path, (one, at) => model(one, at)),
26
+ uses: (value, path) => record(value, path, (one, at) => use(one, at)),
27
+ suggests: (value, path) => record(value, path, (one, at) => is.string(one, at)),
28
+ }
29
+
30
+ /** `value`, read from `file`, as a CognetConfig — or COGNET_CONFIG_INVALID naming the first field that isn't. */
31
+ export function shape(value: Literal, file: string): CognetConfig {
32
+ try {
33
+ return fields(value)
34
+ } catch (error) {
35
+ if (!(error instanceof Invalid)) throw error
36
+ throw err("COGNET_CONFIG_INVALID", { detail: `${file}: \`${error.path || "the config"}\` must be ${error.must}`, context: { file: file, field: error.path } })
37
+ }
38
+ }
39
+
40
+ function fields(value: Literal): CognetConfig {
41
+ const fields = is.object(value, "")
42
+ const config: Record<string, unknown> = {}
43
+ for (const [key, field] of Object.entries(fields)) {
44
+ if (!(key in FIELDS)) wrong(key, `a field of cognet.config.ts — it has ${Object.keys(FIELDS).join(", ")}`)
45
+ config[key] = FIELDS[key as keyof CognetConfig](field, key)
46
+ }
47
+ if (!("mode" in config)) wrong("mode", "present — every cognet says how it wakes")
48
+ const primaries = [
49
+ ...Object.entries((config.engines ?? {}) as Record<string, EngineRequirement>).filter(([, one]) => one.primary).map(([name]) => `engines.${name}`),
50
+ ...Object.entries((config.uses ?? {}) as Record<string, ServiceUse>).filter(([, one]) => one.primary).map(([name]) => `uses.${name}`),
51
+ ]
52
+ if (primaries.length > 1) wrong(primaries[1]!, `the only primary — ${primaries[0]} already is; the user's model picker changes one`)
53
+ for (const name of Object.keys(config.suggests ?? {})) {
54
+ if (!(config.uses as Record<string, unknown> | undefined)?.[name]) wrong(`suggests.${name}`, "a use declared in `uses`")
55
+ }
56
+ return config as CognetConfig
57
+ }
58
+
59
+ function use(value: Literal, path: string): ServiceUse {
60
+ const declared = is.object(value, path)
61
+ const allowed = ["interface", "optional", "requires", "model", "primary", "parallel"]
62
+ for (const key of Object.keys(declared)) {
63
+ if (!allowed.includes(key)) wrong(`${path}.${key}`, `one of ${allowed.join(", ")}`)
64
+ }
65
+ const interfaceName = is.string(declared.interface, `${path}.interface`)
66
+ if (!/^(\.\/interfaces\/|@[\w-]+\/[\w-]+\/)?[a-z][\w-]*@\d+$/.test(interfaceName)) {
67
+ wrong(`${path}.interface`, "an interface and its major version — `depth-metric@1`, or `./interfaces/scene@1`")
68
+ }
69
+ return {
70
+ interface: interfaceName,
71
+ ...(declared.optional !== undefined ? { optional: is.boolean(declared.optional, `${path}.optional`) } : {}),
72
+ ...(declared.requires !== undefined ? { requires: record(declared.requires, `${path}.requires`, requirement) } : {}),
73
+ ...(declared.model !== undefined ? { model: models(declared.model, `${path}.model`) } : {}),
74
+ ...(declared.primary !== undefined ? { primary: is.boolean(declared.primary, `${path}.primary`) } : {}),
75
+ ...(declared.parallel !== undefined ? { parallel: is.whole(declared.parallel, `${path}.parallel`) } : {}),
76
+ }
77
+ }
78
+
79
+ /** A model by the registry's id, or candidates in order. An id names a model, never a route: `anthropic/claude-haiku-4.5`, not `axon:…`. */
80
+ function models(value: Literal, path: string): string | string[] {
81
+ const ids = typeof value === "string" ? [value] : is.array(value, path).map((one, i) => is.string(one, `${path}[${i}]`))
82
+ if (ids.length === 0) wrong(path, "a model id, or a list of them")
83
+ ids.forEach((id, i) => {
84
+ const at = typeof value === "string" ? path : `${path}[${i}]`
85
+ if (id.trim() !== id || id === "") wrong(at, "a model id, with no spaces around it")
86
+ if (ids.indexOf(id) !== i) wrong(at, `named once — ${id} is already in the list`)
87
+ })
88
+ return typeof value === "string" ? ids[0]! : ids
89
+ }
90
+
91
+ function requirement(value: Literal, path: string): ServiceRequirement {
92
+ if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value
93
+ const bound = is.object(value, path)
94
+ if ("includes" in bound) {
95
+ if (Object.keys(bound).length !== 1) wrong(path, "`{ includes }` alone")
96
+ return { includes: is.array(bound.includes, `${path}.includes`).map((one, i) => typeof one === "string" ? one : is.number(one, `${path}.includes[${i}]`)) }
97
+ }
98
+ const keys = Object.keys(bound)
99
+ if (keys.length === 0 || keys.some(key => key !== "min" && key !== "max")) wrong(path, "a value, `{ min, max }`, or `{ includes }`")
100
+ return {
101
+ ...(bound.min !== undefined ? { min: is.number(bound.min, `${path}.min`) } : {}),
102
+ ...(bound.max !== undefined ? { max: is.number(bound.max, `${path}.max`) } : {}),
103
+ }
104
+ }
105
+
106
+ /** A provider's `engines:`, read from `file` — or SERVICE_INVALID naming the first field that is not an engine requirement. */
107
+ export function engines(value: Literal, file: string): Record<string, EngineRequirement> {
108
+ try {
109
+ return record(value, "engines", engine)
110
+ } catch (error) {
111
+ if (!(error instanceof Invalid)) throw error
112
+ throw err("SERVICE_INVALID", { detail: `${file}: \`${error.path}\` must be ${error.must}`, context: { provider: file } })
113
+ }
114
+ }
115
+
116
+ function engine(value: Literal, path: string): EngineRequirement {
117
+ const declared = is.object(value, path)
118
+ if (!["generate", "transform", "stream"].includes(declared.type as string)) wrong(`${path}.type`, `"generate", "transform" or "stream"`)
119
+ const modalities = (one: Literal | undefined, at: string): Modality[] => {
120
+ const list = typeof one === "string" ? [one] : is.array(one, at).map((each, i) => is.string(each, `${at}[${i}]`))
121
+ if (list.length === 0) wrong(at, "a modality, or a list of them")
122
+ return list as Modality[]
123
+ }
124
+ const prefer = declared.prefer === undefined ? undefined : is.object(declared.prefer, `${path}.prefer`)
125
+ return {
126
+ ...(declared as object),
127
+ type: declared.type as EngineRequirement["type"],
128
+ in: modalities(declared.in, `${path}.in`),
129
+ out: modalities(declared.out, `${path}.out`),
130
+ ...(prefer ? { prefer: {
131
+ ...(prefer.in !== undefined ? { in: modalities(prefer.in, `${path}.prefer.in`) } : {}),
132
+ ...(prefer.out !== undefined ? { out: modalities(prefer.out, `${path}.prefer.out`) } : {}),
133
+ } } : {}),
134
+ }
135
+ }
136
+
137
+ function model(value: Literal, path: string): ModelRef {
138
+ if (typeof value === "string") return value
139
+ const declared = is.object(value, path)
140
+ is.string(declared.hf, `${path}.hf`)
141
+ return declared as ModelRef
142
+ }
143
+
144
+ function record<T>(value: Literal, path: string, each: (value: Literal, path: string) => T): Record<string, T> {
145
+ return Object.fromEntries(Object.entries(is.object(value, path)).map(([key, one]) => [key, each(one, `${path}.${key}`)]))
146
+ }
147
+
148
+ const is = {
149
+ object(value: Literal | undefined, path: string): { [key: string]: Literal } {
150
+ if (value === null || typeof value !== "object" || Array.isArray(value)) return wrong(path, "an object")
151
+ return value
152
+ },
153
+ array(value: Literal | undefined, path: string): Literal[] {
154
+ return Array.isArray(value) ? value : wrong(path, "a list")
155
+ },
156
+ string(value: Literal | undefined, path: string): string {
157
+ return typeof value === "string" ? value : wrong(path, "a string")
158
+ },
159
+ boolean(value: Literal | undefined, path: string): boolean {
160
+ return typeof value === "boolean" ? value : wrong(path, "true or false")
161
+ },
162
+ number(value: Literal | undefined, path: string): number {
163
+ return typeof value === "number" ? value : wrong(path, "a number")
164
+ },
165
+ positive(value: Literal | undefined, path: string): number {
166
+ return typeof value === "number" && value > 0 ? value : wrong(path, "a number above 0")
167
+ },
168
+ whole(value: Literal | undefined, path: string): number {
169
+ return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : wrong(path, "a whole number above 0")
170
+ },
171
+ count(value: Literal | undefined, path: string): number {
172
+ return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : wrong(path, `"auto", or a whole number`)
173
+ },
174
+ }
175
+
176
+ /** A field of the wrong shape: where, and what it must be. Becomes COGNET_CONFIG_INVALID, with the file, in `shape`. */
177
+ class Invalid {
178
+ constructor(readonly path: string, readonly must: string) {}
179
+ }
180
+
181
+ function wrong(path: string, must: string): never {
182
+ throw new Invalid(path, must)
183
+ }
@@ -2,9 +2,11 @@
2
2
  // Cognet() is the module's single entry point.
3
3
 
4
4
  export { Cognet, cognetSourceOf, inlineCognetDir, INLINE_COGNET_DIR, type CognetT, type CognetSource } from "./cognet"
5
- export type { CognetArtifact } from "./bundle"
5
+ export { SCHEMA_DIR, SCHEMA_SPECIFIER, type CognetArtifact } from "./bundle"
6
+ export { contractOf } from "./schema"
6
7
  export { DEFAULT_COGNET, cognetName } from "./resolve"
7
8
 
8
9
  // The ABI gate. prepare() compares a cognet against this kernel; publish
9
10
  // records the declared value on the version row without comparing.
10
- export { cognetAbi, readCognetAbi, readCognetModels, readCognetEngines } from "./abi"
11
+ export { cognetAbi } from "./abi"
12
+ export { CognetConfigFile, ProviderFile, type CognetConfigFileT } from "./config"
@@ -0,0 +1,31 @@
1
+ import { err } from "@arcforge/err"
2
+ import type { RustSource } from "./crate"
3
+
4
+ /** Running cargo — private to Crate. */
5
+ export const cargo = {
6
+ /** A release build of the workspace, into `target`. Shows the first compiler error or names a missing cargo. */
7
+ async build(manifestPath: string, target: string, sources: readonly RustSource[]): Promise<void> {
8
+ const spawned = (() => {
9
+ try {
10
+ return Bun.spawn(["cargo", "build", "--release", "--manifest-path", manifestPath], { env: { ...process.env, CARGO_TARGET_DIR: target }, stdout: "pipe", stderr: "pipe" })
11
+ } catch (cause) {
12
+ const systems = sources.flatMap(source => (source.system ? [source.system] : []))
13
+ throw err("COGNET_NATIVE_FAILED", { detail: `this cognet has Rust systems (${systems.join(", ")}) and cargo could not be run — install Rust (rustup.rs) and prepare again`, cause: cause })
14
+ }
15
+ })()
16
+ const [stderr, stdout, exitCode] = await Promise.all([new Response(spawned.stderr).text(), new Response(spawned.stdout).text(), spawned.exited])
17
+ if (exitCode !== 0) {
18
+ throw err("COGNET_NATIVE_FAILED", { detail: cargo.diagnostic(stderr || stdout, exitCode) })
19
+ }
20
+ },
21
+
22
+ diagnostic(output: string, exitCode: number): string {
23
+ const lines = output.trim().split("\n")
24
+ const errors = lines.flatMap((line, at) => /^error(?:\[[^\]]+\])?:/.test(line) ? [at] : [])
25
+ const first = errors.length > 0 ? lines.slice(errors[0], errors[1] ?? lines.length) : lines
26
+ const shown = first.slice(0, 80).join("\n").trim()
27
+ const rest = errors.length > 1 ? `\n${errors.length - 1} further Cargo errors; fix the first and prepare again.` : ""
28
+ const clipped = first.length > 80 ? `\n... ${first.length - 80} more lines in this diagnostic` : ""
29
+ return shown ? `${shown}${clipped}${rest}` : `cargo exited with code ${exitCode} and no diagnostic output`
30
+ },
31
+ }
@@ -0,0 +1,126 @@
1
+ import { createHash } from "node:crypto"
2
+ import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs"
3
+ import { dirname, join } from "node:path"
4
+ import { err } from "@arcforge/err"
5
+ import { fsx } from "../../../../utils/fs"
6
+ import { writeIfChanged } from "../../../project/typegen/write"
7
+ import { rust } from "../schema"
8
+ import { cargo } from "./cargo"
9
+ import { library } from "./library"
10
+ import { manifest } from "./manifest"
11
+
12
+ export type CrateOpts = {
13
+ /** The cognet's source directory. */
14
+ sourceDir: string
15
+ /** The agent compiling it: whose installed `@arcforge/cognet` the Rust runtime comes from. */
16
+ agentRoot: string
17
+ /** The agent frame's `cognet/native/`: the generated crate, its build, and the module it makes. */
18
+ out: string
19
+ /** Whether the cognet's source is its own — an installed cognet's `Cargo.lock` is read, never written back. */
20
+ owned: boolean
21
+ }
22
+
23
+ /** One `.rs` file of the cognet: where it is, the module path it is mounted at, and — for a `*.system.rs` — the name it runs as. */
24
+ export type RustSource = { absPath: string; module: string[]; system: string | null }
25
+
26
+ /** Directories no source lives under: installed code and build output. */
27
+ const SKIP_DIRS = ["node_modules", ".git", ".cognet", ".agent", "target"]
28
+
29
+ /** Where, beside the bundle, the module sits — named for its content, which the generated entry loads relative to itself. */
30
+ export const NATIVE_DIR = "native"
31
+
32
+ /**
33
+ * Crate — a cognet's Rust compiled into one native module.
34
+ *
35
+ * A cognet's Rust is written beside its TypeScript. The author's Cargo package
36
+ * points at a generated library in the agent's frame, which mounts
37
+ * every `.rs` file at the path it sits at, as the TypeScript is imported —
38
+ * `lib/align/align.rs` is `crate::lib::align::align`, a sibling is `super::x`
39
+ * — with the schemas' Rust (`schema.rs`, written by `Schema`) at
40
+ * `crate::schema`, and the `[dependencies]` in the cognet's own `Cargo.toml`
41
+ * lists. `cargo` builds it into a `.node` the generated entry loads — on the
42
+ * main thread and in every worker — and `Discovered` makes each
43
+ * `*.system.rs` an ordinary system. A cognet that lists crates keeps its
44
+ * `Cargo.lock` beside its `Cargo.toml`, as `bun.lock` is.
45
+ */
46
+ export function Crate(opts: CrateOpts) {
47
+ const project = opts.out
48
+ const workspace = join(project, "Cargo.toml")
49
+ return {
50
+ /** Every `.rs` file of the cognet, mounted by its path. None when it has none. */
51
+ async sources(): Promise<RustSource[]> {
52
+ const walked = await fsx.walk(opts.sourceDir, { skipDirs: SKIP_DIRS })
53
+ const named = naming(opts.sourceDir)
54
+ // A `*.components.rs` is a schema the build reads, never Rust it compiles: its types are generated at `crate::schema`.
55
+ return walked.filter(file => file.relPath.endsWith(".rs") && !file.relPath.endsWith(".components.rs")).map(file => {
56
+ const path = named(file.relPath).slice(0, -".rs".length)
57
+ const module = path.split("/").map(rust.segment)
58
+ if (module[0] === "schema") throw err("COGNET_NATIVE_FAILED", { detail: `${file.relPath}: nothing at a cognet's top level can be called schema — that is where its schemas' Rust is mounted` })
59
+ return { absPath: file.absPath, module: module, system: path.endsWith(".system") ? path.slice(0, -".system".length) : null }
60
+ })
61
+ },
62
+
63
+ /**
64
+ * The module built from `sources`, named for its content
65
+ * (`<hash>.node`) — so a process that loads a rebuilt one gets the new
66
+ * code, where the same path would hand back the library already
67
+ * loaded — and every other module beside it removed. The schemas'
68
+ * Rust already at `src/schema.rs`. Throws `cargo`'s own words when it
69
+ * cannot be built, and names `cargo` when it is not installed.
70
+ */
71
+ async build(sources: readonly RustSource[]): Promise<string> {
72
+ const own = join(opts.sourceDir, "Cargo.toml")
73
+ const runtime = join(dirname(Bun.resolveSync("@arcforge/cognet/rust/Cargo.toml", opts.agentRoot)), "cognet")
74
+ if (opts.owned && !existsSync(own)) writeIfChanged(own, manifest.source(opts.sourceDir, opts.agentRoot, opts.out))
75
+ if (opts.owned) {
76
+ const config = join(opts.sourceDir, ".cargo", "config.toml")
77
+ if (!existsSync(config)) {
78
+ mkdirSync(dirname(config), { recursive: true })
79
+ writeIfChanged(config, manifest.config(opts.sourceDir, opts.out))
80
+ }
81
+ }
82
+ mkdirSync(join(project, "systems", "src"), { recursive: true })
83
+ mkdirSync(join(project, "module", "src"), { recursive: true })
84
+ for (const source of sources) mkdirSync(join(project, "systems", "src", ...source.module.slice(0, -1)), { recursive: true })
85
+ const dependencies = manifest.dependencies(own, runtime, opts.owned)
86
+ writeIfChanged(workspace, manifest.workspace(opts.owned))
87
+ if (!opts.owned) writeIfChanged(join(project, "systems", "Cargo.toml"), manifest.systems(dependencies.text))
88
+ writeIfChanged(join(project, "systems", "src", "lib.rs"), library.systems(sources, join(project, "systems", "src")))
89
+ writeIfChanged(join(project, "module", "Cargo.toml"), manifest.module(dependencies.runtime, opts.owned ? opts.sourceDir : null))
90
+ writeIfChanged(join(project, "module", "build.rs"), "fn main() {\n napi_build::setup();\n}\n")
91
+ writeIfChanged(join(project, "module", "src", "lib.rs"), library.module())
92
+ const lock = join(opts.sourceDir, "Cargo.lock")
93
+ if (!opts.owned && existsSync(lock)) copyFileSync(lock, join(project, "Cargo.lock"))
94
+
95
+ const target = join(opts.out, "target")
96
+ await cargo.build(workspace, target, sources)
97
+
98
+ const built = join(target, "release", process.platform === "darwin" ? "libcognet_native.dylib" : "libcognet_native.so")
99
+ if (!existsSync(built)) throw err("COGNET_NATIVE_FAILED", { detail: `cargo succeeded but left no ${built}` })
100
+ const name = `${createHash("sha256").update(readFileSync(built)).digest("hex").slice(0, 16)}.node`
101
+ mkdirSync(opts.out, { recursive: true })
102
+ const module = join(opts.out, name)
103
+ if (!existsSync(module)) copyFileSync(built, module)
104
+ for (const old of readdirSync(opts.out).filter(entry => entry.endsWith(".node") && entry !== name)) rmSync(join(opts.out, old))
105
+ return module
106
+ },
107
+
108
+ /** Where the schemas' Rust goes: the systems crate's `schema` module. */
109
+ schema(): string {
110
+ return join(project, "systems", "src", "schema.rs")
111
+ },
112
+
113
+ /** The crate and its module gone: a cognet with no Rust systems carries neither. */
114
+ clear(): void {
115
+ rmSync(opts.out, { recursive: true, force: true })
116
+ },
117
+ }
118
+ }
119
+
120
+ export type CrateT = ReturnType<typeof Crate>
121
+
122
+ /** The path a file is named by: under `src/` when the cognet keeps its code there, as components and systems are named. */
123
+ function naming(sourceDir: string): (relPath: string) => string {
124
+ const nested = existsSync(join(sourceDir, "src"))
125
+ return relPath => (nested && relPath.startsWith("src/") ? relPath.slice("src/".length) : relPath)
126
+ }
@@ -0,0 +1,2 @@
1
+ // native — a cognet's *.system.rs compiled into one module the bundle loads.
2
+ export { Crate, NATIVE_DIR, type CrateOpts, type CrateT } from "./crate"
@@ -0,0 +1,125 @@
1
+ import type { RustSource } from "./crate"
2
+ import { join, relative } from "node:path"
3
+
4
+ /**
5
+ * The generated crates' `lib.rs` — private to Crate. Two crates, because a
6
+ * napi module cannot be tested: its test binary would need napi's symbols,
7
+ * which only a JavaScript host has. So the systems and the schemas' types are
8
+ * plain Rust (`cognet_systems`, which `cargo test` runs), and the module the
9
+ * bundle loads (`cognet_native`) is only the boundary.
10
+ */
11
+ export const library = {
12
+ /** The schemas, every file mounted at its path, and the list of systems the module serves. */
13
+ systems(sources: readonly RustSource[], root: string): string {
14
+ const tree: Mount = { files: [], folders: new Map() }
15
+ for (const source of sources) {
16
+ let node = tree
17
+ for (const folder of source.module.slice(0, -1)) {
18
+ const next = node.folders.get(folder) ?? { files: [], folders: new Map() }
19
+ node.folders.set(folder, next)
20
+ node = next
21
+ }
22
+ node.files.push({ name: source.module.at(-1)!, absPath: source.absPath })
23
+ }
24
+ const systems = sources.flatMap(source => (source.system ? [{ name: source.system, path: source.module.join("::") }] : []))
25
+ return [
26
+ "// Generated by axon prepare — this cognet's Rust, mounted at the paths it sits at, and the types its schemas declare. Edit those, not this file.",
27
+ "#![allow(non_snake_case, dead_code)]",
28
+ "",
29
+ "/// The types and handles generated from the cognet's schemas.",
30
+ "pub mod schema;",
31
+ "",
32
+ ...library.mount(tree, "", root, []),
33
+ "",
34
+ "/// Every system, by the name it runs as.",
35
+ "pub const SYSTEMS: &[cognet::Served] = &[",
36
+ ...systems.map(system => ` cognet::Served { name: ${JSON.stringify(system.name)}, declare: ${system.path}::__cognet_declare, body: ${system.path}::__COGNET_BODY },`),
37
+ "];",
38
+ "",
39
+ ].join("\n")
40
+ },
41
+
42
+ /** One folder's files, each from where it sits (`#[path]`), and its folders as modules around theirs. */
43
+ mount(node: Mount, indent: string, root: string, folders: string[]): string[] {
44
+ const items = [
45
+ ...node.files.map(file => [`${indent}#[path = ${JSON.stringify(relative(join(root, ...folders), file.absPath))}]`, `${indent}pub mod ${file.name};`]),
46
+ ...[...node.folders].map(([name, folder]) => [`${indent}pub mod ${name} {`, ...library.mount(folder, `${indent} `, root, [...folders, name]), `${indent}}`]),
47
+ ]
48
+ return items.flatMap((item, at) => (at === 0 ? item : ["", ...item]))
49
+ },
50
+
51
+ /** The two functions the runtime calls. */
52
+ module(): string {
53
+ return [
54
+ "// Generated by axon prepare — the boundary the runtime calls this cognet's Rust systems through.",
55
+ "use napi::bindgen_prelude::*;",
56
+ "use napi::Either;",
57
+ "use napi_derive::napi;",
58
+ "",
59
+ "/// The run protocol this module was built against — checked by the runtime before anything runs.",
60
+ "#[napi]",
61
+ "pub fn protocol() -> u32 {",
62
+ " cognet::PROTOCOL",
63
+ "}",
64
+ "",
65
+ "/// How this module speaks to the runtime while an async system is going — set by `listen`.",
66
+ "static OUT: std::sync::Mutex<Option<cognet::Out>> = std::sync::Mutex::new(None);",
67
+ "",
68
+ "/// The runtime's ear: every message an async run says goes here. Weak, so it never holds the process open;",
69
+ "/// set again when a brain is loaded again in the same process.",
70
+ "#[napi]",
71
+ "pub fn listen(callback: napi::threadsafe_function::ThreadsafeFunction<String, Unknown<'static>, String, Status, false, true>) -> Result<()> {",
72
+ " let out: cognet::Out = std::sync::Arc::new(move |text: String| {",
73
+ " callback.call(text, napi::threadsafe_function::ThreadsafeFunctionCallMode::NonBlocking);",
74
+ " });",
75
+ " *OUT.lock().map_err(|_| Error::from_reason(\"the module's ear was poisoned\"))? = Some(out);",
76
+ " Ok(())",
77
+ "}",
78
+ "",
79
+ "/// What the runtime tells an async run: a job, an answer, a cancel.",
80
+ "#[napi]",
81
+ "pub fn tell(text: String) -> Result<()> {",
82
+ " let out = OUT.lock().map_err(|_| Error::from_reason(\"the module's ear was poisoned\"))?.clone().ok_or_else(|| Error::from_reason(\"told before anyone listened\"))?;",
83
+ " cognet::tell(cognet_systems::SYSTEMS, &text, out).map_err(|fault| Error::from_reason(fault.message().to_string()))",
84
+ "}",
85
+ "",
86
+ "/// Every system this module holds, and its declaration.",
87
+ "#[napi]",
88
+ "pub fn declarations(env: &Env) -> Result<Unknown<'_>> {",
89
+ " env.to_js_value(&cognet::declarations(cognet_systems::SYSTEMS))",
90
+ "}",
91
+ "",
92
+ "/// What a run did: `{ changes, effects }` as JSON, and the typed arrays they mark.",
93
+ "#[napi(object)]",
94
+ "pub struct Ran {",
95
+ " pub ran: String,",
96
+ " pub arrays: Vec<Either5<Float64Array, Float32Array, Int32Array, Uint32Array, Uint8Array>>,",
97
+ "}",
98
+ "",
99
+ "/// One run of the system named `name`: handed its snapshot as JSON and the bytes of every typed array it marks, by kind.",
100
+ "#[napi]",
101
+ "pub fn run(name: String, snapshot: String, kinds: Vec<String>, arrays: Vec<Uint8Array>) -> Result<Ran> {",
102
+ " let fail = |fault: cognet::Fault| Error::from_reason(fault.message().to_string());",
103
+ " if kinds.len() != arrays.len() {",
104
+ " return Err(Error::from_reason(format!(\"{} kinds for {} arrays\", kinds.len(), arrays.len())));",
105
+ " }",
106
+ " let blocks = kinds.iter().zip(arrays.iter()).map(|(kind, bytes)| cognet::Block::from_bytes(kind, bytes)).collect::<std::result::Result<Vec<_>, _>>().map_err(fail)?;",
107
+ " let snapshot = cognet::Snapshot::parse(&snapshot, blocks).map_err(fail)?;",
108
+ " let ran = cognet::serve(cognet_systems::SYSTEMS, &name, snapshot).map_err(fail)?;",
109
+ " let json = ran.json().map_err(fail)?;",
110
+ " let arrays = ran.blocks.into_iter().map(|block| match block {",
111
+ " cognet::Block::F64(values) => Either5::A(Float64Array::new(values)),",
112
+ " cognet::Block::F32(values) => Either5::B(Float32Array::new(values)),",
113
+ " cognet::Block::I32(values) => Either5::C(Int32Array::new(values)),",
114
+ " cognet::Block::U32(values) => Either5::D(Uint32Array::new(values)),",
115
+ " cognet::Block::U8(values) => Either5::E(Uint8Array::new(values)),",
116
+ " }).collect();",
117
+ " Ok(Ran { ran: json, arrays: arrays })",
118
+ "}",
119
+ "",
120
+ ].join("\n")
121
+ },
122
+ }
123
+
124
+ /** A folder of the cognet as the crate mounts it. */
125
+ type Mount = { files: Array<{ name: string; absPath: string }>; folders: Map<string, Mount> }