@mindrian_os/cli 2.0.0-beta.29 → 2.0.0-beta.31

package/lib/core/temporal/reference-now.cjs

@@ -0,0 +1,281 @@
+'use strict';
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 160-01 Task 1 -- getReferenceNow(): one authoritative reference clock.
+ * ===========================================================================
+ *
+ * R1 (160-SPEC.md). getReferenceNow() is a PRECEDENCE LADDER (D-01b):
+ *
+ *   1. injected Claude Code `currentDate` wins for the calendar DATE (free, no
+ *      network). The time-of-day is blended from any available seam offset so
+ *      the date is correct without inventing a wall-clock time.
+ *   2. an OPTIONAL online time-fetch clock-skew corrector -- NTP-style: fetch
+ *      ONCE per session, compute offset = authoritativeMs - Date.now(), persist
+ *      the offset to the seam, then `localclock + offset`. getReferenceNow
+ *      itself makes NO network call; it consumes a cached offset only. The
+ *      online rung degrades silently offline (returns null, no throw).
+ *   3. a raw `Date.now()` floor.
+ *
+ * Hybrid capture (D-01): a SessionStart hook seeds ~/.mindrian/reference-now.json
+ * with a Date.now() floor; Larry corrects the seam via a tiny command when the
+ * model-known `currentDate` diverges. The reader routes through the existing
+ * options.now clock seam (D-01a): getReferenceNow returns a plain millisecond
+ * integer directly usable as the value an `options.now` closure would yield.
+ *
+ * Part 8 (LOCAL -> BRAIN: NO). The seam is a LOCAL file; it never leaves the
+ * machine. The ONLY network surface (fetchTimeOffsetOnce) is a bare GET that
+ * reads ONLY the HTTP `Date` response header -- it sends NO body, NO query
+ * params, and NO user-derived headers. Zero user bytes egress. SIGNAL -> LOCAL.
+ *
+ * House rule: hyphens only, no em-dashes. Pure CJS, node built-ins only, zero
+ * new runtime dependencies (native fetch). Reuses isoSecond from the Feynman
+ * timeline-renderer rather than re-implementing ISO rendering.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+// Reuse the existing ISO renderer (Canon Part 7) rather than re-implementing it.
+const { isoSecond } = require('../feynman/timeline-renderer.cjs');
+
+// The default LOCAL seam path. ~/.mindrian/reference-now.json.
+const DEFAULT_SEAM_PATH = path.join(os.homedir(), '.mindrian', 'reference-now.json');
+
+// A bare, keyless public time endpoint. The HTTP Date response header is the
+// authoritative-time source -- no API key, no JSON body, no user bytes.
+const DEFAULT_TIME_ENDPOINT = 'https://www.google.com/generate_204';
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+// ---------- internal helpers ----------
+
+function isFiniteNumber(v) {
+  return typeof v === 'number' && Number.isFinite(v);
+}
+
+// Strict YYYY-MM-DD validation that rejects impossible dates (e.g. 2026-13-99).
+// Returns the UTC-midnight epoch ms for the calendar date, or null.
+function parseCurrentDateToUtcMidnight(currentDateStr) {
+  if (typeof currentDateStr !== 'string') return null;
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(currentDateStr.trim());
+  if (!m) return null;
+  const year = Number(m[1]);
+  const month = Number(m[2]); // 1-12
+  const day = Number(m[3]);   // 1-31
+  if (month < 1 || month > 12) return null;
+  if (day < 1 || day > 31) return null;
+  const ms = Date.UTC(year, month - 1, day, 0, 0, 0, 0);
+  if (!Number.isFinite(ms)) return null;
+  // Round-trip guard: reject overflow dates (e.g. 2026-02-31 -> Mar 3).
+  const d = new Date(ms);
+  if (d.getUTCFullYear() !== year || d.getUTCMonth() !== month - 1 || d.getUTCDate() !== day) {
+    return null;
+  }
+  return ms;
+}
+
+// ---------- seam read / write (LOCAL only) ----------
+
+/*
+ * readSeam(seamPath) -> the parsed seam object, or null on missing/malformed.
+ * Never throws. Validates basic shape (numeric floorMs/offsetMs when present).
+ * Seam shape: { floorMs, offsetMs, lastFetchSession, source, updatedAt }.
+ */
+function readSeam(seamPath) {
+  const p = typeof seamPath === 'string' && seamPath ? seamPath : DEFAULT_SEAM_PATH;
+  try {
+    if (!fs.existsSync(p)) return null;
+    const raw = fs.readFileSync(p, 'utf8');
+    const obj = JSON.parse(raw);
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return null;
+    // Coerce/validate numeric fields; tolerate absent ones.
+    if (obj.floorMs != null && !isFiniteNumber(obj.floorMs)) return null;
+    if (obj.offsetMs != null && !isFiniteNumber(obj.offsetMs)) return null;
+    return obj;
+  } catch (_err) {
+    // Malformed JSON, permission error, etc. Degrade to null (T-160-02).
+    return null;
+  }
+}
+
+/*
+ * writeSeam(seamPath, partial) -> { ok, reason? }. Merges `partial` over any
+ * existing seam, stamps updatedAt (ISO seconds), and writes atomically-ish.
+ * Never throws; returns { ok: false, reason } on failure.
+ */
+function writeSeam(seamPath, partial) {
+  const p = typeof seamPath === 'string' && seamPath ? seamPath : DEFAULT_SEAM_PATH;
+  const patch = partial && typeof partial === 'object' && !Array.isArray(partial) ? partial : {};
+  try {
+    const existing = readSeam(p) || {};
+    const merged = Object.assign({}, existing, patch);
+    merged.updatedAt = isoSecond(Date.now());
+    const dir = path.dirname(p);
+    try { fs.mkdirSync(dir, { recursive: true }); } catch (_e) { /* tolerant */ }
+    const tmp = p + '.tmp-' + process.pid;
+    fs.writeFileSync(tmp, JSON.stringify(merged, null, 2), 'utf8');
+    fs.renameSync(tmp, p);
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, reason: err && err.message ? err.message : String(err) };
+  }
+}
+
+// ---------- applyCurrentDate ----------
+
+/*
+ * applyCurrentDate(currentDateStr, baseMs) -> epoch ms landing on the
+ * currentDate calendar DATE, carrying baseMs's time-of-day so a downstream
+ * delta keeps sub-day granularity. Returns null on a malformed date string.
+ *
+ * Per D-01b currentDate wins the DATE; the time-of-day is whatever the caller
+ * supplies (the seam-blended local clock), never invented.
+ */
+function applyCurrentDate(currentDateStr, baseMs) {
+  const dateMidnight = parseCurrentDateToUtcMidnight(currentDateStr);
+  if (dateMidnight == null) return null;
+  // Time-of-day fraction within the day from baseMs (UTC). Falls back to 0.
+  let todMs = 0;
+  if (isFiniteNumber(baseMs)) {
+    const r = baseMs % MS_PER_DAY;
+    todMs = r >= 0 ? r : r + MS_PER_DAY; // normalize negative epoch (pre-1970) safely
+  }
+  const result = dateMidnight + todMs;
+  // Guard: the blended time-of-day must not roll the calendar date forward.
+  const d = new Date(result);
+  const dm = new Date(dateMidnight);
+  if (d.getUTCFullYear() !== dm.getUTCFullYear() ||
+      d.getUTCMonth() !== dm.getUTCMonth() ||
+      d.getUTCDate() !== dm.getUTCDate()) {
+    return dateMidnight; // clamp to midnight rather than spill into the next day
+  }
+  return result;
+}
+
+// ---------- fetchTimeOffsetOnce (the OPTIONAL online skew corrector) ----------
+
+/*
+ * fetchTimeOffsetOnce(opts) -> Promise<number|null>.
+ *
+ * Performs AT MOST ONE bare GET per session to a public time endpoint, reads
+ * ONLY the HTTP `Date` response header, computes offset = authoritativeMs -
+ * localNowMs, persists the offset to the seam, and returns the offset. On ANY
+ * network or parse failure it returns null silently (degrades). It NEVER
+ * throws and NEVER sends user bytes (no body, no query params, no user headers).
+ *
+ * opts:
+ *   seamPath   LOCAL seam file (default ~/.mindrian/reference-now.json)
+ *   fetchImpl  injectable fetch (default global fetch) -- test seam
+ *   now        injectable clock (default Date.now) -- test seam
+ *   sessionId  fire-once key; if the seam already has this lastFetchSession,
+ *              the fetch is skipped and the cached offset is returned.
+ *   endpoint   override the time endpoint (default DEFAULT_TIME_ENDPOINT)
+ */
+async function fetchTimeOffsetOnce(opts) {
+  const o = opts && typeof opts === 'object' ? opts : {};
+  const seamPath = typeof o.seamPath === 'string' && o.seamPath ? o.seamPath : DEFAULT_SEAM_PATH;
+  const nowFn = typeof o.now === 'function' ? o.now : Date.now;
+  const fetchImpl = typeof o.fetchImpl === 'function'
+    ? o.fetchImpl
+    : (typeof fetch === 'function' ? fetch : null);
+  const endpoint = typeof o.endpoint === 'string' && o.endpoint ? o.endpoint : DEFAULT_TIME_ENDPOINT;
+  const sessionId = typeof o.sessionId === 'string' ? o.sessionId : null;
+
+  // Fire-once-per-session: if the seam already recorded this session id and has
+  // a numeric offset, return the cached offset without a network call.
+  if (sessionId) {
+    const seam = readSeam(seamPath);
+    if (seam && seam.lastFetchSession === sessionId && isFiniteNumber(seam.offsetMs)) {
+      return seam.offsetMs;
+    }
+  }
+
+  if (typeof fetchImpl !== 'function') return null;
+
+  try {
+    // Bare GET. NO body, NO query string, NO user-derived headers. SIGNAL only.
+    const resp = await fetchImpl(endpoint, { method: 'GET' });
+    if (!resp || !resp.headers || typeof resp.headers.get !== 'function') return null;
+    const dateHeader = resp.headers.get('date');
+    if (!dateHeader) return null;
+    const authoritativeMs = Date.parse(dateHeader);
+    if (!Number.isFinite(authoritativeMs)) return null;
+    const localNowMs = nowFn();
+    const offsetMs = authoritativeMs - localNowMs;
+    if (!Number.isFinite(offsetMs)) return null;
+    // Persist the offset + the session marker to the seam (LOCAL write).
+    writeSeam(seamPath, {
+      offsetMs,
+      lastFetchSession: sessionId || undefined,
+      source: 'online_skew',
+    });
+    return offsetMs;
+  } catch (_err) {
+    // ANY failure (network, DNS, parse, abort) degrades to null silently.
+    return null;
+  }
+}
+
+// ---------- getReferenceNow (the precedence ladder) ----------
+
+/*
+ * getReferenceNow(opts) -> { referenceMs, source }.
+ *   source in 'currentDate' | 'online_skew' | 'seam' | 'date_now'.
+ *
+ * Precedence (D-01b):
+ *   1. valid injected currentDate -> calendar date floor blended with the
+ *      seam offset for time-of-day. source 'currentDate'.
+ *   2. (else) a fresh seam value -> source 'seam'.
+ *   3. (else) now() floor (default Date.now) -> source 'date_now'.
+ *
+ * Never throws. opts:
+ *   currentDate  YYYY-MM-DD injected by Claude Code (optional)
+ *   now          injectable clock (default Date.now) -- the options.now seam
+ *   seamPath     LOCAL seam file (default ~/.mindrian/reference-now.json)
+ */
+function getReferenceNow(opts) {
+  const o = opts && typeof opts === 'object' ? opts : {};
+  const nowFn = typeof o.now === 'function' ? o.now : Date.now;
+  const seamPath = typeof o.seamPath === 'string' && o.seamPath ? o.seamPath : DEFAULT_SEAM_PATH;
+
+  let localNow;
+  try { localNow = nowFn(); } catch (_e) { localNow = Date.now(); }
+  if (!isFiniteNumber(localNow)) localNow = Date.now();
+
+  // Read the seam once (LOCAL, no network). Tolerant of missing/malformed.
+  const seam = readSeam(seamPath);
+  const seamOffset = seam && isFiniteNumber(seam.offsetMs) ? seam.offsetMs : 0;
+
+  // Rung 1: injected currentDate wins the calendar DATE.
+  if (typeof o.currentDate === 'string' && o.currentDate.trim()) {
+    // Blend the seam offset into the local clock so time-of-day reflects the
+    // skew-corrected local clock; the DATE is then forced to currentDate.
+    const skewCorrectedNow = localNow + seamOffset;
+    const blended = applyCurrentDate(o.currentDate, skewCorrectedNow);
+    if (blended != null) {
+      return { referenceMs: blended, source: 'currentDate' };
+    }
+    // Malformed currentDate falls through to the next rung.
+  }
+
+  // Rung 2: a fresh seam floor value.
+  if (seam && isFiniteNumber(seam.floorMs)) {
+    return { referenceMs: seam.floorMs, source: 'seam' };
+  }
+
+  // Rung 3: the Date.now (or injected now) floor.
+  return { referenceMs: localNow, source: 'date_now' };
+}
+
+module.exports = {
+  getReferenceNow,
+  readSeam,
+  writeSeam,
+  applyCurrentDate,
+  fetchTimeOffsetOnce,
+  // Exported for the seeder/command + tests.
+  DEFAULT_SEAM_PATH,
+  DEFAULT_TIME_ENDPOINT,
+};

