anchordb 0.2.0

package/dist/cjs/timestamps/index.d.ts

@@ -0,0 +1,47 @@
+import { zonedTimeToUtc } from "./timezone.js";
+export * from "./timezone.js";
+export interface TimeServiceOptions {
+    /** Business/reference zone (§26.2). Display only — never affects storage. */
+    serverTimeZone?: string;
+    /** Overridden by the sync engine once a server clock offset is known. */
+    now?: () => number;
+}
+/**
+ * `db.time` (§26.9).
+ *
+ * Every method either produces canonical UTC or formats canonical UTC for display. None of them can
+ * change a stored value — that separation is the whole point of §26.11.
+ */
+export declare class TimeService {
+    readonly deviceTimeZone: string;
+    readonly serverTimeZone: string | undefined;
+    private nowFn;
+    constructor(opts?: TimeServiceOptions);
+    /** Canonical current timestamp: ISO-8601, UTC, milliseconds. */
+    now(): string;
+    nowMs(): number;
+    nowDate(): Date;
+    /** Normalise anything date-like to canonical UTC. */
+    toUTC(value: Date | string | number): string;
+    /**
+     * Render a stored UTC value as wall-clock text in `tz` (defaults to the device zone).
+     * Display only: `db.time.fromUTC(stored, tz)` never rewrites `stored`.
+     */
+    fromUTC(value: Date | string | number, tz?: string): string;
+    /** Same instant rendered in the configured server/business zone. */
+    inServerZone(value: Date | string | number): string;
+    /** Interpret a wall-clock reading in a zone and return canonical UTC. */
+    fromLocal(local: string, tz?: string): string;
+    /** UTC offset of a zone at an instant, e.g. "+05:30". */
+    offsetAt(value: Date | string | number, tz?: string): string;
+    /** Used by the sync engine to install a server-skew-corrected clock. */
+    setClock(now: () => number): void;
+    /** All three views of one instant — what Lens renders (§44). */
+    describe(value: Date | string | number): {
+        utc: string;
+        device: string;
+        server?: string;
+    };
+}
+export { zonedTimeToUtc };
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/timestamps/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/timestamps/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,cAAc,EACf,MAAM,eAAe,CAAC;AAEvB,cAAc,eAAe,CAAC;AAE9B,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,qBAAa,WAAW;IACtB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,OAAO,CAAC,KAAK,CAAe;gBAEhB,IAAI,GAAE,kBAAuB;IAMzC,gEAAgE;IAChE,GAAG,IAAI,MAAM;IAIb,KAAK,IAAI,MAAM;IAIf,OAAO,IAAI,IAAI;IAIf,qDAAqD;IACrD,KAAK,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM;IAI5C;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM;IAI3D,oEAAoE;IACpE,YAAY,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM;IAOnD,yEAAyE;IACzE,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM;IAI7C,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM;IAK5D,wEAAwE;IACxE,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,GAAG,IAAI;IAIjC,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;CAW1F;AAED,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/cjs/timestamps/index.js

