@temporal-cortex/truth-engine 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -57,6 +57,8 @@ export interface UnifiedAvailability {
     window_end: string;
     privacy: string;
 }
+/** @internal — exposed for testing only. */
+export declare function _resetHint(): void;
 /**
  * Merge N event streams into unified availability within a time window.
  *
@@ -81,3 +83,64 @@ export declare function mergeAvailability(streams: EventStream[], windowStart: s
  * @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;
+export interface ConvertedDatetime {
+    utc: string;
+    local: string;
+    timezone: string;
+    utc_offset: string;
+    dst_active: boolean;
+}
+export interface DurationInfo {
+    total_seconds: number;
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+    human_readable: string;
+}
+export interface AdjustedTimestamp {
+    original: string;
+    adjusted_utc: string;
+    adjusted_local: string;
+    adjustment_applied: string;
+}
+export interface ResolvedDatetime {
+    resolved_utc: string;
+    resolved_local: string;
+    timezone: string;
+    interpretation: string;
+}
+/**
+ * Convert a datetime to a different timezone representation.
+ *
+ * @param datetime - RFC 3339 datetime string (e.g., "2026-03-15T14:00:00Z")
+ * @param targetTimezone - IANA timezone name (e.g., "America/New_York")
+ * @returns Conversion result with UTC, local, offset, and DST info
+ */
+export declare function convertTimezone(datetime: string, targetTimezone: string): ConvertedDatetime;
+/**
+ * Compute the duration between two timestamps.
+ *
+ * @param start - RFC 3339 datetime string
+ * @param end - RFC 3339 datetime string
+ * @returns Duration decomposed into days, hours, minutes, seconds
+ */
+export declare function computeDuration(start: string, end: string): DurationInfo;
+/**
+ * Adjust a timestamp by adding or subtracting a duration.
+ *
+ * @param datetime - RFC 3339 datetime string
+ * @param adjustment - Duration string (e.g., "+2h", "-30m", "+1d2h30m")
+ * @param timezone - IANA timezone for day-level adjustments across DST
+ * @returns Adjusted timestamp in UTC and local time
+ */
+export declare function adjustTimestamp(datetime: string, adjustment: string, timezone: string): AdjustedTimestamp;
+/**
+ * Resolve a relative time expression to an absolute datetime.
+ *
+ * @param anchor - RFC 3339 datetime string (the "now" reference point)
+ * @param expression - Time expression (e.g., "next Tuesday at 2pm", "tomorrow", "+3h")
+ * @param timezone - IANA timezone for interpreting local-time expressions
+ * @returns Resolved datetime in UTC and local time with interpretation
+ */
+export declare function resolveRelative(anchor: string, expression: string, timezone: string): ResolvedDatetime;

package/dist/index.js

@@ -54,6 +54,26 @@ export function findFreeSlots(events, windowStart, windowEnd) {
     return JSON.parse(json);
 }
 // ---------------------------------------------------------------------------
+// One-time hint for multi-calendar users
+// ---------------------------------------------------------------------------
+let _hintShown = false;
+function _maybeShowHint(streamCount) {
+    if (_hintShown)
+        return;
+    if (typeof process !== "undefined" && process.env?.TEMPORAL_CORTEX_QUIET)
+        return;
+    if (streamCount < 3)
+        return;
+    _hintShown = true;
+    console.info("[temporal-cortex] Merging 3+ calendars? Temporal Cortex Platform adds " +
+        "live connectors, booking safety & policy rules. " +
+        "https://tally.so/r/aQ66W2");
+}
+/** @internal — exposed for testing only. */
+export function _resetHint() {
+    _hintShown = false;
+}
+// ---------------------------------------------------------------------------
 // Multi-stream availability API
 // ---------------------------------------------------------------------------
 /**
@@ -69,6 +89,7 @@ export function findFreeSlots(events, windowStart, windowEnd) {
  * @returns Unified availability with busy blocks and free slots
  */
 export function mergeAvailability(streams, windowStart, windowEnd, opaque = true) {
+    _maybeShowHint(streams.length);
     const json = wasm.mergeAvailability(JSON.stringify(streams), windowStart, windowEnd, opaque);
     return JSON.parse(json);
 }
