omkit 0.0.12 → 0.0.13

package/dist/actions/chrome-page.js

@@ -65,15 +65,15 @@ export const chromePage = action("Chrome Page")
     }
     page.on("console", (msg) => {
         logs.append({ source: label, level: "info", message: `console: ${msg.text()}` });
-        emit("console", msg.text());
+        emit("console", `from: ${label}:  ${msg.text()}`);
     });
     page.on("pageerror", (err) => {
         logs.append({ source: label, level: "error", message: err.message });
-        emit("pageerror", err.message);
+        emit("pageerror", `from: ${label}:  ${err.message}`);
     });
     page.on("framenavigated", (frame) => {
         if (frame === page.mainFrame())
-            emit("navigated", frame.url());
+            emit("navigated", `${label}: ${frame.url()}`);
     });
     if (url) {
         await page.goto(url);

package/dist/actions/command.d.ts

@@ -6,8 +6,6 @@ export interface CommandOptions {
      * node was executed from (process.cwd()). Default ".".
      */
     cwd?: string;
-    /** Label the child's output is logged under. Defaults to the action's name. */
-    label?: string;
     /**
      * Environment for the child. Pass the full set you want (e.g.
      * `{ ...process.env, NODE_ENV: "development" }`) — it's handed to the child

package/dist/actions/command.js

@@ -21,7 +21,7 @@ export function command(name, cmdOrFile, argsOrOptions, maybeOptions) {
         // against process.cwd() — exactly the "absolute from where node runs" rule.
         const cwd = path.resolve(options.cwd ?? ".");
         // proc sources the LogsCollector from async context and streams output into it.
-        return proc(options.label ?? name, {
+        return proc(name, {
             cwd,
             ...(options.env ? { env: options.env } : {}),
         })(verbatim(cmdOrFile));
@@ -36,7 +36,7 @@ export function command(name, cmdOrFile, argsOrOptions, maybeOptions) {
  */
 const spawnDirect = (snapshots, logs, signal, name, file, args, options) => {
     const cwd = path.resolve(options.cwd ?? ".");
-    const source = options.label ?? name;
+    const source = name;
     // windowsHide keeps a stray console window from flashing for the child.
     // env omitted -> spawn inherits the parent's process.env (Node's default).
     const child = spawn(file, args, { cwd, windowsHide: true, env: options.env });

package/dist/index.d.ts

@@ -10,6 +10,8 @@
  */
 export { action } from "./orchestration/action/action.ts";
 export type { Action, ActionBuilder, ActionInstance, AnyActionInstance, ActionContext, SystemGlobal, SystemEvents, InstanceEvents, NoEvents, Awaitable, Outcome, } from "./orchestration/action/types.ts";
+export { AssertionError } from "./orchestration/assert.ts";
+export type { Assert } from "./orchestration/assert.ts";
 export { spin } from "./orchestration/spin/spin.ts";
 export type { Nod, SpinContext, SpinBody } from "./orchestration/spin/types.ts";
 export { events } from "./orchestration/events/events.ts";

package/dist/index.js

@@ -10,6 +10,7 @@
  */
 // ── Actions ────────────────────────────────────────────────────────────────
 export { action } from "./orchestration/action/action.js";
+export { AssertionError } from "./orchestration/assert.js";
 // ── Spin (linear orchestration) ──────────────────────────────────────────────
 export { spin } from "./orchestration/spin/spin.js";
 // ── Events ─────────────────────────────────────────────────────────────────

package/dist/orchestration/action/action.js

@@ -123,6 +123,7 @@ class ActionRun {
                 signal: ctx.signal,
                 nod: ctx.nod,
                 output: ctx.output,
+                assert: ctx.assert,
             });
             // Re-throw the inner failure so the wrapper fails too (the framework re-wraps
             // it into this wrapper's own Outcome); only record on success.

package/dist/orchestration/action/types.d.ts

@@ -2,6 +2,7 @@ import type { Logger } from "../../output/log/LogsCollector.ts";
 import type { Output } from "../../output/Output.ts";
 import type { Emitter, EventHandler } from "../events/events.ts";
 import type { Proc } from "../../system/process/process.ts";
+import type { Assert } from "../assert.ts";
 /** An action that declares no events. */
 export type NoEvents = Record<never, never>;
 /** A value an action's `exec` may return: a result, or a promise of one. */
@@ -67,6 +68,12 @@ export interface SystemGlobal {
      * capture their own artifacts.
      */
     readonly output: Output;
+    /**
+     * Assert a boolean invariant for this action. Logs a `⊨` line every call; a
+     * mismatch is recorded into the run's verdict (never throws, never stops the
+     * run). Bound to this action's path for attribution.
+     */
+    readonly assert: Assert;
 }
 /** What an action's implementation receives: the system bag, plus `emit`, `attach`, and `proc`. */
 export interface ActionContext<Events extends object, Handle = void> extends SystemGlobal {

package/dist/orchestration/assert.d.ts

@@ -0,0 +1,22 @@
+import type { Logger } from "../output/log/LogsCollector.ts";
+/**
+ * An inline check injected into every action's `ctx` and the `spin` body. Passes
+ * when `value` is `true`. Every call is logged; a failure is recorded into the
+ * run's verdict — as data, not a throw — so the run keeps going and later
+ * assertions still fire. Returns the pass boolean so a body can branch on it.
+ *
+ *   assert(page.isVisible(), "page loaded")
+ */
+export type Assert = (value: boolean, what: string) => boolean;
+/** Marks a failed assertion in the spin's verdict, distinct from an action's own error. */
+export declare class AssertionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Build an {@link Assert} bound to one action (or the spin body): `name` is its
+ * launch path (used for attribution in the log line and the error), `logs` is the
+ * logger to append to, and `onFail` records a genuine failure into the verdict. The
+ * factory is file-agnostic — it only appends `level: "assert"` entries; the
+ * dedicated `assertions.log` is a downstream projection of that stream.
+ */
+export declare function createAssert(name: string, logs: Logger, onFail: (error: AssertionError) => void): Assert;

package/dist/orchestration/assert.js

@@ -0,0 +1,26 @@
+/** Marks a failed assertion in the spin's verdict, distinct from an action's own error. */
+export class AssertionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AssertionError";
+    }
+}
+/**
+ * Build an {@link Assert} bound to one action (or the spin body): `name` is its
+ * launch path (used for attribution in the log line and the error), `logs` is the
+ * logger to append to, and `onFail` records a genuine failure into the verdict. The
+ * factory is file-agnostic — it only appends `level: "assert"` entries; the
+ * dedicated `assertions.log` is a downstream projection of that stream.
+ */
+export function createAssert(name, logs, onFail) {
+    return (value, what) => {
+        const pass = value;
+        const glyph = pass ? "✓" : "✗";
+        const message = `${name} · ${glyph} ${what}`;
+        logs.append({ source: "assert", level: "assert", message });
+        if (!pass) {
+            onFail(new AssertionError(`${name}: ${what}`));
+        }
+        return pass;
+    };
+}

package/dist/orchestration/spin/SpinHost.js

@@ -4,6 +4,7 @@ import { LogsCollector, ScopedLogger } from "../../output/log/LogsCollector.js";
 import { LogRenderer } from "../../output/log/LogRenderer.js";
 import { actionScope, captureConsole } from "../../output/log/console-capture.js";
 import { Output } from "../../output/Output.js";
+import { createAssert } from "../assert.js";
 /** The entry script, relative to where node was invoked (so the log says what produced it). */
 const scriptPath = () => {
     const entry = process.argv[1];
@@ -239,6 +240,16 @@ export class SpinHost {
             this.nodInto(child, path);
             return child;
         };
+        // A boolean check bound to this action's path: it logs a `⊨` milestone, and a
+        // mismatch records a verdict failure the same way an action's own failure does
+        // — skipped during teardown (cascade, not a fault). Uses `this.logs` (not
+        // `scoped`) the same way `record` below does: the path is already embedded in
+        // the message via `name`, so routing through `scoped` would double-prefix the
+        // `source` field for a nodded child.
+        const assert = createAssert(path, this.logs, (error) => {
+            if (!this.controller.signal.aborted)
+                this.recordFailure(path, error);
+        });
         this.narrate(`launch ${path}`);
         // The action logs into this run's shared store (entries carry their `source`;
         // grouping is applied at render time) and gets the spin's signal directly; the
@@ -259,7 +270,13 @@ export class SpinHost {
                 this.recordFailure(path, error);
         };
         const promise = actionScope
-            .run(path, () => instance.start({ logs: scoped, signal: this.controller.signal, nod, output: this.output }))
+            .run(path, () => instance.start({
+            logs: scoped,
+            signal: this.controller.signal,
+            nod,
+            output: this.output,
+            assert,
+        }))
             .then((outcome) => {
             if (!outcome.ok)
                 record(outcome.error);

package/dist/orchestration/spin/spin.js

@@ -41,6 +41,7 @@ export function spin(body) {
             // the body from there rather than reaching for a module singleton.
             artifactsFolder: ctx.artifactsFolder,
             snapshot: (name, value) => ctx.output.snapshots.snapshot(name, value),
+            assert: ctx.assert,
         });
     });
     const mainSpinAction = hostAction();

package/dist/orchestration/spin/types.d.ts

@@ -1,5 +1,6 @@
 export type { Nod } from "../action/types.ts";
 import type { Nod } from "../action/types.ts";
+import type { Assert } from "../assert.ts";
 /** What a {@link spin} body receives. */
 export interface SpinContext {
     /** Launch an action into the spin; returns the instance for awaiting/chaining. */
@@ -25,6 +26,12 @@ export interface SpinContext {
      * run-scoped counterpart to the action `ctx.output.snapshots`.
      */
     readonly snapshot: (name: string, value: unknown) => Promise<string>;
+    /**
+     * Assert a boolean invariant from the spin body. Same semantics as the action
+     * `ctx.assert`; body assertions are attributed to the host action path
+     * (`omkit:Spin`).
+     */
+    readonly assert: Assert;
 }
 /** The body of a {@link spin}: any (async) function — it isn't named or wrapped by you. */
 export type SpinBody = (ctx: SpinContext) => void | Promise<void>;

package/dist/output/log/LogRenderer.d.ts

@@ -1,6 +1,6 @@
 import type { LogEntry } from "./LogsCollector.ts";
 /** The special "title" log lines that get a distinguishing prefix. */
-export type MarkerKind = "event" | "action" | "run" | "snapshot";
+export type MarkerKind = "event" | "action" | "run" | "snapshot" | "assert";
 /** A run set aside for collapsing: its source and every output line, in order. */
 export interface CollapsedRun {
     readonly source: string;

package/dist/output/log/LogRenderer.js

@@ -3,6 +3,7 @@ const PREFIX = {
     action: "▸",
     run: "●",
     snapshot: "📎",
+    assert: "⊨",
 };
 /**
  * Levels that render as their own top-level milestone line — marker-prefixed and
@@ -13,6 +14,7 @@ const MILESTONE = {
     run: "run",
     event: "event",
     snapshot: "snapshot",
+    assert: "assert",
 };
 /** Only runs *longer than* this collapse, so a trigger always hides a meaningful amount. */
 const COLLAPSE_THRESHOLD = 15;

package/dist/output/log/RunLog.js

@@ -37,10 +37,18 @@ export class RunLog {
         const pretty = createWriteStream(this.folder.resolve("run.log"));
         const renderer = new LogRenderer();
         pretty.write(this.header() + "\n");
+        // The dedicated assertions file is a filtered projection of the same stream:
+        // opened lazily on the first `assert` entry (so runs with none produce no file),
+        // one `⊨ …` line each. Assertions still ride the main run.jsonl / run.log too.
+        let assertions;
         try {
             for await (const entry of entries) {
                 jsonl.write(JSON.stringify(entry) + "\n");
                 pretty.write(renderer.render(entry) + "\n");
+                if (entry.level === "assert") {
+                    assertions ??= createWriteStream(this.folder.resolve("assertions.log"));
+                    assertions.write(LogRenderer.marker("assert", entry.message) + "\n");
+                }
             }
         }
         finally {
@@ -49,7 +57,11 @@ export class RunLog {
             // this stream landed *after* write() truncated run.log, the OS would zero-fill the
             // gap — a multi-MB run of NUL bytes. `run` awaits this promise before calling
             // write(), so this writer is guaranteed done first (and run.jsonl is complete).
-            await Promise.all([closeStream(jsonl), closeStream(pretty)]);
+            await Promise.all([
+                closeStream(jsonl),
+                closeStream(pretty),
+                ...(assertions ? [closeStream(assertions)] : []),
+            ]);
         }
     }
     /**
@@ -112,7 +124,7 @@ export class RunLog {
         const now = new Date();
         return [
             `─── ${this.folder.name()} · ${ymd(now)} ${hms(now)} ───`,
-            `● run  ⚡ event  ▸ action  📎 snapshot  ⇥ output`,
+            `● run  ⚡ event  ▸ action  📎 snapshot  ⇥ output  ⊨ assert`,
             "",
         ].join("\n");
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omkit",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "description": "A tiny runtime for developer workflows: typed actions that pass runtime capabilities and emit typed events, under one run and one shared log. The operational/runtime layer to tskb's knowledge layer.",
   "type": "module",
   "main": "./dist/index.js",