@arcforge/kernel 2.0.141 → 2.0.142

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/kernel",
3
- "version": "2.0.141",
3
+ "version": "2.0.142",
4
4
  "description": "The Axon kernel — ring 0. Owns resources and execution, enforces policy, and is the only constructor of the unprivileged capsule.",
5
5
  "type": "module",
6
6
  "private": false,
@@ -15,13 +15,13 @@
15
15
  "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"
16
16
  },
17
17
  "dependencies": {
18
- "@arcforge/air": "2.0.141",
19
- "@arcforge/engines": "2.0.141",
20
- "@arcforge/err": "2.0.141",
21
- "@arcforge/session": "2.0.141",
22
- "@arcforge/types": "2.0.141",
23
- "@arclabs/cloud": "2.0.141",
24
- "@axon/capsule": "2.0.141"
18
+ "@arcforge/air": "2.0.142",
19
+ "@arcforge/engines": "2.0.142",
20
+ "@arcforge/err": "2.0.142",
21
+ "@arcforge/session": "2.0.142",
22
+ "@arcforge/types": "2.0.142",
23
+ "@arclabs/cloud": "2.0.142",
24
+ "@axon/capsule": "2.0.142"
25
25
  },
26
26
  "devDependencies": {
27
27
  "@types/bun": "latest",
package/src/kernel.ts CHANGED
@@ -9,6 +9,7 @@ import { AxonCapsule, type AxonCapsuleT } from "./capsule"
9
9
  import { Scheduler } from "./scheduler"
10
10
  import type { KernelCognet } from "./contracts"
11
11
  import { Store } from "./store"
12
+ import { Knowledge } from "./knowledge"
12
13
  import type { AxonHost } from "@arcforge/types"
13
14
 
14
15
  type KernelOpts = {
@@ -195,6 +196,33 @@ export async function Kernel(opts: KernelOpts) {
195
196
  session: session,
196
197
  })
197
198
 
199
+ /**
200
+ * Long-term knowledge — the agent's own data/knowledge/ plus every
201
+ * module's, discovered by the build and carried on the blueprint.
202
+ *
203
+ * Entries rather than a directory to walk: a module's corpus stays in its
204
+ * own package, so the runtime is handed paths the same way it is handed
205
+ * resolved model weights. Writes still resolve against the AGENT root
206
+ * (paths.root, not paths.data — authored input, not runtime output), and
207
+ * module material is read-only.
208
+ *
209
+ * Mutations commit through the kernel, never the cognet: same rule as
210
+ * run()'s action/result pair — the brain requests, the kernel records.
211
+ * Fire-and-forget with a swallowed rejection for the same reason emit()
212
+ * swallows: the write already succeeded and resolved to the caller, so a
213
+ * failed telemetry append has nowhere to surface, and must never take
214
+ * down the runtime it is observing.
215
+ */
216
+ const knowledge = Knowledge({
217
+ root: opts.blueprint.paths.root,
218
+ entries: opts.blueprint.knowledge,
219
+ onMutate: (event, name) => {
220
+ void session
221
+ .commit(`cognet:knowledge:${event}`, { name }, scheduler.current() ?? undefined)
222
+ .catch(() => {})
223
+ },
224
+ })
225
+
198
226
  /**
199
227
  * One block or many (concurrent, Promise.all-shaped) — always resolves.
200
228
  *
@@ -425,6 +453,11 @@ export async function Kernel(opts: KernelOpts) {
425
453
  // access, one mediated door like stream/run (see Store())
426
454
  store: store,
427
455
 
456
+ // long-term knowledge — the durable, human-readable counterpart to
457
+ // store's private kv. Same mediation (a name in, the kernel owns the
458
+ // path), different doctrine: this is the record, not a cache.
459
+ knowledge: knowledge,
460
+
428
461
  // The brain's own rhythm. Called from a cognet plugin, never from the
429
462
  // body — see KernelAbi.wake for why the body must not drive this.
430
463
  // Deliberately NOT awaited into the wake: admission is the contract,
@@ -0,0 +1,204 @@
1
+ import { existsSync } from "node:fs"
2
+ import { mkdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises"
3
+ import path from "node:path"
4
+ import { err } from "@arcforge/err"
5
+ import type { AxonKnowledge, KernelKnowledge, KnowledgeEntry } from "@arcforge/types"
6
+
7
+ type KnowledgeOpts = {
8
+ /** The agent root — <root>/data/knowledge/ is the writable store. */
9
+ root: string
10
+ /**
11
+ * Every knowledge file this agent can reach, discovered at build time —
12
+ * its own plus each installed module's, already namespaced.
13
+ *
14
+ * Carried rather than walked because a module's corpus lives in its own
15
+ * package: enumerating one directory would have meant copying every
16
+ * module's material into the agent, which forks it on the first update
17
+ * and duplicates megabytes per agent.
18
+ */
19
+ entries: readonly AxonKnowledge[]
20
+ /** Committed by the kernel on every mutation; the cognet never writes its own record. */
21
+ onMutate?: (event: "write" | "remove", name: string) => void
22
+ }
23
+
24
+ /**
25
+ * The writable store's layout authority — the ONE place that knows an
26
+ * agent's own knowledge lives at <agent>/data/knowledge/.
27
+ *
28
+ * Only the agent's own material has a layout here. A module's files are
29
+ * addressed by the absolute path the build recorded, because they live
30
+ * wherever the package manager put them.
31
+ */
32
+ function storeRoot(root: string): string {
33
+ return path.join(root, "data", "knowledge")
34
+ }
35
+
36
+ /**
37
+ * Resolve a name to a path inside the agent's OWN store, refusing anything
38
+ * that leaves it.
39
+ *
40
+ * A name is an IDENTIFIER, not a path — "axon/terminal.md" is a name whose
41
+ * separators happen to nest. Traversal is refused rather than sanitised
42
+ * because a caller that wrote "../../.env" meant something, and quietly
43
+ * rewriting it to a different file is worse than failing.
44
+ *
45
+ * Enforced, not trusted: the cognet is not adversarial, but a boundary that
46
+ * only holds for well-behaved code is not a boundary.
47
+ */
48
+ function resolveOwn(root: string, name: string): string {
49
+ const store = storeRoot(root)
50
+ const target = path.resolve(store, name)
51
+ const contained = target === store || target.startsWith(store + path.sep)
52
+ if (!contained) {
53
+ throw err("KNOWLEDGE_ESCAPE", { detail: `knowledge name "${name}" resolves outside the store`, context: { name } })
54
+ }
55
+ return target
56
+ }
57
+
58
+ /**
59
+ * Pull a one-line summary out of a written entry's frontmatter.
60
+ *
61
+ * A near-duplicate of the build scanner's parse, and deliberately so: this
62
+ * one runs against content already in memory for a single file the agent
63
+ * just wrote, while the scanner reads 4KB heads off disk across a whole
64
+ * corpus. Sharing would mean the kernel importing the build, which inverts
65
+ * the dependency — ring 0 must not depend on the CLI that produced its
66
+ * blueprint. Both are ten lines and neither is load-bearing on the other:
67
+ * a drift costs one entry a description until the next scan corrects it.
68
+ */
69
+ function describe(content: string): string {
70
+ if (!content.startsWith("---")) return ""
71
+ const end = content.indexOf("\n---", 3)
72
+ if (end < 0) return ""
73
+
74
+ let title = ""
75
+ for (const line of content.slice(3, end).split("\n")) {
76
+ const match = /^\s*(description|title)\s*:\s*(.+?)\s*$/.exec(line)
77
+ if (!match) continue
78
+ const value = match[2]!.replace(/^["'](.*)["']$/, "$1")
79
+ if (match[1] === "description") return value
80
+ title ||= value
81
+ }
82
+ return title
83
+ }
84
+
85
+ /**
86
+ * Knowledge — the cognet's long-term store, mediated.
87
+ *
88
+ * A leaf that owns one concern completely: reading and writing knowledge by
89
+ * NAME. It holds no cognition — no ranking, no retrieval strategy, no notion
90
+ * of relevance. `match` filters on metadata the caller supplied; everything
91
+ * else a brain wants (full-text search, embeddings, a symbolic index) it
92
+ * builds itself, because choosing how a mind recalls is memory policy and the
93
+ * kernel is forbidden from holding one.
94
+ *
95
+ * READS span every source; WRITES only ever touch the agent's own store.
96
+ * A module's files live under node_modules and the next install would
97
+ * destroy anything written there — so a write addressed at module material
98
+ * fails loudly rather than succeeding and disappearing later.
99
+ *
100
+ * See KernelKnowledge in @arcforge/types for the full doctrine.
101
+ */
102
+ export function Knowledge(opts: KnowledgeOpts): KernelKnowledge {
103
+ /**
104
+ * Name → the build's record of it, plus anything written since.
105
+ *
106
+ * Live rather than frozen at construction because the catalogue is the
107
+ * read path's index: an agent that wrote a memory and could not list or
108
+ * read it back until the next scan would have a store that silently
109
+ * forgets, which is precisely the self-managed-memory case this exists
110
+ * for. Writes register here; removals drop out.
111
+ */
112
+ const byName = new Map(opts.entries.map(entry => [entry.name, entry]))
113
+
114
+ return {
115
+ async list(listOpts) {
116
+ // Ordered before filtering and before the cap, so `limit` yields a
117
+ // stable prefix of one total order rather than whichever order the
118
+ // scan happened to produce.
119
+ const entries: KnowledgeEntry[] = [...byName.values()]
120
+ .map(entry => ({ name: entry.name, description: entry.description, size: entry.size, path: entry.path }))
121
+ .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
122
+
123
+ const match = listOpts?.match?.toLowerCase()
124
+ const filtered = match
125
+ ? entries.filter(entry => entry.name.toLowerCase().includes(match) || entry.description.toLowerCase().includes(match))
126
+ : entries
127
+
128
+ return listOpts?.limit === undefined ? filtered : filtered.slice(0, listOpts.limit)
129
+ },
130
+
131
+ async read(name) {
132
+ // The catalogue is the index: a name it knows resolves to the path
133
+ // the build recorded, wherever that package lives. A name it does
134
+ // not know may still be something the agent wrote since the scan,
135
+ // so its own store is checked before giving up.
136
+ const known = byName.get(name)
137
+ const file = known ? known.path : resolveOwn(opts.root, name)
138
+
139
+ if (!existsSync(file)) {
140
+ throw err("KNOWLEDGE_NOT_FOUND", { detail: `no knowledge entry named "${name}"`, context: { name } })
141
+ }
142
+ return readFile(file, "utf-8")
143
+ },
144
+
145
+ async write(name, content) {
146
+ const known = byName.get(name)
147
+ if (known?.origin === "module") {
148
+ throw err("KNOWLEDGE_READONLY", {
149
+ detail: `"${name}" belongs to module ${known.module} and cannot be written`,
150
+ context: { name, module: known.module ?? "" },
151
+ })
152
+ }
153
+
154
+ const file = resolveOwn(opts.root, name)
155
+ await mkdir(path.dirname(file), { recursive: true })
156
+
157
+ // Atomic, like store.set() — but for a different reason. The kv is
158
+ // a cache and a torn write there costs a rebuild; knowledge is the
159
+ // record, so a half-written entry is real loss. temp + rename means
160
+ // a kill mid-write leaves the previous content intact.
161
+ const tmp = `${file}.${crypto.randomUUID().slice(0, 8)}.tmp`
162
+ await writeFile(tmp, content)
163
+ await rename(tmp, file)
164
+
165
+ // Register it so the catalogue reflects the write immediately. The
166
+ // build rescans on the next prepare and supersedes this, but a
167
+ // brain must be able to list and read back what it just wrote
168
+ // within the same session.
169
+ byName.set(name, {
170
+ name,
171
+ description: describe(content),
172
+ size: Buffer.byteLength(content),
173
+ path: file,
174
+ origin: "agent",
175
+ })
176
+
177
+ opts.onMutate?.("write", name)
178
+ },
179
+
180
+ async remove(name) {
181
+ const known = byName.get(name)
182
+ if (known?.origin === "module") {
183
+ throw err("KNOWLEDGE_READONLY", {
184
+ detail: `"${name}" belongs to module ${known.module} and cannot be removed`,
185
+ context: { name, module: known.module ?? "" },
186
+ })
187
+ }
188
+
189
+ const file = resolveOwn(opts.root, name)
190
+ // Idempotent: a brain pruning its own memory should not have to
191
+ // check first, and "already gone" is the outcome it wanted.
192
+ if (!existsSync(file)) {
193
+ byName.delete(name)
194
+ return
195
+ }
196
+ await unlink(file)
197
+ byName.delete(name)
198
+
199
+ opts.onMutate?.("remove", name)
200
+ },
201
+ }
202
+ }
203
+
204
+ export type KnowledgeT = ReturnType<typeof Knowledge>