@temporal-cortex/truth-engine 0.1.0

package/README.md

@@ -0,0 +1,172 @@
+# @temporal-cortex/truth-engine
+
+WASM-powered RRULE expansion, conflict detection, free/busy computation, and multi-calendar availability merging for Node.js.
+
+This package wraps the Rust `truth-engine` library via WebAssembly, providing near-native performance for deterministic calendar operations in JavaScript/TypeScript environments.
+
+## Installation
+
+```bash
+npm install @temporal-cortex/truth-engine
+# or
+pnpm add @temporal-cortex/truth-engine
+```
+
+## Usage
+
+### Expand Recurrence Rules
+
+```typescript
+import { expandRRule } from "@temporal-cortex/truth-engine";
+
+// "Every Tuesday at 2pm Pacific" for 4 weeks
+const events = expandRRule(
+  "FREQ=WEEKLY;COUNT=4;BYDAY=TU",
+  "2026-02-17T14:00:00",
+  60,                    // 60-minute duration
+  "America/Los_Angeles", // IANA timezone (DST-aware)
+);
+// events = [{ start: "2026-02-17T22:00:00+00:00", end: "2026-02-17T23:00:00+00:00" }, ...]
+```
+
+### Merge Multi-Calendar Availability
+
+```typescript
+import { mergeAvailability } from "@temporal-cortex/truth-engine";
+
+const availability = mergeAvailability(
+  [
+    { stream_id: "google", events: [{ start: "2026-03-16T09:00:00Z", end: "2026-03-16T10:00:00Z" }] },
+    { stream_id: "outlook", events: [{ start: "2026-03-16T14:00:00Z", end: "2026-03-16T15:00:00Z" }] },
+  ],
+  "2026-03-16T08:00:00Z",
+  "2026-03-16T17:00:00Z",
+  true, // opaque mode — hides which calendar each block came from
+);
+// availability.busy = [{ start, end, source_count: 0 }, ...]
+// availability.free = [{ start, end, duration_minutes }, ...]
+```
+
+### Find Conflicts
+
+```typescript
+import { findConflicts } from "@temporal-cortex/truth-engine";
+
+const teamA = [{ start: "2026-02-17T14:00:00Z", end: "2026-02-17T15:00:00Z" }];
+const teamB = [{ start: "2026-02-17T14:30:00Z", end: "2026-02-17T15:30:00Z" }];
+
+const conflicts = findConflicts(teamA, teamB);
+// [{ event_a: {...}, event_b: {...}, overlap_minutes: 30 }]
+```
+
+### Find Free Slots
+
+```typescript
+import { findFreeSlots } from "@temporal-cortex/truth-engine";
+
+const busyEvents = [
+  { start: "2026-02-17T09:00:00Z", end: "2026-02-17T10:00:00Z" },
+  { start: "2026-02-17T11:00:00Z", end: "2026-02-17T12:00:00Z" },
+];
+
+const slots = findFreeSlots(busyEvents, "2026-02-17T08:00:00", "2026-02-17T13:00:00");
+// [{ start, end, duration_minutes: 60 }, { ... }, { ... }]
+```
+
+### Find First Available Slot Across Calendars
+
+```typescript
+import { findFirstFreeAcross } from "@temporal-cortex/truth-engine";
+
+const slot = findFirstFreeAcross(
+  [
+    { stream_id: "google", events: [{ start: "2026-03-16T09:00:00Z", end: "2026-03-16T10:00:00Z" }] },
+    { stream_id: "outlook", events: [{ start: "2026-03-16T10:00:00Z", end: "2026-03-16T11:00:00Z" }] },
+  ],
+  "2026-03-16T08:00:00Z",
+  "2026-03-16T17:00:00Z",
+  30, // minimum 30-minute slot
+);
+// { start, end, duration_minutes }
+```
+
+## API
+
+### `expandRRule(rrule, dtstart, durationMinutes, timezone, until?, maxCount?): TimeRange[]`
+
+Expand an RFC 5545 RRULE into concrete event instances. Supports FREQ, BYDAY, BYSETPOS, BYMONTHDAY, COUNT, UNTIL, EXDATE. DST-aware — events at 14:00 Pacific stay at 14:00 Pacific across transitions.
+
+### `findConflicts(eventsA, eventsB): Conflict[]`
+
+Find all pairwise overlaps between two event lists. Adjacent events (end === start) are not conflicts.
+
+### `findFreeSlots(events, windowStart, windowEnd): FreeSlot[]`
+
+Find free time slots within a window, given a list of busy events.
+
+### `mergeAvailability(streams, windowStart, windowEnd, opaque?): UnifiedAvailability`
+
+Merge N event streams into a unified busy/free view. In opaque mode (default), source counts are hidden for privacy.
+
+### `findFirstFreeAcross(streams, windowStart, windowEnd, minDurationMinutes): FreeSlot | null`
+
+Find the first free slot of at least `minDurationMinutes` across all merged streams. Returns `null` if no qualifying slot exists.
+
+## Types
+
+```typescript
+interface TimeRange { start: string; end: string }
+interface Conflict { event_a: TimeRange; event_b: TimeRange; overlap_minutes: number }
+interface FreeSlot { start: string; end: string; duration_minutes: number }
+interface EventStream { stream_id: string; events: TimeRange[] }
+interface BusyBlock { start: string; end: string; source_count: number }
+interface UnifiedAvailability { busy: BusyBlock[]; free: FreeSlot[]; window_start: string; window_end: string; privacy: string }
+```
+
+## Build from Source
+
+This package requires the WASM artifacts to be built from the Rust crate first:
+
+```bash
+# From the monorepo root:
+
+# 1. Build the WASM binary
+cargo build -p truth-engine-wasm --target wasm32-unknown-unknown --release
+
+# 2. Generate Node.js bindings
+wasm-bindgen --target nodejs \
+  --out-dir packages/truth-engine-js/wasm/ \
+  target/wasm32-unknown-unknown/release/truth_engine_wasm.wasm
+
+# 3. Rename for ESM/CJS compatibility
+mv packages/truth-engine-js/wasm/truth_engine_wasm.js packages/truth-engine-js/wasm/truth_engine_wasm.cjs
+
+# 4. Build TypeScript
+pnpm --filter @temporal-cortex/truth-engine build
+
+# 5. Run tests
+pnpm --filter @temporal-cortex/truth-engine test
+```
+
+## Architecture
+
+```
+src/index.ts                     ← Public API, loads WASM via createRequire
+wasm/truth_engine_wasm.cjs       ← wasm-bindgen generated CommonJS bindings
+wasm/truth_engine_wasm.wasm      ← Compiled WASM binary from truth-engine (Rust)
+wasm/truth_engine_wasm.d.ts      ← TypeScript type declarations for WASM exports
+```
+
+The package uses `createRequire(import.meta.url)` to load the CommonJS WASM bindings from an ESM context. This bridges the module system mismatch since `wasm-bindgen --target nodejs` generates CommonJS but the package uses `"type": "module"`.
+
+## Testing
+
+13 tests covering RRULE expansion (8), conflict detection (3), and free/busy computation (2):
+
+```bash
+pnpm --filter @temporal-cortex/truth-engine test
+```
+
+## License
+
+MIT OR Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,83 @@
+export interface TimeRange {
+    start: string;
+    end: string;
+}
+export interface Conflict {
+    event_a: TimeRange;
+    event_b: TimeRange;
+    overlap_minutes: number;
+}
+export interface FreeSlot {
+    start: string;
+    end: string;
+    duration_minutes: number;
+}
+/**
+ * Expand an RFC 5545 RRULE into concrete event instances.
+ *
+ * @param rrule - RFC 5545 recurrence rule (e.g., "FREQ=DAILY;COUNT=3")
+ * @param dtstart - Local datetime for the first occurrence (e.g., "2026-02-17T14:00:00")
+ * @param durationMinutes - Duration of each instance in minutes
+ * @param timezone - IANA timezone (e.g., "America/Los_Angeles")
+ * @param until - Optional end boundary (local datetime string)
+ * @param maxCount - Optional maximum number of instances to generate
+ * @returns Array of {start, end} objects with RFC 3339 datetime strings
+ */
+export declare function expandRRule(rrule: string, dtstart: string, durationMinutes: number, timezone: string, until?: string, maxCount?: number): TimeRange[];
+/**
+ * Find all pairwise conflicts (overlapping time ranges) between two event lists.
+ *
+ * @param eventsA - First list of events
+ * @param eventsB - Second list of events
+ * @returns Array of conflict objects with event_a, event_b, and overlap_minutes
+ */
+export declare function findConflicts(eventsA: TimeRange[], eventsB: TimeRange[]): Conflict[];
+/**
+ * Find free time slots within a given window, given a list of busy events.
+ *
+ * @param events - List of busy events
+ * @param windowStart - Start of the search window (ISO 8601 datetime)
+ * @param windowEnd - End of the search window (ISO 8601 datetime)
+ * @returns Array of free slot objects with start, end, and duration_minutes
+ */
+export declare function findFreeSlots(events: TimeRange[], windowStart: string, windowEnd: string): FreeSlot[];
+export interface EventStream {
+    stream_id: string;
+    events: TimeRange[];
+}
+export interface BusyBlock {
+    start: string;
+    end: string;
+    source_count: number;
+}
+export interface UnifiedAvailability {
+    busy: BusyBlock[];
+    free: FreeSlot[];
+    window_start: string;
+    window_end: string;
+    privacy: string;
+}
+/**
+ * Merge N event streams into unified availability within a time window.
+ *
+ * This is the core of the "Unified Availability Graph" — it computes a
+ * single source of truth for a user's availability across all their calendars.
+ *
+ * @param streams - Array of event streams (from different calendars/providers)
+ * @param windowStart - Start of the analysis window (ISO 8601 datetime)
+ * @param windowEnd - End of the analysis window (ISO 8601 datetime)
+ * @param opaque - If true, hide source counts in busy blocks (privacy mode). Default: true.
+ * @returns Unified availability with busy blocks and free slots
+ */
+export declare function mergeAvailability(streams: EventStream[], windowStart: string, windowEnd: string, opaque?: boolean): UnifiedAvailability;
+/**
+ * Find the first free slot of at least `minDurationMinutes` across N merged
+ * event streams.
+ *
+ * @param streams - Array of event streams
+ * @param windowStart - Start of the search window (ISO 8601 datetime)
+ * @param windowEnd - End of the search window (ISO 8601 datetime)
+ * @param minDurationMinutes - Minimum slot duration in minutes
+ * @returns The first qualifying free slot, or null if none found
+ */
+export declare function findFirstFreeAcross(streams: EventStream[], windowStart: string, windowEnd: string, minDurationMinutes: number): FreeSlot | null;