package/lib/core/temporal/reference-now.test.cjs

@@ -0,0 +1,225 @@
+'use strict';
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 160-01 Task 1 -- getReferenceNow() precedence ladder + local seam tests.
+ *
+ * R1 acceptance (160-SPEC.md):
+ *   (a/b) with currentDate=2026-06-16 injected and now() stubbed to a DIFFERENT
+ *         calendar date, getReferenceNow().referenceMs falls on 2026-06-16.
+ *   (c)   with fetchTimeOffsetOnce's fetch stubbed to throw, it returns null and
+ *         getReferenceNow still returns a valid reference with no thrown error.
+ *
+ * Decisions (160-CONTEXT.md):
+ *   D-01b precedence ladder: injected currentDate (calendar date) beats a fresh
+ *         seam value beats now() floor.
+ *   D-01a route through the options.now seam contract (a plain millisecond int).
+ *
+ * House rule: hyphens only, no em-dashes. Pure CJS, node built-ins only.
+ */
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const {
+  getReferenceNow,
+  readSeam,
+  writeSeam,
+  applyCurrentDate,
+  fetchTimeOffsetOnce,
+} = require('./reference-now.cjs');
+
+// ---------- helpers ----------
+
+function tmpSeam(name) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'refnow-'));
+  return path.join(dir, (name || 'reference-now') + '.json');
+}
+
+// A fixed system-clock stub that lands on a DIFFERENT calendar date than the
+// injected currentDate. 2026-01-02T03:04:05Z (Jan 2), to contrast with Jun 16.
+const DIVERGENT_CLOCK_MS = Date.UTC(2026, 0, 2, 3, 4, 5);
+
+// ---------- exports surface ----------
+
+test('exports the documented surface', () => {
+  assert.equal(typeof getReferenceNow, 'function');
+  assert.equal(typeof readSeam, 'function');
+  assert.equal(typeof writeSeam, 'function');
+  assert.equal(typeof applyCurrentDate, 'function');
+  assert.equal(typeof fetchTimeOffsetOnce, 'function');
+});
+
+// ---------- R1 acceptance a + b: currentDate wins the calendar DATE ----------
+
+test('R1 a/b: injected currentDate wins the calendar date over a divergent system clock', () => {
+  const seamPath = tmpSeam();
+  const res = getReferenceNow({
+    currentDate: '2026-06-16',
+    now: () => DIVERGENT_CLOCK_MS,
+    seamPath,
+  });
+  assert.equal(typeof res.referenceMs, 'number');
+  assert.ok(Number.isFinite(res.referenceMs));
+  // The returned reference must land on the 2026-06-16 calendar date (UTC).
+  const d = new Date(res.referenceMs);
+  assert.equal(d.getUTCFullYear(), 2026);
+  assert.equal(d.getUTCMonth(), 5); // June is month index 5
+  assert.equal(d.getUTCDate(), 16);
+  // It must NOT be the divergent system-clock date (Jan 2).
+  assert.notEqual(d.getUTCMonth(), 0);
+  assert.equal(res.source, 'currentDate');
+});
+
+test('R1 a/b: returned referenceMs is a millisecond integer usable as an options.now value', () => {
+  const seamPath = tmpSeam();
+  const res = getReferenceNow({ currentDate: '2026-06-16', now: () => DIVERGENT_CLOCK_MS, seamPath });
+  // options.now contract: a function returning a ms integer. The reference is
+  // directly usable as that returned value.
+  assert.ok(Number.isInteger(res.referenceMs));
+  const asNowFn = () => res.referenceMs;
+  assert.equal(asNowFn(), res.referenceMs);
+});
+
+test('currentDate blends seam offset for time-of-day while keeping the calendar date', () => {
+  const seamPath = tmpSeam();
+  // Seed a seam with an offset (skew corrector result).
+  writeSeam(seamPath, { floorMs: DIVERGENT_CLOCK_MS, offsetMs: 5000, source: 'seam' });
+  const res = getReferenceNow({ currentDate: '2026-06-16', now: () => DIVERGENT_CLOCK_MS, seamPath });
+  const d = new Date(res.referenceMs);
+  // Calendar date still 2026-06-16.
+  assert.equal(d.getUTCFullYear(), 2026);
+  assert.equal(d.getUTCMonth(), 5);
+  assert.equal(d.getUTCDate(), 16);
+  assert.equal(res.source, 'currentDate');
+});
+
+// ---------- seam fallback ----------
+
+test('no currentDate + a fresh seam value returns the seam value', () => {
+  const seamPath = tmpSeam();
+  const seamFloor = Date.UTC(2026, 5, 10, 12, 0, 0);
+  writeSeam(seamPath, { floorMs: seamFloor, offsetMs: 0, source: 'seam' });
+  const res = getReferenceNow({ now: () => DIVERGENT_CLOCK_MS, seamPath });
+  assert.equal(res.source, 'seam');
+  assert.equal(typeof res.referenceMs, 'number');
+  assert.equal(res.referenceMs, seamFloor);
+});
+
+// ---------- Date.now floor ----------
+
+test('no currentDate + no usable seam falls back to now() with source date_now', () => {
+  const seamPath = tmpSeam(); // path does not exist yet
+  const res = getReferenceNow({ now: () => DIVERGENT_CLOCK_MS, seamPath });
+  assert.equal(res.source, 'date_now');
+  assert.equal(res.referenceMs, DIVERGENT_CLOCK_MS);
+});
+
+test('getReferenceNow never throws on a missing seam path and defaults now to Date.now', () => {
+  const seamPath = tmpSeam();
+  let res;
+  assert.doesNotThrow(() => {
+    res = getReferenceNow({ seamPath });
+  });
+  assert.ok(Number.isFinite(res.referenceMs));
+});
+
+test('getReferenceNow degrades to date_now on a malformed seam (tampering, T-160-02)', () => {
+  const seamPath = tmpSeam();
+  fs.writeFileSync(seamPath, '{ this is not valid json', 'utf8');
+  const res = getReferenceNow({ now: () => DIVERGENT_CLOCK_MS, seamPath });
+  assert.equal(res.source, 'date_now');
+  assert.equal(res.referenceMs, DIVERGENT_CLOCK_MS);
+});
+
+// ---------- applyCurrentDate ----------
+
+test('applyCurrentDate places baseMs time-of-day onto the currentDate calendar date', () => {
+  // base carries a time-of-day of 03:04:05 on Jan 2; applying 2026-06-16 should
+  // keep the calendar date June 16 (time-of-day handling is implementation-defined
+  // but the DATE must be June 16).
+  const out = applyCurrentDate('2026-06-16', DIVERGENT_CLOCK_MS);
+  assert.equal(typeof out, 'number');
+  const d = new Date(out);
+  assert.equal(d.getUTCFullYear(), 2026);
+  assert.equal(d.getUTCMonth(), 5);
+  assert.equal(d.getUTCDate(), 16);
+});
+
+test('applyCurrentDate returns null on a malformed date string', () => {
+  assert.equal(applyCurrentDate('not-a-date', DIVERGENT_CLOCK_MS), null);
+  assert.equal(applyCurrentDate('2026-13-99', DIVERGENT_CLOCK_MS), null);
+  assert.equal(applyCurrentDate('', DIVERGENT_CLOCK_MS), null);
+});
+
+// ---------- readSeam / writeSeam round-trip ----------
+
+test('writeSeam then readSeam round-trips a partial and stamps updatedAt', () => {
+  const seamPath = tmpSeam();
+  const w = writeSeam(seamPath, { floorMs: 123456, offsetMs: 7 });
+  assert.equal(w.ok, true);
+  const r = readSeam(seamPath);
+  assert.equal(r.floorMs, 123456);
+  assert.equal(r.offsetMs, 7);
+  assert.equal(typeof r.updatedAt, 'string');
+});
+
+test('readSeam returns null on a missing file (no throw)', () => {
+  const seamPath = tmpSeam();
+  let r;
+  assert.doesNotThrow(() => { r = readSeam(seamPath); });
+  assert.equal(r, null);
+});
+
+// ---------- R1 acceptance c: offline degrade ----------
+
+test('R1 c: fetchTimeOffsetOnce returns null when fetch throws, and never throws', async () => {
+  const seamPath = tmpSeam();
+  const throwingFetch = async () => { throw new Error('network down'); };
+  let out;
+  await assert.doesNotReject(async () => {
+    out = await fetchTimeOffsetOnce({ seamPath, fetchImpl: throwingFetch, now: () => DIVERGENT_CLOCK_MS });
+  });
+  assert.equal(out, null);
+  // getReferenceNow still returns a valid reference with no thrown error.
+  let res;
+  assert.doesNotThrow(() => { res = getReferenceNow({ now: () => DIVERGENT_CLOCK_MS, seamPath }); });
+  assert.ok(Number.isFinite(res.referenceMs));
+});
+
+test('R1 c: fetchTimeOffsetOnce returns null when the response has no Date header', async () => {
+  const seamPath = tmpSeam();
+  const noDateFetch = async () => ({ headers: { get: () => null } });
+  const out = await fetchTimeOffsetOnce({ seamPath, fetchImpl: noDateFetch, now: () => DIVERGENT_CLOCK_MS });
+  assert.equal(out, null);
+});
+
+test('fetchTimeOffsetOnce computes and persists offset on a successful Date header', async () => {
+  const seamPath = tmpSeam();
+  // Authoritative time is 10 seconds ahead of the local clock.
+  const authoritativeMs = DIVERGENT_CLOCK_MS + 10000;
+  const dateHeader = new Date(authoritativeMs).toUTCString();
+  const okFetch = async () => ({ headers: { get: (k) => (k.toLowerCase() === 'date' ? dateHeader : null) } });
+  const out = await fetchTimeOffsetOnce({ seamPath, fetchImpl: okFetch, now: () => DIVERGENT_CLOCK_MS });
+  assert.equal(typeof out, 'number');
+  // toUTCString truncates to whole seconds; allow up to 1s rounding.
+  assert.ok(Math.abs(out - 10000) <= 1000, 'offset near 10000ms, got ' + out);
+  const seam = readSeam(seamPath);
+  assert.equal(typeof seam.offsetMs, 'number');
+});
+
+test('fetchTimeOffsetOnce calls fetch at most once per session (idempotent on lastFetchSession)', async () => {
+  const seamPath = tmpSeam();
+  let calls = 0;
+  const countingFetch = async () => {
+    calls += 1;
+    return { headers: { get: (k) => (k.toLowerCase() === 'date' ? new Date(DIVERGENT_CLOCK_MS).toUTCString() : null) } };
+  };
+  const sessionId = 'session-abc';
+  await fetchTimeOffsetOnce({ seamPath, fetchImpl: countingFetch, now: () => DIVERGENT_CLOCK_MS, sessionId });
+  await fetchTimeOffsetOnce({ seamPath, fetchImpl: countingFetch, now: () => DIVERGENT_CLOCK_MS, sessionId });
+  assert.equal(calls, 1, 'fetch must fire at most once per session id');
+});