@@ -0,0 +1,88 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.zonedTimeToUtc = exports.TimeService = void 0;
+const timezone_ts_1 = require("./timezone.js");
+Object.defineProperty(exports, "zonedTimeToUtc", { enumerable: true, get: function () { return timezone_ts_1.zonedTimeToUtc; } });
+__exportStar(require("./timezone.js"), exports);
+/**
+ * `db.time` (§26.9).
+ *
+ * Every method either produces canonical UTC or formats canonical UTC for display. None of them can
+ * change a stored value — that separation is the whole point of §26.11.
+ */
+class TimeService {
+    constructor(opts = {}) {
+        this.deviceTimeZone = (0, timezone_ts_1.detectDeviceTimeZone)();
+        this.serverTimeZone = opts.serverTimeZone ? (0, timezone_ts_1.assertValidTimeZone)(opts.serverTimeZone) : undefined;
+        this.nowFn = opts.now ?? (() => Date.now());
+    }
+    /** Canonical current timestamp: ISO-8601, UTC, milliseconds. */
+    now() {
+        return new Date(this.nowFn()).toISOString();
+    }
+    nowMs() {
+        return this.nowFn();
+    }
+    nowDate() {
+        return new Date(this.nowFn());
+    }
+    /** Normalise anything date-like to canonical UTC. */
+    toUTC(value) {
+        return (0, timezone_ts_1.toUtcIso)(value);
+    }
+    /**
+     * Render a stored UTC value as wall-clock text in `tz` (defaults to the device zone).
+     * Display only: `db.time.fromUTC(stored, tz)` never rewrites `stored`.
+     */
+    fromUTC(value, tz) {
+        return (0, timezone_ts_1.formatInTimeZone)(value, tz ?? this.deviceTimeZone);
+    }
+    /** Same instant rendered in the configured server/business zone. */
+    inServerZone(value) {
+        if (!this.serverTimeZone) {
+            throw new Error("No server time zone configured. Pass `timezone: { server: \"...\" }` to AnchorDB.");
+        }
+        return (0, timezone_ts_1.formatInTimeZone)(value, this.serverTimeZone);
+    }
+    /** Interpret a wall-clock reading in a zone and return canonical UTC. */
+    fromLocal(local, tz) {
+        return (0, timezone_ts_1.parseZonedTimeToUtc)(local, tz ?? this.deviceTimeZone).toISOString();
+    }
+    /** UTC offset of a zone at an instant, e.g. "+05:30". */
+    offsetAt(value, tz) {
+        const d = value instanceof Date ? value : new Date(value);
+        return (0, timezone_ts_1.formatOffset)((0, timezone_ts_1.getTimeZoneOffsetMs)(d, tz ?? this.deviceTimeZone));
+    }
+    /** Used by the sync engine to install a server-skew-corrected clock. */
+    setClock(now) {
+        this.nowFn = now;
+    }
+    /** All three views of one instant — what Lens renders (§44). */
+    describe(value) {
+        const utc = (0, timezone_ts_1.toUtcIso)(value);
+        const out = {
+            utc,
+            device: `${(0, timezone_ts_1.formatInTimeZone)(utc, this.deviceTimeZone)} ${this.deviceTimeZone}`,
+        };
+        if (this.serverTimeZone) {
+            out.server = `${(0, timezone_ts_1.formatInTimeZone)(utc, this.serverTimeZone)} ${this.serverTimeZone}`;
+        }
+        return out;
+    }
+}
+exports.TimeService = TimeService;
+//# sourceMappingURL=index.js.map

package/dist/cjs/timestamps/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/timestamps/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,+CASuB;AA4Fd,+FA7FP,4BAAc,OA6FO;AA1FvB,gDAA8B;AAS9B;;;;;GAKG;AACH,MAAa,WAAW;IAKtB,YAAY,OAA2B,EAAE;QACvC,IAAI,CAAC,cAAc,GAAG,IAAA,kCAAoB,GAAE,CAAC;QAC7C,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,IAAA,iCAAmB,EAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACjG,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED,gEAAgE;IAChE,GAAG;QACD,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IAC9C,CAAC;IAED,KAAK;QACH,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAED,OAAO;QACL,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IAChC,CAAC;IAED,qDAAqD;IACrD,KAAK,CAAC,KAA6B;QACjC,OAAO,IAAA,sBAAQ,EAAC,KAAK,CAAC,CAAC;IACzB,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,KAA6B,EAAE,EAAW;QAChD,OAAO,IAAA,8BAAgB,EAAC,KAAK,EAAE,EAAE,IAAI,IAAI,CAAC,cAAc,CAAC,CAAC;IAC5D,CAAC;IAED,oEAAoE;IACpE,YAAY,CAAC,KAA6B;QACxC,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,mFAAmF,CAAC,CAAC;QACvG,CAAC;QACD,OAAO,IAAA,8BAAgB,EAAC,KAAK,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;IACtD,CAAC;IAED,yEAAyE;IACzE,SAAS,CAAC,KAAa,EAAE,EAAW;QAClC,OAAO,IAAA,iCAAmB,EAAC,KAAK,EAAE,EAAE,IAAI,IAAI,CAAC,cAAc,CAAC,CAAC,WAAW,EAAE,CAAC;IAC7E,CAAC;IAED,yDAAyD;IACzD,QAAQ,CAAC,KAA6B,EAAE,EAAW;QACjD,MAAM,CAAC,GAAG,KAAK,YAAY,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1D,OAAO,IAAA,0BAAY,EAAC,IAAA,iCAAmB,EAAC,CAAC,EAAE,EAAE,IAAI,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC;IACzE,CAAC;IAED,wEAAwE;IACxE,QAAQ,CAAC,GAAiB;QACxB,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC;IACnB,CAAC;IAED,gEAAgE;IAChE,QAAQ,CAAC,KAA6B;QACpC,MAAM,GAAG,GAAG,IAAA,sBAAQ,EAAC,KAAK,CAAC,CAAC;QAC5B,MAAM,GAAG,GAAqD;YAC5D,GAAG;YACH,MAAM,EAAE,GAAG,IAAA,8BAAgB,EAAC,GAAG,EAAE,IAAI,CAAC,cAAc,CAAC,IAAI,IAAI,CAAC,cAAc,EAAE;SAC/E,CAAC;QACF,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,GAAG,CAAC,MAAM,GAAG,GAAG,IAAA,8BAAgB,EAAC,GAAG,EAAE,IAAI,CAAC,cAAc,CAAC,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;QACtF,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;CACF;AAzED,kCAyEC"}