@@ -86,3 +107,52 @@ export function findFirstFreeAcross(streams, windowStart, windowEnd, minDuration
     const json = wasm.findFirstFreeAcross(JSON.stringify(streams), windowStart, windowEnd, minDurationMinutes);
     return JSON.parse(json);
 }
+// ---------------------------------------------------------------------------
+// Temporal computation API
+// ---------------------------------------------------------------------------
+/**
+ * Convert a datetime to a different timezone representation.
+ *
+ * @param datetime - RFC 3339 datetime string (e.g., "2026-03-15T14:00:00Z")
+ * @param targetTimezone - IANA timezone name (e.g., "America/New_York")
+ * @returns Conversion result with UTC, local, offset, and DST info
+ */
+export function convertTimezone(datetime, targetTimezone) {
+    const json = wasm.convertTimezone(datetime, targetTimezone);
+    return JSON.parse(json);
+}
+/**
+ * Compute the duration between two timestamps.
+ *
+ * @param start - RFC 3339 datetime string
+ * @param end - RFC 3339 datetime string
+ * @returns Duration decomposed into days, hours, minutes, seconds
+ */
+export function computeDuration(start, end) {
+    const json = wasm.computeDuration(start, end);
+    return JSON.parse(json);
+}
+/**
+ * Adjust a timestamp by adding or subtracting a duration.
+ *
+ * @param datetime - RFC 3339 datetime string
+ * @param adjustment - Duration string (e.g., "+2h", "-30m", "+1d2h30m")
+ * @param timezone - IANA timezone for day-level adjustments across DST
+ * @returns Adjusted timestamp in UTC and local time
+ */
+export function adjustTimestamp(datetime, adjustment, timezone) {
+    const json = wasm.adjustTimestamp(datetime, adjustment, timezone);
+    return JSON.parse(json);
+}
+/**
+ * Resolve a relative time expression to an absolute datetime.
+ *
+ * @param anchor - RFC 3339 datetime string (the "now" reference point)
+ * @param expression - Time expression (e.g., "next Tuesday at 2pm", "tomorrow", "+3h")
+ * @param timezone - IANA timezone for interpreting local-time expressions
+ * @returns Resolved datetime in UTC and local time with interpretation
+ */
+export function resolveRelative(anchor, expression, timezone) {
+    const json = wasm.resolveRelative(anchor, expression, timezone);
+    return JSON.parse(json);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@temporal-cortex/truth-engine",
-  "version": "0.1.0",
-  "description": "Truth Engine — deterministic RRULE expansion, conflict detection, free/busy for AI calendar agents",
+  "version": "0.2.0",
+  "description": "Truth Engine — deterministic temporal resolution, timezone conversion, RRULE expansion, conflict detection, and availability merging for AI calendar agents",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,6 +14,8 @@
     "calendar",
     "icalendar",
     "recurrence",
+    "timezone",
+    "datetime",
     "wasm"
   ],
   "license": "MIT OR Apache-2.0",