package/lib/core/temporal/resolve-relative-time.cjs

@@ -0,0 +1,116 @@
+'use strict';
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 160-02 Task 1 -- resolveRelativeTime(): chrono-node NL-time resolver.
+ * ==========================================================================
+ *
+ * R2 (160-SPEC.md). Turns a user's relative-time expression ("yesterday",
+ * "last Tuesday", "next quarter") into an absolute epoch-ms `valid_at`,
+ * ANCHORED to getReferenceNow() (D-01a -- the same options.now clock seam tests
+ * inject), with chrono `forwardDate` enabled for future-biased phrases.
+ *
+ * Anchor contract (D-01a): the resolver never reads Date.now() directly for its
+ * reference. It accepts an explicit `opts.referenceMs` (the value an
+ * `options.now` closure would yield), or an injected `opts.currentDate`
+ * (YYYY-MM-DD), and otherwise calls getReferenceNow() from the Wave 1 module.
+ * A test that injects a fixed reference shows resolution MOVES with it, never
+ * with the system clock.
+ *
+ * Part 8 (LOCAL -> BRAIN: NO). Pure LOCAL classifier: operates ONLY on the
+ * supplied user text. NO network, NO Brain. Returns scalars only -- epoch ms, a
+ * matched boolean, a forward boolean, and the matched time SPAN (the time
+ * phrase, never the whole user sentence). It never echoes arbitrary user prose
+ * to any wire. Mirrors the LOCAL-classifier discipline of dual-path-detector.
+ *
+ * House rule: hyphens only, no em-dashes. Pure CJS. chrono-node is the ONLY new
+ * runtime dependency (v2.9.1, MIT, zero transitive deps -- legitimacy-verified).
+ */
+
+const chrono = require('chrono-node');
+const { getReferenceNow } = require('./reference-now.cjs');
+
+// Future-biased lexical cues. When the user's phrase looks forward ("next",
+// "upcoming", "in N <unit>", "tomorrow"), chrono's forwardDate is enabled so an
+// ambiguous bare phrase ("Tuesday", "March") resolves to the NEXT occurrence
+// rather than the most recent past one. Past-biased phrases ("last", "ago",
+// "yesterday") resolve backward, which is chrono's default.
+const FORWARD_BIAS_RE = /\b(next|upcoming|tomorrow|coming)\b|\bin\s+\d/i;
+
+function isForwardBiased(text) {
+  return FORWARD_BIAS_RE.test(text);
+}
+
+/*
+ * resolveRelativeTime(text, opts) -> { validAtMs, matched, forward, span } | null
+ *
+ * Returns null when `text` carries no resolvable time expression (or is empty/
+ * non-string). On a match returns:
+ *   validAtMs  epoch ms of the resolved instant (anchored to the reference)
+ *   matched    always true on a non-null return
+ *   forward    whether forwardDate was applied (future-biased phrase)
+ *   span       the matched time-phrase substring (scalar; never the full text)
+ *
+ * opts (all optional; the anchor precedence is referenceMs > currentDate > seam):
+ *   referenceMs  explicit reference epoch ms (the options.now seam value, D-01a)
+ *   currentDate  YYYY-MM-DD injected by Claude Code (routes through getReferenceNow)
+ *   now          injectable clock forwarded to getReferenceNow (test seam)
+ *   seamPath     LOCAL seam file forwarded to getReferenceNow
+ */
+function resolveRelativeTime(text, opts) {
+  if (typeof text !== 'string' || text.trim() === '') return null;
+  const o = opts && typeof opts === 'object' ? opts : {};
+
+  // Resolve the anchor instant (D-01a). Explicit referenceMs wins so tests can
+  // pin a fixed reference; otherwise route through getReferenceNow() so the
+  // Wave 1 precedence ladder (currentDate > seam > Date.now()) applies.
+  let referenceMs;
+  if (typeof o.referenceMs === 'number' && Number.isFinite(o.referenceMs)) {
+    referenceMs = o.referenceMs;
+  } else {
+    const ref = getReferenceNow({
+      currentDate: typeof o.currentDate === 'string' ? o.currentDate : undefined,
+      now: typeof o.now === 'function' ? o.now : undefined,
+      seamPath: typeof o.seamPath === 'string' ? o.seamPath : undefined,
+    });
+    referenceMs = ref && Number.isFinite(ref.referenceMs) ? ref.referenceMs : Date.now();
+  }
+
+  const forward = isForwardBiased(text);
+
+  // chrono.parse(text, referenceDate, options). Anchor the instant to the
+  // reference and force UTC so day-granularity resolution is timezone-stable
+  // and deterministic across machines. forwardDate biases ambiguous phrases.
+  let results;
+  try {
+    results = chrono.parse(
+      text,
+      { instant: new Date(referenceMs), timezone: 'UTC' },
+      { forwardDate: forward }
+    );
+  } catch (_err) {
+    // A parser fault must never throw into the caller; degrade to no-match.
+    return null;
+  }
+
+  if (!Array.isArray(results) || results.length === 0) return null;
+
+  const first = results[0];
+  if (!first || !first.start || typeof first.start.date !== 'function') return null;
+
+  const resolved = first.start.date();
+  const validAtMs = resolved instanceof Date ? resolved.getTime() : NaN;
+  if (!Number.isFinite(validAtMs)) return null;
+
+  // span is the matched time-phrase only (scalar). chrono exposes the matched
+  // text on result.text; fall back to a trimmed copy when absent.
+  const span = typeof first.text === 'string' ? first.text : '';
+
+  return { validAtMs, matched: true, forward, span };
+}
+
+module.exports = {
+  resolveRelativeTime,
+  // Exported for downstream reuse (dual-stamp consumes this) + targeted tests.
+  isForwardBiased,
+};