@mostlyrightmd/core 0.1.0-rc.7

package/dist/temporal/index.d.cts

@@ -0,0 +1,121 @@
+/**
+ * UTC-aware timestamp wrapper.
+ *
+ * Equivalent to Python's `mostlyright.core.TimePoint`. Constructed from either
+ * a `Date` (rejects NaN/Infinity) or a tz-aware ISO 8601 string (rejects
+ * naive / date-only inputs). Internally stored as an epoch-ms Date (for
+ * display/timezone ops) PLUS an epoch-µs `bigint` (used for comparisons).
+ *
+ * Immutable: the underlying Date is hidden behind a private `#utc` field
+ * and `toUTCDate()` returns a defensive copy so callers cannot mutate the
+ * wrapped instant. The `#epochMicros` field carries full µs precision
+ * captured from string inputs with 4-6 digit fractional seconds.
+ */
+declare class TimePoint {
+    #private;
+    constructor(value: Date | string);
+    /** Return a defensive copy of the underlying UTC Date. */
+    toUTCDate(): Date;
+    /**
+     * Return the epoch microseconds as a `bigint`.
+     *
+     * Iter-11 C13: this is the comparison-safe accessor. JS `Date` only
+     * carries ms precision, so callers comparing `toUTCDate().getTime()`
+     * across two TimePoints constructed from `.123456Z` and `.123789Z`
+     * would see them as equal — they're not. Use `equals`/`before`/`after`
+     * (or this accessor directly) to compare with full µs precision.
+     */
+    toEpochMicros(): bigint;
+    /** Return the canonical ISO 8601 UTC string (always ends in 'Z'). */
+    toISOString(): string;
+    /**
+     * Return the Python-compatible ISO 8601 UTC string.
+     *
+     * Where {@link toISOString} emits the JS-native `"...Z"` suffix and
+     * forces `.000` millisecond padding, this method matches Python's
+     * `datetime.isoformat()` output for a UTC-tz-aware datetime:
+     *
+     *   - tz suffix is `+00:00`, never `Z`
+     *   - subsecond portion is omitted when zero (`"...T12:00:00+00:00"`)
+     *   - microsecond portion appears as 6 digits when non-zero
+     *     (`"...T12:00:00.123456+00:00"`); built from the µs-precision
+     *     `#epochMicros` field so 4-6 digit fractional inputs round-trip
+     *     exactly (iter-11 C13 fix).
+     *
+     * Used by error payloads (LeakageError.toDict, sample violations) so
+     * MCP clients comparing the on-wire string across the Python and TS
+     * SDKs see byte-equivalent values. Iter-1 H1 fix; iter-11 C13 extends
+     * to full µs precision.
+     */
+    toPythonIso(): string;
+    /**
+     * Format this instant in an IANA timezone via Intl.DateTimeFormat.
+     * Display helper only — canonical storage stays UTC.
+     *
+     * Uses `en-CA` locale for a YYYY-MM-DD, HH:MM:SS shape that's easy to grep
+     * in logs. The exact output format may vary slightly across Node releases;
+     * callers writing tests should use loose contains-style assertions.
+     */
+    asZone(tz: string): string;
+    equals(other: TimePoint): boolean;
+    before(other: TimePoint): boolean;
+    after(other: TimePoint): boolean;
+    /** Return a TimePoint for the current UTC instant. */
+    static now(): TimePoint;
+}
+
+/**
+ * A filtered, knowledge-time-bounded view over an array of rows.
+ *
+ * @template Row — caller's row type. Must have a string `knowledge_time` field.
+ */
+declare class KnowledgeView<Row extends {
+    knowledge_time: string;
+}> {
+    #private;
+    constructor(rows: ReadonlyArray<Row>, asOf: TimePoint);
+    /**
+     * Return a freshly filtered array — only rows where
+     * `knowledge_time <= asOf`. The returned array is a NEW reference each
+     * call (defensive copy semantics), so callers can mutate it without
+     * affecting subsequent calls.
+     */
+    rows(): ReadonlyArray<Row>;
+    /** The as-of cutoff supplied at construction. */
+    get asOf(): TimePoint;
+}
+
+/**
+ * Throw {@link LeakageError} if any row's `knowledge_time` is strictly
+ * greater than `asOf`. Leak-free input returns void.
+ *
+ * Loudly rejects rows whose `knowledge_time` is missing, not a string,
+ * or not a tz-aware ISO 8601 datetime — these surface as
+ * {@link SchemaValidationError} (rule: `required` /
+ * `datetime_dtype` / `tz_aware_utc`), mirroring Python's
+ * `assert_no_leakage` validation contract.
+ *
+ * @template Row — caller's row type. Must have a string `knowledge_time` field.
+ */
+declare function assertNoLeakage<Row extends {
+    knowledge_time: string;
+}>(rows: ReadonlyArray<Row>, asOf: TimePoint): void;
+/**
+ * Convenience wrapper for repeated leakage checks against a fixed `asOf`.
+ *
+ * ```ts
+ * const detector = new LeakageDetector(asOf);
+ * detector.check(trainingRows);
+ * detector.check(featureRows);
+ * ```
+ */
+declare class LeakageDetector {
+    #private;
+    constructor(asOf: TimePoint);
+    get asOf(): TimePoint;
+    check<Row extends {
+        knowledge_time: string;
+    }>(rows: ReadonlyArray<Row>): void;
+}
+
+export { KnowledgeView, LeakageDetector, TimePoint, assertNoLeakage };

