toiljs 0.0.59 → 0.0.61

package/src/devserver/wasm/surface.ts

@@ -0,0 +1,88 @@
+/**
+ * Parse a compiled artifact's `toil.surface` custom section. Emitted into EVERY
+ * Toil artifact by the toilscript `buildToilSurface` pass (hot AND cold). The dev
+ * server reads it to decide whether each artifact carries the daemon surface
+ * (start the daemon emulator) or the stream surface (Phase 4, deferred).
+ *
+ * Byte layout (RECONCILIATION Part 5, all little-endian; mirrors the toilscript
+ * `CatWriter` emitter byte-for-byte):
+ *
+ *   u16 format_version = 1
+ *   u8  target_mode            (0 = hot, 1 = cold; there is no target_mode = 2)
+ *   u8  reserved0
+ *   u32 surface_flags          (bit0 rest, bit1 stream, bit2 daemon,
+ *                               bit3 scheduled, bit4 database, bit5 render)
+ *   u16 abi_version
+ *   str build_id               (u32 len + UTF-8)
+ *   u32 fingerprint
+ *   u32 data_coherence_hash
+ *   u32 pair_coherence_hash    (exactly THREE u32 after build_id, not four)
+ *
+ * Fail-closed per Part 5's host rule: an ABSENT section is "legacy single
+ * artifact, load as hot" (NOT a hard reject); a PRESENT-but-unparseable section is
+ * a corrupt artifact -> do not start that artifact's emulator.
+ */
+
+import { DataReader } from 'toiljs/io';
+
+import { customSection } from './sections.js';
+
+export interface SurfaceFlags {
+    readonly rest: boolean;
+    readonly stream: boolean;
+    readonly daemon: boolean;
+    readonly scheduled: boolean;
+    readonly database: boolean;
+    readonly render: boolean;
+}
+
+export interface Surface {
+    /** 0 = hot, 1 = cold. */
+    readonly targetMode: 'hot' | 'cold';
+    readonly flags: SurfaceFlags;
+    readonly abiVersion: number;
+    readonly buildId: string;
+    readonly fingerprint: number;
+    readonly dataCoherenceHash: number;
+    readonly pairCoherenceHash: number;
+}
+
+/** `'absent'` => legacy single artifact (load as hot, no emulators).
+ *  `'invalid'` => present but corrupt (fail closed). Otherwise the parsed surface. */
+export function parseSurface(wasm: Buffer): Surface | 'absent' | 'invalid' {
+    let sec: Buffer | null;
+    try {
+        sec = customSection(wasm, 'toil.surface');
+    } catch {
+        return 'invalid'; // garbage section table
+    }
+    if (sec === null) return 'absent';
+
+    const r = new DataReader(sec);
+    r.readU16(); // format_version
+    const targetMode = r.readU8() === 1 ? 'cold' : 'hot';
+    r.readU8(); // reserved0
+    const f = r.readU32(); // surface_flags
+    const abiVersion = r.readU16();
+    const buildId = r.readString();
+    const fingerprint = r.readU32();
+    const dataCoherenceHash = r.readU32(); // exactly THREE u32 after build_id
+    const pairCoherenceHash = r.readU32();
+    if (!r.ok) return 'invalid'; // PRESENT but corrupt => fail closed
+    return {
+        targetMode,
+        flags: {
+            rest: !!(f & 1),
+            stream: !!(f & 2),
+            daemon: !!(f & 4),
+            scheduled: !!(f & 8),
+            database: !!(f & 16),
+            render: !!(f & 32),
+        },
+        abiVersion,
+        buildId,
+        fingerprint,
+        dataCoherenceHash,
+        pairCoherenceHash,
+    };
+}

package/test/daemon-build.test.ts

