@arcforge/kernel 2.0.106 → 2.0.108
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 +8 -8
- package/src/kernel.ts +18 -5
- package/src/scheduler/continuous.ts +57 -24
- package/src/scheduler/scheduler.ts +24 -11
- package/src/scope-dts.ts +6 -0
- package/src/scope.ts +44 -1
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@arcforge/kernel",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.108",
|
|
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/cognet": "2.0.
|
|
19
|
-
"@arcforge/engines": "2.0.
|
|
20
|
-
"@arcforge/err": "2.0.
|
|
21
|
-
"@arcforge/session": "2.0.
|
|
22
|
-
"@arcforge/types": "2.0.
|
|
23
|
-
"@arclabs/cloud": "2.0.
|
|
24
|
-
"@axon/capsule": "2.0.
|
|
18
|
+
"@arcforge/cognet": "2.0.108",
|
|
19
|
+
"@arcforge/engines": "2.0.108",
|
|
20
|
+
"@arcforge/err": "2.0.108",
|
|
21
|
+
"@arcforge/session": "2.0.108",
|
|
22
|
+
"@arcforge/types": "2.0.108",
|
|
23
|
+
"@arclabs/cloud": "2.0.108",
|
|
24
|
+
"@axon/capsule": "2.0.108"
|
|
25
25
|
},
|
|
26
26
|
"devDependencies": {
|
|
27
27
|
"@types/bun": "latest",
|
package/src/kernel.ts
CHANGED
|
@@ -297,6 +297,16 @@ export async function Kernel(opts: KernelOpts) {
|
|
|
297
297
|
return { ok: true, entries }
|
|
298
298
|
},
|
|
299
299
|
|
|
300
|
+
/**
|
|
301
|
+
* Advance a continuous cognet by one wake, handing it whatever is on
|
|
302
|
+
* the stimulus buffer. Resolves false if a wake was already running
|
|
303
|
+
* and this tick was skipped — see scheduler/continuous.ts for why
|
|
304
|
+
* skipping is the policy and why it is a return value, not a throw.
|
|
305
|
+
*/
|
|
306
|
+
tick(): Promise<boolean> {
|
|
307
|
+
return scheduler.tick()
|
|
308
|
+
},
|
|
309
|
+
|
|
300
310
|
/** Abort the active wake, if any. Safe to call when idle. */
|
|
301
311
|
interrupt(reason: "user" | "shutdown" = "user") {
|
|
302
312
|
scheduler.interrupt(reason)
|
|
@@ -337,14 +347,17 @@ export async function Kernel(opts: KernelOpts) {
|
|
|
337
347
|
},
|
|
338
348
|
|
|
339
349
|
/**
|
|
340
|
-
* Drain the mind: abort any wake,
|
|
341
|
-
*
|
|
342
|
-
*
|
|
343
|
-
*
|
|
350
|
+
* Drain the mind: abort any wake, unload the brain, kill the
|
|
351
|
+
* userland. Session is not kernel's to close — AxonRuntime.shutdown()
|
|
352
|
+
* ends it after this resolves, so a failure here never skips flushing
|
|
353
|
+
* the log.
|
|
354
|
+
*
|
|
355
|
+
* No clock to stop: a continuous cognet is ticked by the body (a
|
|
356
|
+
* plugin driving `axon.tick()`), which tears its own interval down on
|
|
357
|
+
* `shutdown:before` — before this runs.
|
|
344
358
|
*/
|
|
345
359
|
async shutdown() {
|
|
346
360
|
scheduler.interrupt("shutdown")
|
|
347
|
-
scheduler.stop()
|
|
348
361
|
|
|
349
362
|
// A failed unload must never strand the userland: the capsule is
|
|
350
363
|
// a real OS process, and skipping its teardown leaks it for the
|
|
@@ -1,4 +1,3 @@
|
|
|
1
|
-
import { err } from "@arcforge/err"
|
|
2
1
|
import type { AxonEntry, AxonStimulusEntry } from "@arcforge/types"
|
|
3
2
|
import type { AxonSessionT } from "@arcforge/session"
|
|
4
3
|
|
|
@@ -10,33 +9,67 @@ type ContinuousOpts = {
|
|
|
10
9
|
}
|
|
11
10
|
|
|
12
11
|
/**
|
|
13
|
-
* Continuous trigger:
|
|
14
|
-
* anything arrived — an empty stimuli diff is the ordinary steady state,
|
|
15
|
-
* not an edge case a cognet needs to special-case.
|
|
12
|
+
* Continuous trigger: one wake per tick, driven by whoever owns the clock.
|
|
16
13
|
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
23
|
-
*
|
|
24
|
-
*
|
|
25
|
-
*
|
|
14
|
+
* THE BODY OWNS THE CLOCK, not the cognet and not the kernel. This used to
|
|
15
|
+
* hold a `start(tickMs)` that ran its own setInterval off a `tickMs` the
|
|
16
|
+
* cognet declared in its config — which had the brain asserting how fast the
|
|
17
|
+
* world turns, something it cannot possibly know, and contradicted the rule
|
|
18
|
+
* that a cognet learns nothing about its environment. The clock now lives in
|
|
19
|
+
* agent code (a plugin driving `axon.tick()`), where the thing that actually
|
|
20
|
+
* knows the world's rate can set it.
|
|
21
|
+
*
|
|
22
|
+
* What remains here is the one thing a caller must not have to reimplement:
|
|
23
|
+
* OVERLAP POLICY. A tick arriving while a wake is still running is SKIPPED,
|
|
24
|
+
* reported as `false`, and never throws. Skip rather than queue because a
|
|
25
|
+
* late tick is worthless to a controller — the freshest sense data is the
|
|
26
|
+
* only useful one, and a queue would put the mind further behind the world
|
|
27
|
+
* with every overrun. Rather than concurrent because one session is one log
|
|
28
|
+
* with one writer, and two wakes interleaving entries would corrupt the
|
|
29
|
+
* record that makes the mind replayable.
|
|
30
|
+
*
|
|
31
|
+
* That policy is not settled forever — cancelling the in-flight wake in
|
|
32
|
+
* favour of the newer sense data is a defensible alternative, and so is
|
|
33
|
+
* bounded concurrency. It is settled ENOUGH to ship, and the return value is
|
|
34
|
+
* what makes revisiting it cheap: a caller already distinguishes "ran" from
|
|
35
|
+
* "skipped", so a future policy change alters what fills the gap, not the
|
|
36
|
+
* contract.
|
|
26
37
|
*/
|
|
27
|
-
export function Continuous(
|
|
28
|
-
let timer: ReturnType<typeof setInterval> | null = null
|
|
29
|
-
|
|
38
|
+
export function Continuous(opts: ContinuousOpts) {
|
|
30
39
|
return {
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
40
|
+
/**
|
|
41
|
+
* Wake the cognet with whatever is on the stimulus buffer.
|
|
42
|
+
*
|
|
43
|
+
* Resolves `true` once the wake has fully drained, `false` when one
|
|
44
|
+
* was already in flight and this tick was skipped. Drives the wake to
|
|
45
|
+
* completion internally: a tick has no caller waiting on entries (a
|
|
46
|
+
* clock is not asking a question), so unlike invocation there is no
|
|
47
|
+
* wire to hand back — the entries reach the log, which is where a
|
|
48
|
+
* ticked cognet's output belongs.
|
|
49
|
+
*/
|
|
50
|
+
async tick(): Promise<boolean> {
|
|
51
|
+
let reservationId: string
|
|
52
|
+
try {
|
|
53
|
+
reservationId = opts.reserve()
|
|
54
|
+
} catch {
|
|
55
|
+
// The one contention path, and the reason this returns a
|
|
56
|
+
// boolean instead of throwing: a skipped tick is an ordinary
|
|
57
|
+
// steady state for a clock running near capacity, not an
|
|
58
|
+
// error. Callers fire this from an interval where a thrown
|
|
59
|
+
// RUN_IN_PROGRESS would surface as an unhandled rejection.
|
|
60
|
+
return false
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
const stimuli = opts.session.stimuli.drain()
|
|
64
|
+
|
|
65
|
+
// Drain the wake here rather than yielding it. runWake's finally
|
|
66
|
+
// releases the reservation, so the generator MUST be consumed to
|
|
67
|
+
// completion or the scheduler stays locked forever.
|
|
68
|
+
for await (const _entry of opts.runWake(reservationId, { stimuli })) {
|
|
69
|
+
// entries commit as they are produced; nothing to collect
|
|
70
|
+
}
|
|
36
71
|
|
|
37
|
-
|
|
38
|
-
if (timer) clearInterval(timer)
|
|
39
|
-
timer = null
|
|
72
|
+
return true
|
|
40
73
|
},
|
|
41
74
|
}
|
|
42
75
|
}
|
|
@@ -23,13 +23,19 @@ type InvokeInput = {
|
|
|
23
23
|
* once started (that's wake.ts, unchanged regardless of trigger source).
|
|
24
24
|
*
|
|
25
25
|
* Two trigger sources, one mechanism: invocation.ts fires on an admitted
|
|
26
|
-
* stimulus, continuous.ts fires
|
|
27
|
-
* runWake(), which drains session.stimuli and hands the diff to
|
|
28
|
-
* Neither trigger source knows the other exists; the cognet's
|
|
29
|
-
* `mode` picks which
|
|
26
|
+
* stimulus, continuous.ts fires when the body ticks it — both call the same
|
|
27
|
+
* internal runWake(), which drains session.stimuli and hands the diff to
|
|
28
|
+
* Wake(). Neither trigger source knows the other exists; the cognet's
|
|
29
|
+
* declared `mode` picks which verb is legal against it.
|
|
30
|
+
*
|
|
31
|
+
* Note the clock is NOT here. A continuous cognet is advanced by agent code
|
|
32
|
+
* calling axon.tick(); the scheduler owns what happens on contention, never
|
|
33
|
+
* when a tick occurs.
|
|
30
34
|
*
|
|
31
35
|
* SCHEDULING POLICY (policy, not physics — revisit without contract change):
|
|
32
|
-
* one wake at a time, globally. A concurrent invoke throws RUN_IN_PROGRESS
|
|
36
|
+
* one wake at a time, globally. A concurrent invoke throws RUN_IN_PROGRESS;
|
|
37
|
+
* a concurrent tick is skipped and reported as false, because a clock
|
|
38
|
+
* running near capacity is a steady state rather than a caller error.
|
|
33
39
|
*/
|
|
34
40
|
export function Scheduler(opts: SchedulerOpts) {
|
|
35
41
|
let cognet: KernelCognet | null = null
|
|
@@ -113,7 +119,19 @@ export function Scheduler(opts: SchedulerOpts) {
|
|
|
113
119
|
/** register the loaded cognet — the kernel runs load(abi) first */
|
|
114
120
|
attach(next: KernelCognet) {
|
|
115
121
|
cognet = next
|
|
116
|
-
|
|
122
|
+
},
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* Advance a continuous cognet by one wake. The clock belongs to the
|
|
126
|
+
* body (a plugin driving `axon.tick()`), never to this scheduler —
|
|
127
|
+
* see continuous.ts. Resolves false when a wake was already running.
|
|
128
|
+
*/
|
|
129
|
+
tick() {
|
|
130
|
+
if (!cognet) throw err("NO_COGNET_LOADED")
|
|
131
|
+
if (cognet.mode.kind !== "continuous") {
|
|
132
|
+
throw err("SCHEDULER_MODE_MISMATCH", { detail: "tick() drives continuous cognets; an invocation cognet wakes on a stimulus via stream()" })
|
|
133
|
+
}
|
|
134
|
+
return continuous.tick()
|
|
117
135
|
},
|
|
118
136
|
|
|
119
137
|
/** Invoke on a stimulus admission (invocation mode) — no-op shape for continuous cognets, which never call this. */
|
|
@@ -142,11 +160,6 @@ export function Scheduler(opts: SchedulerOpts) {
|
|
|
142
160
|
},
|
|
143
161
|
|
|
144
162
|
interrupt,
|
|
145
|
-
|
|
146
|
-
/** stop the continuous clock, if running — called on kernel shutdown/reload */
|
|
147
|
-
stop() {
|
|
148
|
-
continuous.stop()
|
|
149
|
-
},
|
|
150
163
|
}
|
|
151
164
|
}
|
|
152
165
|
|
package/src/scope-dts.ts
CHANGED
|
@@ -9,6 +9,12 @@ import type { AxonScope } from "@arcforge/types"
|
|
|
9
9
|
* calls in the author's own src/tools, src/scripts, hooks, and routes
|
|
10
10
|
* typecheck against exactly what the capsule will provide.
|
|
11
11
|
*
|
|
12
|
+
* These globals are real in host-side code, not only inside the capsule:
|
|
13
|
+
* Inject().runtime() binds each one to the matching axon.tools.* proxy when
|
|
14
|
+
* the runtime comes up (see core/src/platform/inject.ts). That is what makes
|
|
15
|
+
* this file honest — for a while it declared globals a script could not
|
|
16
|
+
* actually call, so `kanban.list()` typechecked and then threw at runtime.
|
|
17
|
+
*
|
|
12
18
|
* These two must never disagree about WHAT is in scope. They cannot,
|
|
13
19
|
* because neither decides it — toScope() does, once, and both render its
|
|
14
20
|
* result. This file only chooses how to spell it for `tsc`:
|
package/src/scope.ts
CHANGED
|
@@ -47,7 +47,50 @@ export function toScopeModule(tool: AxonTool): AxonScopeModule {
|
|
|
47
47
|
* The blueprint's executable scope. Tools with no loadable entry are
|
|
48
48
|
* excluded — declaring something the capsule cannot call would tell the
|
|
49
49
|
* model to invoke a function that does not exist there.
|
|
50
|
+
*
|
|
51
|
+
* Flat members are then deduped by CALLABLE NAME, which is a different
|
|
52
|
+
* question from the one merge() answers. merge() resolves collisions between
|
|
53
|
+
* TOOL names (the filename): an agent's `weather.ts` shadowing a module's
|
|
54
|
+
* `weather.ts`. It cannot see two differently-named files whose exports
|
|
55
|
+
* collide — an agent's `weather.ts` and a module's `forecast.ts` both
|
|
56
|
+
* exporting `now()` are two distinct tools by its reckoning, so both survive.
|
|
57
|
+
*
|
|
58
|
+
* Both then install flat, and everything downstream silently picks a winner:
|
|
59
|
+
* the .d.ts and the model's <scope> each declare `function now()` twice, and
|
|
60
|
+
* the capsule builds its globals with Object.assign, so whichever tool loads
|
|
61
|
+
* last wins and the other export is unreachable with nothing reported. The
|
|
62
|
+
* agent always wins here, matching merge()'s precedence, and the loser is
|
|
63
|
+
* dropped from the scope rather than rendered as a duplicate declaration.
|
|
50
64
|
*/
|
|
51
65
|
export function toScope(blueprint: AxonBlueprint): AxonScope {
|
|
52
|
-
|
|
66
|
+
const loadable = blueprint.tools.filter(isLoadable)
|
|
67
|
+
const claimed = new Set<string>()
|
|
68
|
+
const modules: AxonScopeModule[] = []
|
|
69
|
+
|
|
70
|
+
// Agent-origin tools first so they claim contested names, regardless of the
|
|
71
|
+
// order modules happen to appear in the blueprint.
|
|
72
|
+
for (const tool of [...loadable].sort((a, b) => rank(a) - rank(b))) {
|
|
73
|
+
const module = toScopeModule(tool)
|
|
74
|
+
if (!module.flat) {
|
|
75
|
+
modules.push(module)
|
|
76
|
+
continue
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
const members = module.members.filter(member => !claimed.has(member.name))
|
|
80
|
+
for (const member of members) claimed.add(member.name)
|
|
81
|
+
if (members.length > 0) modules.push({ ...module, members })
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
// Restore blueprint order: the filtering above needs agent-first, but the
|
|
85
|
+
// rendered scope should read in the order the blueprint declares.
|
|
86
|
+
return { modules: modules.sort((a, b) => order(loadable, a) - order(loadable, b)) }
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/** Agent-authored tools outrank module tools when both claim a callable name. */
|
|
90
|
+
function rank(tool: AxonTool): number {
|
|
91
|
+
return tool.origin === "module" ? 1 : 0
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
function order(tools: AxonTool[], module: AxonScopeModule): number {
|
|
95
|
+
return tools.findIndex(tool => tool.name === module.name)
|
|
53
96
|
}
|