package/dist/temporal/index.d.ts

@@ -0,0 +1,121 @@
+/**
+ * UTC-aware timestamp wrapper.
+ *
+ * Equivalent to Python's `mostlyright.core.TimePoint`. Constructed from either
+ * a `Date` (rejects NaN/Infinity) or a tz-aware ISO 8601 string (rejects
+ * naive / date-only inputs). Internally stored as an epoch-ms Date (for
+ * display/timezone ops) PLUS an epoch-µs `bigint` (used for comparisons).
+ *
+ * Immutable: the underlying Date is hidden behind a private `#utc` field
+ * and `toUTCDate()` returns a defensive copy so callers cannot mutate the
+ * wrapped instant. The `#epochMicros` field carries full µs precision
+ * captured from string inputs with 4-6 digit fractional seconds.
+ */
+declare class TimePoint {
+    #private;
+    constructor(value: Date | string);
+    /** Return a defensive copy of the underlying UTC Date. */
+    toUTCDate(): Date;
+    /**
+     * Return the epoch microseconds as a `bigint`.
+     *
+     * Iter-11 C13: this is the comparison-safe accessor. JS `Date` only
+     * carries ms precision, so callers comparing `toUTCDate().getTime()`
+     * across two TimePoints constructed from `.123456Z` and `.123789Z`
+     * would see them as equal — they're not. Use `equals`/`before`/`after`
+     * (or this accessor directly) to compare with full µs precision.
+     */
+    toEpochMicros(): bigint;
+    /** Return the canonical ISO 8601 UTC string (always ends in 'Z'). */
+    toISOString(): string;
+    /**
+     * Return the Python-compatible ISO 8601 UTC string.
+     *
+     * Where {@link toISOString} emits the JS-native `"...Z"` suffix and
+     * forces `.000` millisecond padding, this method matches Python's
+     * `datetime.isoformat()` output for a UTC-tz-aware datetime:
+     *
+     *   - tz suffix is `+00:00`, never `Z`
+     *   - subsecond portion is omitted when zero (`"...T12:00:00+00:00"`)
+     *   - microsecond portion appears as 6 digits when non-zero
+     *     (`"...T12:00:00.123456+00:00"`); built from the µs-precision
+     *     `#epochMicros` field so 4-6 digit fractional inputs round-trip
+     *     exactly (iter-11 C13 fix).
+     *
+     * Used by error payloads (LeakageError.toDict, sample violations) so
+     * MCP clients comparing the on-wire string across the Python and TS
+     * SDKs see byte-equivalent values. Iter-1 H1 fix; iter-11 C13 extends
+     * to full µs precision.
+     */
+    toPythonIso(): string;
+    /**
+     * Format this instant in an IANA timezone via Intl.DateTimeFormat.
+     * Display helper only — canonical storage stays UTC.
+     *
+     * Uses `en-CA` locale for a YYYY-MM-DD, HH:MM:SS shape that's easy to grep
+     * in logs. The exact output format may vary slightly across Node releases;
+     * callers writing tests should use loose contains-style assertions.
+     */
+    asZone(tz: string): string;
+    equals(other: TimePoint): boolean;
+    before(other: TimePoint): boolean;
+    after(other: TimePoint): boolean;
+    /** Return a TimePoint for the current UTC instant. */
+    static now(): TimePoint;
+}
+
+/**
+ * A filtered, knowledge-time-bounded view over an array of rows.
+ *
+ * @template Row — caller's row type. Must have a string `knowledge_time` field.
+ */
+declare class KnowledgeView<Row extends {
+    knowledge_time: string;
+}> {
+    #private;
+    constructor(rows: ReadonlyArray<Row>, asOf: TimePoint);
+    /**
+     * Return a freshly filtered array — only rows where
+     * `knowledge_time <= asOf`. The returned array is a NEW reference each
+     * call (defensive copy semantics), so callers can mutate it without
+     * affecting subsequent calls.
+     */
+    rows(): ReadonlyArray<Row>;
+    /** The as-of cutoff supplied at construction. */
+    get asOf(): TimePoint;
+}
+
+/**
+ * Throw {@link LeakageError} if any row's `knowledge_time` is strictly
+ * greater than `asOf`. Leak-free input returns void.
+ *
+ * Loudly rejects rows whose `knowledge_time` is missing, not a string,
+ * or not a tz-aware ISO 8601 datetime — these surface as
+ * {@link SchemaValidationError} (rule: `required` /
+ * `datetime_dtype` / `tz_aware_utc`), mirroring Python's
+ * `assert_no_leakage` validation contract.
+ *
+ * @template Row — caller's row type. Must have a string `knowledge_time` field.
+ */
+declare function assertNoLeakage<Row extends {
+    knowledge_time: string;
+}>(rows: ReadonlyArray<Row>, asOf: TimePoint): void;
+/**
+ * Convenience wrapper for repeated leakage checks against a fixed `asOf`.
+ *
+ * ```ts
+ * const detector = new LeakageDetector(asOf);
+ * detector.check(trainingRows);
+ * detector.check(featureRows);
+ * ```
+ */
+declare class LeakageDetector {
+    #private;
+    constructor(asOf: TimePoint);
+    get asOf(): TimePoint;
+    check<Row extends {
+        knowledge_time: string;
+    }>(rows: ReadonlyArray<Row>): void;
+}
+
+export { KnowledgeView, LeakageDetector, TimePoint, assertNoLeakage };