@arcforge/cognet 2.0.101 → 2.0.103

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcforge/cognet",
-  "version": "2.0.101",
+  "version": "2.0.103",
   "description": "A cognitive engine",
   "type": "module",
   "private": false,
@@ -18,8 +18,8 @@
     "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"
   },
   "dependencies": {
-    "@arcforge/err": "2.0.101",
-    "@arcforge/types": "2.0.101",
+    "@arcforge/err": "2.0.103",
+    "@arcforge/types": "2.0.103",
     "hookable": "^5.5.3"
   },
   "devDependencies": {

package/src/clock.ts

@@ -57,10 +57,11 @@ export function Clock(opts: ClockOpts) {
         async runTick<T>(fn: () => Promise<T>): Promise<T> {
             tick += 1
             const current = tick
+            const started = Date.now()
             void emit("cognet:tick:start", { tick: current })
             try {
                 const result = await fn()
-                void emit("cognet:tick:complete", { tick: current })
+                void emit("cognet:tick:complete", { tick: current, durationMs: Date.now() - started })
                 return result
             } catch (cause) {
                 if (signal?.aborted) {
@@ -68,7 +69,7 @@ export function Clock(opts: ClockOpts) {
                     throw cause
                 }
                 const failure = err(cause)
-                void emit("cognet:tick:failed", { tick: current, error: failure })
+                void emit("cognet:tick:failed", { tick: current, error: failure, durationMs: Date.now() - started })
                 throw failure
             }
         },
@@ -76,10 +77,11 @@ export function Clock(opts: ClockOpts) {
         /** A named stage within a tick. Sets the current phase for its duration. */
         async runPhase<T>(name: string, fn: () => Promise<T>): Promise<T> {
             phase = name
+            const started = Date.now()
             void emit("cognet:phase:start", { tick, phase: name })
             try {
                 const result = await fn()
-                void emit("cognet:phase:complete", { tick, phase: name })
+                void emit("cognet:phase:complete", { tick, phase: name, durationMs: Date.now() - started })
                 return result
             } catch (cause) {
                 if (signal?.aborted) {
@@ -87,14 +89,14 @@ export function Clock(opts: ClockOpts) {
                     throw cause
                 }
                 const failure = err(cause)
-                void emit("cognet:phase:failed", { tick, phase: name, error: failure })
+                void emit("cognet:phase:failed", { tick, phase: name, error: failure, durationMs: Date.now() - started })
                 throw failure
             } finally {
                 phase = null
             }
         },
 
-        /** A unit of work within a phase. Timed for the flame graph. */
+        /** A unit of work within a phase — the innermost bracket. */
         async runSystem<T>(name: string, fn: () => Promise<T>): Promise<T> {
             const started = Date.now()
             void emit("cognet:system:start", { ...stamp(), system: name })
@@ -108,7 +110,7 @@ export function Clock(opts: ClockOpts) {
                     throw cause
                 }
                 const failure = err(cause)
-                void emit("cognet:system:failed", { ...stamp(), system: name, error: failure })
+                void emit("cognet:system:failed", { ...stamp(), system: name, error: failure, durationMs: Date.now() - started })
                 throw failure
             }
         },

package/src/ecs/component.ts

@@ -9,12 +9,26 @@ type ComponentOpts = {
 
 /**
  * Component — the single write path for component data.
- * Every write emits kernel telemetry and fires watchers; Entity() delegates
+ * Every write emits cognet telemetry and fires watchers; Entity() delegates
  * here so there is exactly one place a component can change.
  *
- * Telemetry goes to the runtime bus (→ tracing pipeline), never the session
- * log. Bus emit never rejects (handler errors are re-emitted as
- * axon:bus:error), so firing without await keeps writes synchronous.
+ * DURABILITY. These events go through abi.emit, which commits to the
+ * session log like every other cognet:* event and forwards to the bus after
+ * the append lands. They are not bus-only — a brain whose world mutations
+ * vanish on restart cannot be debugged after the fact, which is the whole
+ * point of the log.
+ *
+ * The cost is real and known: a continuous-mode cognet ticking fast writes
+ * one durable line per component change, which is the highest-volume event
+ * source in the system by construction. That is acceptable while the ECS is
+ * opt-in and unwired (no cognet constructs Ecs() today). Whoever wires the
+ * first continuous world should measure it and, if it bites, gate at the
+ * write — sample, batch, or make durability a per-component declaration.
+ * Do NOT "fix" it by quietly routing these to the bus alone; that trades a
+ * measurable cost for an invisible hole.
+ *
+ * emit() is fire-and-forget by design (sync, void) so a world write is never
+ * an await point.
  */
 export function Component(opts: ComponentOpts) {
     const { state, emit } = opts