@arcforge/platform 2.0.218 → 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
@@ -1,5 +1,6 @@
1
1
  import { stat } from "node:fs/promises"
2
2
  import { err } from "@arcforge/err"
3
+ import { onnx } from "./onnx"
3
4
  import { basenameOf, downloadUrl, type ParsedModel } from "./specifier"
4
5
  import type { ModelStoreT, StoredModel } from "./store"
5
6
 
@@ -24,12 +25,21 @@ import type { ModelStoreT, StoredModel } from "./store"
24
25
  * so the cache is content-addressed either way.
25
26
  */
26
27
 
28
+ /** Own acquisition of files and complete repositories. Construction does no I/O. */
29
+ export function Fetch(opts: { store: ModelStoreT; fetch?: ((input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => Promise<Response>) }) {
30
+ return {
31
+ file: (model: ParsedModel, input: Omit<FetchOpts, "store" | "fetch"> = {}) => fetchModel(model, { ...opts, ...input }),
32
+ manifest: (input: { repo: { host: "hf"; repo: string; rev: string; key: string }; files: string[]; primary: string; options?: Omit<FetchOpts, "store" | "fetch">; traits?: ModelTraitsInput }) =>
33
+ fetchManifest(input.repo, input.files, input.primary, { ...opts, ...input.options }, input.traits),
34
+ }
35
+ }
36
+
27
37
  /** The hash HF claims for this file, when it can be known before downloading. */
28
- async function expectedHash(model: ParsedModel): Promise<string | null> {
38
+ async function expectedHash(model: ParsedModel, signal?: AbortSignal, doFetch: ((input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => Promise<Response>) = fetch): Promise<string | null> {
29
39
  if (model.sha256) return model.sha256
30
40
 
31
41
  try {
32
- const response = await fetch(downloadUrl(model), { method: "HEAD", redirect: "follow" })
42
+ const response = await doFetch(downloadUrl(model), { method: "HEAD", redirect: "follow", signal: signal })
33
43
  if (!response.ok) return null
34
44
 
35
45
  // ONLY `x-linked-etag`. That header is the LFS object's sha256 — the
@@ -43,7 +53,8 @@ async function expectedHash(model: ParsedModel): Promise<string | null> {
43
53
  // hash at all.
44
54
  const linked = response.headers.get("x-linked-etag")?.replace(/"/g, "").trim()
45
55
  return linked && /^[0-9a-f]{64}$/i.test(linked) ? linked.toLowerCase() : null
46
- } catch {
56
+ } catch (cause) {
57
+ if (signal?.aborted) throw cause
47
58
  // A HEAD that fails is not itself a failure — the GET below reports
48
59
  // the real problem with a better message.
49
60
  return null
@@ -51,6 +62,8 @@ async function expectedHash(model: ParsedModel): Promise<string | null> {
51
62
  }
52
63
 
53
64
  export type FetchOpts = {
65
+ fetch?: ((input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => Promise<Response>)
66
+ signal?: AbortSignal
54
67
  store: ModelStoreT
55
68
  /** Called before a download actually starts — nothing is emitted for a cache hit. */
56
69
  onDownload?: (model: ParsedModel) => void
@@ -90,10 +103,17 @@ export type FetchOpts = {
90
103
  * broken, and discovering that at first inference is far worse than at
91
104
  * prepare.
92
105
  */
93
- export async function fetchModel(model: ParsedModel, opts: FetchOpts): Promise<StoredModel> {
106
+ async function fetchModel(model: ParsedModel, opts: FetchOpts): Promise<StoredModel> {
107
+ const doFetch = opts.fetch ?? fetch
108
+ opts.signal?.throwIfAborted()
94
109
  // A pinned model is answerable from its own address, with no network.
95
110
  const cached = await opts.store.find(model)
96
- if (cached) return cached
111
+ if (cached) {
112
+ if (opts.remember !== false) {
113
+ await opts.store.remember(specifierOf(model), cached, basenameOf(model), { traits: model.traits, signal: opts.signal })
114
+ }
115
+ return cached
116
+ }
97
117
 
98
118
  // An unpinned one needs the index: without a declared hash there is no
99
119
  // address to look up, and a registry may not publish a usable one either.
@@ -104,7 +124,7 @@ export async function fetchModel(model: ParsedModel, opts: FetchOpts): Promise<S
104
124
  return remembered
105
125
  }
106
126
 
107
- const expected = await expectedHash(model)
127
+ const expected = await expectedHash(model, opts.signal, doFetch)
108
128
  if (expected && opts.store.has(expected, basenameOf(model))) {
109
129
  const path = opts.store.pathFor(expected, basenameOf(model))
110
130
  const hit = {
@@ -117,8 +137,7 @@ export async function fetchModel(model: ParsedModel, opts: FetchOpts): Promise<S
117
137
  bytes: (await stat(path)).size,
118
138
  }
119
139
  if (opts.remember !== false) {
120
- await opts.store.remember(specifierOf(model), hit, basenameOf(model))
121
- if (model.traits) await opts.store.describe(specifierOf(model), model.traits)
140
+ await opts.store.remember(specifierOf(model), hit, basenameOf(model), { traits: model.traits, signal: opts.signal })
122
141
  }
123
142
  return hit
124
143
  }
@@ -127,7 +146,7 @@ export async function fetchModel(model: ParsedModel, opts: FetchOpts): Promise<S
127
146
 
128
147
  let response: Response
129
148
  try {
130
- response = await fetch(downloadUrl(model), { redirect: "follow" })
149
+ response = await doFetch(downloadUrl(model), { redirect: "follow", signal: opts.signal })
131
150
  } catch (cause) {
132
151
  throw err("MODEL_FETCH_FAILED", {
133
152
  detail: `${model.key}: could not reach huggingface.co for ${model.repo}/${model.file}`,
@@ -147,15 +166,20 @@ export async function fetchModel(model: ParsedModel, opts: FetchOpts): Promise<S
147
166
  })
148
167
  }
149
168
 
150
- const data = opts.onProgress
151
- ? await readWithProgress(response, model, opts.onProgress)
152
- : new Uint8Array(await response.arrayBuffer())
153
- // put() hashes and refuses a mismatch — verification lives at the write,
154
- // so nothing can reach the cache unverified by any path.
155
- const stored = await opts.store.put(basenameOf(model), data, expected ?? undefined)
169
+ if (!response.body) throw err("MODEL_FETCH_FAILED", { detail: `${model.key}: model response has no body` })
170
+ const length = response.headers.get("content-length")
171
+ const total = length === null ? null : Number(length)
172
+ opts.onProgress?.({ model: model, received: 0, total: total })
173
+ const stored = await opts.store.receive({
174
+ filename: basenameOf(model),
175
+ body: response.body,
176
+ ...(expected ? { expected: expected } : {}),
177
+ ...(opts.signal ? { signal: opts.signal } : {}),
178
+ progress: received => opts.onProgress?.({ model: model, received: received, total: total }),
179
+ })
180
+ opts.signal?.throwIfAborted()
156
181
  if (opts.remember !== false) {
157
- await opts.store.remember(specifierOf(model), stored, basenameOf(model))
158
- if (model.traits) await opts.store.describe(specifierOf(model), model.traits)
182
+ await opts.store.remember(specifierOf(model), stored, basenameOf(model), { traits: model.traits, signal: opts.signal })
159
183
  }
160
184
  return stored
161
185
  }
@@ -220,10 +244,12 @@ async function discoverManifest(repo: { host: "hf"; repo: string; rev: string })
220
244
  })
221
245
  }
222
246
 
223
- return { files: names, primary }
247
+ // An ONNX repository holds the graph once per quantisation; a runtime
248
+ // loads one. Take that one set, not the repository.
249
+ return onnx.plan(names) ?? { files: names, primary }
224
250
  }
225
251
 
226
- export async function fetchManifest(
252
+ async function fetchManifest(
227
253
  repo: { host: "hf"; repo: string; rev: string; key: string },
228
254
  files: string[],
229
255
  primary: string,
@@ -254,6 +280,7 @@ export async function fetchManifest(
254
280
  })
255
281
  }
256
282
 
283
+ opts.signal?.throwIfAborted()
257
284
  await opts.store.rememberSet(specifier, collected, resolvedPrimary, traits)
258
285
 
259
286
  const resolved = await opts.store.resolved(specifier)
@@ -281,39 +308,7 @@ export async function fetchManifest(
281
308
  * verification — this changes how the bytes arrive, not whether they are
282
309
  * checked.
283
310
  */
284
- async function readWithProgress(
285
- response: Response,
286
- model: ParsedModel,
287
- onProgress: NonNullable<FetchOpts["onProgress"]>,
288
- ): Promise<Uint8Array> {
289
- const declared = Number.parseInt(response.headers.get("content-length") ?? "", 10)
290
- const total = Number.isFinite(declared) && declared > 0 ? declared : null
291
-
292
- const body = response.body
293
- if (!body) return new Uint8Array(await response.arrayBuffer())
294
311
 
295
- const reader = body.getReader()
296
- const chunks: Uint8Array[] = []
297
- let received = 0
298
-
299
- onProgress({ model, received: 0, total })
300
- for (;;) {
301
- const { done, value } = await reader.read()
302
- if (done) break
303
- if (!value) continue
304
- chunks.push(value)
305
- received += value.byteLength
306
- onProgress({ model, received, total })
307
- }
308
-
309
- const data = new Uint8Array(received)
310
- let offset = 0
311
- for (const chunk of chunks) {
312
- data.set(chunk, offset)
313
- offset += chunk.byteLength
314
- }
315
- return data
316
- }
317
312
 
318
313
  /** The index key: what was declared, including the revision it was declared at. */
319
314
  function specifierOf(model: ParsedModel): string {
@@ -5,5 +5,6 @@
5
5
  export { Models, type ModelsT, type ResolveResult } from "./models"
6
6
  export { ModelStore, type ModelStoreT, type StoredModel } from "./store"
7
7
  export { parseModel, parseModels, downloadUrl, basenameOf, type ParsedModel } from "./specifier"
8
- export { fetchModel, fetchManifest } from "./fetch"
8
+ export { Fetch } from "./fetch"
9
9
  export type { ModelFile } from "./store"
10
+ export { onnx } from "./onnx"
@@ -1,6 +1,6 @@
1
1
  import { err } from "@arcforge/err"
2
2
  import type { ModelRef } from "@arcforge/types"
3
- import { fetchManifest, fetchModel } from "./fetch"
3
+ import { Fetch } from "./fetch"
4
4
  import { parseModels, type ParsedModel } from "./specifier"
5
5
  import { ModelStore, type ModelStoreT, type StoredModel } from "./store"
6
6
 
@@ -32,6 +32,7 @@ export type ResolveResult = {
32
32
 
33
33
  export function Models(opts: ModelsOpts = {}) {
34
34
  const store = opts.store ?? ModelStore()
35
+ const fetcher = Fetch({ store: store })
35
36
 
36
37
  return {
37
38
  get store() {
@@ -77,17 +78,13 @@ export function Models(opts: ModelsOpts = {}) {
77
78
  files: string[],
78
79
  primary: string,
79
80
  resolveOpts: {
81
+ signal?: AbortSignal
80
82
  onDownload?: (model: ParsedModel) => void
81
83
  onProgress?: (progress: { model: ParsedModel; received: number; total: number | null }) => void
82
84
  traits?: ParsedModel["traits"]
83
85
  } = {},
84
86
  ): Promise<StoredModel> {
85
- return await fetchManifest(repo, files, primary, {
86
- store,
87
- ...(resolveOpts.onDownload ? { onDownload: resolveOpts.onDownload } : {}),
88
- ...(resolveOpts.onProgress ? { onProgress: resolveOpts.onProgress } : {}),
89
- ...(resolveOpts.traits ? { traits: resolveOpts.traits } : {}),
90
- })
87
+ return await fetcher.manifest({ repo: repo, files: files, primary: primary, options: resolveOpts, traits: resolveOpts.traits })
91
88
  },
92
89
 
93
90
  /**
@@ -102,6 +99,7 @@ export function Models(opts: ModelsOpts = {}) {
102
99
  models: Record<string, ModelRef> | undefined,
103
100
  resolveOpts: {
104
101
  frozen?: boolean
102
+ signal?: AbortSignal
105
103
  onDownload?: (model: ParsedModel) => void
106
104
  /** Bytes as they arrive. Forwarded straight to the fetcher — see FetchOpts. */
107
105
  onProgress?: (progress: { model: ParsedModel; received: number; total: number | null }) => void
@@ -130,41 +128,16 @@ export function Models(opts: ModelsOpts = {}) {
130
128
 
131
129
  for (const model of parsed) {
132
130
  if (model.set) {
133
- const stored = await fetchManifest(
134
- { host: model.host, repo: model.repo, rev: model.rev, key: model.key },
135
- [],
136
- "",
137
- {
138
- store,
139
- ...(resolveOpts.onDownload ? { onDownload: resolveOpts.onDownload } : {}),
140
- ...(resolveOpts.onProgress ? { onProgress: resolveOpts.onProgress } : {}),
141
- },
142
- model.traits,
143
- )
131
+ const stored = await fetcher.manifest({
132
+ repo: { host: model.host, repo: model.repo, rev: model.rev, key: model.key },
133
+ files: [], primary: "", options: resolveOpts, traits: model.traits,
134
+ })
144
135
  paths[model.key] = stored.path
145
136
  if (stored.path) fetched.push(model.key)
146
137
  continue
147
138
  }
148
139
 
149
- if (model.set) {
150
- const stored = await fetchManifest(
151
- { host: model.host, repo: model.repo, rev: model.rev, key: model.key },
152
- [],
153
- "",
154
- {
155
- store,
156
- ...(resolveOpts.onDownload ? { onDownload: resolveOpts.onDownload } : {}),
157
- ...(resolveOpts.onProgress ? { onProgress: resolveOpts.onProgress } : {}),
158
- },
159
- model.traits,
160
- )
161
- paths[model.key] = stored.path
162
- fetched.push(model.key)
163
- continue
164
- }
165
-
166
- const stored = await fetchModel(model, {
167
- store,
140
+ const stored = await fetcher.file(model, {
168
141
  onDownload: m => {
169
142
  fetched.push(m.key)
170
143
  resolveOpts.onDownload?.(m)
@@ -172,7 +145,8 @@ export function Models(opts: ModelsOpts = {}) {
172
145
  // Threaded rather than dropped: the fetcher reports bytes as
173
146
  // they land, and a caller that cannot see them can only show
174
147
  // a spinner for a five-gigabyte transfer.
175
- ...(resolveOpts.onProgress ? { onProgress: resolveOpts.onProgress } : {}),
148
+ ...(resolveOpts.signal ? { signal: resolveOpts.signal } : {}),
149
+ ...(resolveOpts.onProgress ? { onProgress: resolveOpts.onProgress } : {}),
176
150
  ...(model.traits ? { traits: model.traits } : {}),
177
151
 
178
152
  })
@@ -0,0 +1,82 @@
1
+ import { err } from "@arcforge/err"
2
+
3
+ /**
4
+ * One coherent ONNX set out of a repository — plain functions, no I/O.
5
+ *
6
+ * An ONNX repository ships the same graph many times: fp32, fp16, q4, int8…
7
+ * each `name_<variant>.onnx` with its own weight data. A runtime loads ONE of
8
+ * them, so a set is the chosen variant's graphs, their `.onnx_data`, and the
9
+ * root configs — never the whole repository. Fetching everything cost ~1GB
10
+ * of quantisations for a 150MB model nobody would load.
11
+ *
12
+ * Lives with the model toolchain because both halves need it: acquisition
13
+ * (what to download) and the runtime (which dtype to load it as). One copy,
14
+ * so what is downloaded and what is loaded cannot disagree.
15
+ */
16
+
17
+ const DTYPES = { quantized: "q8", q4f16: "q4f16", q2f16: "q2f16", q1f16: "q1f16", bnb4: "bnb4", int8: "int8", uint8: "uint8", fp16: "fp16", q4: "q4", q2: "q2", q1: "q1" } as const
18
+ /** Longest first, so `q4f16` is not read as `q4`. */
19
+ const QUANTISATIONS = Object.keys(DTYPES).sort((a, b) => b.length - a.length)
20
+
21
+ export const onnx = {
22
+ /**
23
+ * The files of one variant — `variant` if the repository has it, else the
24
+ * unquantised one, else the first by name. Null when there is no ONNX.
25
+ */
26
+ plan(names: string[], variant = ""): { files: string[]; primary: string } | null {
27
+ const weights = names.filter(name => name.toLowerCase().endsWith(".onnx"))
28
+ if (weights.length === 0) return null
29
+
30
+ const grouped = new Map<string, string[]>()
31
+ for (const name of weights) {
32
+ const key = onnx.variant(name)
33
+ grouped.set(key, [...(grouped.get(key) ?? []), name])
34
+ }
35
+
36
+ const chosen = grouped.get(variant)
37
+ ?? grouped.get("")
38
+ ?? [...grouped.entries()].sort(([a], [b]) => a.localeCompare(b))[0]?.[1]
39
+ if (!chosen || chosen.length === 0) return null
40
+
41
+ const data = names.filter(name => name.toLowerCase().endsWith(".onnx_data")
42
+ && chosen.some(weight => name.startsWith(weight)))
43
+
44
+ const merged = chosen.some(name => /_merged/i.test(name))
45
+ const kept = merged
46
+ ? chosen.filter(name => !/_with_past_model/i.test(name) && !/decoder_model(?!_merged)/i.test(name))
47
+ : chosen
48
+
49
+ return { files: [...names.filter(isConfig), ...kept, ...data], primary: primaryOf(kept) }
50
+ },
51
+
52
+ /** Which quantisation a graph file is — `""` for unquantised. */
53
+ variant(name: string): string {
54
+ const stem = name.slice(0, -".onnx".length)
55
+ return QUANTISATIONS.find(suffix => stem.toLowerCase().endsWith(`_${suffix}`)) ?? ""
56
+ },
57
+
58
+ /** The dtype a runtime loads a set as. Refuses a directory holding more than one variant. */
59
+ dtype(names: string[]): string {
60
+ const variants = new Set(names.filter(name => name.endsWith(".onnx")).map(onnx.variant))
61
+ if (variants.size !== 1) throw err("MODEL_LOAD_FAILED", { detail: "ONNX repository must contain one coherent quantization" })
62
+ const variant = [...variants][0]
63
+ if (variant === "") return "fp32"
64
+ if (variant !== undefined && variant in DTYPES) return DTYPES[variant as keyof typeof DTYPES]
65
+ throw err("MODEL_LOAD_FAILED", { detail: `unsupported ONNX quantization: ${variant}` })
66
+ },
67
+ }
68
+
69
+ function primaryOf(weights: string[]): string {
70
+ const sorted = [...weights].sort()
71
+ return sorted.find(name => /_merged/i.test(name))
72
+ ?? sorted.find(name => /(^|\/)model[^/]*\.onnx$/i.test(name))
73
+ ?? sorted.find(name => /decoder/i.test(name))
74
+ ?? sorted[0]!
75
+ }
76
+
77
+ /** A root-level config a runtime reads beside the graph — tokeniser, preprocessor, model config. */
78
+ function isConfig(name: string): boolean {
79
+ if (name.includes("/")) return false
80
+ if (/^readme|^\.git|^license/i.test(name)) return false
81
+ return /\.(json|txt|model)$/i.test(name)
82
+ }
@@ -95,7 +95,7 @@ export function parseModel(key: string, ref: ModelRef): ParsedModel {
95
95
  })
96
96
  }
97
97
 
98
- const segments = ref.slice(colon + 1).split("/").filter(Boolean)
98
+ const segments = ref.slice(colon + 1).split("/")
99
99
  if (segments.length < 3) {
100
100
  // Two segments is a bare repo, which is ambiguous: a repo is a
101
101
  // directory, and `ggerganov/whisper.cpp` alone names twenty
@@ -108,12 +108,18 @@ export function parseModel(key: string, ref: ModelRef): ParsedModel {
108
108
  })
109
109
  }
110
110
 
111
+ const repository = segments[1]!.split("@")
112
+ const name = repository[0]
113
+ const revision = repository[1] ?? "main"
114
+ if (!name || !revision || repository.length > 2 || segments.some(segment => !segment || segment === "." || segment === "..")) {
115
+ throw err("MODEL_SPECIFIER_INVALID", { detail: `models.${key}: invalid repository, revision or file path`, context: { key: key, specifier: ref } })
116
+ }
111
117
  return {
112
118
  key,
113
119
  host: "hf",
114
- repo: `${segments[0]}/${segments[1]}`,
120
+ repo: `${segments[0]}/${name}`,
115
121
  file: segments.slice(2).join("/"),
116
- rev: "main",
122
+ rev: revision,
117
123
  }
118
124
  }
119
125
 
@@ -0,0 +1,27 @@
1
+ import { mkdir, rename, rm, writeFile } from "node:fs/promises"
2
+ import { join } from "node:path"
3
+ import { randomUUID } from "node:crypto"
4
+ import { lock } from "proper-lockfile"
5
+ import { fsx } from "../../../../utils/fs"
6
+
7
+ /** Serialize model-index mutations across handles and processes; readers see atomic snapshots. */
8
+ export function Index<T>(opts: { root: string }) {
9
+ const path = join(opts.root, "index.json")
10
+ async function read(): Promise<Record<string, T>> { return await fsx.readJson<Record<string, T>>(path) ?? {} }
11
+ async function update<R>(mutate: (index: Record<string, T>) => Promise<R>): Promise<R> {
12
+ await mkdir(opts.root, { recursive: true })
13
+ const release = await lock(path, { realpath: false, stale: 10_000, update: 2000,
14
+ retries: { retries: 100, minTimeout: 10, maxTimeout: 100, factor: 1.1 } })
15
+ const temporary = `${path}.${randomUUID()}.tmp`
16
+ try {
17
+ const index = await read()
18
+ const result = await mutate(index)
19
+ await writeFile(temporary, JSON.stringify(index, null, 4))
20
+ await rename(temporary, path)
21
+ return result
22
+ } finally {
23
+ try { await rm(temporary, { force: true }) } finally { await release() }
24
+ }
25
+ }
26
+ return { read: read, update: update }
27
+ }
@@ -0,0 +1 @@
1
+ export { Index } from "./index-store"
@@ -1,9 +1,11 @@
1
+ import { fsx } from "../../../utils/fs"
2
+ import { Blobs } from "./blobs"
3
+ import { Index } from "./storage"
1
4
  import { createHash } from "node:crypto"
2
5
  import { link, mkdir, mkdtemp, rename, rm, stat } from "node:fs/promises"
3
6
  import { homedir, tmpdir } from "node:os"
4
7
  import { join } from "node:path"
5
8
  import { err } from "@arcforge/err"
6
- import { fsx } from "../../../utils/fs"
7
9
  import { basenameOf, type ParsedModel } from "./specifier"
8
10
 
9
11
  /**
@@ -116,7 +118,6 @@ function isSet(entry: Entry): entry is SetEntry {
116
118
  }
117
119
 
118
120
  /** The on-disk index: specifier → where the bytes are, and what they are. */
119
- type IndexEntry = Record<string, Entry>
120
121
 
121
122
  function defaultRoot(): string {
122
123
  return process.env.AXON_MODELS_DIR ?? join(homedir(), ".axon", "models")
@@ -125,7 +126,8 @@ function defaultRoot(): string {
125
126
  export function ModelStore(opts: ModelStoreOpts = {}) {
126
127
  const root = opts.root ?? defaultRoot()
127
128
  /** specifier → { sha256, file, traits? }. A hint for unpinned models; see resolved(). */
128
- const indexPath = join(root, "index.json")
129
+ const blobs = Blobs({ root: root })
130
+ const indexStore = Index<Entry>({ root: root })
129
131
 
130
132
  /** Where a given hash's file lives. Pure — no I/O. */
131
133
  function pathFor(sha256: string, filename: string): string {
@@ -203,7 +205,7 @@ export function ModelStore(opts: ModelStoreOpts = {}) {
203
205
  * refetch and cannot produce wrong bytes.
204
206
  */
205
207
  async resolved(specifier: string): Promise<StoredModel | null> {
206
- const index = await fsx.readJson<IndexEntry>(indexPath)
208
+ const index = await indexStore.read()
207
209
  const hit = index?.[specifier]
208
210
  if (!hit) return null
209
211
 
@@ -256,7 +258,7 @@ export function ModelStore(opts: ModelStoreOpts = {}) {
256
258
  primary?: string
257
259
  traits?: ModelTraits
258
260
  }[]> {
259
- const index = await fsx.readJson<IndexEntry>(indexPath)
261
+ const index = await indexStore.read()
260
262
  if (!index) return []
261
263
 
262
264
  const found: {
@@ -322,15 +324,15 @@ export function ModelStore(opts: ModelStoreOpts = {}) {
322
324
  * rest survives.
323
325
  */
324
326
  async describe(specifier: string, traits: ModelTraits): Promise<void> {
325
- const index = (await fsx.readJson<IndexEntry>(indexPath)) ?? {}
327
+ return indexStore.update(async index => {
326
328
  const hit = index[specifier]
327
329
  // Describing something the store has never seen would write an
328
330
  // entry with no bytes behind it, which `list()` would then skip
329
331
  // forever. Silent because a describe racing a removal is ordinary.
330
- if (!hit) return
332
+ if (!hit) throw err("MODEL_NOT_CACHED", { detail: `${specifier} has no stored model to describe` })
331
333
  index[specifier] = { ...hit, traits: { ...hit.traits, ...traits } }
332
334
  await mkdir(root, { recursive: true })
333
- await Bun.write(indexPath, JSON.stringify(index, null, 4))
335
+ })
334
336
  },
335
337
 
336
338
  /**
@@ -371,6 +373,7 @@ export function ModelStore(opts: ModelStoreOpts = {}) {
371
373
  primary: string,
372
374
  traits?: ModelTraits,
373
375
  ): Promise<void> {
376
+ return indexStore.update(async index => {
374
377
  const name = treeNameFor(specifier)
375
378
  const tree = treeFor(name)
376
379
 
@@ -390,7 +393,6 @@ export function ModelStore(opts: ModelStoreOpts = {}) {
390
393
  }
391
394
  }
392
395
 
393
- const index = (await fsx.readJson<IndexEntry>(indexPath)) ?? {}
394
396
  const previous = index[specifier]
395
397
  index[specifier] = {
396
398
  tree: name,
@@ -401,18 +403,19 @@ export function ModelStore(opts: ModelStoreOpts = {}) {
401
403
  ...(traits ?? previous?.traits ? { traits: traits ?? previous?.traits } : {}),
402
404
  }
403
405
  await mkdir(root, { recursive: true })
404
- await Bun.write(indexPath, JSON.stringify(index, null, 4))
406
+ })
405
407
  },
406
408
 
407
409
  /** Record what a specifier resolved to, so the next run can skip the network. */
408
- async remember(specifier: string, stored: StoredModel, filename: string): Promise<void> {
409
- const index = (await fsx.readJson<IndexEntry>(indexPath)) ?? {}
410
+ async remember(specifier: string, stored: StoredModel, filename: string, opts?: { traits?: ModelTraits; signal?: AbortSignal }): Promise<void> {
411
+ return indexStore.update(async index => {
412
+ opts?.signal?.throwIfAborted()
410
413
  // Traits are preserved across a re-fetch: they describe the MODEL,
411
414
  // not the bytes, and re-downloading the same weight must not
412
415
  // forget what it is.
413
- index[specifier] = { ...index[specifier], sha256: stored.sha256, file: filename }
416
+ index[specifier] = { ...index[specifier], sha256: stored.sha256, file: filename, ...(opts?.traits ? { traits: opts.traits } : {}) }
414
417
  await mkdir(root, { recursive: true })
415
- await Bun.write(indexPath, JSON.stringify(index, null, 4))
418
+ })
416
419
  },
417
420
 
418
421
  /**
@@ -431,6 +434,8 @@ export function ModelStore(opts: ModelStoreOpts = {}) {
431
434
  * throws rather than storing: caching corrupt weights is worse than
432
435
  * failing to cache.
433
436
  */
437
+ receive: blobs.receive,
438
+
434
439
  async put(filename: string, data: Uint8Array, expected?: string): Promise<StoredModel> {
435
440
  const sha256 = createHash("sha256").update(data).digest("hex")
436
441
 
@@ -500,13 +505,12 @@ export function ModelStore(opts: ModelStoreOpts = {}) {
500
505
  * has.
501
506
  */
502
507
  async remove(specifier: string): Promise<boolean> {
503
- const index = await fsx.readJson<IndexEntry>(indexPath)
508
+ return indexStore.update(async index => {
504
509
  const hit = index?.[specifier]
505
510
  if (!index || !hit) return false
506
511
 
507
512
  delete index[specifier]
508
513
  await mkdir(root, { recursive: true })
509
- await Bun.write(indexPath, JSON.stringify(index, null, 4))
510
514
 
511
515
  /*
512
516
  * Every hash the survivors still reference, from BOTH shapes.
@@ -539,6 +543,7 @@ export function ModelStore(opts: ModelStoreOpts = {}) {
539
543
  await rm(join(root, sha256), { recursive: true, force: true })
540
544
  }
541
545
  return true
546
+ })
542
547
  },
543
548
  }
544
549
  }