@@ -0,0 +1,198 @@
+/**
+ * Two-pass build pipeline (doc 08 section 1). Asserts:
+ *
+ *   - `serverArtifacts` derives the `-hot`/`-cold` paths from `outFile` when
+ *     `hotFile`/`coldFile` are absent, and honors them when present.
+ *   - `SURFACE_DECORATOR` matches `@stream`/`@daemon`/`@scheduled` at line start
+ *     (not in a comment).
+ *   - `buildServer` on a project that declares a `@daemon` runs TWO toilscript
+ *     passes (one `--targetMode cold`, one `--targetMode hot`) and produces BOTH
+ *     `release-hot.wasm` and `release-cold.wasm`; the cold artifact decodes to a
+ *     daemon catalog and its `toil.surface` is target_mode = cold.
+ *   - a project with only the legacy request surface keeps the single-artifact
+ *     path (no cold pass, no cold artifact).
+ *
+ * The build invokes the LOCAL toilscript (branch feat/streams-phase0-compiler),
+ * which supports `--targetMode`; the test links it into the fixture project's
+ * `node_modules` the same way the dev build resolves it (`require.resolve`).
+ */
+
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import {
+    buildServer,
+    serverArtifacts,
+    splitSurfaceFiles,
+    SURFACE_DECORATOR,
+} from '../src/compiler/index.js';
+import { parseDaemonCatalog } from '../src/devserver/daemon/catalog.js';
+import { parseSurface } from '../src/devserver/wasm/surface.js';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const LOCAL_TOILSCRIPT = join(here, '..', '..', 'toilscript');
+
+let tmp: string;
+
+beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'daemon-build-'));
+});
+afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+});
+
+/** Scaffold a minimal project at `tmp` with `server/main.ts` = `serverSrc`, the
+ *  given toilconfig, and `node_modules/toilscript` symlinked to the local build. */
+function scaffold(serverSrc: string, toilconfig: object): void {
+    writeFileSync(join(tmp, 'package.json'), JSON.stringify({ name: 'fixture', type: 'module' }));
+    writeFileSync(join(tmp, 'toilconfig.json'), JSON.stringify(toilconfig, null, 2));
+    mkdirSync(join(tmp, 'server'), { recursive: true });
+    writeFileSync(join(tmp, 'server', 'main.ts'), serverSrc);
+    mkdirSync(join(tmp, 'node_modules'), { recursive: true });
+    symlinkSync(LOCAL_TOILSCRIPT, join(tmp, 'node_modules', 'toilscript'), 'dir');
+}
+
+const BASE_TOILCONFIG = {
+    entries: ['server/main.ts'],
+    targets: { release: { outFile: 'build/server/release.wasm' } },
+    options: { runtime: 'stub', optimizeLevel: 0, shrinkLevel: 0 },
+};
+
+// A @daemon that declares its host imports directly (no toiljs globals lib needed).
+const DAEMON_SRC = `@daemon
+class Jobs {
+  @scheduled("2s") fast(): void {}
+  @scheduled("0 0 * * *") nightly(): void {}
+}
+export function probe(): i32 { return 1; }
+`;
+
+const LEGACY_SRC = `export function handle(ofs: i32, len: i32): i64 { return 0; }
+export function probe(): i32 { return 1; }
+`;
+
+describe('serverArtifacts path derivation', () => {
+    it('derives -hot/-cold from outFile when hotFile/coldFile are absent', () => {
+        writeFileSync(
+            join(tmp, 'toilconfig.json'),
+            JSON.stringify({ targets: { release: { outFile: 'build/server/release.wasm' } } }),
+        );
+        const a = serverArtifacts(tmp);
+        expect(a.hot).toBe(join(tmp, 'build/server/release-hot.wasm'));
+        expect(a.cold).toBe(join(tmp, 'build/server/release-cold.wasm'));
+    });
+
+    it('honors explicit hotFile/coldFile when present', () => {
+        writeFileSync(
+            join(tmp, 'toilconfig.json'),
+            JSON.stringify({
+                targets: {
+                    release: {
+                        outFile: 'build/server/release.wasm',
+                        hotFile: 'out/hot.wasm',
+                        coldFile: 'out/cold.wasm',
+                    },
+                },
+            }),
+        );
+        const a = serverArtifacts(tmp);
+        expect(a.hot).toBe(join(tmp, 'out/hot.wasm'));
+        expect(a.cold).toBe(join(tmp, 'out/cold.wasm'));
+    });
+});
+
+describe('SURFACE_DECORATOR', () => {
+    it('matches the streams/daemon decorators at line start', () => {
+        for (const deco of ['@stream', '@daemon', '@scheduled', '@rest', '@data']) {
+            expect(SURFACE_DECORATOR.test(`${deco} class X {}`)).toBe(true);
+            expect(SURFACE_DECORATOR.test(`  ${deco}\nclass X {}`)).toBe(true);
+        }
+    });
+
+    it('does NOT match a decorator mentioned only in a comment', () => {
+        expect(SURFACE_DECORATOR.test('// the @daemon decorator marks a cold class')).toBe(false);
+        expect(SURFACE_DECORATOR.test('const s = "uses @scheduled internally";')).toBe(false);
+    });
+});
+
+describe('splitSurfaceFiles per-pass classification', () => {
+    /** Lay down `name -> contents` files under `tmp` and return their relative paths. */
+    function lay(files: Record<string, string>): string[] {
+        mkdirSync(join(tmp, 'server'), { recursive: true });
+        const rels: string[] = [];
+        for (const [name, src] of Object.entries(files)) {
+            writeFileSync(join(tmp, name), src);
+            rels.push(name);
+        }
+        return rels;
+    }
+
+    it('drops daemon-only files from the hot pass and hot-only files from the cold pass', () => {
+        const rels = lay({
+            'server/jobs.ts': '@daemon\nclass J { @scheduled("1s") t(): void {} }\n',
+            'server/api.ts': '@rest\nclass A {}\n',
+            'server/model.ts': '@data\nclass M {}\n',
+            'server/util.ts': 'export function helper(): i32 { return 1; }\n',
+        });
+        const split = splitSurfaceFiles(tmp, rels);
+        expect(split.hasDaemon).toBe(true);
+        // hot pass: everything except the daemon-only jobs.ts.
+        expect(split.hot.sort()).toEqual(
+            ['server/api.ts', 'server/model.ts', 'server/util.ts'].sort(),
+        );
+        // cold pass: everything except the hot-only api.ts.
+        expect(split.cold.sort()).toEqual(
+            ['server/jobs.ts', 'server/model.ts', 'server/util.ts'].sort(),
+        );
+    });
+
+    it('keeps a file that mixes both surfaces in both passes', () => {
+        const rels = lay({ 'server/both.ts': '@daemon\nclass J {}\n@rest\nclass A {}\n' });
+        const split = splitSurfaceFiles(tmp, rels);
+        expect(split.hot).toContain('server/both.ts');
+        expect(split.cold).toContain('server/both.ts');
+    });
+});
+
+// Needs the local toilscript dev build (with --targetMode) linked as a sibling
+// repo; skip where it is absent (e.g. CI, which has only the published dep).
+describe.skipIf(!existsSync(LOCAL_TOILSCRIPT))('buildServer two-pass (daemon project)', () => {
+    it('runs the cold pass and produces the cold artifact with a daemon catalog', async () => {
+        scaffold(DAEMON_SRC, BASE_TOILCONFIG);
+        await buildServer(tmp);
+
+        const cold = join(tmp, 'build/server/release-cold.wasm');
+        expect(existsSync(cold), 'cold artifact missing').toBe(true);
+
+        // The cold artifact carries the daemon surface + catalog (decoded byte-for-byte).
+        const coldBytes = readFileSync(cold);
+        const surface = parseSurface(coldBytes);
+        expect(surface !== 'absent' && surface !== 'invalid' && surface.targetMode).toBe('cold');
+        expect(surface !== 'absent' && surface !== 'invalid' && surface.flags.daemon).toBe(true);
+
+        const catalog = parseDaemonCatalog(coldBytes);
+        expect(catalog).not.toBeNull();
+        expect(catalog!.hasDaemon).toBe(true);
+        expect(catalog!.tasks.map((t) => t.name)).toEqual(['fast', 'nightly']);
+        expect(catalog!.tasks[0].schedule.kind).toBe('interval');
+        expect(catalog!.tasks[1].schedule.kind).toBe('cron');
+
+        // A daemon-only project (no request/stream surface) has no hot files, so the hot pass is
+        // skipped (toilscript would HARD-ERROR a @daemon class under --targetMode hot). The legacy
+        // single-artifact `release.wasm` is therefore not produced for a pure background worker.
+        expect(existsSync(join(tmp, 'build/server/release.wasm'))).toBe(false);
+    }, 60_000);
+
+    it('keeps the single-artifact path for a legacy (no-daemon) project', async () => {
+        scaffold(LEGACY_SRC, BASE_TOILCONFIG);
+        await buildServer(tmp);
+
+        expect(existsSync(join(tmp, 'build/server/release.wasm'))).toBe(true);
+        // No @daemon -> no cold pass -> no cold artifact.
+        expect(existsSync(join(tmp, 'build/server/release-cold.wasm'))).toBe(false);
+    }, 60_000);
+});

