@cavelang/core 0.20.0 → 0.27.3

package/dist/src/index.d.ts

@@ -16,6 +16,7 @@ export * as Entity from './entity.ts';
 export * as Key from './key.ts';
 export * as Multiplier from './multiplier.ts';
 export * as Tag from './tag.ts';
+export * as Time from './time.ts';
 export * as Uncertainty from './uncertainty.ts';
 export * as Uuidv7 from './uuidv7.ts';
 export * as Value from './value.ts';

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAC7C,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,KAAK,GAAG,MAAM,UAAU,CAAA;AAC/B,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAC7C,OAAO,KAAK,GAAG,MAAM,UAAU,CAAA;AAC/B,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAA;AAC/C,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AACjC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAC7C,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,KAAK,GAAG,MAAM,UAAU,CAAA;AAC/B,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAC7C,OAAO,KAAK,GAAG,MAAM,UAAU,CAAA;AAC/B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AACjC,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAA;AAC/C,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AACjC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA"}

package/dist/src/index.js

@@ -16,6 +16,7 @@ export * as Entity from "./entity.js";
 export * as Key from "./key.js";
 export * as Multiplier from "./multiplier.js";
 export * as Tag from "./tag.js";
+export * as Time from "./time.js";
 export * as Uncertainty from "./uncertainty.js";
 export * as Uuidv7 from "./uuidv7.js";
 export * as Value from "./value.js";

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAC7C,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,KAAK,GAAG,MAAM,UAAU,CAAA;AAC/B,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAC7C,OAAO,KAAK,GAAG,MAAM,UAAU,CAAA;AAC/B,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAA;AAC/C,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AACjC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAC7C,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,KAAK,GAAG,MAAM,UAAU,CAAA;AAC/B,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAC7C,OAAO,KAAK,GAAG,MAAM,UAAU,CAAA;AAC/B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AACjC,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAA;AAC/C,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AACjC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA"}

package/dist/src/time.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Valid time — periods, ranges, instants (spec §32).
+ *
+ * A date-like context names a calendar *period*, read as a UTC interval
+ * `[start, end)`: `@2025` the year, `@2026-04` the month, `@2026-04-10`
+ * the day, `@2026-Q1` / `@2026-H2` the quarter/half, `@2026-W15` the ISO
+ * week. A *range* context joins two points with `..` — `@2025..2028`,
+ * open-ended `@..2025` / `@2026..` — and covers whole periods at both
+ * ends. Ranges are lexically ordinary contexts (spec §6.1 already admits
+ * `.` in context atoms); this module is the semantic pass that reads
+ * them, exactly like `REVERSE` declarations are ordinary claims read
+ * semantically (spec §5.5).
+ *
+ * These are *valid-time* semantics — when a claim applies in the world —
+ * independent of transaction time (when the store learned it, spec §9.1,
+ * §12.3). `cave query --at` filters and interpolates on this axis.
+ */
+/** Calendar period as a UTC interval `[start, end)`, in ms since epoch. */
+export type Period = {
+    readonly start: number;
+    readonly end: number;
+};
+export type t = Period;
+/** How a context reads as time: a point period, or a `..` range. */
+export type TimeContext = {
+    readonly kind: 'point';
+    readonly period: Period;
+} | {
+    readonly kind: 'range';
+    readonly start?: Period;
+    readonly end?: Period;
+};
+/**
+ * Parses a date-like time point as the calendar period it names:
+ * `2025`, `2026-04`, `2026-04-10`, `2026-Q1`, `2026-H2`, `2026-W15`.
+ * @returns `undefined` when `text` is not a time point (including
+ * out-of-calendar dates like `2026-02-30`).
+ */
+export declare const parsePeriod: (text: string) => undefined | Period;
+/**
+ * Parses a `A..B` / `..B` / `A..` time range. The end point of a closed
+ * range may abbreviate by dropping *leading* numeric segments, inherited
+ * from the start point (spec §32.2): `2026-04-10..04-11` reads as
+ * `2026-04-10..2026-04-11`, `2026-04-10..11` likewise. `Q`/`H`/`W`
+ * points are always written in full. A closed range must be non-empty
+ * (`2028..2025` is not a time range).
+ * @returns `undefined` when `text` is not a range.
+ */
+export declare const parseRange: (text: string) => undefined | {
+    start?: Period;
+    end?: Period;
+};
+/**
+ * Reads a context as time, when it is one (spec §32.2): a bare or
+ * `time:`-prefixed date-like point or `..` range. Every other context —
+ * `production`, `src:filing`, `auth.ts:42` — is opaque and returns
+ * `undefined`; a context that fails to parse as time is opaque too, the
+ * robust-extraction default (spec §1.6).
+ */
+export declare const ofContext: (context: string) => undefined | TimeContext;
+/**
+ * Parses a query anchor into an instant (ms since epoch): a date-like
+ * period reads as its *start* instant (`2026` is 2026-01-01T00:00:00Z —
+ * name the finer period to anchor inside one), a `T` timestamp reads
+ * exactly. @returns `undefined` when `text` is neither.
+ */
+export declare const parseInstant: (text: string) => undefined | number;
+/** @returns whether a time context covers the instant (spec §32.4). */
+export declare const covers: (context: TimeContext, instant: number) => boolean;
+/**
+ * Whether a claim with these contexts applies at the instant
+ * (spec §32.4): timeless claims — no time context — always apply; a
+ * time-anchored claim applies when *any* of its time contexts covers
+ * the instant. Opaque contexts never participate.
+ */
+export declare const appliesAt: (contexts: readonly string[], instant: number) => boolean;
+/**
+ * The single closed range among a claim's contexts — the interval a
+ * trajectory value interpolates over (spec §32.3). @returns `undefined`
+ * when there is none, or more than one (ambiguous — no interpolation).
+ */
+export declare const closedRangeOf: (contexts: readonly string[]) => undefined | {
+    start: Period;
+    end: Period;
+};
+/**
+ * Where an instant sits along a closed range, as the interpolation
+ * fraction in [0, 1] (spec §32.3): endpoint values anchor at the *start*
+ * instants of the periods that name them — `20B -> 40B @2025..2028` is
+ * 20B at 2025-01-01 and 40B at 2028-01-01 — and the fraction clamps to 1
+ * through the end period's tail ("40B *in* 2028" holds all of 2028).
+ */
+export declare const fractionAt: (range: {
+    start: Period;
+    end: Period;
+}, instant: number) => number;
+//# sourceMappingURL=time.d.ts.map

package/dist/src/time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.d.ts","sourceRoot":"","sources":["../../src/time.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,2EAA2E;AAC3E,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,CAAC,GAAG,MAAM,CAAA;AAEtB,oEAAoE;AACpE,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAgB9E;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,KAAG,SAAS,GAAG,MAwCtD,CAAA;AAID;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,KAAG,SAAS,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAiCnF,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GAAI,SAAS,MAAM,KAAG,SAAS,GAAG,WAQvD,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,SAAS,GAAG,MAUvD,CAAA;AAED,uEAAuE;AACvE,eAAO,MAAM,MAAM,GAAI,SAAS,WAAW,EAAE,SAAS,MAAM,KAAG,OAIH,CAAA;AAE5D;;;;;GAKG;AACH,eAAO,MAAM,SAAS,GAAI,UAAU,SAAS,MAAM,EAAE,EAAE,SAAS,MAAM,KAAG,OAaxE,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,UAAU,SAAS,MAAM,EAAE,KAAG,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAanG,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,SAAS,MAAM,KAAG,MAMnF,CAAA"}

