@arcforge/platform 2.0.181 → 2.0.183

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@arcforge/platform",
3
- "version": "2.0.181",
3
+ "version": "2.0.183",
4
4
  "description": "The Axon developer platform — headless project discovery, blueprint scanning, typegen, agent lifecycle, registry, benches and tests. Shared by the CLI/TUI and the Fleet extension.",
5
5
  "type": "module",
6
6
  "private": false,
@@ -44,24 +44,24 @@
44
44
  "deploy": "echo \"This package is published ONLY by apps/tui/scripts/release.ts, which pins workspace:* deps to concrete versions first. Publishing it directly ships an unresolvable dependency.\" && exit 1"
45
45
  },
46
46
  "dependencies": {
47
- "@arcforge/session": "2.0.181",
48
- "@arcforge/engines": "2.0.181",
49
- "@arcforge/err": "2.0.181",
50
- "@arcforge/types": "2.0.181",
51
- "@arcforge/cloud": "2.0.181",
52
- "@arcforge/capsule": "2.0.181",
53
- "@arcforge/core": "2.0.181",
54
- "@arcforge/vstr": "2.0.181",
47
+ "@arcforge/session": "2.0.183",
48
+ "@arcforge/engines": "2.0.183",
49
+ "@arcforge/err": "2.0.183",
50
+ "@arcforge/types": "2.0.183",
51
+ "@arcforge/cloud": "2.0.183",
52
+ "@arcforge/capsule": "2.0.183",
53
+ "@arcforge/core": "2.0.183",
54
+ "@arcforge/vstr": "2.0.183",
55
55
  "fft.js": "^4.0.4",
56
56
  "h3": "^1.15.11",
57
57
  "semver": "^7.7.4",
58
58
  "sharp": "^0.35.3",
59
59
  "typescript": "5.9.2",
60
- "@arcforge/link": "2.0.181"
60
+ "@arcforge/link": "2.0.183"
61
61
  },
