@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,316 @@
1
+ import { dirname } from "node:path"
2
+ import { getOption, ScalarType, type DescEnum, type DescExtension, type DescField, type DescFile, type DescMessage, type FileRegistry } from "@bufbuild/protobuf"
3
+ import { err } from "@arcforge/err"
4
+ import { arrayOf } from "./arrays"
5
+
6
+ /**
7
+ * Rust — every schema of a cognet as one Rust module, `schema`: messages as
8
+ * structs, enums as enums, unions as tagged enums, components as typed
9
+ * handles, frames as named handles — each with serde attributes that make its JSON exactly the
10
+ * TypeScript value's. Values cross from the TypeScript world to a Rust system
11
+ * as JSON, and every typed array beside it as memory (`cognet::Array`), so
12
+ * this agreement IS the contract: a field's JSON name, an enum's text, a
13
+ * union's tag, what may be absent and what may be null are the same on both
14
+ * sides. Plain functions, no I/O.
15
+ *
16
+ * Module paths follow the schemas' — `control/rhythm/rhythm.proto` is
17
+ * `schema::control::rhythm::rhythm` — made into Rust names (`L0-measure` →
18
+ * `l0_measure`, a keyword gets a trailing `_`); a component keeps its real
19
+ * name (`"sense/L0-measure/inertia"`) as a string.
20
+ */
21
+ export const rust = {
22
+ /** The `schema` module: every file's types and handles, nested by path. */
23
+ module(files: readonly DescFile[], registry: FileRegistry | null): string {
24
+ if (!registry || files.length === 0) return "// Generated by axon prepare — this cognet declares no schemas.\n"
25
+ const ctx: Ctx = { ext: Extensions(registry), registry: registry }
26
+ const tree: Tree = { children: new Map(), body: [] }
27
+ for (const file of [...files].sort((a, b) => (a.name < b.name ? -1 : 1))) {
28
+ let node = tree
29
+ for (const segment of file.name.split("/")) {
30
+ const name = names.module(segment)
31
+ const child = node.children.get(name) ?? { children: new Map(), body: [] }
32
+ node.children.set(name, child)
33
+ node = child
34
+ }
35
+ node.body.push(...emit.file(file, ctx))
36
+ }
37
+ return [`// Generated by axon prepare from this cognet's schemas — edit the schemas, not this file.`, "#![allow(dead_code, clippy::all)]", "", ...render(tree, "")].join("\n")
38
+ },
39
+
40
+ /** A path segment — a folder's or a file's name — as the Rust module it is: `L0-measure` → `l0_measure`, `rhythm.system` → `rhythm_system`. */
41
+ segment(name: string): string {
42
+ return names.module(name)
43
+ },
44
+ }
45
+
46
+ type Tree = { children: Map<string, Tree>; body: string[] }
47
+
48
+ function render(node: Tree, indent: string): string[] {
49
+ const lines = node.body.map(line => (line ? `${indent}${line}` : line))
50
+ for (const [name, child] of node.children) {
51
+ const uses = child.body.some(line => line.includes("Serialize")) ? [`${indent} use ::cognet::serde::{Deserialize, Serialize};`, ""] : []
52
+ lines.push(`${indent}pub mod ${name} {`, ...uses, ...render(child, `${indent} `), `${indent}}`, "")
53
+ }
54
+ return lines
55
+ }
56
+
57
+ type Ext = ReturnType<typeof Extensions>
58
+
59
+ /** What emitting needs beyond the element: the runtime's options, and every schema, to find what a field names. */
60
+ type Ctx = { ext: Ext; registry: FileRegistry }
61
+
62
+ /** The runtime's options, from the image the schemas were compiled with. */
63
+ function Extensions(registry: FileRegistry) {
64
+ const get = (name: string): DescExtension => {
65
+ const found = registry.getExtension(name)
66
+ if (!found) throw err("COGNET_SCHEMA_INVALID", { detail: `the runtime's schema defines no ${name} — the installed @arcforge/cognet is older than this platform` })
67
+ return found
68
+ }
69
+ return {
70
+ components: get("cognet.components"),
71
+ frames: get("cognet.frames"),
72
+ fixed: get("cognet.fixed"),
73
+ keys: get("cognet.keys"),
74
+ text: get("cognet.text"),
75
+ union: get("cognet.union"),
76
+ optional: get("cognet.optional"),
77
+ nullable: get("cognet.nullable"),
78
+ array: get("cognet.array"),
79
+ }
80
+ }
81
+
82
+ /** What each schema element becomes — private to the emitter. */
83
+ const emit = {
84
+ file(file: DescFile, ctx: Ctx): string[] {
85
+ const lines: string[] = []
86
+ for (const one of file.enums) lines.push(...emit.enumeration(one, ctx))
87
+ for (const one of file.messages) lines.push(...emit.message(one, ctx))
88
+ return lines
89
+ },
90
+
91
+ enumeration(desc: DescEnum, ctx: Ctx): string[] {
92
+ const ext = ctx.ext
93
+ const values = desc.values.filter(value => !(value.number === 0 && value.name.endsWith("_UNSPECIFIED")))
94
+ const variants = values.map(value => ({ text: option.string(value, ext.text) || names.text(value.name, desc.name), name: names.variant(value.name, desc.name) }))
95
+ return [
96
+ ...docs.of(desc),
97
+ "#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]",
98
+ `pub enum ${names.local(desc)} {`,
99
+ ...variants.flatMap(variant => [` #[serde(rename = ${JSON.stringify(variant.text)})]`, ` ${variant.name},`]),
100
+ "}",
101
+ "",
102
+ `impl ${names.local(desc)} {`,
103
+ " /// Every value, in the schema's order.",
104
+ ` pub const ALL: [Self; ${variants.length}] = [${variants.map(variant => `Self::${variant.name}`).join(", ")}];`,
105
+ "",
106
+ " /// Its text, as the TypeScript side says it.",
107
+ " pub fn text(self) -> &'static str {",
108
+ " match self {",
109
+ ...variants.map(variant => ` Self::${variant.name} => ${JSON.stringify(variant.text)},`),
110
+ " }",
111
+ " }",
112
+ "}",
113
+ "",
114
+ ]
115
+ },
116
+
117
+ message(desc: DescMessage, ctx: Ctx): string[] {
118
+ const ext = ctx.ext
119
+ const lines: string[] = []
120
+ for (const one of desc.nestedEnums) lines.push(...emit.enumeration(one, ctx))
121
+ for (const one of desc.nestedMessages) lines.push(...emit.message(one, ctx))
122
+ const folder = dirname(desc.file.name)
123
+ const full = (field: DescField) => (folder === "." ? field.jsonName : `${folder}/${field.jsonName}`)
124
+ if (option.boolean(desc, ext.frames)) {
125
+ for (const field of desc.fields) lines.push(...docs.of(field), `pub const ${names.constant(field.name)}: ::cognet::Frame = ::cognet::Frame::new(${JSON.stringify(full(field))});`, "")
126
+ return lines
127
+ }
128
+ if (option.boolean(desc, ext.components)) {
129
+ for (const field of desc.fields) lines.push(...docs.of(field), `pub const ${names.constant(field.name)}: ::cognet::Component<${types.of(field, ctx)}> = ::cognet::Component::new(${JSON.stringify(full(field))});`, "")
130
+ return lines
131
+ }
132
+ const tag = option.string(desc, ext.union)
133
+ if (tag) return [...lines, ...emit.union(desc, tag)]
134
+ const fields = desc.fields.flatMap(field => emit.field(field, ctx))
135
+ return [...lines, ...docs.of(desc), "#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]", `pub struct ${names.local(desc)} {`, ...fields, "}", ""]
136
+ },
137
+
138
+ /** A field, with the serde that makes its JSON the TypeScript value's: its JSON name; absent when optional; null when nullable. */
139
+ field(field: DescField, ctx: Ctx): string[] {
140
+ const ext = ctx.ext
141
+ const inner = types.of(field, ctx)
142
+ const absent = field.proto.proto3Optional || option.boolean(field, ext.optional)
143
+ const nullable = option.boolean(field, ext.nullable)
144
+ const attributes: string[] = []
145
+ // Named as its JSON is, whatever Rust calls it: `move` is `move_`, `relative_to` is `relativeTo`.
146
+ if (field.jsonName !== names.field(field.name)) attributes.push(`rename = ${JSON.stringify(field.jsonName)}`)
147
+ let type = inner
148
+ if (absent && nullable) {
149
+ type = `Option<Option<${inner}>>`
150
+ attributes.push(`default`, `skip_serializing_if = "Option::is_none"`, `with = "::cognet::absent_or_null"`)
151
+ } else if (absent) {
152
+ type = `Option<${inner}>`
153
+ attributes.push(`default`, `skip_serializing_if = "Option::is_none"`)
154
+ } else if (nullable) {
155
+ type = `Option<${inner}>`
156
+ }
157
+ return [...docs.of(field, " "), ...(attributes.length ? [` #[serde(${attributes.join(", ")})]`] : []), ` pub ${names.field(field.name)}: ${type},`]
158
+ },
159
+
160
+ /** A union: one variant a member, each the member's struct, tagged by `tag` as the TypeScript union is. */
161
+ union(desc: DescMessage, tag: string): string[] {
162
+ const oneof = desc.oneofs[0]
163
+ if (desc.oneofs.length !== 1 || !oneof || desc.fields.some(field => field.oneof !== oneof)) {
164
+ throw err("COGNET_SCHEMA_INVALID", { detail: `${desc.file.name}.proto, ${desc.name}: a union holds one oneof and nothing else` })
165
+ }
166
+ const variants = oneof.fields.map(field => {
167
+ if (field.fieldKind !== "message") throw err("COGNET_SCHEMA_INVALID", { detail: `${desc.file.name}.proto, ${desc.name}.${field.name}: a union's members are messages` })
168
+ return [` #[serde(rename = ${JSON.stringify(field.jsonName)})]`, ` ${names.type(field.jsonName)}(${types.path(field.message)}),`]
169
+ })
170
+ return [...docs.of(desc), "#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]", `#[serde(tag = ${JSON.stringify(tag)})]`, `pub enum ${names.local(desc)} {`, ...variants.flat(), "}", ""]
171
+ },
172
+ }
173
+
174
+ /** Field types in Rust — private to the emitter. */
175
+ const types = {
176
+ of(field: DescField, ctx: Ctx): string {
177
+ if (option.boolean(field, ctx.ext.array)) return `::cognet::Array<${arrayOf(field, option.number(field, ctx.ext.fixed)).rust}>`
178
+ switch (field.fieldKind) {
179
+ case "scalar":
180
+ return types.scalar(field.scalar, field)
181
+ case "enum":
182
+ return types.path(field.enum)
183
+ case "message":
184
+ return types.path(field.message)
185
+ case "list": {
186
+ const element = field.listKind === "scalar" ? types.scalar(field.scalar, field) : field.listKind === "enum" ? types.path(field.enum) : types.path(field.message)
187
+ const fixed = option.number(field, ctx.ext.fixed)
188
+ return fixed > 0 ? `[${element}; ${fixed}]` : `Vec<${element}>`
189
+ }
190
+ case "map": {
191
+ const value = field.mapKind === "scalar" ? types.scalar(field.scalar, field) : field.mapKind === "enum" ? types.path(field.enum) : types.path(field.message)
192
+ const keys = option.string(field, ctx.ext.keys)
193
+ if (keys) {
194
+ const found = ctx.registry.getEnum(keys) ?? ctx.registry.getEnum(`${field.parent.file.proto.package}.${keys}`)
195
+ if (!found) throw invalid(field, `its keys name the enum "${keys}", which no schema defines`)
196
+ return `::std::collections::BTreeMap<${types.path(found)}, ${value}>`
197
+ }
198
+ return `::std::collections::BTreeMap<${field.mapKey === ScalarType.STRING ? "String" : "i64"}, ${value}>`
199
+ }
200
+ }
201
+ },
202
+
203
+ /** A message or enum, by its path from the crate root — wherever it is used, it is the same path. */
204
+ path(desc: DescMessage | DescEnum): string {
205
+ return `crate::schema::${desc.file.name.split("/").map(names.module).join("::")}::${names.local(desc)}`
206
+ },
207
+
208
+ scalar(scalar: ScalarType, field: DescField): string {
209
+ switch (scalar) {
210
+ case ScalarType.DOUBLE:
211
+ return "f64"
212
+ case ScalarType.FLOAT:
213
+ return "f32"
214
+ case ScalarType.INT32:
215
+ case ScalarType.SINT32:
216
+ case ScalarType.SFIXED32:
217
+ return "i32"
218
+ case ScalarType.UINT32:
219
+ case ScalarType.FIXED32:
220
+ return "u32"
221
+ case ScalarType.BOOL:
222
+ return "bool"
223
+ case ScalarType.STRING:
224
+ return "String"
225
+ case ScalarType.BYTES:
226
+ return "::cognet::Array<u8>"
227
+ default:
228
+ throw invalid(field, "a 64-bit integer cannot cross as JSON — use double (envelope ms are doubles) or a 32-bit integer")
229
+ }
230
+ },
231
+ }
232
+
233
+ /** Options, read — private to the emitter. */
234
+ const option = {
235
+ boolean(desc: Parameters<typeof getOption>[0], ext: DescExtension): boolean {
236
+ return getOption(desc, ext) === true
237
+ },
238
+ number(desc: Parameters<typeof getOption>[0], ext: DescExtension): number {
239
+ const value: unknown = getOption(desc, ext)
240
+ return typeof value === "number" ? value : 0
241
+ },
242
+ string(desc: Parameters<typeof getOption>[0], ext: DescExtension): string {
243
+ const value: unknown = getOption(desc, ext)
244
+ return typeof value === "string" ? value : ""
245
+ },
246
+ }
247
+
248
+ /** Rust names — private to the emitter. */
249
+ const names = {
250
+ /** A message's or enum's name: nested ones carry their parents', as in TypeScript. */
251
+ local(desc: DescMessage | DescEnum): string {
252
+ const name = desc.parent ? `${names.local(desc.parent)}${desc.name}` : desc.name
253
+ // `Self` is special syntax in Rust and cannot be used even as a raw identifier.
254
+ return name === "Self" ? "SelfValue" : name
255
+ },
256
+
257
+ /** A path segment as a module: lowercase, words joined by `_`, a keyword set apart. */
258
+ module(segment: string): string {
259
+ const name = segment.replace(/[^A-Za-z0-9]+/g, "_").replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase()
260
+ return KEYWORDS.has(name) ? `${name}_` : name
261
+ },
262
+
263
+ /** A field as a Rust field: its proto name, a keyword set apart. */
264
+ field(name: string): string {
265
+ return KEYWORDS.has(name) ? `${name}_` : name
266
+ },
267
+
268
+ /** A component's handle: SCREAMING_SNAKE of its field. */
269
+ constant(name: string): string {
270
+ return name.toUpperCase()
271
+ },
272
+
273
+ /** An enum value as a variant: its name less its enum's prefix, in UpperCamel. */
274
+ variant(value: string, enumName: string): string {
275
+ return names.type(names.text(value, enumName))
276
+ },
277
+
278
+ /** lowerCamel or snake as UpperCamel. */
279
+ type(text: string): string {
280
+ return text.replace(/(^|[^A-Za-z0-9]+)([A-Za-z0-9])/g, (_, __, next: string) => next.toUpperCase())
281
+ },
282
+
283
+ /** An enum value's text: as the TypeScript generator says it. */
284
+ text(value: string, enumName: string): string {
285
+ const prefix = `${enumName.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase()}_`
286
+ const rest = value.startsWith(prefix) ? value.slice(prefix.length) : value
287
+ return rest.toLowerCase().replace(/_([a-z0-9])/g, (_, next: string) => next.toUpperCase())
288
+ },
289
+ }
290
+
291
+ /** Rust's keywords, which no generated name may be. */
292
+ const KEYWORDS = new Set(["as", "async", "await", "break", "const", "continue", "crate", "dyn", "else", "enum", "extern", "false", "fn", "for", "if", "impl", "in", "let", "loop", "match", "mod", "move", "mut", "pub", "ref", "return", "self", "static", "struct", "super", "trait", "true", "type", "unsafe", "use", "where", "while", "abstract", "become", "box", "do", "final", "macro", "override", "priv", "try", "typeof", "unsized", "virtual", "yield"])
293
+
294
+ /** Doc comments, from the schema's own — private to the emitter. */
295
+ const docs = {
296
+ of(desc: DescMessage | DescEnum | DescField, indent = ""): string[] {
297
+ const file = desc.kind === "field" ? desc.parent.file : desc.file
298
+ const path = docs.path(desc)
299
+ const text = file.proto.sourceCodeInfo?.location.find(one => one.path.length === path.length && one.path.every((step, at) => step === path[at]))?.leadingComments
300
+ if (!text) return []
301
+ const lines = text.split("\n").map(line => line.replace(/^ /, "").trimEnd())
302
+ while (lines.length && lines[0] === "") lines.shift()
303
+ while (lines.length && lines.at(-1) === "") lines.pop()
304
+ return lines.map(line => `${indent}///${line ? ` ${line}` : ""}`)
305
+ },
306
+
307
+ path(desc: DescMessage | DescEnum | DescField): number[] {
308
+ if (desc.kind === "field") return [...docs.path(desc.parent), 2, desc.parent.proto.field.indexOf(desc.proto)]
309
+ if (desc.kind === "enum") return desc.parent ? [...docs.path(desc.parent), 4, desc.parent.proto.enumType.indexOf(desc.proto)] : [5, desc.file.proto.enumType.indexOf(desc.proto)]
310
+ return desc.parent ? [...docs.path(desc.parent), 3, desc.parent.proto.nestedType.indexOf(desc.proto)] : [4, desc.file.proto.messageType.indexOf(desc.proto)]
311
+ },
312
+ }
313
+
314
+ function invalid(field: DescField, why: string): Error {
315
+ return err("COGNET_SCHEMA_INVALID", { detail: `${field.parent.file.name}.proto, ${field.parent.name}.${field.name}: ${why}` })
316
+ }
@@ -0,0 +1,248 @@
1
+ import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs"
2
+ import { dirname, join } from "node:path"
3
+ import { getOption, type DescFile, type DescMessage } from "@bufbuild/protobuf"
4
+ import { err } from "@arcforge/err"
5
+ import type { ServiceUse } from "@arcforge/types"
6
+ import { fsx } from "../../../../utils/fs"
7
+ import { writeIfChanged } from "../../../project/typegen/write"
8
+ import { compile, type Source } from "./compile"
9
+ import { Authored } from "./authored"
10
+ import { Components } from "./components"
11
+ import { Interfaces } from "./interfaces"
12
+ import { rust } from "./rust"
13
+ import { python } from "./python"
14
+ import { HEADER, typescript, type Context } from "./typescript"
15
+
16
+ export type SchemaOpts = {
17
+ /** The cognet's source directory. */
18
+ sourceDir: string
19
+ /** The agent compiling it: whose installed `@arcforge/cognet` the runtime's schema comes from. */
20
+ agentRoot: string
21
+ /** The cognet's package name — the scope its own interfaces are named in. */
22
+ cognet: string
23
+ /** What the cognet uses: the interfaces it needs compiled. */
24
+ uses: Readonly<Record<string, ServiceUse>>
25
+ /** Where the generated modules go — the agent frame's `cognet/schema/`, which `#schema/` imports resolve to. */
26
+ out: string
27
+ /** Where the schemas' Rust goes — the native crate's `src/schema.rs` — when the cognet has Rust systems; null when it has none. */
28
+ rust: string | null
29
+ /** Python's generated dataclasses and editor accessors, when Python systems exist. */
30
+ python?: string | null
31
+ /** Scratch the schemas are staged and compiled in. */
32
+ stage: string
33
+ }
34
+
35
+ /** Directories no schema lives under: installed code and build output. */
36
+ const SKIP_DIRS = ["node_modules", ".git", ".cognet", ".agent", "target", ".venv", "__pycache__"]
37
+
38
+ /** `export const world = frame({...})` — a frame an author still writes by hand. */
39
+ const HANDWRITTEN_FRAME = /^export\s+const\s+([A-Za-z_$][\w$]*)\s*(?::[^=\n]+)?=\s*frame\s*\(/gm
40
+
41
+ /** Modules an older build generated beside their schemas, which the move to the frame leaves behind. */
42
+ const BESIDE = /\.pb(\.handles)?\.ts$/
43
+
44
+ /**
45
+ * Schema — a cognet's native component sources and older schemas compiled through protobuf.
46
+ *
47
+ * The `types/` declarations are the source of truth for the cognet's world:
48
+ * its types, components and frames. Protobuf is an intermediate. Existing
49
+ * annotated TypeScript and `.proto` files remain readable during migration.
50
+ * Each language's form is
51
+ * generated into the AGENT'S frame, never into the source — `types/control/control.ts`
52
+ * → `<frame>/cognet/schema/control/control.ts` (the handles) and
53
+ * `control.types.ts` (the types, plain data) — and imported as
54
+ * `#schema/control/control`, which the agent's tsconfig and the bundler both
55
+ * resolve. Discovery, naming and typegen read the generated handles as if
56
+ * they sat at the schema's path. So nothing generated is ever committed or
57
+ * published: an installed cognet's schemas are compiled into the agent that
58
+ * installs it, like any other. Run before the brain is bundled; a schema that
59
+ * does not compile, or says something no language can be generated from,
60
+ * fails the build here.
61
+ */
62
+ export function Schema(opts: SchemaOpts) {
63
+ return {
64
+ /** Every schema compiled and its modules written; anything else under `out` removed. The modules, by path, and every interface compiled. */
65
+ async generate(): Promise<{ written: string[]; interfaces: Described[] }> {
66
+ const walked = await fsx.walk(opts.sourceDir, { skipDirs: SKIP_DIRS })
67
+ // Left by a build that generated beside the schemas: never imported again, and read as a duplicate if kept.
68
+ for (const old of walked.filter(file => BESIDE.test(file.relPath))) {
69
+ if (readFileSync(old.absPath, "utf8").startsWith(HEADER)) rmSync(old.absPath)
70
+ }
71
+ const named = naming(opts.sourceDir)
72
+ const proto: Source[] = walked.filter(file => file.relPath.endsWith(".proto")).map(file => ({ absPath: file.absPath, named: named(file.relPath) }))
73
+ // Design examples are source sketches, not schemas for this cognet.
74
+ const declarations = walked.filter(file => file.relPath.startsWith("types/") && !file.relPath.startsWith("types/examples/"))
75
+ // Component files are found anywhere in the cognet — in types/, or beside the systems that use them.
76
+ const anywhere = walked.filter(file => !file.relPath.startsWith("types/examples/"))
77
+ const oldComponent = anywhere.find(file => /\.component\.(ts|rs|py)$/.test(file.relPath))
78
+ if (oldComponent) throw err("COGNET_SCHEMA_INVALID", { detail: `${oldComponent.relPath}: rename this file to *.components.${oldComponent.relPath.split(".").at(-1)}; component sources use the plural suffix` })
79
+ const isComponents = (path: string): boolean => /\.components\.(ts|rs|py)$/.test(path)
80
+ const legacyComponents = (file: { absPath: string; relPath: string }): boolean => file.relPath.endsWith(".components.ts") && /@package\s+[^\s*]+/.test(readFileSync(file.absPath, "utf8"))
81
+ const authored = Authored({ root: opts.sourceDir, files: declarations.filter(file => file.relPath.endsWith(".ts") && (!isComponents(file.relPath) || legacyComponents(file)) && !file.relPath.endsWith(".d.ts") && !file.relPath.endsWith(".test.ts")) }).sources()
82
+ const components = Components({ root: opts.sourceDir, files: anywhere.filter(file => isComponents(file.relPath) && !legacyComponents(file)), legacy: [...proto, ...authored] })
83
+ const { sources: native, files: componentFiles } = components.sources()
84
+ const interfaces = Interfaces({ root: opts.sourceDir, cognet: opts.cognet, uses: opts.uses, standard: name => standard(name, opts.agentRoot), components: componentFiles }).sources()
85
+ const sources = [...proto, ...authored, ...native, ...interfaces.sources]
86
+ const seen = new Set<string>()
87
+ for (const source of sources) {
88
+ if (source.named === "cognet/cognet.proto") throw err("COGNET_SCHEMA_INVALID", { detail: "cognet/cognet.proto belongs to the runtime and cannot be replaced by a cognet" })
89
+ if (seen.has(source.named)) throw err("COGNET_SCHEMA_INVALID", { detail: `${source.named} is defined in both types/ and .proto — remove the .proto when moving its schema to TypeScript` })
90
+ seen.add(source.named)
91
+ }
92
+ const written: string[] = []
93
+ const described: Described[] = []
94
+ if (opts.python) rmSync(opts.python, { recursive: true, force: true })
95
+ if (opts.rust) {
96
+ mkdirSync(dirname(opts.rust), { recursive: true })
97
+ if (sources.length === 0) writeIfChanged(opts.rust, rust.module([], null))
98
+ }
99
+ if (sources.length > 0) {
100
+ compile.stage(opts.stage, sources, opts.agentRoot)
101
+ const registry = compile.image(opts.stage)
102
+ const componentMarker = registry.getExtension("cognet.components")
103
+ if (!componentMarker) throw err("COGNET_SCHEMA_INVALID", { detail: "the runtime's schema defines no cognet.components" })
104
+ const newSources = new Set(native.map(source => source.named))
105
+ const componentNames = new Map<string, { source: string; full: string }>()
106
+ for (const source of sources) {
107
+ const file = registry.getFile(source.named)
108
+ if (!file) continue
109
+ const folder = dirname(file.name)
110
+ for (const message of file.messages) {
111
+ if (getOption(message, componentMarker) !== true) continue
112
+ for (const field of message.fields) {
113
+ const full = folder === "." ? field.jsonName : `${folder}/${field.jsonName}`
114
+ const prior = componentNames.get(full)
115
+ if (prior && (newSources.has(source.named) || newSources.has(prior.source))) throw err("COGNET_SCHEMA_INVALID", { detail: `${full} overlaps ${prior.full}; ${field.jsonName} is already a component in ${prior.source}` })
116
+ componentNames.set(full, { source: source.named, full: full })
117
+ }
118
+ }
119
+ }
120
+ const ours = new Set(sources.map(source => source.named.slice(0, -".proto".length)))
121
+ const base = (file: DescFile): string => {
122
+ if (!ours.has(file.name)) throw err("COGNET_SCHEMA_INVALID", { detail: `${file.name}.proto is imported, but it is not one of this cognet's schemas — a cognet's schemas import only each other and cognet/cognet.proto` })
123
+ return join(opts.out, file.name)
124
+ }
125
+ const marker = registry.getExtension("cognet.frames")
126
+ if (!marker) throw err("COGNET_SCHEMA_INVALID", { detail: "the runtime's schema defines no cognet.frames — the installed @arcforge/cognet is older than this platform" })
127
+ const frames = Frames({
128
+ walked: walked,
129
+ named: named,
130
+ files: sources.map(source => registry.getFile(source.named)).filter(file => file !== undefined),
131
+ handles: base,
132
+ isFrames: message => getOption(message, marker) === true,
133
+ })
134
+ const context: Context = { registry: registry, types: file => `${base(file)}.types`, handles: base, frame: frames.find }
135
+
136
+ for (const source of sources) {
137
+ const file = registry.getFile(source.named)
138
+ if (!file) throw err("COGNET_SCHEMA_INVALID", { detail: `${source.named} compiled to nothing` })
139
+ const generated = typescript.file(file, source.named, context)
140
+ mkdirSync(dirname(base(file)), { recursive: true })
141
+ writeIfChanged(`${context.types(file)}.ts`, generated.types)
142
+ written.push(`${context.types(file)}.ts`)
143
+ if (generated.handles) {
144
+ writeIfChanged(`${base(file)}.ts`, generated.handles)
145
+ written.push(`${base(file)}.ts`)
146
+ }
147
+ }
148
+ const files = sources.map(source => registry.getFile(source.named)).filter(file => file !== undefined)
149
+ for (const one of interfaces.compiled) described.push(describe(one, registry.getFile(one.named)))
150
+ if (opts.rust) writeIfChanged(opts.rust, rust.module(files, registry))
151
+ if (opts.python) {
152
+ for (const [relativePath, content] of python.files(files, registry)) {
153
+ const target = join(opts.python, relativePath)
154
+ mkdirSync(dirname(target), { recursive: true })
155
+ writeIfChanged(target, content)
156
+ let directory = dirname(target)
157
+ while (directory !== opts.python) {
158
+ writeIfChanged(join(directory, "__init__.py"), "# Generated by axon prepare.\n")
159
+ directory = dirname(directory)
160
+ }
161
+ }
162
+ }
163
+ }
164
+ // `out` is the generator's alone: whatever it did not write this time is a schema that is gone.
165
+ const kept = new Set(written)
166
+ for (const stale of existsSync(opts.out) ? await fsx.walk(opts.out) : []) {
167
+ if (!kept.has(stale.absPath)) rmSync(stale.absPath)
168
+ }
169
+ if (native.length || existsSync(join(dirname(opts.out), ".schema-lock.json"))) components.save()
170
+ return { written: written, interfaces: described }
171
+ },
172
+ }
173
+ }
174
+
175
+ export type SchemaT = ReturnType<typeof Schema>
176
+
177
+ /** One interface as the runtime holds it: its name, how a use writes it, and each method's kind. */
178
+ export type Described = { name: string; written: string; methods: Record<string, { kind: "describe" | "call" | "stream" | "session"; params: string[] }>; conformance: string | null }
179
+
180
+ /** An interface's methods and their kinds, read from its compiled service: the streaming says the kind. */
181
+ function describe(compiled: { name: string; written: string; named: string; conformance: string | null }, file: DescFile | undefined): Described {
182
+ const service = file?.services[0]
183
+ if (!service) throw err("COGNET_SCHEMA_INVALID", { detail: `${compiled.named} compiled to no service` })
184
+ const methods: Described["methods"] = {}
185
+ for (const method of service.methods) {
186
+ const name = method.name[0]!.toLowerCase() + method.name.slice(1)
187
+ const kind = name === "describe" ? "describe" : method.methodKind === "bidi_streaming" ? "session" : method.methodKind === "server_streaming" ? "stream" : "call"
188
+ // A call's arguments are its request's fields, by the names the interface gave its parameters.
189
+ methods[name] = { kind: kind, params: kind === "call" || kind === "stream" ? method.input.fields.map(field => field.jsonName) : [] }
190
+ }
191
+ return { name: compiled.name, written: compiled.written, methods: methods, conformance: compiled.conformance }
192
+ }
193
+
194
+ /** The standard library's file for `chat@1`, from the agent's installed runtime; null when it has none. */
195
+ function standard(name: string, agentRoot: string): string | null {
196
+ if (!/^[a-z][a-z0-9-]*@\d+$/.test(name)) return null
197
+ try {
198
+ return Bun.resolveSync(`@arcforge/cognet/interfaces/${name}`, agentRoot)
199
+ } catch {
200
+ // Resolution failing is the answer: the installed runtime has no such interface.
201
+ return null
202
+ }
203
+ }
204
+
205
+ /**
206
+ * Every frame a schema may draw a component in, by name: those its schemas
207
+ * declare, and those still written by hand in TypeScript. Named as
208
+ * components are: the folder, then the export; found by the full name, or the
209
+ * bare one when one frame alone is called that.
210
+ */
211
+ function Frames(opts: { walked: Array<{ absPath: string; relPath: string }>; named: (relPath: string) => string; files: DescFile[]; handles: (file: DescFile) => string; isFrames: (message: DescMessage) => boolean }) {
212
+ const all: Array<{ name: string; module: string; exported: string }> = []
213
+ for (const file of opts.files) {
214
+ const folder = dirname(file.name)
215
+ for (const message of everyMessage(file.messages)) {
216
+ if (!opts.isFrames(message)) continue
217
+ for (const field of message.fields) all.push({ name: folder === "." ? field.jsonName : `${folder}/${field.jsonName}`, module: opts.handles(file), exported: field.jsonName })
218
+ }
219
+ }
220
+ for (const file of opts.walked) {
221
+ if (!file.relPath.endsWith(".ts") || file.relPath.endsWith(".d.ts") || file.relPath.endsWith(".test.ts") || BESIDE.test(file.relPath)) continue
222
+ const folder = dirname(opts.named(file.relPath))
223
+ for (const match of readFileSync(file.absPath, "utf8").matchAll(HANDWRITTEN_FRAME)) {
224
+ all.push({ name: folder === "." ? match[1]! : `${folder}/${match[1]!}`, module: file.absPath.slice(0, -".ts".length), exported: match[1]! })
225
+ }
226
+ }
227
+ return {
228
+ find(name: string): { module: string; exported: string } {
229
+ const exact = all.filter(one => one.name === name)
230
+ const bare = exact.length > 0 ? exact : all.filter(one => one.exported === name)
231
+ if (bare.length === 1) return bare[0]!
232
+ throw err("COGNET_SCHEMA_INVALID", {
233
+ detail: bare.length === 0 ? `no frame is named "${name}"` : `"${name}" is ${bare.map(one => one.name).join(" and ")} — write the full name`,
234
+ })
235
+ },
236
+ }
237
+ }
238
+
239
+ /** A message and every message nested in it, depth first. */
240
+ function everyMessage(messages: readonly DescMessage[]): DescMessage[] {
241
+ return messages.flatMap(message => [message, ...everyMessage(message.nestedMessages)])
242
+ }
243
+
244
+ /** The path a schema is NAMED and imported by: under `src/` when the cognet keeps its code there, as components are named. */
245
+ function naming(sourceDir: string): (relPath: string) => string {
246
+ const nested = existsSync(join(sourceDir, "src"))
247
+ return relPath => (nested && relPath.startsWith("src/") ? relPath.slice("src/".length) : relPath)
248
+ }