package/dist/src/time.js

@@ -0,0 +1,209 @@
+/**
+ * Valid time — periods, ranges, instants (spec §32).
+ *
+ * A date-like context names a calendar *period*, read as a UTC interval
+ * `[start, end)`: `@2025` the year, `@2026-04` the month, `@2026-04-10`
+ * the day, `@2026-Q1` / `@2026-H2` the quarter/half, `@2026-W15` the ISO
+ * week. A *range* context joins two points with `..` — `@2025..2028`,
+ * open-ended `@..2025` / `@2026..` — and covers whole periods at both
+ * ends. Ranges are lexically ordinary contexts (spec §6.1 already admits
+ * `.` in context atoms); this module is the semantic pass that reads
+ * them, exactly like `REVERSE` declarations are ordinary claims read
+ * semantically (spec §5.5).
+ *
+ * These are *valid-time* semantics — when a claim applies in the world —
+ * independent of transaction time (when the store learned it, spec §9.1,
+ * §12.3). `cave query --at` filters and interpolates on this axis.
+ */
+const dayMs = 86_400_000;
+const utcDay = (year, month, day) => Date.UTC(year, month - 1, day);
+/** Monday starting ISO week `week` of `year` (ISO 8601: week 1 contains Jan 4). */
+const isoWeekStart = (year, week) => {
+    const jan4 = utcDay(year, 1, 4);
+    const monday = jan4 - ((new Date(jan4).getUTCDay() + 6) % 7) * dayMs;
+    return monday + (week - 1) * 7 * dayMs;
+};
+const periodRe = /^(\d{4})(?:-(?:Q([1-4])|H([1-2])|W(\d{1,2})|(\d{2})(?:-(\d{2}))?))?$/;
+/**
+ * Parses a date-like time point as the calendar period it names:
+ * `2025`, `2026-04`, `2026-04-10`, `2026-Q1`, `2026-H2`, `2026-W15`.
+ * @returns `undefined` when `text` is not a time point (including
+ * out-of-calendar dates like `2026-02-30`).
+ */
+export const parsePeriod = (text) => {
+    const match = periodRe.exec(text);
+    if (!match) {
+        return undefined;
+    }
+    const year = Number(match[1]);
+    const [, , quarter, half, week, month, day] = match;
+    if (quarter !== undefined) {
+        const q = Number(quarter);
+        return { start: utcDay(year, (q - 1) * 3 + 1, 1), end: utcDay(year, q * 3 + 1, 1) };
+    }
+    if (half !== undefined) {
+        const h = Number(half);
+        return { start: utcDay(year, (h - 1) * 6 + 1, 1), end: utcDay(year, h * 6 + 1, 1) };
+    }
+    if (week !== undefined) {
+        const w = Number(week);
+        if (w < 1 || w > 53) {
+            return undefined;
+        }
+        const start = isoWeekStart(year, w);
+        return { start, end: start + 7 * dayMs };
+    }
+    if (month !== undefined) {
+        const m = Number(month);
+        if (m < 1 || m > 12) {
+            return undefined;
+        }
+        if (day !== undefined) {
+            const d = Number(day);
+            const start = utcDay(year, m, d);
+            const date = new Date(start);
+            if (date.getUTCMonth() !== m - 1 || date.getUTCDate() !== d) {
+                return undefined;
+            }
+            return { start, end: start + dayMs };
+        }
+        return { start: utcDay(year, m, 1), end: utcDay(year, m + 1, 1) };
+    }
+    return { start: utcDay(year, 1, 1), end: utcDay(year + 1, 1, 1) };
+};
+const numericPointRe = /^[\d-]+$/;
+/**
+ * Parses a `A..B` / `..B` / `A..` time range. The end point of a closed
+ * range may abbreviate by dropping *leading* numeric segments, inherited
+ * from the start point (spec §32.2): `2026-04-10..04-11` reads as
+ * `2026-04-10..2026-04-11`, `2026-04-10..11` likewise. `Q`/`H`/`W`
+ * points are always written in full. A closed range must be non-empty
+ * (`2028..2025` is not a time range).
+ * @returns `undefined` when `text` is not a range.
+ */
+export const parseRange = (text) => {
+    const at = text.indexOf('..');
+    if (at === -1 || text.indexOf('..', at + 2) !== -1) {
+        return undefined;
+    }
+    const leftText = text.slice(0, at);
+    const rightText = text.slice(at + 2);
+    if (leftText === '' && rightText === '') {
+        return undefined;
+    }
+    if (leftText === '') {
+        const end = parsePeriod(rightText);
+        return end === undefined ? undefined : { end };
+    }
+    const start = parsePeriod(leftText);
+    if (start === undefined) {
+        return undefined;
+    }
+    if (rightText === '') {
+        return { start };
+    }
+    let end = parsePeriod(rightText);
+    if (end === undefined && numericPointRe.test(leftText) && numericPointRe.test(rightText)) {
+        const leftSegments = leftText.split('-');
+        const rightSegments = rightText.split('-');
+        if (rightSegments.length < leftSegments.length) {
+            end = parsePeriod([...leftSegments.slice(0, leftSegments.length - rightSegments.length), ...rightSegments].join('-'));
+        }
+    }
+    if (end === undefined || end.end <= start.start) {
+        return undefined;
+    }
+    return { start, end };
+};
+/**
+ * Reads a context as time, when it is one (spec §32.2): a bare or
+ * `time:`-prefixed date-like point or `..` range. Every other context —
+ * `production`, `src:filing`, `auth.ts:42` — is opaque and returns
+ * `undefined`; a context that fails to parse as time is opaque too, the
+ * robust-extraction default (spec §1.6).
+ */
+export const ofContext = (context) => {
+    const body = context.startsWith('time:') ? context.slice('time:'.length) : context;
+    if (body.includes('..')) {
+        const range = parseRange(body);
+        return range === undefined ? undefined : { kind: 'range', ...range };
+    }
+    const period = parsePeriod(body);
+    return period === undefined ? undefined : { kind: 'point', period };
+};
+/**
+ * Parses a query anchor into an instant (ms since epoch): a date-like
+ * period reads as its *start* instant (`2026` is 2026-01-01T00:00:00Z —
+ * name the finer period to anchor inside one), a `T` timestamp reads
+ * exactly. @returns `undefined` when `text` is neither.
+ */
+export const parseInstant = (text) => {
+    const period = parsePeriod(text);
+    if (period !== undefined) {
+        return period.start;
+    }
+    if (!text.includes('T')) {
+        return undefined;
+    }
+    const parsed = Date.parse(text);
+    return Number.isNaN(parsed) ? undefined : parsed;
+};
+/** @returns whether a time context covers the instant (spec §32.4). */
+export const covers = (context, instant) => context.kind === 'point' ?
+    instant >= context.period.start && instant < context.period.end :
+    (context.start === undefined || instant >= context.start.start) &&
+        (context.end === undefined || instant < context.end.end);
+/**
+ * Whether a claim with these contexts applies at the instant
+ * (spec §32.4): timeless claims — no time context — always apply; a
+ * time-anchored claim applies when *any* of its time contexts covers
+ * the instant. Opaque contexts never participate.
+ */
+export const appliesAt = (contexts, instant) => {
+    let anchored = false;
+    for (const context of contexts) {
+        const time = ofContext(context);
+        if (time === undefined) {
+            continue;
+        }
+        anchored = true;
+        if (covers(time, instant)) {
+            return true;
+        }
+    }
+    return !anchored;
+};
+/**
+ * The single closed range among a claim's contexts — the interval a
+ * trajectory value interpolates over (spec §32.3). @returns `undefined`
+ * when there is none, or more than one (ambiguous — no interpolation).
+ */
+export const closedRangeOf = (contexts) => {
+    let found;
+    for (const context of contexts) {
+        const time = ofContext(context);
+        if (time === undefined || time.kind !== 'range' || time.start === undefined || time.end === undefined) {
+            continue;
+        }
+        if (found !== undefined) {
+            return undefined;
+        }
+        found = { start: time.start, end: time.end };
+    }
+    return found;
+};
+/**
+ * Where an instant sits along a closed range, as the interpolation
+ * fraction in [0, 1] (spec §32.3): endpoint values anchor at the *start*
+ * instants of the periods that name them — `20B -> 40B @2025..2028` is
+ * 20B at 2025-01-01 and 40B at 2028-01-01 — and the fraction clamps to 1
+ * through the end period's tail ("40B *in* 2028" holds all of 2028).
+ */
+export const fractionAt = (range, instant) => {
+    const span = range.end.start - range.start.start;
+    if (span <= 0) {
+        return 1;
+    }
+    return Math.min(1, Math.max(0, (instant - range.start.start) / span));
+};
+//# sourceMappingURL=time.js.map

