@arcforge/kernel 2.0.107 → 2.0.109
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/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@arcforge/kernel",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.109",
|
|
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.109",
|
|
19
|
+
"@arcforge/engines": "2.0.109",
|
|
20
|
+
"@arcforge/err": "2.0.109",
|
|
21
|
+
"@arcforge/session": "2.0.109",
|
|
22
|
+
"@arcforge/types": "2.0.109",
|
|
23
|
+
"@arclabs/cloud": "2.0.109",
|
|
24
|
+
"@axon/capsule": "2.0.109"
|
|
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
|
|