package/dist/cjs/timestamps/timezone.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Timezone handling.
+ *
+ * The rule the whole system rests on: **UTC is the only canonical representation**. Device zone and
+ * configured server zone are presentation/reference concerns and can never influence what is
+ * stored. Everything here either produces UTC or formats UTC for display; nothing converts storage.
+ *
+ * Implemented entirely on `Intl`, with no date library, so React Native and browsers carry no extra
+ * dependency. The one platform caveat is ICU availability, handled in `assertIntlSupport()`.
+ */
+/** `Intl.DateTimeFormat().resolvedOptions().timeZone`, e.g. "Asia/Colombo". */
+export declare function detectDeviceTimeZone(): string;
+/**
+ * True for a real IANA zone. Prefers `Intl.supportedValuesOf('timeZone')` where present and falls
+ * back to constructing a formatter, which throws `RangeError` on an unknown zone.
+ */
+export declare function isValidTimeZone(tz: string): boolean;
+/**
+ * Fail loudly at configuration time (§26.10). Silently falling back to UTC would mean every
+ * displayed timestamp in the app is quietly wrong, which is far worse than refusing to start.
+ */
+export declare function assertValidTimeZone(tz: string, settingName?: string): string;
+/** Detects the stripped-ICU builds where every zone silently formats as UTC. */
+export declare function assertIntlSupport(): void;
+/**
+ * Offset of `tz` at a given instant, in milliseconds east of UTC.
+ * `Asia/Colombo` → +19800000 (5h30m). Handles DST because it asks about a specific instant.
+ */
+export declare function getTimeZoneOffsetMs(instant: Date, tz: string): number;
+/**
+ * Interpret a wall-clock reading *in a zone* and return the UTC instant.
+ *
+ * DST makes this genuinely ambiguous, so a naive "measure the offset then subtract it" pass is
+ * wrong — around a transition it can silently resolve to a different local time than the one asked
+ * for. We instead form the two candidate instants implied by the offsets on either side of any
+ * nearby transition and check which of them actually round-trips:
+ *
+ *   both valid   normal time, or a fall-back OVERLAP -> take the earlier instant
+ *   one valid    unambiguous
+ *   neither      a spring-forward GAP: the requested local time does not exist, so shift forward
+ *                past the gap
+ *
+ * This matches Temporal's `disambiguation: "compatible"` and Luxon's default, which is the
+ * behaviour developers already expect. Both branches are covered by tests.
+ */
+export declare function zonedTimeToUtc(wall: {
+    year: number;
+    month: number;
+    day: number;
+    hour?: number;
+    minute?: number;
+    second?: number;
+    ms?: number;
+}, tz: string): Date;
+/** Parse "2026-08-31 10:29:00" / "2026-08-31T10:29" as a wall time in `tz`. */
+export declare function parseZonedTimeToUtc(local: string, tz: string): Date;
+/** Canonical storage format: ISO-8601, UTC, millisecond precision, `Z` suffix. */
+export declare function toUtcIso(value: Date | string | number): string;
+/** Render a UTC instant as wall-clock text in `tz`. Display only — storage is untouched. */
+export declare function formatInTimeZone(value: Date | string | number, tz: string, opts?: {
+    withZone?: boolean;
+    separator?: string;
+}): string;
+export declare function formatOffset(offsetMs: number): string;
+//# sourceMappingURL=timezone.d.ts.map