package/dist/src/time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.js","sourceRoot":"","sources":["../../src/time.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAeH,MAAM,KAAK,GAAG,UAAU,CAAA;AAExB,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,KAAa,EAAE,GAAW,EAAU,EAAE,CAClE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,GAAG,CAAC,CAAA;AAEhC,mFAAmF;AACnF,MAAM,YAAY,GAAG,CAAC,IAAY,EAAE,IAAY,EAAU,EAAE;IAC1D,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IAC/B,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,CAAA;IACpE,OAAO,MAAM,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;AACxC,CAAC,CAAA;AAED,MAAM,QAAQ,GAAG,sEAAsE,CAAA;AAEvF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAY,EAAsB,EAAE;IAC9D,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACjC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IAC7B,MAAM,CAAC,EAAE,AAAD,EAAG,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,GAAG,KAAK,CAAA;IACnD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAA;QACzB,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,CAAA;IACrF,CAAC;IACD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAA;QACtB,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,CAAA;IACrF,CAAC;IACD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAA;QACtB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;YACpB,OAAO,SAAS,CAAA;QAClB,CAAC;QACD,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC,CAAA;QACnC,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,GAAG,KAAK,EAAE,CAAA;IAC1C,CAAC;IACD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;QACvB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;YACpB,OAAO,SAAS,CAAA;QAClB,CAAC;QACD,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAA;YACrB,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;YAChC,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,CAAA;YAC5B,IAAI,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,EAAE,CAAC;gBAC5D,OAAO,SAAS,CAAA;YAClB,CAAC;YACD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,GAAG,KAAK,EAAE,CAAA;QACtC,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,CAAA;IACnE,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAA;AACnE,CAAC,CAAA;AAED,MAAM,cAAc,GAAG,UAAU,CAAA;AAEjC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,IAAY,EAAgD,EAAE;IACvF,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7B,IAAI,EAAE,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QACnD,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IAClC,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAA;IACpC,IAAI,QAAQ,KAAK,EAAE,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;QACxC,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,IAAI,QAAQ,KAAK,EAAE,EAAE,CAAC;QACpB,MAAM,GAAG,GAAG,WAAW,CAAC,SAAS,CAAC,CAAA;QAClC,OAAO,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAA;IAChD,CAAC;IACD,MAAM,KAAK,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAA;IACnC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;QACrB,OAAO,EAAE,KAAK,EAAE,CAAA;IAClB,CAAC;IACD,IAAI,GAAG,GAAG,WAAW,CAAC,SAAS,CAAC,CAAA;IAChC,IAAI,GAAG,KAAK,SAAS,IAAI,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QACzF,MAAM,YAAY,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QACxC,MAAM,aAAa,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QAC1C,IAAI,aAAa,CAAC,MAAM,GAAG,YAAY,CAAC,MAAM,EAAE,CAAC;YAC/C,GAAG,GAAG,WAAW,CAAC,CAAC,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,EAAE,GAAG,aAAa,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;QACvH,CAAC;IACH,CAAC;IACD,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,GAAG,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAChD,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,CAAA;AACvB,CAAC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,OAAe,EAA2B,EAAE;IACpE,MAAM,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAA;IAClF,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,CAAA;QAC9B,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,KAAK,EAAE,CAAA;IACtE,CAAC;IACD,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,CAAA;IAChC,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAA;AACrE,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAY,EAAsB,EAAE;IAC/D,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,CAAA;IAChC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,MAAM,CAAC,KAAK,CAAA;IACrB,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IAC/B,OAAO,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAA;AAClD,CAAC,CAAA;AAED,uEAAuE;AACvE,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,OAAoB,EAAE,OAAe,EAAW,EAAE,CACvE,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;IACxB,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,IAAI,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;QAC/D,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,IAAI,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;AAE5D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,QAA2B,EAAE,OAAe,EAAW,EAAE;IACjF,IAAI,QAAQ,GAAG,KAAK,CAAA;IACpB,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,CAAA;QAC/B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,SAAQ;QACV,CAAC;QACD,QAAQ,GAAG,IAAI,CAAA;QACf,IAAI,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,CAAC;YAC1B,OAAO,IAAI,CAAA;QACb,CAAC;IACH,CAAC;IACD,OAAO,CAAC,QAAQ,CAAA;AAClB,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,QAA2B,EAA8C,EAAE;IACvG,IAAI,KAAiD,CAAA;IACrD,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,CAAA;QAC/B,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;YACtG,SAAQ;QACV,CAAC;QACD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,SAAS,CAAA;QAClB,CAAC;QACD,KAAK,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAA;IAC9C,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,KAAqC,EAAE,OAAe,EAAU,EAAE;IAC3F,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAA;IAChD,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;QACd,OAAO,CAAC,CAAA;IACV,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC,CAAA;AACvE,CAAC,CAAA"}