62
62
  "devDependencies": {
63
- "@arcforge/air": "2.0.167",
64
- "@arcforge/cognet": "2.0.167",
63
+ "@arcforge/air": "2.0.181",
64
+ "@arcforge/cognet": "2.0.181",
65
65
  "@arclabs/repo": "1.0.0",
66
66
  "@types/bun": "latest",
67
67
  "@types/semver": "^7.7.1"
@@ -3,7 +3,7 @@ import { AsyncLocalStorage } from "node:async_hooks"
3
3
  import { defineModule, definePrompt } from "@arcforge/types"
4
4
  import { defineCognet } from "@arcforge/cognet"
5
5
  import type { AxonConfig, ModuleEntry } from "@arcforge/types"
6
- import { Axon, Ollama, Codex, OpenRouter, HuggingFace, Mock } from "@arcforge/engines"
6
+ import { Axon, Local, Ollama, Codex, OpenRouter, HuggingFace, Mock } from "@arcforge/engines"
7
7
  import { err } from "@arcforge/err"
8
8
  import { fsx } from "../../../utils/fs"
9
9
  import { resolveModulePaths, type ResolvedModulePath } from "./moduleImports"
@@ -121,6 +121,7 @@ function installAuthoringGlobals(): void {
121
121
  // the AUTHORITATIVE binding for the duration of an evaluation is applied
122
122
  // by withProviderGlobals() below rather than trusted from module load.
123
123
  g.Axon ??= Axon
124
+ g.Local ??= Local
124
125
  g.Ollama ??= Ollama
125
126
  g.Codex ??= Codex
126
127
  g.OpenRouter ??= OpenRouter
@@ -149,7 +150,7 @@ function installAuthoringGlobals(): void {
149
150
  */
150
151
  export async function withProviderGlobals<T>(body: () => Promise<T>): Promise<T> {
151
152
  const g = globalThis as Record<string, unknown>
152
- const factories = { Axon, Ollama, Codex, OpenRouter, HuggingFace, Mock }
153
+ const factories = { Axon, Local, Ollama, Codex, OpenRouter, HuggingFace, Mock }
153
154
  const previous = Object.fromEntries(Object.keys(factories).map(name => [name, g[name]]))
154
155
  Object.assign(g, factories)
155
156
  try {
@@ -1,3 +1,4 @@
1
+ import { stat } from "node:fs/promises"
1
2
  import { err } from "@arcforge/err"
2
3
  import { basenameOf, downloadUrl, type ParsedModel } from "./specifier"
3
4
  import type { ModelStoreT, StoredModel } from "./store"
@@ -65,6 +66,20 @@ export type FetchOpts = {
65
66
  * throttling here would decide the cadence for every caller.
66
67
  */
67
68
  onProgress?: (progress: { model: ParsedModel; received: number; total: number | null }) => void
69
+
70
+ /**
71
+ * Record this file in the specifier index. Default true.
72
+ *
73
+ * False for a file fetched as a MEMBER of a set. The bytes still land in
74
+ * the content-addressed store — that is what makes them shared and
75
+ * verified — but the index maps "a model this machine has" to an address,
76
+ * and a set's thirteen tokeniser and config files are not thirteen models.
77
+ * Remembering them individually put `config.json` and `vocab.json` in the
78
+ * machine's model list as though someone had downloaded them.
79
+ *
80
+ * The set writes ONE entry, for the set. That is the model.
81
+ */
82
+ remember?: boolean
68
83
  }
69
84
 
70
85
  /**
@@ -88,12 +103,17 @@ export async function fetchModel(model: ParsedModel, opts: FetchOpts): Promise<S
88
103
 
89
104
  const expected = await expectedHash(model)
90
105
  if (expected && opts.store.has(expected, basenameOf(model))) {
106
+ const path = opts.store.pathFor(expected, basenameOf(model))
91
107
  const hit = {
92
- path: opts.store.pathFor(expected, basenameOf(model)),
108
+ path: path,
93
109
  sha256: expected,
94
- bytes: 0,
110
+ // Measured, not zero. Nothing read this until a manifest had to
111
+ // sum its members' sizes to answer "how big is this model" — and
112
+ // a set whose bytes came back short would be admitted into video
113
+ // memory it does not fit in.
114
+ bytes: (await stat(path)).size,
95
115
  }
96
- await opts.store.remember(specifierOf(model), hit, basenameOf(model))
116
+ if (opts.remember !== false) await opts.store.remember(specifierOf(model), hit, basenameOf(model))
97
117
  return hit
98
118
  }
99
119
 
@@ -127,10 +147,75 @@ export async function fetchModel(model: ParsedModel, opts: FetchOpts): Promise<S
127
147
  // put() hashes and refuses a mismatch — verification lives at the write,
128
148
  // so nothing can reach the cache unverified by any path.
129
149
  const stored = await opts.store.put(basenameOf(model), data, expected ?? undefined)
130
- await opts.store.remember(specifierOf(model), stored, basenameOf(model))
150
+ if (opts.remember !== false) await opts.store.remember(specifierOf(model), stored, basenameOf(model))
131
151
  return stored
132
152
  }
133
153
 
154
+ /**
155
+ * Fetch a model that is a SET of files, and remember it as one.
156
+ *
157
+ * ── Why this is separate from fetchModel ────────────────────────────────────
158
+ *
159
+ * Not a loop around it. `fetchModel` answers "is this weight here, and if not
160
+ * get it" and each of its three cache paths is about ONE file's address; a set
161
+ * is cached or not as a whole, and a set half-fetched is not a model. So the
162
+ * unit of the cache check, the unit of the index write and the unit of failure
163
+ * all move up a level, and expressing that by calling the single-file function
164
+ * n times would make each of those three things wrong in a different way.
165
+ *
166
+ * The single-file path is untouched. A GGUF genuinely is one file and pays
167
+ * nothing for this.
168
+ *
169
+ * ── Order, and what a crash leaves behind ───────────────────────────────────
170
+ *
171
+ * Every file is fetched and verified before the manifest is written, and the
172
+ * manifest is what makes the set cached. Interrupt this and the blobs are
173
+ * already in the content-addressed store — so nothing is lost and the retry
174
+ * skips what it has — while the index never claimed a model it did not have.
175
+ *
176
+ * The reverse order is the one that breaks: an index naming a set whose files
177
+ * are missing hands a caller a directory path into nothing, which surfaces as
178
+ * a runtime error about a config file rather than as "not downloaded".
179
+ */
180
+ export async function fetchManifest(
181
+ repo: { host: "hf"; repo: string; rev: string; key: string },
182
+ files: string[],
183
+ primary: string,
184
+ opts: FetchOpts,
185
+ ): Promise<StoredModel> {
186
+ const specifier = `${repo.host}:${repo.repo}@${repo.rev}`
187
+
188
+ const cached = await opts.store.resolved(specifier)
189
+ if (cached) return cached
190
+
191
+ const collected: { file: { path: string; sha256: string; bytes: number }; stored: StoredModel }[] = []
192
+
193
+ for (const path of files) {
194
+ // Reuses the whole single-file machine per member — hash expectation,
195
+ // verification at the write, dedup against bytes already held. A set
196
+ // sharing a config file with another set costs nothing twice.
197
+ const member: ParsedModel = { key: `${repo.key}:${path}`, host: repo.host, repo: repo.repo, file: path, rev: repo.rev }
198
+ const stored = await fetchModel(member, { ...opts, remember: false })
199
+ collected.push({
200
+ file: { path: path, sha256: stored.sha256, bytes: stored.bytes },
201
+ stored: stored,
202
+ })
203
+ }
204
+
205
+ await opts.store.rememberSet(specifier, collected, primary)
206
+
207
+ const resolved = await opts.store.resolved(specifier)
208
+ if (!resolved) {
209
+ // Written and immediately unreadable is a fault in the store, not a
210
+ // user error, and it must not read as "this model is not cached".
211
+ throw err("MODEL_FETCH_FAILED", {
212
+ detail: `${repo.repo}: the set was written but could not be read back`,
213
+ context: { repo: repo.repo, files: files.length },
214
+ })
215
+ }
216
+ return resolved
217
+ }
218
+
134
219
  /**
135
220
  * Drain the body, reporting progress as it arrives.
136
221
  *
@@ -5,4 +5,5 @@
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 } from "./fetch"
8
+ export { fetchModel, fetchManifest } from "./fetch"
9
+ export type { ModelFile } from "./store"
@@ -1,8 +1,8 @@
1
1
  import { err } from "@arcforge/err"
2
2
  import type { ModelRef } from "@arcforge/types"
3
- import { fetchModel } from "./fetch"
3
+ import { fetchManifest, fetchModel } from "./fetch"
4
4
  import { parseModels, type ParsedModel } from "./specifier"
5
- import { ModelStore, type ModelStoreT } from "./store"
5
+ import { ModelStore, type ModelStoreT, type StoredModel } from "./store"
6
6
 
7
7
  /**
8
8
  * Models — a cognet's declared weights, from specifier to absolute path.
@@ -59,6 +59,35 @@ export function Models(opts: ModelsOpts = {}) {
59
59
  })
60
60
  },
61
61
 
62
+ /**
63
+ * Resolve one model that is a SET of files, to the directory holding it.
64
+ *
65
+ * The counterpart of `resolve` for repositories rather than weights.
66
+ * Deliberately singular: a set is chosen by a person or a planner
67
+ * looking at one repository's file list, where `resolve` reconciles a
68
+ * whole cognet's declarations at once.
69
+ *
70
+ * What comes back is a DIRECTORY, and that is the point — a runtime
71
+ * that needs a tokeniser beside its weights is handed the layout it
72
+ * expects, and `ResolveResult.paths` stays `name → path` for both
73
+ * kinds without a consumer learning the difference.
74
+ */
75
+ async resolveSet(
76
+ repo: { host: "hf"; repo: string; rev: string; key: string },
77
+ files: string[],
78
+ primary: string,
79
+ resolveOpts: {
80
+ onDownload?: (model: ParsedModel) => void
81
+ onProgress?: (progress: { model: ParsedModel; received: number; total: number | null }) => void
82
+ } = {},
83
+ ): Promise<StoredModel> {
84
+ return await fetchManifest(repo, files, primary, {
85
+ store,
86
+ ...(resolveOpts.onDownload ? { onDownload: resolveOpts.onDownload } : {}),
87
+ ...(resolveOpts.onProgress ? { onProgress: resolveOpts.onProgress } : {}),
88
+ })
89
+ },
90
+
62
91
  /**
63
92
  * Resolve every declared model to an absolute path, fetching what is
64
93
  * absent.
@@ -69,7 +98,12 @@ export function Models(opts: ModelsOpts = {}) {
69
98
  */
70
99
  async resolve(
71
100
  models: Record<string, ModelRef> | undefined,
72
- resolveOpts: { frozen?: boolean; onDownload?: (model: ParsedModel) => void } = {},
101
+ resolveOpts: {
102
+ frozen?: boolean
103
+ onDownload?: (model: ParsedModel) => void
104
+ /** Bytes as they arrive. Forwarded straight to the fetcher — see FetchOpts. */
105
+ onProgress?: (progress: { model: ParsedModel; received: number; total: number | null }) => void
106
+ } = {},
73
107
  ): Promise<ResolveResult> {
74
108
  const parsed = parseModels(models)
75
109
  if (parsed.length === 0) return { paths: {}, fetched: [] }
@@ -99,6 +133,10 @@ export function Models(opts: ModelsOpts = {}) {
99
133
  fetched.push(m.key)
100
134
  resolveOpts.onDownload?.(m)
101
135
  },
136
+ // Threaded rather than dropped: the fetcher reports bytes as
137
+ // they land, and a caller that cannot see them can only show
138
+ // a spinner for a five-gigabyte transfer.
139
+ ...(resolveOpts.onProgress ? { onProgress: resolveOpts.onProgress } : {}),
102
140
  })
103
141
  paths[model.key] = stored.path
104
142
  }
@@ -1,5 +1,5 @@
1
1
  import { createHash } from "node:crypto"
2
- import { mkdir, mkdtemp, rename, rm, stat } from "node:fs/promises"
2
+ import { link, mkdir, mkdtemp, rename, rm, stat } from "node:fs/promises"
3
3
  import { homedir, tmpdir } from "node:os"
4
4
  import { join } from "node:path"
5
5
  import { err } from "@arcforge/err"
@@ -30,19 +30,101 @@ type ModelStoreOpts = {
30
30
  }
31
31
 
32
32
  export type StoredModel = {
33
- /** Absolute path to the file — what a cognet ultimately receives. */
33
+ /**
34
+ * Absolute path — what a cognet ultimately receives.
35
+ *
36
+ * A FILE for a single-file weight, a DIRECTORY for a set. That difference
37
+ * is deliberately not a type distinction: llama.cpp takes a `.gguf` path
38
+ * and transformers.js takes a directory, so what a runtime wants is
39
+ * already a path either way. Widening this to a union would push a branch
40
+ * into every consumer to express something no consumer needs to know.
41
+ */
34
42
  path: string
43
+ /**
44
+ * The content hash. For a set, the PRIMARY weight's hash.
45
+ *
46
+ * Still an address of real bytes, so `has()` and the pinned-ref fast path
47
+ * keep working unchanged. It is not an address of the whole set — nothing
48
+ * needs one, because a set is addressed by its specifier.
49
+ */
35
50
  sha256: string
51
+ /** Bytes on disk. For a set, the sum of every file in it. */
36
52
  bytes: number
53
+ /** Absolute path to the weight inside a set. Absent for a single file. */
54
+ primary?: string
37
55
  }
38
56
 
57
+ /** One file inside a model set, at its path RELATIVE to the repository root. */
58
+ export type ModelFile = {
59
+ /** e.g. `onnx/model.onnx`, `config.json`. Never flattened — see `tree`. */
60
+ path: string
61
+ sha256: string
62
+ bytes: number
63
+ }
64
+
65
+ /**
66
+ * What a cached weight is, as the registry described it when it was fetched.
67
+ *
68
+ * Optional throughout: a weight fetched before this existed, or by a path that
69
+ * never knew, has none — and absent is an honest answer where "other" was a
70
+ * claim.
71
+ */
72
+ export type ModelTraits = {
73
+ capability?: string
74
+ type?: string
75
+ in?: string[]
76
+ out?: string[]
77
+ }
78
+
79
+ /**
80
+ * One cached weight that is a single file.
81
+ *
82
+ * Unchanged from the first version of this index, and deliberately so: a GGUF
83
+ * quantisation genuinely IS one file, and making it carry a one-element
84
+ * manifest would be ceremony around the common case.
85
+ */
86
+ type SingleEntry = {
87
+ sha256: string
88
+ file: string
89
+ traits?: ModelTraits
90
+ }
91
+
92
+ /**
93
+ * One cached weight that is a set of files.
94
+ *
95
+ * An ONNX repository is not a weight, it is a weight plus the tokeniser,
96
+ * preprocessor and generation config needed to turn a person's input into
97
+ * tensors. transformers.js reads those from a DIRECTORY laid out as the
98
+ * repository lays them out, which is why `files[].path` keeps its
99
+ * repository-relative shape rather than being flattened to a basename.
100
+ */
101
+ type SetEntry = {
102
+ /** Directory name under `root/trees` holding the materialised layout. */
103
+ tree: string
104
+ /** Every file, repository-relative. The manifest — this is the record. */
105
+ files: ModelFile[]
106
+ /** Which of `files` is the weight, for a runtime that wants one path. */
107
+ primary: string
108
+ traits?: ModelTraits
109
+ }
110
+
111
+ type Entry = SingleEntry | SetEntry
112
+
113
+ /** Discriminates the two shapes. A manifest has files; a single file has one name. */
114
+ function isSet(entry: Entry): entry is SetEntry {
115
+ return Array.isArray((entry as SetEntry).files)
116
+ }
117
+
118
+ /** The on-disk index: specifier → where the bytes are, and what they are. */
119
+ type IndexEntry = Record<string, Entry>
120
+
39
121
  function defaultRoot(): string {
40
122
  return process.env.AXON_MODELS_DIR ?? join(homedir(), ".axon", "models")
41
123
  }
42
124
 
43
125
  export function ModelStore(opts: ModelStoreOpts = {}) {
44
126
  const root = opts.root ?? defaultRoot()
45
- /** specifier → { sha256, file }. A hint for unpinned models; see resolved(). */
127
+ /** specifier → { sha256, file, traits? }. A hint for unpinned models; see resolved(). */
46
128
  const indexPath = join(root, "index.json")
47
129
 
48
130
  /** Where a given hash's file lives. Pure — no I/O. */
@@ -50,6 +132,30 @@ export function ModelStore(opts: ModelStoreOpts = {}) {
50
132
  return join(root, sha256, filename)
51
133
  }
52
134
 
135
+ /**
136
+ * Where a set's materialised layout lives.
137
+ *
138
+ * Separate from the content-addressed blobs, and under a directory of its
139
+ * own so a stray tree can never be mistaken for a hash. Trees hold
140
+ * HARDLINKS to the blobs: same bytes, no second copy, and removing a tree
141
+ * cannot damage a weight another specifier still names.
142
+ */
143
+ function treeFor(name: string): string {
144
+ return join(root, "trees", name)
145
+ }
146
+
147
+ /**
148
+ * A stable directory name for a specifier.
149
+ *
150
+ * Hashed rather than sanitised, because a specifier carries `/`, `@` and
151
+ * `:` and every escaping scheme that flattens those is a scheme two
152
+ * different specifiers can collide in. Truncated because this names a
153
+ * directory, not bytes — it needs to be unique, not tamper-evident.
154
+ */
155
+ function treeNameFor(specifier: string): string {
156
+ return createHash("sha256").update(specifier).digest("hex").slice(0, 32)
157
+ }
158
+
53
159
  return {
54
160
  get root() {
55
161
  return root
@@ -97,10 +203,32 @@ export function ModelStore(opts: ModelStoreOpts = {}) {
97
203
  * refetch and cannot produce wrong bytes.
98
204
  */
99
205
  async resolved(specifier: string): Promise<StoredModel | null> {
100
- const index = await fsx.readJson<Record<string, { sha256: string; file: string }>>(indexPath)
206
+ const index = await fsx.readJson<IndexEntry>(indexPath)
101
207
  const hit = index?.[specifier]
102
208
  if (!hit) return null
103
209
 
210
+ if (isSet(hit)) {
211
+ const tree = treeFor(hit.tree)
212
+ const primary = join(tree, hit.primary)
213
+ /*
214
+ * The PRIMARY file is the liveness test for the whole set.
215
+ *
216
+ * Checking all forty would be forty stats on a path a caller
217
+ * takes hundreds of times, and it would not buy correctness:
218
+ * a set missing a config fails at load with the file named,
219
+ * which is a better error than this could produce. The weight
220
+ * being gone is the case that means "not cached".
221
+ */
222
+ if (!fsx.isFile(primary)) return null
223
+ const weight = hit.files.find(file => file.path === hit.primary)
224
+ return {
225
+ path: tree,
226
+ sha256: weight?.sha256 ?? "",
227
+ bytes: hit.files.reduce((sum, file) => sum + file.bytes, 0),
228
+ primary: primary,
229
+ }
230
+ }
231
+
104
232
  const path = pathFor(hit.sha256, hit.file)
105
233
  if (!fsx.isFile(path)) return null
106
234
 
@@ -120,23 +248,168 @@ export function ModelStore(opts: ModelStoreOpts = {}) {
120
248
  * the index is a cache hint and the bytes are the fact, so an entry
121
249
  * pointing at nothing is stale rather than a model.
122
250
  */
123
- async list(): Promise<{ specifier: string; path: string; sha256: string; bytes: number }[]> {
124
- const index = await fsx.readJson<Record<string, { sha256: string; file: string }>>(indexPath)
251
+ async list(): Promise<{
252
+ specifier: string
253
+ path: string
254
+ sha256: string
255
+ bytes: number
256
+ primary?: string
257
+ traits?: ModelTraits
258
+ }[]> {
259
+ const index = await fsx.readJson<IndexEntry>(indexPath)
125
260
  if (!index) return []
126
261
 
127
- const found: { specifier: string; path: string; sha256: string; bytes: number }[] = []
262
+ const found: {
263
+ specifier: string
264
+ path: string
265
+ sha256: string
266
+ bytes: number
267
+ primary?: string
268
+ traits?: ModelTraits
269
+ }[] = []
270
+
128
271
  for (const [specifier, hit] of Object.entries(index)) {
272
+ if (isSet(hit)) {
273
+ const tree = treeFor(hit.tree)
274
+ const primary = join(tree, hit.primary)
275
+ if (!fsx.isFile(primary)) continue
276
+ const weight = hit.files.find(file => file.path === hit.primary)
277
+ found.push({
278
+ specifier,
279
+ path: tree,
280
+ sha256: weight?.sha256 ?? "",
281
+ // The manifest's own sum, not a walk of the tree. The
282
+ // sizes were measured when the bytes were verified;
283
+ // re-stating forty files per listing would be slower
284
+ // and no more true.
285
+ bytes: hit.files.reduce((sum, file) => sum + file.bytes, 0),
286
+ primary: primary,
287
+ ...(hit.traits ? { traits: hit.traits } : {}),
288
+ })
289
+ continue
290
+ }
291
+
129
292
  const path = pathFor(hit.sha256, hit.file)
130
293
  if (!fsx.isFile(path)) continue
131
- found.push({ specifier, path, sha256: hit.sha256, bytes: (await stat(path)).size })
294
+ found.push({
295
+ specifier,
296
+ path,
297
+ sha256: hit.sha256,
298
+ bytes: (await stat(path)).size,
299
+ ...(hit.traits ? { traits: hit.traits } : {}),
300
+ })
132
301
  }
133
302
  return found
134
303
  },
135
304
 
305
+ /**
306
+ * Record what a cached weight IS, beside where it landed.
307
+ *
308
+ * ── Why the store holds this ────────────────────────────────────────
309
+ *
310
+ * A file on disk declares no task: `model.onnx` could be a
311
+ * transcriber, an embedder or a face detector, and enumerating the
312
+ * cache could only ever report "other". The registry knows — it is in
313
+ * the listing that was open when the download started — and that
314
+ * knowledge was being thrown away the moment the bytes landed.
315
+ *
316
+ * So it is written down. Here rather than in a sidecar of its own,
317
+ * because the index is already the one record of "what has this
318
+ * machine fetched" and a second file would be a second answer to the
319
+ * same question, free to disagree.
320
+ *
321
+ * Merged, never replaced: the caller supplies what it knows and the
322
+ * rest survives.
323
+ */
324
+ async describe(specifier: string, traits: ModelTraits): Promise<void> {
325
+ const index = (await fsx.readJson<IndexEntry>(indexPath)) ?? {}
326
+ const hit = index[specifier]
327
+ // Describing something the store has never seen would write an
328
+ // entry with no bytes behind it, which `list()` would then skip
329
+ // forever. Silent because a describe racing a removal is ordinary.
330
+ if (!hit) return
331
+ index[specifier] = { ...hit, traits: { ...hit.traits, ...traits } }
332
+ await mkdir(root, { recursive: true })
333
+ await Bun.write(indexPath, JSON.stringify(index, null, 4))
334
+ },
335
+
336
+ /**
337
+ * Record a specifier that resolved to a SET of files, and materialise
338
+ * its layout.
339
+ *
340
+ * ── Why a tree of hardlinks ─────────────────────────────────────────
341
+ *
342
+ * Two requirements pull in opposite directions. Content-addressing is
343
+ * what lets ten agents share one weight, and `remove()`'s whole
344
+ * correctness argument rests on it. transformers.js, meanwhile, wants
345
+ * a DIRECTORY laid out as the repository lays it out — `config.json`
346
+ * beside `onnx/model.onnx` — because that is how it finds the
347
+ * tokeniser and preprocessor it needs.
348
+ *
349
+ * Hardlinks satisfy both. The blob stays the one copy of those bytes
350
+ * at its hash; the tree is a second name for the same inode. No extra
351
+ * disk, and `rm -rf` of a tree decrements a link count rather than
352
+ * destroying a weight some other specifier still points at.
353
+ *
354
+ * A copy is the fallback, and only for `EXDEV` — a link across
355
+ * filesystems. That cannot happen with the default root, but a
356
+ * relocated `AXON_MODELS_DIR` beside a bind-mounted blob store could
357
+ * produce it, and failing the whole fetch over a layout detail would
358
+ * be the wrong trade.
359
+ *
360
+ * ── The manifest is written LAST ────────────────────────────────────
361
+ *
362
+ * Files are linked first, index second. A crash in between leaves an
363
+ * orphaned tree nothing references, which the next fetch overwrites;
364
+ * the reverse order would leave the index claiming a model whose files
365
+ * are not there, and `resolved()` would hand a caller a path into
366
+ * nothing.
367
+ */
368
+ async rememberSet(
369
+ specifier: string,
370
+ files: { file: ModelFile; stored: StoredModel }[],
371
+ primary: string,
372
+ ): Promise<void> {
373
+ const name = treeNameFor(specifier)
374
+ const tree = treeFor(name)
375
+
376
+ // Replaced wholesale rather than merged: a refetch may resolve a
377
+ // different variant, and a tree holding both would hand
378
+ // transformers.js two models in one directory.
379
+ await rm(tree, { recursive: true, force: true })
380
+
381
+ for (const entry of files) {
382
+ const target = join(tree, entry.file.path)
383
+ await mkdir(join(target, ".."), { recursive: true })
384
+ try {
385
+ await link(entry.stored.path, target)
386
+ } catch (cause) {
387
+ if ((cause as { code?: string }).code !== "EXDEV") throw cause
388
+ await Bun.write(target, Bun.file(entry.stored.path))
389
+ }
390
+ }
391
+
392
+ const index = (await fsx.readJson<IndexEntry>(indexPath)) ?? {}
393
+ const previous = index[specifier]
394
+ index[specifier] = {
395
+ tree: name,
396
+ files: files.map(entry => entry.file),
397
+ primary: primary,
398
+ // Traits describe the MODEL, not the bytes — a refetch must
399
+ // not forget what it is.
400
+ ...(previous?.traits ? { traits: previous.traits } : {}),
401
+ }
402
+ await mkdir(root, { recursive: true })
403
+ await Bun.write(indexPath, JSON.stringify(index, null, 4))
404
+ },
405
+
136
406
  /** Record what a specifier resolved to, so the next run can skip the network. */
137
407
  async remember(specifier: string, stored: StoredModel, filename: string): Promise<void> {
138
- const index = (await fsx.readJson<Record<string, { sha256: string; file: string }>>(indexPath)) ?? {}
139
- index[specifier] = { sha256: stored.sha256, file: filename }
408
+ const index = (await fsx.readJson<IndexEntry>(indexPath)) ?? {}
409
+ // Traits are preserved across a re-fetch: they describe the MODEL,
410
+ // not the bytes, and re-downloading the same weight must not
411
+ // forget what it is.
412
+ index[specifier] = { ...index[specifier], sha256: stored.sha256, file: filename }
140
413
  await mkdir(root, { recursive: true })
141
414
  await Bun.write(indexPath, JSON.stringify(index, null, 4))
142
415
  },
@@ -226,7 +499,7 @@ export function ModelStore(opts: ModelStoreOpts = {}) {
226
499
  * has.
227
500
  */
228
501
  async remove(specifier: string): Promise<boolean> {
229
- const index = await fsx.readJson<Record<string, { sha256: string; file: string }>>(indexPath)
502
+ const index = await fsx.readJson<IndexEntry>(indexPath)
230
503
  const hit = index?.[specifier]
231
504
  if (!index || !hit) return false
232
505
 
@@ -234,13 +507,36 @@ export function ModelStore(opts: ModelStoreOpts = {}) {
234
507
  await mkdir(root, { recursive: true })
235
508
  await Bun.write(indexPath, JSON.stringify(index, null, 4))
236
509
 
237
- const shared = Object.values(index).some(entry => entry.sha256 === hit.sha256)
238
- if (shared) return true
510
+ /*
511
+ * Every hash the survivors still reference, from BOTH shapes.
512
+ *
513
+ * A set holds forty hashes and a single file holds one, and a blob
514
+ * may well be referenced by one of each — the same `model.onnx`
515
+ * fetched once on its own and once as part of a repository is one
516
+ * file at one address. Gathering the survivors into a set and
517
+ * asking it per hash is the only version of this that stays right
518
+ * as shapes are added; a check written per shape would have to be
519
+ * edited every time one is.
520
+ */
521
+ const live = new Set<string>()
522
+ for (const entry of Object.values(index)) {
523
+ if (isSet(entry)) for (const file of entry.files) live.add(file.sha256)
524
+ else live.add(entry.sha256)
525
+ }
526
+
527
+ // The tree goes unconditionally: it belongs to this specifier
528
+ // alone, and its hardlinks are references the blobs below have
529
+ // already been counted without.
530
+ if (isSet(hit)) await rm(treeFor(hit.tree), { recursive: true, force: true })
239
531
 
240
- // The hash directory, not just the file: a hash addresses exactly
241
- // one set of bytes, so with the last reference gone the directory
242
- // holding them has nothing left to hold.
243
- await rm(join(root, hit.sha256), { recursive: true, force: true })
532
+ const held = isSet(hit) ? hit.files.map(file => file.sha256) : [hit.sha256]
533
+ for (const sha256 of new Set(held)) {
534
+ if (live.has(sha256)) continue
535
+ // The hash directory, not just the file: a hash addresses
536
+ // exactly one set of bytes, so with the last reference gone
537
+ // the directory holding them has nothing left to hold.
538
+ await rm(join(root, sha256), { recursive: true, force: true })
539
+ }
244
540
  return true
245
541
  },
246
542
  }
@@ -275,6 +275,12 @@ export const CONFIG_DTS = HEADER + SHARED_BODY + `
275
275
  */
276
276
  const Axon: typeof import("@arcforge/engines").Axon
277
277
 
278
+ /** Local inference on this machine, managed by Axond. It is implicit; declare it only to override options. */
279
+ const Local: typeof import("@arcforge/engines").Local
280
+
281
+ /** Local inference on this machine, managed by Axond. It is implicit; declare it only to override options. */
282
+ const Local: typeof import("@arcforge/engines").Local
283
+
278
284
  /**
279
285
  * Ollama local inference.
280
286
  *
@@ -83,6 +83,8 @@ ${TUI_CONTRACT}
83
83
  * ProviderEntry itself is spelled out in tui.ts.
84
84
  */
85
85
  function Axon(options?: ProviderOptions): ProviderEntry
86
+ function Local(options?: ProviderOptions): ProviderEntry
87
+ function Local(options?: ProviderOptions): ProviderEntry
86
88
  function Codex(options?: ProviderOptions): ProviderEntry
87
89
  function OpenRouter(options?: ProviderOptions): ProviderEntry
88
90
  function Ollama(options?: ProviderOptions): ProviderEntry
@@ -1,7 +1,7 @@
1
1
  import { err } from "@arcforge/err"
2
2
  import { AxonSession } from "@arcforge/session"
3
3
  import { AxonBus } from "@arcforge/core"
4
- import type { AxonBlueprint, AxonEngineRawEvent, InferCall } from "@arcforge/types"
4
+ import type { AxonBlueprint, AxonEngineRawEvent, EngineCapability, InferCall } from "@arcforge/types"
5
5
  import type { AxonCloudClient } from "@arcforge/cloud"
6
6
  import { Inference } from "@arcforge/core"
7
7
 
@@ -26,6 +26,8 @@ type ServicesOpts = {
26
26
  cloud: AxonCloudClient
27
27
  /** Where the log lives. Opened here, on the supervisor's side. */
28
28
  sessionId: string
29
+ /** The daemon-owned local inference bridge for this machine. */
30
+ local?: { catalogue(): Promise<EngineCapability[]>; run(model: string, prompt: string): Promise<string> }
29
31
  }
30
32
 
31
33
  export async function SupervisorSideServices(opts: ServicesOpts) {
@@ -53,7 +55,12 @@ export async function SupervisorSideServices(opts: ServicesOpts) {
53
55
  * providers over the network and building a driver from a credential,
54
56
  * which is exactly the work the boundary exists to keep out of the box.
55
57
  */
56
- const engines = await Inference({ blueprint: opts.blueprint, cloud: opts.cloud, session })
58
+ const engines = await Inference({
59
+ blueprint: opts.blueprint,
60
+ cloud: opts.cloud,
61
+ session,
62
+ ...(opts.local ? { local: opts.local } : {}),
63
+ })
57
64
 
58
65
  return {
59
66
  session,