package/dist/cjs/timestamps/timezone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timezone.d.ts","sourceRoot":"","sources":["../../../src/timestamps/timezone.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,+EAA+E;AAC/E,wBAAgB,oBAAoB,IAAI,MAAM,CAQ7C;AAID;;;GAGG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAcnD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,SAAoB,GAAG,MAAM,CAiBvF;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,IAAI,IAAI,CASxC;AA+CD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAIrE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,EAChH,EAAE,EAAE,MAAM,GACT,IAAI,CAyBN;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAmBnE;AAED,kFAAkF;AAClF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAM9D;AAED,4FAA4F;AAC5F,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,EAC7B,EAAE,EAAE,MAAM,EACV,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACpD,MAAM,CAUR;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMrD"}

package/dist/cjs/timestamps/timezone.js

@@ -0,0 +1,208 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectDeviceTimeZone = detectDeviceTimeZone;
+exports.isValidTimeZone = isValidTimeZone;
+exports.assertValidTimeZone = assertValidTimeZone;
+exports.assertIntlSupport = assertIntlSupport;
+exports.getTimeZoneOffsetMs = getTimeZoneOffsetMs;
+exports.zonedTimeToUtc = zonedTimeToUtc;
+exports.parseZonedTimeToUtc = parseZonedTimeToUtc;
+exports.toUtcIso = toUtcIso;
+exports.formatInTimeZone = formatInTimeZone;
+exports.formatOffset = formatOffset;
+const errors_ts_1 = require("../core/errors.js");
+/**
+ * Timezone handling.
+ *
+ * The rule the whole system rests on: **UTC is the only canonical representation**. Device zone and
+ * configured server zone are presentation/reference concerns and can never influence what is
+ * stored. Everything here either produces UTC or formats UTC for display; nothing converts storage.
+ *
+ * Implemented entirely on `Intl`, with no date library, so React Native and browsers carry no extra
+ * dependency. The one platform caveat is ICU availability, handled in `assertIntlSupport()`.
+ */
+/** `Intl.DateTimeFormat().resolvedOptions().timeZone`, e.g. "Asia/Colombo". */
+function detectDeviceTimeZone() {
+    try {
+        const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+        if (tz)
+            return tz;
+    }
+    catch {
+        /* fall through */
+    }
+    return "UTC";
+}
+const validCache = new Map();
+/**
+ * True for a real IANA zone. Prefers `Intl.supportedValuesOf('timeZone')` where present and falls
+ * back to constructing a formatter, which throws `RangeError` on an unknown zone.
+ */
+function isValidTimeZone(tz) {
+    if (typeof tz !== "string" || tz.length === 0)
+        return false;
+    const cached = validCache.get(tz);
+    if (cached !== undefined)
+        return cached;
+    let valid = false;
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: tz });
+        valid = true;
+    }
+    catch {
+        valid = false;
+    }
+    validCache.set(tz, valid);
+    return valid;
+}
+/**
+ * Fail loudly at configuration time (§26.10). Silently falling back to UTC would mean every
+ * displayed timestamp in the app is quietly wrong, which is far worse than refusing to start.
+ */
+function assertValidTimeZone(tz, settingName = "timezone.server") {
+    if (!isValidTimeZone(tz)) {
+        let suggestion = "";
+        try {
+            const all = Intl.supportedValuesOf?.("timeZone") ?? [];
+            const needle = tz.toLowerCase().replace(/[_\s-]/g, "");
+            const near = all.filter((z) => z.toLowerCase().replace(/[_\s-]/g, "").includes(needle)).slice(0, 3);
+            if (near.length)
+                suggestion = ` Did you mean: ${near.join(", ")}?`;
+        }
+        catch {
+            /* suggestions are best-effort */
+        }
+        throw new errors_ts_1.AnchorConfigError(`Invalid IANA time zone "${tz}" for ${settingName}.${suggestion} ` +
+            `Expected a name like "Asia/Colombo", "America/New_York" or "UTC".`);
+    }
+    return tz;
+}
+/** Detects the stripped-ICU builds where every zone silently formats as UTC. */
+function assertIntlSupport() {
+    const probe = new Date("2026-01-15T12:00:00.000Z");
+    const colombo = formatParts(probe, "Asia/Colombo");
+    if (colombo.hour === 12 && colombo.minute === 0) {
+        throw new errors_ts_1.AnchorConfigError("This JavaScript runtime has no full ICU data: time zone conversion silently returns UTC. " +
+            "On React Native, ensure Hermes is built with Intl support, or install a polyfill.");
+    }
+}
+const formatterCache = new Map();
+function getFormatter(tz) {
+    let f = formatterCache.get(tz);
+    if (!f) {
+        f = new Intl.DateTimeFormat("en-US", {
+            timeZone: tz,
+            hourCycle: "h23", // h23 rather than hour12:false — some ICU builds emit hour "24" otherwise
+            year: "numeric",
+            month: "2-digit",
+            day: "2-digit",
+            hour: "2-digit",
+            minute: "2-digit",
+            second: "2-digit",
+        });
+        formatterCache.set(tz, f);
+    }
+    return f;
+}
+function formatParts(instant, tz) {
+    const parts = getFormatter(tz).formatToParts(instant);
+    const out = {};
+    for (const p of parts) {
+        if (p.type !== "literal")
+            out[p.type] = Number(p.value);
+    }
+    return {
+        year: out.year ?? 0,
+        month: out.month ?? 1,
+        day: out.day ?? 1,
+        hour: out.hour ?? 0,
+        minute: out.minute ?? 0,
+        second: out.second ?? 0,
+    };
+}
+/**
+ * Offset of `tz` at a given instant, in milliseconds east of UTC.
+ * `Asia/Colombo` → +19800000 (5h30m). Handles DST because it asks about a specific instant.
+ */
+function getTimeZoneOffsetMs(instant, tz) {
+    const p = formatParts(instant, tz);
+    const asIfUtc = Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute, p.second, instant.getUTCMilliseconds());
+    return asIfUtc - instant.getTime();
+}
+/**
+ * Interpret a wall-clock reading *in a zone* and return the UTC instant.
+ *
+ * DST makes this genuinely ambiguous, so a naive "measure the offset then subtract it" pass is
+ * wrong — around a transition it can silently resolve to a different local time than the one asked
+ * for. We instead form the two candidate instants implied by the offsets on either side of any
+ * nearby transition and check which of them actually round-trips:
+ *
+ *   both valid   normal time, or a fall-back OVERLAP -> take the earlier instant
+ *   one valid    unambiguous
+ *   neither      a spring-forward GAP: the requested local time does not exist, so shift forward
+ *                past the gap
+ *
+ * This matches Temporal's `disambiguation: "compatible"` and Luxon's default, which is the
+ * behaviour developers already expect. Both branches are covered by tests.
+ */
+function zonedTimeToUtc(wall, tz) {
+    const naive = Date.UTC(wall.year, wall.month - 1, wall.day, wall.hour ?? 0, wall.minute ?? 0, wall.second ?? 0, wall.ms ?? 0);
+    const DAY = 86_400_000;
+    const offsetBefore = getTimeZoneOffsetMs(new Date(naive - DAY), tz);
+    const offsetAfter = getTimeZoneOffsetMs(new Date(naive + DAY), tz);
+    const candidateA = naive - offsetBefore;
+    const candidateB = naive - offsetAfter;
+    const aValid = getTimeZoneOffsetMs(new Date(candidateA), tz) === offsetBefore;
+    const bValid = getTimeZoneOffsetMs(new Date(candidateB), tz) === offsetAfter;
+    if (aValid && bValid)
+        return new Date(Math.min(candidateA, candidateB)); // overlap -> earlier
+    if (aValid)
+        return new Date(candidateA);
+    if (bValid)
+        return new Date(candidateB);
+    return new Date(Math.max(candidateA, candidateB)); // gap -> forward past it
+}
+/** Parse "2026-08-31 10:29:00" / "2026-08-31T10:29" as a wall time in `tz`. */
+function parseZonedTimeToUtc(local, tz) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2}))?(?:\.(\d{1,3}))?$/.exec(local.trim());
+    if (!m) {
+        throw new errors_ts_1.AnchorConfigError(`Expected a local date-time like "2026-08-31 10:29:00" but received "${local}".`);
+    }
+    return zonedTimeToUtc({
+        year: Number(m[1]),
+        month: Number(m[2]),
+        day: Number(m[3]),
+        hour: Number(m[4]),
+        minute: Number(m[5]),
+        second: m[6] ? Number(m[6]) : 0,
+        ms: m[7] ? Number(m[7].padEnd(3, "0")) : 0,
+    }, tz);
+}
+/** Canonical storage format: ISO-8601, UTC, millisecond precision, `Z` suffix. */
+function toUtcIso(value) {
+    const d = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(d.getTime())) {
+        throw new errors_ts_1.AnchorConfigError(`Cannot convert ${JSON.stringify(value)} to a UTC timestamp.`);
+    }
+    return d.toISOString();
+}
+/** Render a UTC instant as wall-clock text in `tz`. Display only — storage is untouched. */
+function formatInTimeZone(value, tz, opts = {}) {
+    assertValidTimeZone(tz, "timezone");
+    const d = value instanceof Date ? value : new Date(value);
+    const p = formatParts(d, tz);
+    const pad = (n, w = 2) => String(n).padStart(w, "0");
+    const sep = opts.separator ?? " ";
+    const base = `${p.year}-${pad(p.month)}-${pad(p.day)}${sep}${pad(p.hour)}:${pad(p.minute)}:${pad(p.second)}`;
+    if (!opts.withZone)
+        return base;
+    return `${base} ${formatOffset(getTimeZoneOffsetMs(d, tz))}`;
+}
+function formatOffset(offsetMs) {
+    const sign = offsetMs < 0 ? "-" : "+";
+    const abs = Math.abs(offsetMs);
+    const h = Math.floor(abs / 3_600_000);
+    const m = Math.floor((abs % 3_600_000) / 60_000);
+    return `${sign}${String(h).padStart(2, "0")}:${String(m).padStart(2, "0")}`;
+}
+//# sourceMappingURL=timezone.js.map