package/dist/src/uuidv7.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"uuidv7.d.ts","sourceRoot":"","sources":["../../src/uuidv7.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH;;;;;;;GAOG;AACH,eAAO,MAAM,EAAE,GAAI,IAAI,MAAM,EAAE,KAAK,MAAM,EAAE,MAAM,UAAU,KAAG,MAmB9D,CAAA;AAKD;;;GAGG;AACH,eAAO,MAAM,IAAI,GAAI,MAAK,MAAM,MAAiB,KAAG,MAgBnD,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,IAAI,GAAI,IAAI,MAAM,KAAG,MACqB,CAAA;AAIvD,6DAA6D;AAC7D,eAAO,MAAM,EAAE,GAAI,GAAG,MAAM,KAAG,OACf,CAAA;AAMhB;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,GAAI,IAAI,MAAM,KAAG,IAUpC,CAAA"}
+{"version":3,"file":"uuidv7.d.ts","sourceRoot":"","sources":["../../src/uuidv7.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH;;;;;;;GAOG;AACH,eAAO,MAAM,EAAE,GAAI,IAAI,MAAM,EAAE,KAAK,MAAM,EAAE,MAAM,UAAU,KAAG,MAmB9D,CAAA;AAKD;;;GAGG;AACH,eAAO,MAAM,IAAI,GAAI,MAAK,MAAM,MAAiB,KAAG,MAkBnD,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,IAAI,GAAI,IAAI,MAAM,KAAG,MACqB,CAAA;AAIvD,6DAA6D;AAC7D,eAAO,MAAM,EAAE,GAAI,GAAG,MAAM,KAAG,OACf,CAAA;AAMhB;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,GAAI,IAAI,MAAM,KAAG,IAUpC,CAAA"}

package/dist/src/uuidv7.js

@@ -9,7 +9,6 @@
  * increment a 12-bit sequence in the `rand_a` field, and a backwards system
  * clock never produces a smaller id.
  */
-import { randomFillSync } from 'node:crypto';
 const hex = (n, digits) => n.toString(16).padStart(digits, '0');
 /**
  * Formats a UUIDv7 from parts — pure, for tests and deterministic imports.
@@ -60,7 +59,9 @@ export const next = (now = Date.now) => {
     }
     lastMs = ms;
     const rand = new Uint8Array(8);
-    randomFillSync(rand);
+    // Web Crypto is available in supported Node.js releases and browsers,
+    // keeping UUID generation portable without weakening randomness.
+    globalThis.crypto.getRandomValues(rand);
     return at(ms, lastSeq, rand);
 };
 /**

package/dist/src/uuidv7.js.map

@@ -1 +1 @@
-{"version":3,"file":"uuidv7.js","sourceRoot":"","sources":["../../src/uuidv7.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"uuidv7.js","sourceRoot":"","sources":["../../src/uuidv7.ts"],"names":[],"mappings":"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"}

package/dist/src/value.d.ts

@@ -1,5 +1,5 @@
 /**
- * Values, units and multipliers (spec §7.1).
+ * Values, units and multipliers (spec §7.1), and trajectories (spec §32.3).
  *
  * A value is the payload of an attribute claim (`HAS attr: value`), a metric
  * claim (`metric IS value`), or a `+/-` uncertainty delta. Parsing keeps the
@@ -11,6 +11,7 @@
  * - `~20B USD/yr`    → the same, `approx` set
  * - `94.5%`          → num 94.5, unit `%`
  * - `20 conn`        → num 20, unit `conn`
+ * - `20B -> 40B USD/yr` → trajectory, from 2e10 to 4e10, unit `USD/yr`
  * - `2026-H2`        → date-like, kept textual
  * - `token-expiry`   → atom, kept textual
  *
@@ -18,17 +19,25 @@
  * with their kind already known; use {@link ofText} / {@link ofCode}.
  */
 /** How the value text was classified. */
-export type Kind = 'number' | 'date' | 'atom' | 'text' | 'code';
+export type Kind = 'number' | 'trajectory' | 'date' | 'atom' | 'text' | 'code';
 export type Value = {
     /** Exactly as written, including `~` and multiplier letter. */
     readonly raw: string;
     readonly kind: Kind;
     /** `~` prefix (spec §7.1): the value is approximate. */
     readonly approx: boolean;
-    /** Normalized numeric value with multiplier expanded, when parseable. */
+    /**
+     * Normalized numeric value with multiplier expanded, when parseable.
+     * Unset for trajectories — a trajectory is not one number, so every
+     * scalar consumer (fusion, filters, σ) conservatively skips it.
+     */
     readonly num?: number;
     /** Normalized unit expression (`USD/yr`, `ms`, `%`), when present. */
     readonly unit?: string;
+    /** Trajectory start value, multiplier expanded (kind `trajectory`). */
+    readonly from?: number;
+    /** Trajectory end value, multiplier expanded (kind `trajectory`). */
+    readonly to?: number;
 };
 export type t = Value;
 /** @returns `true` if `s` is a valid unit expression (`USD/yr`, `ms`, `%`). */
@@ -40,10 +49,34 @@ export declare const isUnit: (s: string) => boolean;
 export declare const isDateLike: (s: string) => boolean;
 /**
  * Parses an unquoted value string (spec §16 `value`), classifying it as
- * number, date or atom. The raw text (including `~` and multiplier letters)
- * is preserved verbatim.
+ * number, trajectory, date or atom. The raw text (including `~` and
+ * multiplier letters) is preserved verbatim.
  */
 export declare const parse: (raw: string) => Value;
+/**
+ * Plain-decimal text of a finite number. The CAVE number grammar
+ * (spec §16) has no exponent form, so `String`'s occasional `1e-7` /
+ * `1.5e+21` output is expanded to `0.0000001` / `1500000000000000000000`.
+ * The digits are JavaScript's shortest round-trip representation, so
+ * `parse(formatNumber(n)).num === n`. Every generator writing numbers
+ * into CAVE text must go through this (or emit a multiplier form built
+ * on it) — `String(n)` alone round-trips tiny and huge magnitudes as
+ * atoms. Throws on non-finite input: CAVE has no text for it.
+ */
+export declare const formatNumber: (n: number) => string;
+/**
+ * Linear interpolation of a trajectory at `fraction` ∈ [0, 1], clamped
+ * (spec §32.3). @returns `undefined` for non-trajectory values.
+ */
+export declare const interpolate: (value: Value, fraction: number) => undefined | number;
+/**
+ * Canonical scalar text of a trajectory at `fraction`, in the
+ * trajectory's own style (spec §32.3): multipliers re-compress when the
+ * endpoints used them, a glued unit stays glued, 4 significant digits.
+ * `20B -> 40B USD/yr` at 0.5 → `30B USD/yr`; `5ms -> 800ms` at 0.5 →
+ * `402.5ms`. @returns `undefined` for non-trajectory values.
+ */
+export declare const formatAt: (value: Value, fraction: number) => undefined | string;
 /** @returns value for a double-quoted natural-language literal (spec §4.2). */
 export declare const ofText: (text: string) => Value;
 /** @returns value for a backticked exact code literal (spec §4.2). */

package/dist/src/value.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"value.d.ts","sourceRoot":"","sources":["../../src/value.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,yCAAyC;AACzC,MAAM,MAAM,IAAI,GACZ,QAAQ,GACR,MAAM,GACN,MAAM,GACN,MAAM,GACN,MAAM,CAAA;AAEV,MAAM,MAAM,KAAK,GAAG;IAClB,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,yEAAyE;IACzE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,MAAM,MAAM,CAAC,GAAG,KAAK,CAAA;AAMrB,+EAA+E;AAC/E,eAAO,MAAM,MAAM,GAAI,GAAG,MAAM,KAAG,OACnB,CAAA;AAEhB;;;GAGG;AACH,eAAO,MAAM,UAAU,GAAI,GAAG,MAAM,KAAG,OACvB,CAAA;AAsChB;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAAI,KAAK,MAAM,KAAG,KAanC,CAAA;AAED,+EAA+E;AAC/E,eAAO,MAAM,MAAM,GAAI,MAAM,MAAM,KAAG,KACQ,CAAA;AAE9C,sEAAsE;AACtE,eAAO,MAAM,MAAM,GAAI,MAAM,MAAM,KAAG,KACQ,CAAA;AAE9C;;;;GAIG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,KAAK,KAAG,MASrC,CAAA"}
+{"version":3,"file":"value.d.ts","sourceRoot":"","sources":["../../src/value.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,yCAAyC;AACzC,MAAM,MAAM,IAAI,GACZ,QAAQ,GACR,YAAY,GACZ,MAAM,GACN,MAAM,GACN,MAAM,GACN,MAAM,CAAA;AAEV,MAAM,MAAM,KAAK,GAAG;IAClB,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB;;;;OAIG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,uEAAuE;IACvE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,CAAC,GAAG,KAAK,CAAA;AAMrB,+EAA+E;AAC/E,eAAO,MAAM,MAAM,GAAI,GAAG,MAAM,KAAG,OACnB,CAAA;AAEhB;;;GAGG;AACH,eAAO,MAAM,UAAU,GAAI,GAAG,MAAM,KAAG,OACvB,CAAA;AA8EhB;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAAI,KAAK,MAAM,KAAG,KAoBnC,CAAA;AAID;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GAAI,GAAG,MAAM,KAAG,MAcxC,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,KAAK,EAAE,UAAU,MAAM,KAAG,SAAS,GAAG,MAGI,CAAA;AAE7E;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,KAAK,EAAE,UAAU,MAAM,KAAG,SAAS,GAAG,MAqBrE,CAAA;AAED,+EAA+E;AAC/E,eAAO,MAAM,MAAM,GAAI,MAAM,MAAM,KAAG,KACQ,CAAA;AAE9C,sEAAsE;AACtE,eAAO,MAAM,MAAM,GAAI,MAAM,MAAM,KAAG,KACQ,CAAA;AAE9C;;;;GAIG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,KAAK,KAAG,MASrC,CAAA"}

package/dist/src/value.js

@@ -1,5 +1,5 @@
 /**
- * Values, units and multipliers (spec §7.1).
+ * Values, units and multipliers (spec §7.1), and trajectories (spec §32.3).
  *
  * A value is the payload of an attribute claim (`HAS attr: value`), a metric
  * claim (`metric IS value`), or a `+/-` uncertainty delta. Parsing keeps the
@@ -11,6 +11,7 @@
  * - `~20B USD/yr`    → the same, `approx` set
  * - `94.5%`          → num 94.5, unit `%`
  * - `20 conn`        → num 20, unit `conn`
+ * - `20B -> 40B USD/yr` → trajectory, from 2e10 to 4e10, unit `USD/yr`
  * - `2026-H2`        → date-like, kept textual
  * - `token-expiry`   → atom, kept textual
  *
@@ -63,14 +64,51 @@ const parseNumeric = (body) => {
     }
     return unit === undefined ? { num } : { num, unit };
 };
+const multiplierHeadRe = /^-?\d+(?:\.\d+)?[TBMK]$/;
+/**
+ * Splits `body` as trajectory `from -> to [unit]` (spec §32.3). Each side
+ * parses like a scalar; the unit is shared — glued per endpoint or spaced
+ * after either — and both sides naming different units is not a
+ * trajectory. Style (glue, multipliers) is kept for {@link formatAt}.
+ */
+const parseTrajectory = (body) => {
+    const parts = body.split(' -> ');
+    if (parts.length !== 2 || parts[0] === '' || parts[1] === '') {
+        return undefined;
+    }
+    const [leftText, rightText] = parts;
+    const left = parseNumeric(leftText);
+    const right = parseNumeric(rightText);
+    if (left === undefined || right === undefined) {
+        return undefined;
+    }
+    if (left.unit !== undefined && right.unit !== undefined && left.unit !== right.unit) {
+        return undefined;
+    }
+    const unit = left.unit ?? right.unit;
+    return {
+        num: left.num,
+        to: right.num,
+        ...unit === undefined ? {} : { unit },
+        glued: unit !== undefined && !leftText.includes(' ') && !rightText.includes(' '),
+        multiplier: multiplierHeadRe.test(leftText.split(' ')[0]) || multiplierHeadRe.test(rightText.split(' ')[0])
+    };
+};
 /**
  * Parses an unquoted value string (spec §16 `value`), classifying it as
- * number, date or atom. The raw text (including `~` and multiplier letters)
- * is preserved verbatim.
+ * number, trajectory, date or atom. The raw text (including `~` and
+ * multiplier letters) is preserved verbatim.
  */
 export const parse = (raw) => {
     const approx = raw.startsWith('~');
     const body = approx ? raw.slice(1) : raw;
+    const trajectory = body.includes(' -> ') ? parseTrajectory(body) : undefined;
+    if (trajectory !== undefined) {
+        return {
+            raw, kind: 'trajectory', approx, from: trajectory.num, to: trajectory.to,
+            ...trajectory.unit === undefined ? {} : { unit: trajectory.unit }
+        };
+    }
     const numeric = parseNumeric(body);
     if (numeric !== undefined) {
         return numeric.unit === undefined ?
@@ -82,6 +120,68 @@ export const parse = (raw) => {
     }
     return { raw, kind: 'atom', approx };
 };
+const exponentRe = /^(-?)(\d+)(?:\.(\d+))?e([+-]\d+)$/;
+/**
+ * Plain-decimal text of a finite number. The CAVE number grammar
+ * (spec §16) has no exponent form, so `String`'s occasional `1e-7` /
+ * `1.5e+21` output is expanded to `0.0000001` / `1500000000000000000000`.
+ * The digits are JavaScript's shortest round-trip representation, so
+ * `parse(formatNumber(n)).num === n`. Every generator writing numbers
+ * into CAVE text must go through this (or emit a multiplier form built
+ * on it) — `String(n)` alone round-trips tiny and huge magnitudes as
+ * atoms. Throws on non-finite input: CAVE has no text for it.
+ */
+export const formatNumber = (n) => {
+    if (!Number.isFinite(n)) {
+        throw new Error(`Expected a finite number, got ${n}.`);
+    }
+    const match = exponentRe.exec(String(n));
+    if (match === null) {
+        return String(n);
+    }
+    const [, sign = '', whole = '', fraction = '', exponent = '0'] = match;
+    const digits = `${whole}${fraction}`;
+    const point = whole.length + Number(exponent);
+    return point <= 0 ? `${sign}0.${'0'.repeat(-point)}${digits}` :
+        point >= digits.length ? `${sign}${digits}${'0'.repeat(point - digits.length)}` :
+            `${sign}${digits.slice(0, point)}.${digits.slice(point)}`;
+};
+/**
+ * Linear interpolation of a trajectory at `fraction` ∈ [0, 1], clamped
+ * (spec §32.3). @returns `undefined` for non-trajectory values.
+ */
+export const interpolate = (value, fraction) => value.from === undefined || value.to === undefined ?
+    undefined :
+    value.from + (value.to - value.from) * Math.min(1, Math.max(0, fraction));
+/**
+ * Canonical scalar text of a trajectory at `fraction`, in the
+ * trajectory's own style (spec §32.3): multipliers re-compress when the
+ * endpoints used them, a glued unit stays glued, 4 significant digits.
+ * `20B -> 40B USD/yr` at 0.5 → `30B USD/yr`; `5ms -> 800ms` at 0.5 →
+ * `402.5ms`. @returns `undefined` for non-trajectory values.
+ */
+export const formatAt = (value, fraction) => {
+    const num = interpolate(value, fraction);
+    if (num === undefined) {
+        return undefined;
+    }
+    const style = parseTrajectory(value.approx ? value.raw.slice(1) : value.raw);
+    let scaled = num;
+    let letter = '';
+    if (style?.multiplier === true) {
+        for (const m of ['T', 'B', 'M', 'K']) {
+            if (Math.abs(num) >= Multiplier.factor(m)) {
+                scaled = num / Multiplier.factor(m);
+                letter = m;
+                break;
+            }
+        }
+    }
+    const digits = formatNumber(Number(scaled.toPrecision(4)));
+    return value.unit === undefined ?
+        `${digits}${letter}` :
+        `${digits}${letter}${style?.glued === true ? '' : ' '}${value.unit}`;
+};
 /** @returns value for a double-quoted natural-language literal (spec §4.2). */
 export const ofText = (text) => ({ raw: text, kind: 'text', approx: false });
 /** @returns value for a backticked exact code literal (spec §4.2). */

package/dist/src/value.js.map

@@ -1 +1 @@
-{"version":3,"file":"value.js","sourceRoot":"","sources":["../../src/value.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"value.js","sourceRoot":"","sources":["../../src/value.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cavelang/core",
-  "version": "0.20.0",
+  "version": "0.27.3",
   "type": "module",
   "description": "CAVE domain model — claims, values, units, uncertainty, claim keys, UUIDv7 transactions.",
   "license": "CC0-1.0",

package/src/index.ts

@@ -17,6 +17,7 @@ export * as Entity from './entity.ts'
 export * as Key from './key.ts'
 export * as Multiplier from './multiplier.ts'
 export * as Tag from './tag.ts'
+export * as Time from './time.ts'
 export * as Uncertainty from './uncertainty.ts'
 export * as Uuidv7 from './uuidv7.ts'
 export * as Value from './value.ts'

package/src/time.ts

@@ -0,0 +1,236 @@
+/**
+ * Valid time — periods, ranges, instants (spec §32).
+ *
+ * A date-like context names a calendar *period*, read as a UTC interval
+ * `[start, end)`: `@2025` the year, `@2026-04` the month, `@2026-04-10`
+ * the day, `@2026-Q1` / `@2026-H2` the quarter/half, `@2026-W15` the ISO
+ * week. A *range* context joins two points with `..` — `@2025..2028`,
+ * open-ended `@..2025` / `@2026..` — and covers whole periods at both
+ * ends. Ranges are lexically ordinary contexts (spec §6.1 already admits
+ * `.` in context atoms); this module is the semantic pass that reads
+ * them, exactly like `REVERSE` declarations are ordinary claims read
+ * semantically (spec §5.5).
+ *
+ * These are *valid-time* semantics — when a claim applies in the world —
+ * independent of transaction time (when the store learned it, spec §9.1,
+ * §12.3). `cave query --at` filters and interpolates on this axis.
+ */
+
+/** Calendar period as a UTC interval `[start, end)`, in ms since epoch. */
+export type Period = {
+  readonly start: number
+  readonly end: number
+}
+
+export type t = Period
+
+/** How a context reads as time: a point period, or a `..` range. */
+export type TimeContext =
+  | { readonly kind: 'point', readonly period: Period }
+  | { readonly kind: 'range', readonly start?: Period, readonly end?: Period }
+
+const dayMs = 86_400_000
+
+const utcDay = (year: number, month: number, day: number): number =>
+  Date.UTC(year, month - 1, day)
+
+/** Monday starting ISO week `week` of `year` (ISO 8601: week 1 contains Jan 4). */
+const isoWeekStart = (year: number, week: number): number => {
+  const jan4 = utcDay(year, 1, 4)
+  const monday = jan4 - ((new Date(jan4).getUTCDay() + 6) % 7) * dayMs
+  return monday + (week - 1) * 7 * dayMs
+}
+
+const periodRe = /^(\d{4})(?:-(?:Q([1-4])|H([1-2])|W(\d{1,2})|(\d{2})(?:-(\d{2}))?))?$/
+
+/**
+ * Parses a date-like time point as the calendar period it names:
+ * `2025`, `2026-04`, `2026-04-10`, `2026-Q1`, `2026-H2`, `2026-W15`.
+ * @returns `undefined` when `text` is not a time point (including
+ * out-of-calendar dates like `2026-02-30`).
+ */
+export const parsePeriod = (text: string): undefined | Period => {
+  const match = periodRe.exec(text)
+  if (!match) {
+    return undefined
+  }
+  const year = Number(match[1])
+  const [, , quarter, half, week, month, day] = match
+  if (quarter !== undefined) {
+    const q = Number(quarter)
+    return { start: utcDay(year, (q - 1) * 3 + 1, 1), end: utcDay(year, q * 3 + 1, 1) }
+  }
+  if (half !== undefined) {
+    const h = Number(half)
+    return { start: utcDay(year, (h - 1) * 6 + 1, 1), end: utcDay(year, h * 6 + 1, 1) }
+  }
+  if (week !== undefined) {
+    const w = Number(week)
+    if (w < 1 || w > 53) {
+      return undefined
+    }
+    const start = isoWeekStart(year, w)
+    return { start, end: start + 7 * dayMs }
+  }
+  if (month !== undefined) {
+    const m = Number(month)
+    if (m < 1 || m > 12) {
+      return undefined
+    }
+    if (day !== undefined) {
+      const d = Number(day)
+      const start = utcDay(year, m, d)
+      const date = new Date(start)
+      if (date.getUTCMonth() !== m - 1 || date.getUTCDate() !== d) {
+        return undefined
+      }
+      return { start, end: start + dayMs }
+    }
+    return { start: utcDay(year, m, 1), end: utcDay(year, m + 1, 1) }
+  }
+  return { start: utcDay(year, 1, 1), end: utcDay(year + 1, 1, 1) }
+}
+
+const numericPointRe = /^[\d-]+$/
+
+/**
+ * Parses a `A..B` / `..B` / `A..` time range. The end point of a closed
+ * range may abbreviate by dropping *leading* numeric segments, inherited
+ * from the start point (spec §32.2): `2026-04-10..04-11` reads as
+ * `2026-04-10..2026-04-11`, `2026-04-10..11` likewise. `Q`/`H`/`W`
+ * points are always written in full. A closed range must be non-empty
+ * (`2028..2025` is not a time range).
+ * @returns `undefined` when `text` is not a range.
+ */
+export const parseRange = (text: string): undefined | { start?: Period, end?: Period } => {
+  const at = text.indexOf('..')
+  if (at === -1 || text.indexOf('..', at + 2) !== -1) {
+    return undefined
+  }
+  const leftText = text.slice(0, at)
+  const rightText = text.slice(at + 2)
+  if (leftText === '' && rightText === '') {
+    return undefined
+  }
+  if (leftText === '') {
+    const end = parsePeriod(rightText)
+    return end === undefined ? undefined : { end }
+  }
+  const start = parsePeriod(leftText)
+  if (start === undefined) {
+    return undefined
+  }
+  if (rightText === '') {
+    return { start }
+  }
+  let end = parsePeriod(rightText)
+  if (end === undefined && numericPointRe.test(leftText) && numericPointRe.test(rightText)) {
+    const leftSegments = leftText.split('-')
+    const rightSegments = rightText.split('-')
+    if (rightSegments.length < leftSegments.length) {
+      end = parsePeriod([...leftSegments.slice(0, leftSegments.length - rightSegments.length), ...rightSegments].join('-'))
+    }
+  }
+  if (end === undefined || end.end <= start.start) {
+    return undefined
+  }
+  return { start, end }
+}
+
+/**
+ * Reads a context as time, when it is one (spec §32.2): a bare or
+ * `time:`-prefixed date-like point or `..` range. Every other context —
+ * `production`, `src:filing`, `auth.ts:42` — is opaque and returns
+ * `undefined`; a context that fails to parse as time is opaque too, the
+ * robust-extraction default (spec §1.6).
+ */
+export const ofContext = (context: string): undefined | TimeContext => {
+  const body = context.startsWith('time:') ? context.slice('time:'.length) : context
+  if (body.includes('..')) {
+    const range = parseRange(body)
+    return range === undefined ? undefined : { kind: 'range', ...range }
+  }
+  const period = parsePeriod(body)
+  return period === undefined ? undefined : { kind: 'point', period }
+}
+
+/**
+ * Parses a query anchor into an instant (ms since epoch): a date-like
+ * period reads as its *start* instant (`2026` is 2026-01-01T00:00:00Z —
+ * name the finer period to anchor inside one), a `T` timestamp reads
+ * exactly. @returns `undefined` when `text` is neither.
+ */
+export const parseInstant = (text: string): undefined | number => {
+  const period = parsePeriod(text)
+  if (period !== undefined) {
+    return period.start
+  }
+  if (!text.includes('T')) {
+    return undefined
+  }
+  const parsed = Date.parse(text)
+  return Number.isNaN(parsed) ? undefined : parsed
+}
+
+/** @returns whether a time context covers the instant (spec §32.4). */
+export const covers = (context: TimeContext, instant: number): boolean =>
+  context.kind === 'point' ?
+    instant >= context.period.start && instant < context.period.end :
+    (context.start === undefined || instant >= context.start.start) &&
+    (context.end === undefined || instant < context.end.end)
+
+/**
+ * Whether a claim with these contexts applies at the instant
+ * (spec §32.4): timeless claims — no time context — always apply; a
+ * time-anchored claim applies when *any* of its time contexts covers
+ * the instant. Opaque contexts never participate.
+ */
+export const appliesAt = (contexts: readonly string[], instant: number): boolean => {
+  let anchored = false
+  for (const context of contexts) {
+    const time = ofContext(context)
+    if (time === undefined) {
+      continue
+    }
+    anchored = true
+    if (covers(time, instant)) {
+      return true
+    }
+  }
+  return !anchored
+}
+
+/**
+ * The single closed range among a claim's contexts — the interval a
+ * trajectory value interpolates over (spec §32.3). @returns `undefined`
+ * when there is none, or more than one (ambiguous — no interpolation).
+ */
+export const closedRangeOf = (contexts: readonly string[]): undefined | { start: Period, end: Period } => {
+  let found: undefined | { start: Period, end: Period }
+  for (const context of contexts) {
+    const time = ofContext(context)
+    if (time === undefined || time.kind !== 'range' || time.start === undefined || time.end === undefined) {
+      continue
+    }
+    if (found !== undefined) {
+      return undefined
+    }
+    found = { start: time.start, end: time.end }
+  }
+  return found
+}
+
+/**
+ * Where an instant sits along a closed range, as the interpolation
+ * fraction in [0, 1] (spec §32.3): endpoint values anchor at the *start*
+ * instants of the periods that name them — `20B -> 40B @2025..2028` is
+ * 20B at 2025-01-01 and 40B at 2028-01-01 — and the fraction clamps to 1
+ * through the end period's tail ("40B *in* 2028" holds all of 2028).
+ */
+export const fractionAt = (range: { start: Period, end: Period }, instant: number): number => {
+  const span = range.end.start - range.start.start
+  if (span <= 0) {
+    return 1
+  }
+  return Math.min(1, Math.max(0, (instant - range.start.start) / span))
+}

package/src/uuidv7.ts

@@ -10,8 +10,6 @@
  * clock never produces a smaller id.
  */
 
-import { randomFillSync } from 'node:crypto'
-
 const hex = (n: number, digits: number): string =>
   n.toString(16).padStart(digits, '0')
 
@@ -65,7 +63,9 @@ export const next = (now: () => number = Date.now): string => {
   }
   lastMs = ms
   const rand = new Uint8Array(8)
-  randomFillSync(rand)
+  // Web Crypto is available in supported Node.js releases and browsers,
+  // keeping UUID generation portable without weakening randomness.
+  globalThis.crypto.getRandomValues(rand)
   return at(ms, lastSeq, rand)
 }
 

package/src/value.ts

@@ -1,5 +1,5 @@
 /**
- * Values, units and multipliers (spec §7.1).
+ * Values, units and multipliers (spec §7.1), and trajectories (spec §32.3).
  *
  * A value is the payload of an attribute claim (`HAS attr: value`), a metric
  * claim (`metric IS value`), or a `+/-` uncertainty delta. Parsing keeps the
@@ -11,6 +11,7 @@
  * - `~20B USD/yr`    → the same, `approx` set
  * - `94.5%`          → num 94.5, unit `%`
  * - `20 conn`        → num 20, unit `conn`
+ * - `20B -> 40B USD/yr` → trajectory, from 2e10 to 4e10, unit `USD/yr`
  * - `2026-H2`        → date-like, kept textual
  * - `token-expiry`   → atom, kept textual
  *
@@ -22,11 +23,12 @@ import * as Multiplier from './multiplier.ts'
 
 /** How the value text was classified. */
 export type Kind =
-  | 'number' // numeric, possibly with multiplier and unit
-  | 'date'   // date-like: 2026-H2, 2026-Q1, 2026-04-10
-  | 'atom'   // bare word(s): token-expiry, critical
-  | 'text'   // double-quoted natural-language literal
-  | 'code'   // backticked exact literal
+  | 'number'     // numeric, possibly with multiplier and unit
+  | 'trajectory' // two numeric endpoints: 20B -> 40B USD/yr (spec §32.3)
+  | 'date'       // date-like: 2026-H2, 2026-Q1, 2026-04-10
+  | 'atom'       // bare word(s): token-expiry, critical
+  | 'text'       // double-quoted natural-language literal
+  | 'code'       // backticked exact literal
 
 export type Value = {
   /** Exactly as written, including `~` and multiplier letter. */
@@ -34,10 +36,18 @@ export type Value = {
   readonly kind: Kind
   /** `~` prefix (spec §7.1): the value is approximate. */
   readonly approx: boolean
-  /** Normalized numeric value with multiplier expanded, when parseable. */
+  /**
+   * Normalized numeric value with multiplier expanded, when parseable.
+   * Unset for trajectories — a trajectory is not one number, so every
+   * scalar consumer (fusion, filters, σ) conservatively skips it.
+   */
   readonly num?: number
   /** Normalized unit expression (`USD/yr`, `ms`, `%`), when present. */
   readonly unit?: string
+  /** Trajectory start value, multiplier expanded (kind `trajectory`). */
+  readonly from?: number
+  /** Trajectory end value, multiplier expanded (kind `trajectory`). */
+  readonly to?: number
 }
 
 export type t = Value
@@ -93,14 +103,61 @@ const parseNumeric = (body: string): undefined | Numeric => {
   return unit === undefined ? { num } : { num, unit }
 }
 
+type Trajectory = Numeric & {
+  to: number
+  /** The unit was glued to the endpoint numbers (`5ms -> 800ms`). */
+  glued: boolean
+  /** An endpoint used a multiplier letter (`20B -> 40B`). */
+  multiplier: boolean
+}
+
+const multiplierHeadRe = /^-?\d+(?:\.\d+)?[TBMK]$/
+
+/**
+ * Splits `body` as trajectory `from -> to [unit]` (spec §32.3). Each side
+ * parses like a scalar; the unit is shared — glued per endpoint or spaced
+ * after either — and both sides naming different units is not a
+ * trajectory. Style (glue, multipliers) is kept for {@link formatAt}.
+ */
+const parseTrajectory = (body: string): undefined | Trajectory => {
+  const parts = body.split(' -> ')
+  if (parts.length !== 2 || parts[0] === '' || parts[1] === '') {
+    return undefined
+  }
+  const [leftText, rightText] = parts as [string, string]
+  const left = parseNumeric(leftText)
+  const right = parseNumeric(rightText)
+  if (left === undefined || right === undefined) {
+    return undefined
+  }
+  if (left.unit !== undefined && right.unit !== undefined && left.unit !== right.unit) {
+    return undefined
+  }
+  const unit = left.unit ?? right.unit
+  return {
+    num: left.num,
+    to: right.num,
+    ...unit === undefined ? {} : { unit },
+    glued: unit !== undefined && !leftText.includes(' ') && !rightText.includes(' '),
+    multiplier: multiplierHeadRe.test(leftText.split(' ')[0]!) || multiplierHeadRe.test(rightText.split(' ')[0]!)
+  }
+}
+
 /**
  * Parses an unquoted value string (spec §16 `value`), classifying it as
- * number, date or atom. The raw text (including `~` and multiplier letters)
- * is preserved verbatim.
+ * number, trajectory, date or atom. The raw text (including `~` and
+ * multiplier letters) is preserved verbatim.
  */
 export const parse = (raw: string): Value => {
   const approx = raw.startsWith('~')
   const body = approx ? raw.slice(1) : raw
+  const trajectory = body.includes(' -> ') ? parseTrajectory(body) : undefined
+  if (trajectory !== undefined) {
+    return {
+      raw, kind: 'trajectory', approx, from: trajectory.num, to: trajectory.to,
+      ...trajectory.unit === undefined ? {} : { unit: trajectory.unit }
+    }
+  }
   const numeric = parseNumeric(body)
   if (numeric !== undefined) {
     return numeric.unit === undefined ?
@@ -113,6 +170,73 @@ export const parse = (raw: string): Value => {
   return { raw, kind: 'atom', approx }
 }
 
+const exponentRe = /^(-?)(\d+)(?:\.(\d+))?e([+-]\d+)$/
+
+/**
+ * Plain-decimal text of a finite number. The CAVE number grammar
+ * (spec §16) has no exponent form, so `String`'s occasional `1e-7` /
+ * `1.5e+21` output is expanded to `0.0000001` / `1500000000000000000000`.
+ * The digits are JavaScript's shortest round-trip representation, so
+ * `parse(formatNumber(n)).num === n`. Every generator writing numbers
+ * into CAVE text must go through this (or emit a multiplier form built
+ * on it) — `String(n)` alone round-trips tiny and huge magnitudes as
+ * atoms. Throws on non-finite input: CAVE has no text for it.
+ */
+export const formatNumber = (n: number): string => {
+  if (!Number.isFinite(n)) {
+    throw new Error(`Expected a finite number, got ${n}.`)
+  }
+  const match = exponentRe.exec(String(n))
+  if (match === null) {
+    return String(n)
+  }
+  const [, sign = '', whole = '', fraction = '', exponent = '0'] = match
+  const digits = `${whole}${fraction}`
+  const point = whole.length + Number(exponent)
+  return point <= 0 ? `${sign}0.${'0'.repeat(-point)}${digits}` :
+    point >= digits.length ? `${sign}${digits}${'0'.repeat(point - digits.length)}` :
+    `${sign}${digits.slice(0, point)}.${digits.slice(point)}`
+}
+
+/**
+ * Linear interpolation of a trajectory at `fraction` ∈ [0, 1], clamped
+ * (spec §32.3). @returns `undefined` for non-trajectory values.
+ */
+export const interpolate = (value: Value, fraction: number): undefined | number =>
+  value.from === undefined || value.to === undefined ?
+    undefined :
+    value.from + (value.to - value.from) * Math.min(1, Math.max(0, fraction))
+
+/**
+ * Canonical scalar text of a trajectory at `fraction`, in the
+ * trajectory's own style (spec §32.3): multipliers re-compress when the
+ * endpoints used them, a glued unit stays glued, 4 significant digits.
+ * `20B -> 40B USD/yr` at 0.5 → `30B USD/yr`; `5ms -> 800ms` at 0.5 →
+ * `402.5ms`. @returns `undefined` for non-trajectory values.
+ */
+export const formatAt = (value: Value, fraction: number): undefined | string => {
+  const num = interpolate(value, fraction)
+  if (num === undefined) {
+    return undefined
+  }
+  const style = parseTrajectory(value.approx ? value.raw.slice(1) : value.raw)
+  let scaled = num
+  let letter = ''
+  if (style?.multiplier === true) {
+    for (const m of ['T', 'B', 'M', 'K'] as const) {
+      if (Math.abs(num) >= Multiplier.factor(m)) {
+        scaled = num / Multiplier.factor(m)
+        letter = m
+        break
+      }
+    }
+  }
+  const digits = formatNumber(Number(scaled.toPrecision(4)))
+  return value.unit === undefined ?
+    `${digits}${letter}` :
+    `${digits}${letter}${style?.glued === true ? '' : ' '}${value.unit}`
+}
+
 /** @returns value for a double-quoted natural-language literal (spec §4.2). */
 export const ofText = (text: string): Value =>
   ({ raw: text, kind: 'text', approx: false })