@@ -28,9 +30,9 @@
     "url": "https://github.com/billylui/temporal-cortex-core/issues"
   },
   "devDependencies": {
-    "@types/node": "^20",
+    "@types/node": "^25",
     "typescript": "^5",
-    "vitest": "^3"
+    "vitest": "^4.0.18"
   },
   "scripts": {
     "build": "tsc",

package/wasm/truth_engine_wasm.cjs

@@ -1,5 +1,125 @@
 /* @ts-self-types="./truth_engine_wasm.d.ts" */
 
+/**
+ * Adjust a timestamp by a duration string.
+ *
+ * `adjustment` format: `+2h`, `-30m`, `+1d2h30m`, `+1w`, etc.
+ * `timezone` is an IANA timezone for day-level adjustments across DST.
+ *
+ * Returns a JSON string with `{original, adjusted_utc, adjusted_local, adjustment_applied}`.
+ * @param {string} datetime
+ * @param {string} adjustment
+ * @param {string} timezone
+ * @returns {string}
+ */
+function adjustTimestamp(datetime, adjustment, timezone) {
+    let deferred5_0;
+    let deferred5_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(datetime, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(adjustment, 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;
+        wasm.adjustTimestamp(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.adjustTimestamp = adjustTimestamp;
+
+/**
+ * Compute the duration between two timestamps.
+ *
+ * Returns a JSON string with `{total_seconds, days, hours, minutes, seconds, human_readable}`.
+ * @param {string} start
+ * @param {string} end
+ * @returns {string}
+ */
+function computeDuration(start, end) {
+    let deferred4_0;
+    let deferred4_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(start, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(end, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len1 = WASM_VECTOR_LEN;
+        wasm.computeDuration(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.computeDuration = computeDuration;
+
+/**
+ * Convert a datetime to a different timezone.
+ *
+ * Returns a JSON string with `{utc, local, timezone, utc_offset, dst_active}`.
+ * @param {string} datetime
+ * @param {string} target_timezone
+ * @returns {string}
+ */
+function convertTimezone(datetime, target_timezone) {
+    let deferred4_0;
+    let deferred4_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(datetime, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(target_timezone, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len1 = WASM_VECTOR_LEN;
+        wasm.convertTimezone(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.convertTimezone = convertTimezone;
+
 /**
  * Expand an RRULE string into concrete datetime instances.
  *
@@ -228,6 +348,51 @@ function mergeAvailability(streams_json, window_start, window_end, opaque) {
 }
 exports.mergeAvailability = mergeAvailability;
 
+/**
+ * Resolve a relative time expression to an absolute datetime.
+ *
+ * `anchor` is an RFC 3339 datetime (the "now" reference point).
+ * `expression` is a time expression (e.g., "next Tuesday at 2pm", "tomorrow", "+3h").
+ * `timezone` is an IANA timezone for interpreting local-time expressions.
+ *
+ * Returns a JSON string with `{resolved_utc, resolved_local, timezone, interpretation}`.
+ * @param {string} anchor
+ * @param {string} expression
+ * @param {string} timezone
+ * @returns {string}
+ */
+function resolveRelative(anchor, expression, timezone) {
+    let deferred5_0;
+    let deferred5_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(anchor, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(expression, 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;
+        wasm.resolveRelative(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.resolveRelative = resolveRelative;
+
 function __wbg_get_imports() {
     const import0 = {
         __proto__: null,

package/wasm/truth_engine_wasm.d.ts

@@ -1,6 +1,30 @@
 /* tslint:disable */
 /* eslint-disable */
 
+/**
+ * Adjust a timestamp by a duration string.
+ *
+ * `adjustment` format: `+2h`, `-30m`, `+1d2h30m`, `+1w`, etc.
+ * `timezone` is an IANA timezone for day-level adjustments across DST.
+ *
+ * Returns a JSON string with `{original, adjusted_utc, adjusted_local, adjustment_applied}`.
+ */
+export function adjustTimestamp(datetime: string, adjustment: string, timezone: string): string;
+
+/**
+ * Compute the duration between two timestamps.
+ *
+ * Returns a JSON string with `{total_seconds, days, hours, minutes, seconds, human_readable}`.
+ */
+export function computeDuration(start: string, end: string): string;
+
+/**
+ * Convert a datetime to a different timezone.
+ *
+ * Returns a JSON string with `{utc, local, timezone, utc_offset, dst_active}`.
+ */
+export function convertTimezone(datetime: string, target_timezone: string): string;
+
 /**
  * Expand an RRULE string into concrete datetime instances.
  *
@@ -54,3 +78,14 @@ export function findFreeSlots(events_json: string, window_start: string, window_
  * 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;
+
+/**
+ * Resolve a relative time expression to an absolute datetime.
+ *
+ * `anchor` is an RFC 3339 datetime (the "now" reference point).
+ * `expression` is a time expression (e.g., "next Tuesday at 2pm", "tomorrow", "+3h").
+ * `timezone` is an IANA timezone for interpreting local-time expressions.
+ *
+ * Returns a JSON string with `{resolved_utc, resolved_local, timezone, interpretation}`.
+ */
+export function resolveRelative(anchor: string, expression: string, timezone: string): string;

package/wasm/truth_engine_wasm_bg.wasm.d.ts

@@ -1,11 +1,15 @@
 /* tslint:disable */
 /* eslint-disable */
 export const memory: WebAssembly.Memory;
+export const adjustTimestamp: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+export const computeDuration: (a: number, b: number, c: number, d: number, e: number) => void;
+export const convertTimezone: (a: number, b: number, c: number, d: number, e: number) => void;
 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 resolveRelative: (a: number, b: number, c: number, d: number, e: number, f: number, g: 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;