package/dist/cjs/timestamps/timezone.js.map

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

package/dist/esm/conflict/strategies.d.ts

@@ -0,0 +1,110 @@
+import type { ConflictContext, ConflictResolutionConfig, ConflictStrategyName, Resolution } from "./types.js";
+/**
+ * The five conflict strategies, behind one interface.
+ *
+ * The sync engine knows only `resolve(context) -> Resolution`. No strategy-specific branching leaks
+ * into the engine, which is what makes switching strategy a pure configuration change (§19) and
+ * makes a sixth strategy a matter of registering one more object.
+ */
+export interface ConflictStrategyHandler<T extends Record<string, unknown> = Record<string, unknown>> {
+    readonly name: ConflictStrategyName | string;
+    resolve(context: ConflictContext<T>): Promise<Resolution<T>> | Resolution<T>;
+}
+/**
+ * Last write wins — the default.
+ *
+ * "Latest" is decided by the hybrid logical clock, never by raw device wall-clock strings. The
+ * comparison order is documented in SYNC_PROTOCOL.md:
+ *
+ *   1. HLC physical time (already skew-corrected against the server)
+ *   2. HLC logical counter, for writes inside the same millisecond
+ *   3. clientId, lexicographically
+ *
+ * Step 3 is what makes this a *total* order. Without it two devices could produce genuinely equal
+ * stamps and the winner would depend on evaluation order — different devices would converge to
+ * different documents, which is precisely the failure LWW is supposed to prevent.
+ *
+ * On an exact tie the server wins, because the server's copy is the one everyone else has already
+ * observed; preferring the client would make convergence depend on who pushed last.
+ */
+export declare class LastWriteWinsStrategy<T extends Record<string, unknown>> implements ConflictStrategyHandler<T> {
+    readonly name = "last-write-wins";
+    resolve(ctx: ConflictContext<T>): Resolution<T>;
+}
+/**
+ * Server wins — the local change is discarded and the server's document adopted.
+ *
+ * `pushBack: false` matters: re-pushing a document the server just gave us would create an endless
+ * echo between the two.
+ */
+export declare class ServerWinsStrategy<T extends Record<string, unknown>> implements ConflictStrategyHandler<T> {
+    readonly name = "server-wins";
+    resolve(ctx: ConflictContext<T>): Resolution<T>;
+}
+/**
+ * Client wins — the local change overwrites the server's.
+ *
+ * The loop hazard is real and is handled by the engine rather than here: the re-push carries
+ * `baseVersion = remoteVersion` (the version we just observed), so the server's optimistic check
+ * now passes instead of conflicting again forever. The engine also caps `conflictAttempts`.
+ */
+export declare class ClientWinsStrategy<T extends Record<string, unknown>> implements ConflictStrategyHandler<T> {
+    readonly name = "client-wins";
+    resolve(ctx: ConflictContext<T>): Resolution<T>;
+}
+declare const DELETED: unique symbol;
+/**
+ * Field-level three-way merge.
+ *
+ * Compares local and remote against their common ancestor (`base`, the last server-confirmed
+ * document kept in the shadow table). Paths only one side touched merge silently; paths both sides
+ * touched are a genuine conflict and fall to `fieldPolicy`.
+ *
+ * Documented edge cases, each with a test:
+ *
+ *  - **No base.** Without an ancestor we cannot tell an edit from an insert, so a merge would be a
+ *    guess. Falls back to last-write-wins rather than inventing a result.
+ *  - **Arrays are atomic by default.** Element-wise merging of two concurrently reordered arrays
+ *    has no correct answer in general. `arrayStrategy: "union-by-id"` opts into merging arrays of
+ *    objects that carry `_id`/`id`.
+ *  - **Deleted fields.** "Deleted on one side" is distinguished from "absent on both" by diffing
+ *    against base — otherwise a deletion would be silently undone by the other side's copy.
+ *  - **Type changes** (string -> object) are treated as an ordinary same-path conflict.
+ *  - **Object replacement.** An edit at `a` conflicts with an edit at `a.b`: parent/child overlap is
+ *    detected explicitly, because treating them as unrelated paths would resurrect a replaced object.
+ */
+export declare class FieldLevelStrategy<T extends Record<string, unknown>> implements ConflictStrategyHandler<T> {
+    readonly name = "field-level";
+    private readonly policy;
+    private readonly arrayStrategy;
+    private readonly fallback;
+    constructor(config?: ConflictResolutionConfig<T>);
+    resolve(ctx: ConflictContext<T>): Resolution<T>;
+    private decide;
+    /** Opt-in array merging for arrays of objects with a stable identity. */
+    private mergeArraysById;
+}
+/**
+ * Custom resolver.
+ *
+ * The developer's function may return either a bare document (treated as the resolved value) or a
+ * full `Resolution` when it needs to control `pushBack`. A throwing resolver is *not* caught here —
+ * the engine parks the mutation and keeps draining the queue, so one bad resolver cannot wedge sync
+ * for every other document.
+ */
+export declare class CustomStrategy<T extends Record<string, unknown>> implements ConflictStrategyHandler<T> {
+    readonly name = "custom";
+    private readonly resolver;
+    constructor(config: ConflictResolutionConfig<T>);
+    resolve(ctx: ConflictContext<T>): Promise<Resolution<T>>;
+}
+/** Registry — open for user-defined strategies (§11). */
+export declare class ConflictStrategyRegistry<T extends Record<string, unknown> = Record<string, unknown>> {
+    private readonly strategies;
+    constructor(config?: ConflictResolutionConfig<T>);
+    register(strategy: ConflictStrategyHandler<T>): void;
+    get(name: string): ConflictStrategyHandler<T>;
+    names(): string[];
+}
+export { DELETED as FIELD_DELETED };
+//# sourceMappingURL=strategies.d.ts.map

package/dist/esm/conflict/strategies.d.ts.map

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