package/dist/index.js

@@ -0,0 +1,88 @@
+// @temporal-cortex/truth-engine — WASM-powered RRULE expansion, conflict
+// detection, and free/busy computation for Node.js.
+//
+// This module loads the WASM binary compiled from the truth-engine-wasm Rust
+// crate. The WASM bindings are generated by wasm-bindgen as CommonJS (.cjs),
+// but this package uses ESM ("type": "module" in package.json). We bridge the
+// two module systems using Node's createRequire().
+//
+// Build chain:
+//   truth-engine (Rust) -> truth-engine-wasm (wasm-bindgen) -> truth-engine-js (this wrapper)
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+// Load the WASM-generated Node.js bindings (.cjs for CommonJS/ESM compat)
+const wasm = require("../wasm/truth_engine_wasm.cjs");
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Expand an RFC 5545 RRULE into concrete event instances.
+ *
+ * @param rrule - RFC 5545 recurrence rule (e.g., "FREQ=DAILY;COUNT=3")
+ * @param dtstart - Local datetime for the first occurrence (e.g., "2026-02-17T14:00:00")
+ * @param durationMinutes - Duration of each instance in minutes
+ * @param timezone - IANA timezone (e.g., "America/Los_Angeles")
+ * @param until - Optional end boundary (local datetime string)
+ * @param maxCount - Optional maximum number of instances to generate
+ * @returns Array of {start, end} objects with RFC 3339 datetime strings
+ */
+export function expandRRule(rrule, dtstart, durationMinutes, timezone, until, maxCount) {
+    const json = wasm.expandRRule(rrule, dtstart, durationMinutes, timezone, until ?? undefined, maxCount ?? undefined);
+    return JSON.parse(json);
+}
+/**
+ * Find all pairwise conflicts (overlapping time ranges) between two event lists.
+ *
+ * @param eventsA - First list of events
+ * @param eventsB - Second list of events
+ * @returns Array of conflict objects with event_a, event_b, and overlap_minutes
+ */
+export function findConflicts(eventsA, eventsB) {
+    const json = wasm.findConflicts(JSON.stringify(eventsA), JSON.stringify(eventsB));
+    return JSON.parse(json);
+}
+/**
+ * Find free time slots within a given window, given a list of busy events.
+ *
+ * @param events - List of busy events
+ * @param windowStart - Start of the search window (ISO 8601 datetime)
+ * @param windowEnd - End of the search window (ISO 8601 datetime)
+ * @returns Array of free slot objects with start, end, and duration_minutes
+ */
+export function findFreeSlots(events, windowStart, windowEnd) {
+    const json = wasm.findFreeSlots(JSON.stringify(events), windowStart, windowEnd);
+    return JSON.parse(json);
+}
+// ---------------------------------------------------------------------------
+// Multi-stream availability API
+// ---------------------------------------------------------------------------
+/**
+ * Merge N event streams into unified availability within a time window.
+ *
+ * This is the core of the "Unified Availability Graph" — it computes a
+ * single source of truth for a user's availability across all their calendars.
+ *
+ * @param streams - Array of event streams (from different calendars/providers)
+ * @param windowStart - Start of the analysis window (ISO 8601 datetime)
+ * @param windowEnd - End of the analysis window (ISO 8601 datetime)
+ * @param opaque - If true, hide source counts in busy blocks (privacy mode). Default: true.
+ * @returns Unified availability with busy blocks and free slots
+ */
+export function mergeAvailability(streams, windowStart, windowEnd, opaque = true) {
+    const json = wasm.mergeAvailability(JSON.stringify(streams), windowStart, windowEnd, opaque);
+    return JSON.parse(json);
+}
+/**
+ * Find the first free slot of at least `minDurationMinutes` across N merged
+ * event streams.
+ *
+ * @param streams - Array of event streams
+ * @param windowStart - Start of the search window (ISO 8601 datetime)
+ * @param windowEnd - End of the search window (ISO 8601 datetime)
+ * @param minDurationMinutes - Minimum slot duration in minutes
+ * @returns The first qualifying free slot, or null if none found
+ */
+export function findFirstFreeAcross(streams, windowStart, windowEnd, minDurationMinutes) {
+    const json = wasm.findFirstFreeAcross(JSON.stringify(streams), windowStart, windowEnd, minDurationMinutes);
+    return JSON.parse(json);
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@temporal-cortex/truth-engine",
+  "version": "0.1.0",
+  "description": "Truth Engine — deterministic RRULE expansion, conflict detection, free/busy for AI calendar agents",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "wasm"
+  ],
+  "keywords": [
+    "rrule",
+    "calendar",
+    "icalendar",
+    "recurrence",
+    "wasm"
+  ],
+  "license": "MIT OR Apache-2.0",
+  "author": "Billy Lui",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/billylui/temporal-cortex-core.git",
+    "directory": "packages/truth-engine-js"
+  },
+  "homepage": "https://github.com/billylui/temporal-cortex-core",
+  "bugs": {
+    "url": "https://github.com/billylui/temporal-cortex-core/issues"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5",
+    "vitest": "^3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/wasm/truth_engine_wasm.cjs

@@ -0,0 +1,383 @@
+/* @ts-self-types="./truth_engine_wasm.d.ts" */
+
+/**
+ * Expand an RRULE string into concrete datetime instances.
+ *
+ * Returns a JSON string containing an array of `{start, end}` objects with
+ * RFC 3339 datetime strings.
+ *
+ * # Arguments
+ * - `rrule` -- RFC 5545 RRULE string (e.g., "FREQ=WEEKLY;BYDAY=TU,TH")
+ * - `dtstart` -- Local datetime string (e.g., "2026-02-17T14:00:00")
+ * - `duration_minutes` -- Duration of each instance in minutes
+ * - `timezone` -- IANA timezone (e.g., "America/Los_Angeles")
+ * - `until` -- Optional end boundary for expansion (local datetime string)
+ * - `max_count` -- Optional maximum number of instances
+ * @param {string} rrule
+ * @param {string} dtstart
+ * @param {number} duration_minutes
+ * @param {string} timezone
+ * @param {string | null} [until]
+ * @param {number | null} [max_count]
+ * @returns {string}
+ */
+function expandRRule(rrule, dtstart, duration_minutes, timezone, until, max_count) {
+    let deferred6_0;
+    let deferred6_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(rrule, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(dtstart, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len1 = WASM_VECTOR_LEN;
+        const ptr2 = passStringToWasm0(timezone, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len2 = WASM_VECTOR_LEN;
+        var ptr3 = isLikeNone(until) ? 0 : passStringToWasm0(until, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        var len3 = WASM_VECTOR_LEN;
+        wasm.expandRRule(retptr, ptr0, len0, ptr1, len1, duration_minutes, ptr2, len2, ptr3, len3, isLikeNone(max_count) ? 0x100000001 : (max_count) >>> 0);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+        var ptr5 = r0;
+        var len5 = r1;
+        if (r3) {
+            ptr5 = 0; len5 = 0;
+            throw takeObject(r2);
+        }
+        deferred6_0 = ptr5;
+        deferred6_1 = len5;
+        return getStringFromWasm0(ptr5, len5);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export3(deferred6_0, deferred6_1, 1);
+    }
+}
+exports.expandRRule = expandRRule;
+
+/**
+ * Find all pairwise conflicts (overlapping time ranges) between two event lists.
+ *
+ * Both arguments must be JSON arrays of `{start, end}` objects with ISO 8601
+ * datetime strings. Returns a JSON string containing an array of conflict objects,
+ * each with `event_a`, `event_b`, and `overlap_minutes`.
+ * @param {string} events_a_json
+ * @param {string} events_b_json
+ * @returns {string}
+ */
+function findConflicts(events_a_json, events_b_json) {
+    let deferred4_0;
+    let deferred4_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(events_a_json, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(events_b_json, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len1 = WASM_VECTOR_LEN;
+        wasm.findConflicts(retptr, ptr0, len0, ptr1, len1);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+        var ptr3 = r0;
+        var len3 = r1;
+        if (r3) {
+            ptr3 = 0; len3 = 0;
+            throw takeObject(r2);
+        }
+        deferred4_0 = ptr3;
+        deferred4_1 = len3;
+        return getStringFromWasm0(ptr3, len3);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export3(deferred4_0, deferred4_1, 1);
+    }
+}
+exports.findConflicts = findConflicts;
+
+/**
+ * Find the first free slot of at least `min_duration_minutes` across N merged
+ * event streams.
+ *
+ * `streams_json` must be a JSON array of `{stream_id, events: [{start, end}]}`.
+ * Returns a JSON string with `{start, end, duration_minutes}` or `null`.
+ * @param {string} streams_json
+ * @param {string} window_start
+ * @param {string} window_end
+ * @param {bigint} min_duration_minutes
+ * @returns {string}
+ */
+function findFirstFreeAcross(streams_json, window_start, window_end, min_duration_minutes) {
+    let deferred5_0;
+    let deferred5_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(streams_json, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(window_start, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len1 = WASM_VECTOR_LEN;
+        const ptr2 = passStringToWasm0(window_end, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len2 = WASM_VECTOR_LEN;
+        wasm.findFirstFreeAcross(retptr, ptr0, len0, ptr1, len1, ptr2, len2, min_duration_minutes);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+        var ptr4 = r0;
+        var len4 = r1;
+        if (r3) {
+            ptr4 = 0; len4 = 0;
+            throw takeObject(r2);
+        }
+        deferred5_0 = ptr4;
+        deferred5_1 = len4;
+        return getStringFromWasm0(ptr4, len4);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export3(deferred5_0, deferred5_1, 1);
+    }
+}
+exports.findFirstFreeAcross = findFirstFreeAcross;
+
+/**
+ * Find free time slots within a given time window, given a list of busy events.
+ *
+ * `events_json` must be a JSON array of `{start, end}` objects. `window_start`
+ * and `window_end` are ISO 8601 datetime strings. Returns a JSON string containing
+ * an array of `{start, end, duration_minutes}` objects.
+ * @param {string} events_json
+ * @param {string} window_start
+ * @param {string} window_end
+ * @returns {string}
+ */
+function findFreeSlots(events_json, window_start, window_end) {
+    let deferred5_0;
+    let deferred5_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(events_json, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(window_start, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len1 = WASM_VECTOR_LEN;
+        const ptr2 = passStringToWasm0(window_end, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len2 = WASM_VECTOR_LEN;
+        wasm.findFreeSlots(retptr, ptr0, len0, ptr1, len1, ptr2, len2);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+        var ptr4 = r0;
+        var len4 = r1;
+        if (r3) {
+            ptr4 = 0; len4 = 0;
+            throw takeObject(r2);
+        }
+        deferred5_0 = ptr4;
+        deferred5_1 = len4;
+        return getStringFromWasm0(ptr4, len4);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export3(deferred5_0, deferred5_1, 1);
+    }
+}
+exports.findFreeSlots = findFreeSlots;
+
+/**
+ * Merge N event streams into unified availability within a time window.
+ *
+ * `streams_json` must be a JSON array of `{stream_id, events: [{start, end}]}`.
+ * `window_start` and `window_end` are ISO 8601 datetime strings.
+ * `opaque` controls privacy: true = hide source counts, false = show them.
+ *
+ * Returns a JSON string with `{busy, free, window_start, window_end, privacy}`.
+ * @param {string} streams_json
+ * @param {string} window_start
+ * @param {string} window_end
+ * @param {boolean} opaque
+ * @returns {string}
+ */
+function mergeAvailability(streams_json, window_start, window_end, opaque) {
+    let deferred5_0;
+    let deferred5_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(streams_json, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(window_start, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len1 = WASM_VECTOR_LEN;
+        const ptr2 = passStringToWasm0(window_end, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len2 = WASM_VECTOR_LEN;
+        wasm.mergeAvailability(retptr, ptr0, len0, ptr1, len1, ptr2, len2, opaque);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+        var ptr4 = r0;
+        var len4 = r1;
+        if (r3) {
+            ptr4 = 0; len4 = 0;
+            throw takeObject(r2);
+        }
+        deferred5_0 = ptr4;
+        deferred5_1 = len4;
+        return getStringFromWasm0(ptr4, len4);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export3(deferred5_0, deferred5_1, 1);
+    }
+}
+exports.mergeAvailability = mergeAvailability;
+
+function __wbg_get_imports() {
+    const import0 = {
+        __proto__: null,
+        __wbg___wbindgen_throw_be289d5034ed271b: function(arg0, arg1) {
+            throw new Error(getStringFromWasm0(arg0, arg1));
+        },
+        __wbg_getTimezoneOffset_81776d10a4ec18a8: function(arg0) {
+            const ret = getObject(arg0).getTimezoneOffset();
+            return ret;
+        },
+        __wbg_new_245cd5c49157e602: function(arg0) {
+            const ret = new Date(getObject(arg0));
+            return addHeapObject(ret);
+        },
+        __wbg_new_with_year_month_day_hr_min_sec_f82362c71c4dfc23: function(arg0, arg1, arg2, arg3, arg4, arg5) {
+            const ret = new Date(arg0 >>> 0, arg1, arg2, arg3, arg4, arg5);
+            return addHeapObject(ret);
+        },
+        __wbindgen_cast_0000000000000001: function(arg0) {
+            // Cast intrinsic for `F64 -> Externref`.
+            const ret = arg0;
+            return addHeapObject(ret);
+        },
+        __wbindgen_cast_0000000000000002: function(arg0, arg1) {
+            // Cast intrinsic for `Ref(String) -> Externref`.
+            const ret = getStringFromWasm0(arg0, arg1);
+            return addHeapObject(ret);
+        },
+        __wbindgen_object_drop_ref: function(arg0) {
+            takeObject(arg0);
+        },
+    };
+    return {
+        __proto__: null,
+        "./truth_engine_wasm_bg.js": import0,
+    };
+}
+
+function addHeapObject(obj) {
+    if (heap_next === heap.length) heap.push(heap.length + 1);
+    const idx = heap_next;
+    heap_next = heap[idx];
+
+    heap[idx] = obj;
+    return idx;
+}
+
+function dropObject(idx) {
+    if (idx < 132) return;
+    heap[idx] = heap_next;
+    heap_next = idx;
+}
+
+let cachedDataViewMemory0 = null;
+function getDataViewMemory0() {
+    if (cachedDataViewMemory0 === null || cachedDataViewMemory0.buffer.detached === true || (cachedDataViewMemory0.buffer.detached === undefined && cachedDataViewMemory0.buffer !== wasm.memory.buffer)) {
+        cachedDataViewMemory0 = new DataView(wasm.memory.buffer);
+    }
+    return cachedDataViewMemory0;
+}
+
+function getStringFromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return decodeText(ptr, len);
+}
+
+let cachedUint8ArrayMemory0 = null;
+function getUint8ArrayMemory0() {
+    if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
+        cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer);
+    }
+    return cachedUint8ArrayMemory0;
+}
+
+function getObject(idx) { return heap[idx]; }
+
+let heap = new Array(128).fill(undefined);
+heap.push(undefined, null, true, false);
+
+let heap_next = heap.length;
+
+function isLikeNone(x) {
+    return x === undefined || x === null;
+}
+
+function passStringToWasm0(arg, malloc, realloc) {
+    if (realloc === undefined) {
+        const buf = cachedTextEncoder.encode(arg);
+        const ptr = malloc(buf.length, 1) >>> 0;
+        getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf);
+        WASM_VECTOR_LEN = buf.length;
+        return ptr;
+    }
+
+    let len = arg.length;
+    let ptr = malloc(len, 1) >>> 0;
+
+    const mem = getUint8ArrayMemory0();
+
+    let offset = 0;
+
+    for (; offset < len; offset++) {
+        const code = arg.charCodeAt(offset);
+        if (code > 0x7F) break;
+        mem[ptr + offset] = code;
+    }
+    if (offset !== len) {
+        if (offset !== 0) {
+            arg = arg.slice(offset);
+        }
+        ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
+        const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+        const ret = cachedTextEncoder.encodeInto(arg, view);
+
+        offset += ret.written;
+        ptr = realloc(ptr, len, offset, 1) >>> 0;
+    }
+
+    WASM_VECTOR_LEN = offset;
+    return ptr;
+}
+
+function takeObject(idx) {
+    const ret = getObject(idx);
+    dropObject(idx);
+    return ret;
+}
+
+let cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+cachedTextDecoder.decode();
+function decodeText(ptr, len) {
+    return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
+}
+
+const cachedTextEncoder = new TextEncoder();
+
+if (!('encodeInto' in cachedTextEncoder)) {
+    cachedTextEncoder.encodeInto = function (arg, view) {
+        const buf = cachedTextEncoder.encode(arg);
+        view.set(buf);
+        return {
+            read: arg.length,
+            written: buf.length
+        };
+    };
+}
+
+let WASM_VECTOR_LEN = 0;
+
+const wasmPath = `${__dirname}/truth_engine_wasm_bg.wasm`;
+const wasmBytes = require('fs').readFileSync(wasmPath);
+const wasmModule = new WebAssembly.Module(wasmBytes);
+const wasm = new WebAssembly.Instance(wasmModule, __wbg_get_imports()).exports;

package/wasm/truth_engine_wasm.d.ts

@@ -0,0 +1,56 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Expand an RRULE string into concrete datetime instances.
+ *
+ * Returns a JSON string containing an array of `{start, end}` objects with
+ * RFC 3339 datetime strings.
+ *
+ * # Arguments
+ * - `rrule` -- RFC 5545 RRULE string (e.g., "FREQ=WEEKLY;BYDAY=TU,TH")
+ * - `dtstart` -- Local datetime string (e.g., "2026-02-17T14:00:00")
+ * - `duration_minutes` -- Duration of each instance in minutes
+ * - `timezone` -- IANA timezone (e.g., "America/Los_Angeles")
+ * - `until` -- Optional end boundary for expansion (local datetime string)
+ * - `max_count` -- Optional maximum number of instances
+ */
+export function expandRRule(rrule: string, dtstart: string, duration_minutes: number, timezone: string, until?: string | null, max_count?: number | null): string;
+
+/**
+ * Find all pairwise conflicts (overlapping time ranges) between two event lists.
+ *
+ * Both arguments must be JSON arrays of `{start, end}` objects with ISO 8601
+ * datetime strings. Returns a JSON string containing an array of conflict objects,
+ * each with `event_a`, `event_b`, and `overlap_minutes`.
+ */
+export function findConflicts(events_a_json: string, events_b_json: string): string;
+
+/**
+ * Find the first free slot of at least `min_duration_minutes` across N merged
+ * event streams.
+ *
+ * `streams_json` must be a JSON array of `{stream_id, events: [{start, end}]}`.
+ * Returns a JSON string with `{start, end, duration_minutes}` or `null`.
+ */
+export function findFirstFreeAcross(streams_json: string, window_start: string, window_end: string, min_duration_minutes: bigint): string;
+
+/**
+ * Find free time slots within a given time window, given a list of busy events.
+ *
+ * `events_json` must be a JSON array of `{start, end}` objects. `window_start`
+ * and `window_end` are ISO 8601 datetime strings. Returns a JSON string containing
+ * an array of `{start, end, duration_minutes}` objects.
+ */
+export function findFreeSlots(events_json: string, window_start: string, window_end: string): string;
+
+/**
+ * Merge N event streams into unified availability within a time window.
+ *
+ * `streams_json` must be a JSON array of `{stream_id, events: [{start, end}]}`.
+ * `window_start` and `window_end` are ISO 8601 datetime strings.
+ * `opaque` controls privacy: true = hide source counts, false = show them.
+ *
+ * Returns a JSON string with `{busy, free, window_start, window_end, privacy}`.
+ */
+export function mergeAvailability(streams_json: string, window_start: string, window_end: string, opaque: boolean): string;

package/wasm/truth_engine_wasm_bg.wasm.d.ts

@@ -0,0 +1,12 @@
+/* tslint:disable */
+/* eslint-disable */
+export const memory: WebAssembly.Memory;
+export const expandRRule: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number) => void;
+export const findConflicts: (a: number, b: number, c: number, d: number, e: number) => void;
+export const findFirstFreeAcross: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: bigint) => void;
+export const findFreeSlots: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+export const mergeAvailability: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
+export const __wbindgen_add_to_stack_pointer: (a: number) => number;
+export const __wbindgen_export: (a: number, b: number) => number;
+export const __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
+export const __wbindgen_export3: (a: number, b: number, c: number) => void;