@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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@arcforge/kernel",
3
- "version": "2.0.106",
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.106",
19
- "@arcforge/engines": "2.0.106",
20
- "@arcforge/err": "2.0.106",
21
- "@arcforge/session": "2.0.106",
22
- "@arcforge/types": "2.0.106",
23
- "@arclabs/cloud": "2.0.106",
24
- "@axon/capsule": "2.0.106"
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, stop the scheduler's clock (if
341
- * continuous), unload the brain, kill the userland. Session is not
342
- * kernel's to close — AxonRuntime.shutdown() ends it after this
343
- * resolves, so a failure here never skips flushing the log.
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: invoked on a fixed clock regardless of whether
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
- * STUBBED. Landing the shape (type, wiring, start/stop lifecycle) now
18
- * without guessing at tick semantics — no real continuous cognet exists
19
- * yet to validate wake-overlap policy against (does a slow tick skip the
20
- * next one, queue, or run concurrently?). Answering this without a real
21
- * workload would be exactly the kind of premature generalization this
22
- * whole redesign was trying to avoid. (The removal of "thread" as a
23
- * concept actually simplifies what's left to design here — there's no
24
- * longer a question of which of several conversations a tick addresses;
25
- * one cognet instance is always exactly one continuous stream.)
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(_opts: ContinuousOpts) {
28
- let timer: ReturnType<typeof setInterval> | null = null
29
-
38
+ export function Continuous(opts: ContinuousOpts) {
30
39
  return {
31
- start(_tickMs: number) {
32
- throw err("SCHEDULER_CONTINUOUS_NOT_IMPLEMENTED", {
33
- detail: "continuous mode is a declared, stubbed shape — no cognet may select it yet",
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
- stop() {
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 on a clock — both call the same internal
27
- * runWake(), which drains session.stimuli and hands the diff to Wake().
28
- * Neither trigger source knows the other exists; the cognet's declared
29
- * `mode` picks which one is wired up.
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
- if (next.mode.kind === "continuous") continuous.start(next.mode.tickMs)
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
- return { modules: blueprint.tools.filter(isLoadable).map(toScopeModule) }
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
  }