package/test/daemon-catalog.test.ts

@@ -0,0 +1,265 @@
+/**
+ * Unit tests for the daemon-side custom-section parsers and cron evaluator
+ * (RECONCILIATION Part 5 byte layouts / F6 bitmask cron). These mirror the DB
+ * catalog tests' style: hand-build the Part 5 bytes with `DataWriter`, wrap them
+ * in a minimal wasm custom section, and assert the parser decodes them field-for-
+ * field and fails CLOSED on a truncated/garbage section.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { DataWriter } from '../src/io/codec.js';
+import { parseDaemonCatalog } from '../src/devserver/daemon/catalog.js';
+import { cronMatches, cronNeverFires, nextCronFireMs } from '../src/devserver/daemon/cron.js';
+import { customSection } from '../src/devserver/wasm/sections.js';
+import { parseSurface } from '../src/devserver/wasm/surface.js';
+
+/** Wrap a section payload (after the name) into a minimal one-section wasm module.
+ *  Mirrors the DB catalog test's `wasmWithSection` helper. */
+function wasmWithSection(name: string, payload: Uint8Array): Buffer {
+    const nameBytes = Buffer.from(name);
+    const sectionPayload = Buffer.concat([
+        Buffer.from([nameBytes.length]),
+        nameBytes,
+        Buffer.from(payload),
+    ]);
+    return Buffer.concat([
+        Buffer.from([0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00, 0x00, sectionPayload.length]),
+        sectionPayload,
+    ]);
+}
+
+// --- toildaemon.catalog (Part 5) byte builders -----------------------------
+
+interface BuildTask {
+    name: string;
+    taskIndex: number;
+    kind: 0 | 1;
+    intervalMs?: bigint;
+    cron?: { minute: bigint; hour: number; dom: number; month: number; dow: number };
+}
+
+/** Emit a Part 5 `toildaemon.catalog` body (the bytes AFTER the section name). */
+function buildDaemonCatalogBytes(hasDaemon: boolean, tasks: BuildTask[]): Uint8Array {
+    const w = new DataWriter();
+    w.writeU16(1); // format_version
+    w.writeU8(hasDaemon ? 1 : 0);
+    w.writeU16(tasks.length); // n_scheduled
+    for (const t of tasks) {
+        w.writeString(t.name);
+        w.writeU16(t.taskIndex);
+        w.writeU8(t.kind);
+        w.writeU64(t.kind === 0 ? (t.intervalMs ?? 0n) : 0n); // interval_ms
+        w.writeU64(t.cron?.minute ?? 0n); // cron_minute_mask
+        w.writeU32(t.cron?.hour ?? 0); // cron_hour_mask
+        w.writeU32(t.cron?.dom ?? 0); // cron_dom_mask
+        w.writeU16(t.cron?.month ?? 0); // cron_month_mask
+        w.writeU8(t.cron?.dow ?? 0); // cron_dow_mask
+        w.writeU8(0); // overlap_policy
+        w.writeU8(0); // catchup_policy
+        w.writeU64(0n); // gas_hint
+    }
+    return w.toBytes();
+}
+
+describe('parseDaemonCatalog (Part 5)', () => {
+    it('decodes an interval task and a cron task field-for-field', () => {
+        // `0 */6 * * *`: minute 0; hours 0,6,12,18; dom 1..31; month 1..12; dow 0..6.
+        const payload = buildDaemonCatalogBytes(true, [
+            { name: 'tick', taskIndex: 0, kind: 0, intervalMs: 1000n },
+            {
+                name: 'sixHourly',
+                taskIndex: 1,
+                kind: 1,
+                cron: {
+                    minute: 1n, // bit 0 (minute 0)
+                    hour: (1 << 0) | (1 << 6) | (1 << 12) | (1 << 18),
+                    dom: 0xfffffffe, // bits 1..31
+                    month: 0x1ffe, // bits 1..12
+                    dow: 0x7f, // bits 0..6
+                },
+            },
+        ]);
+        const wasm = wasmWithSection('toildaemon.catalog', payload);
+        const cat = parseDaemonCatalog(wasm);
+        expect(cat).not.toBeNull();
+        expect(cat!.hasDaemon).toBe(true);
+        expect(cat!.tasks).toHaveLength(2);
+
+        const [interval, cron] = cat!.tasks;
+        expect(interval.name).toBe('tick');
+        expect(interval.taskIndex).toBe(0);
+        expect(interval.schedule).toEqual({ kind: 'interval', ms: 1000 });
+        expect(interval.overlapPolicy).toBe(0);
+        expect(interval.catchupPolicy).toBe(0);
+        expect(interval.gasHint).toBe(0n);
+
+        expect(cron.name).toBe('sixHourly');
+        expect(cron.taskIndex).toBe(1);
+        expect(cron.schedule.kind).toBe('cron');
+        if (cron.schedule.kind === 'cron') {
+            // The masks round-trip as BIT TESTS, never a string parse.
+            const m = cron.schedule.masks;
+            expect(m.minute).toBe(1n);
+            expect((m.hour & (1 << 6)) !== 0).toBe(true);
+            expect((m.hour & (1 << 7)) !== 0).toBe(false);
+            expect(m.dom).toBe(0xfffffffe);
+            expect(m.month).toBe(0x1ffe);
+            expect(m.dow).toBe(0x7f);
+        }
+    });
+
+    it('decodes a 60-bit minute mask without precision loss', () => {
+        // minute 59 = bit 59, which is above 2^53 and must survive as a bigint.
+        const minuteMask = 1n << 59n;
+        const payload = buildDaemonCatalogBytes(true, [
+            {
+                name: 'lateMinute',
+                taskIndex: 0,
+                kind: 1,
+                cron: { minute: minuteMask, hour: 0xffffff, dom: 0xfffffffe, month: 0x1ffe, dow: 0x7f },
+            },
+        ]);
+        const cat = parseDaemonCatalog(wasmWithSection('toildaemon.catalog', payload));
+        const t = cat!.tasks[0];
+        expect(t.schedule.kind === 'cron' && t.schedule.masks.minute).toBe(minuteMask);
+    });
+
+    it('returns null for an absent section (no daemon -> emulator stays off)', () => {
+        const wasm = wasmWithSection('toildb.catalog', Buffer.from([0x01, 0x00]));
+        expect(parseDaemonCatalog(wasm)).toBeNull();
+    });
+
+    it('fails closed: a truncated record yields only the cleanly-decoded prefix', () => {
+        // Claim 2 tasks but truncate inside the second record's interval_ms.
+        const full = buildDaemonCatalogBytes(true, [
+            { name: 'a', taskIndex: 0, kind: 0, intervalMs: 5000n },
+            { name: 'b', taskIndex: 1, kind: 0, intervalMs: 9000n },
+        ]);
+        const truncated = full.subarray(0, full.length - 20); // chop the 2nd record's tail
+        const cat = parseDaemonCatalog(wasmWithSection('toildaemon.catalog', truncated));
+        expect(cat).not.toBeNull();
+        // Only the first task survived; the loop stopped on the short read.
+        expect(cat!.tasks.map((t) => t.name)).toEqual(['a']);
+    });
+
+    it('returns null for a wholly garbage section (header short-read, no daemon)', () => {
+        const cat = parseDaemonCatalog(wasmWithSection('toildaemon.catalog', Buffer.from([0x01])));
+        expect(cat).toBeNull();
+    });
+});
+
+// --- toil.surface (Part 5) -------------------------------------------------
+
+function buildSurfaceBytes(opts: {
+    mode: 0 | 1;
+    flags: number;
+    abi?: number;
+    buildId?: string;
+}): Uint8Array {
+    const w = new DataWriter();
+    w.writeU16(1); // format_version
+    w.writeU8(opts.mode); // target_mode
+    w.writeU8(0); // reserved0
+    w.writeU32(opts.flags); // surface_flags
+    w.writeU16(opts.abi ?? 1); // abi_version
+    w.writeString(opts.buildId ?? ''); // build_id
+    w.writeU32(0xdeadbeef); // fingerprint
+    w.writeU32(0x11111111); // data_coherence_hash
+    w.writeU32(0x22222222); // pair_coherence_hash (exactly THREE u32 after build_id)
+    return w.toBytes();
+}
+
+describe('parseSurface (Part 5)', () => {
+    it('decodes a cold daemon surface with exactly three trailing u32 hashes', () => {
+        const flags = 0b000100 | 0b001000; // daemon (bit2) + scheduled (bit3)
+        const s = parseSurface(wasmWithSection('toil.surface', buildSurfaceBytes({ mode: 1, flags })));
+        expect(s).not.toBe('absent');
+        expect(s).not.toBe('invalid');
+        if (s !== 'absent' && s !== 'invalid') {
+            expect(s.targetMode).toBe('cold');
+            expect(s.flags.daemon).toBe(true);
+            expect(s.flags.scheduled).toBe(true);
+            expect(s.flags.rest).toBe(false);
+            expect(s.fingerprint).toBe(0xdeadbeef);
+            expect(s.dataCoherenceHash).toBe(0x11111111);
+            expect(s.pairCoherenceHash).toBe(0x22222222);
+        }
+    });
+
+    it('decodes a hot surface (target_mode 0)', () => {
+        const s = parseSurface(wasmWithSection('toil.surface', buildSurfaceBytes({ mode: 0, flags: 1 })));
+        expect(s !== 'absent' && s !== 'invalid' && s.targetMode).toBe('hot');
+    });
+
+    it("treats an ABSENT section as 'absent' (legacy single artifact, load as hot)", () => {
+        const wasm = wasmWithSection('toildb.catalog', Buffer.from([0x01, 0x00]));
+        expect(parseSurface(wasm)).toBe('absent');
+    });
+
+    it("fails closed: a PRESENT but truncated section is 'invalid'", () => {
+        const full = buildSurfaceBytes({ mode: 1, flags: 4 });
+        const truncated = full.subarray(0, full.length - 3); // chop a trailing hash
+        expect(parseSurface(wasmWithSection('toil.surface', truncated))).toBe('invalid');
+    });
+});
+
+describe('customSection bounds-checking', () => {
+    it('returns null for a non-wasm buffer', () => {
+        expect(customSection(Buffer.from('not a wasm module at all'), 'toil.surface')).toBeNull();
+    });
+
+    it('returns null for a truncated section table (no over-read)', () => {
+        // Magic + version, then a custom-section id with a length that runs past the end.
+        const wasm = Buffer.from([0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00, 0x00, 0x7f]);
+        expect(customSection(wasm, 'toil.surface')).toBeNull();
+    });
+});
+
+describe('cron bitmask evaluation (F6, never a string parse)', () => {
+    // `0 */6 * * *`: minute 0; hours 0,6,12,18; every dom/month/dow.
+    const sixHourly = {
+        minute: 1n, // bit 0
+        hour: (1 << 0) | (1 << 6) | (1 << 12) | (1 << 18),
+        dom: 0xfffffffe,
+        month: 0x1ffe,
+        dow: 0x7f,
+    };
+
+    it('matches the right minute/hour and rejects others', () => {
+        expect(cronMatches(sixHourly, new Date(2026, 5, 22, 6, 0, 0))).toBe(true);
+        expect(cronMatches(sixHourly, new Date(2026, 5, 22, 12, 0, 0))).toBe(true);
+        expect(cronMatches(sixHourly, new Date(2026, 5, 22, 6, 1, 0))).toBe(false); // wrong minute
+        expect(cronMatches(sixHourly, new Date(2026, 5, 22, 7, 0, 0))).toBe(false); // wrong hour
+    });
+
+    it('computes the next fire time by walking forward minute by minute', () => {
+        const from = new Date(2026, 5, 22, 6, 1, 0).getTime();
+        const next = nextCronFireMs(sixHourly, from);
+        expect(next).not.toBeNull();
+        expect(new Date(next!).getHours()).toBe(12);
+        expect(new Date(next!).getMinutes()).toBe(0);
+    });
+
+    it('honors the dom/dow union rule', () => {
+        // Fire on the 1st of the month OR on Sunday (both restricted -> union).
+        const masks = {
+            minute: 1n, // minute 0
+            hour: 1, // hour 0
+            dom: 1 << 1, // only day-of-month 1
+            month: 0x1ffe, // every month
+            dow: 1 << 0, // only Sunday
+        };
+        // 2026-06-01 is a Monday -> matches via dom (the 1st).
+        expect(cronMatches(masks, new Date(2026, 5, 1, 0, 0, 0))).toBe(true);
+        // 2026-06-07 is a Sunday -> matches via dow.
+        expect(cronMatches(masks, new Date(2026, 5, 7, 0, 0, 0))).toBe(true);
+        // 2026-06-03 is a Wednesday, not the 1st -> no match.
+        expect(cronMatches(masks, new Date(2026, 5, 3, 0, 0, 0))).toBe(false);
+    });
+
+    it('flags an all-zero (unsatisfiable) mask as never-firing', () => {
+        expect(cronNeverFires({ minute: 0n, hour: 0, dom: 0, month: 0, dow: 0 })).toBe(true);
+        expect(cronNeverFires(sixHourly)).toBe(false);
+    });
+});