dsh-plugin-usage 0.1.4 → 0.2.2

package/lib/host/rpc.js

@@ -0,0 +1,191 @@
+/**
+ * RPC registration.
+ *
+ * Dynamic-plugin runs expose `harness` directly; static (bundle) installs
+ * expose the Connection service. Support both from one file, plus the
+ * official Typert gateway path (P0-3).
+ *
+ * Host side, preference order:
+ *   1. dynamic-plugin run      -> `harness.handle(endpoint, fn)`
+ *   2. Typert gateway present  -> `typert.register(channel, endpoints)`
+ *   3. static (bundle) install -> Connection
+ *
+ * Connection has two registries and they are NOT interchangeable:
+ *
+ *   - `connection.fetch.register(route)` adds one exact route to the shared
+ *     `/api` dispatch table. It only touches the service's own map, so it
+ *     works from any fiber.
+ *   - `connection.rpc.handle(channel, handler)` mounts a physical prefix route
+ *     through `owner.webServer.register(route)`, where `owner` is the fiber
+ *     that READ the service. On 0.2.x every plugin fiber is a strict proxy: a
+ *     plugin whose `inject` is `['timer']` throws `cannot get property
+ *     "webServer" without inject` inside that registration, `effect()`
+ *     rethrows it, and the channel silently never mounts — observed as HTTP
+ *     405 on `/usage/*` with no host-side message. Adding `webServer` to the
+ *     plugin's static `inject` would "fix" it only for compositions that own a
+ *     web server, and would gate dynamic-plugin loads on a service they never
+ *     get, so the fetch registry is the correct seam for a bundle install.
+ *
+ * Therefore: register exact Fetch routes on the shared `/api` channel when
+ * that registry exists, and keep the legacy `/usage` prefix channel as a
+ * best-effort fallback for older hosts. The browser half calls the Fetch route
+ * first and falls back to the legacy channel on "route missing".
+ *
+ * Wire format of one Fetch route (POST `/api/usage/<endpoint>`):
+ *   request body  = JSON of the endpoint args (or empty for no args)
+ *   response body = `{ ok: true, value }` | `{ ok: false, error: { code, message } }`
+ * i.e. the same result shape the legacy RPC channel wraps, minus its envelope.
+ */
+/** Absolute logical channel owned by this plugin on pre-0.2 hosts. */
+export const USAGE_RPC_CHANNEL = '/usage';
+/** Shared-channel path prefix owned by this plugin (`/api` is Connection's mount). */
+export const USAGE_API_PREFIX = '/api/usage';
+/**
+ * Exact Fetch route path for one endpoint.
+ *
+ * @param {string} endpoint - endpoint name such as `query`.
+ * @returns {string} absolute path below `/api`, as `connection.fetch.register` requires.
+ */
+export function fetchRoutePath(endpoint) {
+    return USAGE_API_PREFIX + '/' + endpoint;
+}
+/**
+ * Failure result in the Connection RPC result shape.
+ *
+ * @param {string} message - human-readable failure.
+ * @param {string} [code] - stable error code.
+ * @returns {{ ok: false, error: { code: string, message: string, details: object } }} failure result.
+ */
+export function errorResult(message, code = 'internal') {
+    return { ok: false, error: { code, message, details: {} } };
+}
+/**
+ * Run one endpoint through the handler map, converting throws into results.
+ *
+ * @param {Map<string, (args: any) => any>} handlers - endpoint handlers.
+ * @param {string} endpoint - endpoint name.
+ * @param {unknown} args - decoded endpoint arguments.
+ * @returns {Promise<{ ok: true, value: any } | { ok: false, error: object }>} RPC result.
+ */
+export async function dispatch(handlers, endpoint, args) {
+    const fn = handlers.get(endpoint);
+    if (fn === undefined)
+        return errorResult(`unknown endpoint: ${endpoint}`, 'bad-request');
+    try {
+        return { ok: true, value: await fn(args) };
+    }
+    catch (error) {
+        return errorResult(String((error && error.message) || error));
+    }
+}
+/**
+ * Build the Fetch-shaped handler for one exact route.
+ *
+ * @param {Map<string, (args: any) => any>} handlers - endpoint handlers.
+ * @param {string} endpoint - endpoint name.
+ * @returns {(request: Request) => Promise<Response>} route handler.
+ */
+export function createFetchRoute(handlers, endpoint) {
+    return async function fetchRoute(request) {
+        let args = null;
+        const text = await request.text();
+        if (text.length > 0) {
+            try {
+                args = JSON.parse(text);
+            }
+            catch {
+                return Response.json(errorResult('request body is not JSON', 'bad-request'), { status: 400 });
+            }
+        }
+        return Response.json(await dispatch(handlers, endpoint, args));
+    };
+}
+/**
+ * Register every endpoint on the best transport this host offers.
+ *
+ * @param {any} ctx - host plugin context.
+ * @param {Map<string, (args: any) => any>} handlers - endpoint handlers.
+ */
+export function registerRPC(ctx, handlers) {
+    const dynamicHarness = (typeof harness !== 'undefined' && harness && typeof harness.handle === 'function') ? harness : null;
+    if (dynamicHarness !== null) {
+        for (const [endpoint, fn] of handlers) {
+            dynamicHarness.handle('usage/' + endpoint, fn);
+        }
+        return;
+    }
+    // P0-3 official Typert gateway path.
+    //
+    // Target API: @deepseek-ai/dsh-api-gateway host service, exposed on the host
+    // Read the gateway only via `ctx.get('typertGateway')` — cordis ctx is a
+    // property). The installed v0.1.0-rc.7 `TypertGateway` interface exposes
+    // only invoke() (see the package's lib/types/types.d.ts); the documented
+    // contribution path (@Remote/@RemoteScope + TypertRemoteService or
+    // bindTypertRemote from @deepseek-ai/dsh-typert-protocol) needs a runtime
+    // dependency this plugin must not add, so we only claim endpoints through a
+    // registration surface that already exists on the detected object:
+    // `typert.register(channel, endpoints)`, a forward-compatible contribution
+    // hook for host compositions that expose the gateway with registration.
+    //
+    // Precondition for this path to activate: the resolved typert gateway is
+    // non-null AND `typert.register` is a function. Endpoint functions receive
+    // (args) and return the raw value; the gateway/connection side owns the
+    // RPC envelope. Otherwise we fall back silently to the connection bridge
+    // below. All guards are typeof-based: nothing is imported, zero deps.
+    // cordis ctx is a strict proxy: direct property access to an un-injected
+    // service throws — always use ctx.get (returns undefined when absent).
+    const typert = typeof ctx.get === 'function' ? ctx.get('typertGateway') : undefined;
+    if (typert && typeof typert.register === 'function') {
+        const endpoints = {};
+        for (const [endpoint, fn] of handlers) {
+            endpoints[endpoint] = fn;
+        }
+        typert.register('usage', endpoints);
+        return;
+    }
+    // Static (bundle) installs: the `connection` service is provided
+    // asynchronously by the client-connection plugin, so wait for it before
+    // registering (the official api-gateway pattern).
+    ctx.inject(['connection'], (connectionCtx) => {
+        const connection = connectionCtx.connection;
+        if (connection === undefined || connection === null)
+            return;
+        // 0.2+: exact Fetch routes on the shared /api channel. This is the path
+        // that actually mounts a route: it never reads `webServer`, so the strict
+        // fiber proxy cannot reject it.
+        const fetchRegistry = connection.fetch;
+        let mountedFetchRoutes = 0;
+        if (fetchRegistry !== undefined && typeof fetchRegistry.register === 'function') {
+            for (const endpoint of handlers.keys()) {
+                const path = fetchRoutePath(endpoint);
+                try {
+                    fetchRegistry.register({
+                        path,
+                        methods: ['POST'],
+                        requestBody: 'buffered',
+                        fetch: createFetchRoute(handlers, endpoint),
+                    });
+                    mountedFetchRoutes += 1;
+                }
+                catch (error) {
+                    console.warn(`[usage] failed to mount shared Fetch route ${path}: ${String((error && error.message) || error)}`);
+                }
+            }
+        }
+        // Pre-0.2 hosts (and any composition that still exposes the prefix
+        // channel): the legacy /usage RPC bridge. On 0.2.x this throws inside
+        // effect() because the reading fiber owns no `webServer`; that is expected
+        // and already covered by the Fetch routes, so the failure stays local.
+        const rpcRegistry = connection.rpc;
+        if (rpcRegistry !== undefined && typeof rpcRegistry.handle === 'function') {
+            try {
+                rpcRegistry.handle(USAGE_RPC_CHANNEL, async (endpoint, args) => dispatch(handlers, endpoint, args), { authority: 'loopback' });
+            }
+            catch (error) {
+                if (mountedFetchRoutes === 0) {
+                    console.warn(`[usage] failed to mount ${USAGE_RPC_CHANNEL} RPC channel: ${String((error && error.message) || error)}`);
+                }
+            }
+        }
+    });
+}

package/lib/host/scan.js

@@ -0,0 +1,233 @@
+/**
+ * Live/persisted session scanning + startup backfill.
+ *
+ * DSH 0.2.x session accessors (verified against @deepseek-ai/dsh-session and
+ * @deepseek-ai/dsh-session-persistence 0.2.0-rc.2 / 0.2.1-rc.2):
+ *
+ *  - live:     `ctx.sessions.list()` -> `Session`, events via
+ *              `session.snapshotEvents(fromSeq)`.
+ *  - persisted: `ctx.sessionPersistence.list()` -> `{ header, revision,
+ *              eventCount?, sizeBytes? }`, then `open(id, 'read')` and
+ *              `handle.read(offset)`; the handle carries
+ *              `inheritedEventCount` and must be closed.
+ *
+ * A forked session replays its parent's prefix; `inheritedEventCount` is the
+ * cut, so folding starts there and the parent is never billed twice.
+ *
+ * Optimization lives here: bounded-concurrency backfill, per-session failure
+ * backoff, revision-based skip (unchanged logs are not re-read), progress
+ * callbacks, and watermark repair when a log shrank.
+ */
+import { foldNew } from './fold.js';
+/** How many persisted headers are read concurrently per batch. */
+const BATCH_SIZE = 8;
+/**
+ * Per-session backoff bookkeeping, kept at module (closure) scope so it spans
+ * multiple passes. Value is { failures, skipLeft }: consecutive failure count
+ * plus the number of upcoming passes the session is skipped for
+ * (2 ** failures, capped at 5; decays by one each pass).
+ */
+const backoffBySession = new Map();
+/** True while a scanPersisted pass is in flight; overlapping passes are dropped. */
+let persistedInFlight = false;
+/**
+ * Events of one live session at or after `fromSeq`.
+ *
+ * @param {any} session - live Session.
+ * @param {number} fromSeq - first seq to return.
+ * @returns {ReadonlyArray<object>} events in log order.
+ */
+export function liveEvents(session, fromSeq) {
+    if (session === null || typeof session !== 'object')
+        return [];
+    if (typeof session.snapshotEvents === 'function')
+        return session.snapshotEvents(fromSeq);
+    // Legacy pre-0.2 sessions exposed the whole log as `events`.
+    if (Array.isArray(session.events)) {
+        return session.events.filter((event) => !event || typeof event.seq !== 'number' || event.seq >= fromSeq);
+    }
+    return [];
+}
+/** Scan live in-memory sessions (cheap, every tick). */
+export function scanLive(ctx, state) {
+    const sessions = ctx.get('sessions');
+    if (sessions === undefined || sessions === null)
+        return;
+    for (const s of sessions.list()) {
+        if (!s || !s.id)
+            continue;
+        const wm = state.watermarks.get(s.id) ?? -1;
+        // Never bill the fork-inherited prefix to the child.
+        const inherited = typeof s.inheritedEventCount === 'number' ? s.inheritedEventCount : 0;
+        const from = Math.max(wm + 1, inherited);
+        const next = foldNew(state, s.id, liveEvents(s, from), wm);
+        if (next > wm)
+            state.watermarks.set(s.id, next);
+    }
+}
+/** Id of one persistence listing snapshot (`{header:{id}}` in 0.2.x). */
+function snapshotId(snap) {
+    if (!snap || typeof snap !== 'object')
+        return undefined;
+    if (snap.header && typeof snap.header.id === 'string')
+        return snap.header.id;
+    if (typeof snap.id === 'string')
+        return snap.id;
+    return undefined;
+}
+/**
+ * Read events for one persisted session at or after `fromSeq`, preferring the
+ * 0.2.x handle API and falling back to a legacy `readFrom` backend.
+ *
+ * @param {any} persistence - sessionPersistence service.
+ * @param {string} id - session id.
+ * @param {number} fromSeq - first seq to return.
+ * @returns {Promise<{ events: ReadonlyArray<object>, inherited: number }>} events + fork cut.
+ */
+export async function readSessionEvents(persistence, id, fromSeq) {
+    if (typeof persistence.open === 'function') {
+        const handle = await persistence.open(id, 'read');
+        try {
+            const inherited = typeof handle.inheritedEventCount === 'number' ? handle.inheritedEventCount : 0;
+            const page = await handle.read(Math.max(fromSeq, inherited));
+            return { events: (page && page.events) || [], inherited };
+        }
+        finally {
+            if (handle && typeof handle.close === 'function') {
+                try {
+                    await handle.close();
+                }
+                catch {
+                    // A close failure must not turn a successful read into a failed scan.
+                }
+            }
+        }
+    }
+    if (typeof persistence.readFrom === 'function') {
+        const page = await persistence.readFrom(id, fromSeq);
+        return { events: (page && page.events) || [], inherited: 0 };
+    }
+    return { events: [], inherited: 0 };
+}
+/**
+ * Incremental scan of persisted sessions (slow cadence). Headers are read in
+ * small concurrent batches; unchanged revisions are skipped; a failing session
+ * is backed off for an exponentially growing number of passes instead of
+ * aborting the pass.
+ */
+export async function scanPersisted(ctx, state, options) {
+    const sp = ctx.get('sessionPersistence');
+    if (sp === undefined || sp === null)
+        return;
+    if (persistedInFlight)
+        return; // previous pass still running: skip this tick
+    persistedInFlight = true;
+    try {
+        const headers = await sp.list();
+        if (!Array.isArray(headers))
+            return;
+        state.backfill.total = headers.length;
+        for (let i = 0; i < headers.length; i += BATCH_SIZE) {
+            const batch = headers.slice(i, i + BATCH_SIZE);
+            await Promise.all(batch.map((h) => processHeader(sp, state, h, options)));
+        }
+    }
+    finally {
+        persistedInFlight = false;
+        if (options && typeof options.onDone === 'function') {
+            options.onDone({
+                status: state.backfill.status,
+                total: state.backfill.total,
+                done: state.backfill.done,
+            });
+        }
+    }
+}
+/** Read + fold one persisted session header; bounded by the batch caller. */
+async function processHeader(sp, state, snap, options) {
+    const id = snapshotId(snap);
+    if (id === undefined)
+        return;
+    const backoff = backoffBySession.get(id);
+    if (backoff && backoff.skipLeft > 0) {
+        backoff.skipLeft -= 1; // decay the skip count one pass at a time
+        return;
+    }
+    try {
+        const revision = snap && snap.revision;
+        if (revision !== undefined && Object.is(state.revisions.get(id), revision)) {
+            // The backend reports the same change token: the log is unchanged.
+            backoffBySession.delete(id);
+            return;
+        }
+        let wm = state.watermarks.get(id) ?? -1;
+        // A crash-repaired or migrated log can shrink below our watermark; the
+        // backend reports the current event count, so repair instead of stalling.
+        if (typeof snap.eventCount === 'number' && wm >= snap.eventCount) {
+            wm = -1;
+            state.watermarks.set(id, -1);
+            state.lastSample.delete(id);
+        }
+        const { events } = await readSessionEvents(sp, id, wm + 1);
+        const next = foldNew(state, id, events, wm);
+        if (next > wm)
+            state.watermarks.set(id, next);
+        if (revision !== undefined)
+            state.revisions.set(id, revision);
+        backoffBySession.delete(id); // success resets the consecutive-failure chain
+    }
+    catch (error) {
+        // A session may be gone or mid-rewrite: back off before trying again.
+        const b = backoffBySession.get(id) || { failures: 0, skipLeft: 0 };
+        b.failures += 1;
+        b.skipLeft = Math.min(5, 2 ** b.failures);
+        backoffBySession.set(id, b);
+        return;
+    }
+    finally {
+        if (state.backfill.status === 'running') {
+            state.backfill.done += 1;
+            if (options && typeof options.onProgress === 'function') {
+                options.onProgress({
+                    status: state.backfill.status,
+                    total: state.backfill.total,
+                    done: state.backfill.done,
+                });
+            }
+        }
+    }
+}
+/** Full history scan, once at startup. */
+export async function runBackfill(ctx, state, options) {
+    const sp = ctx.get('sessionPersistence');
+    if (sp === undefined || sp === null) {
+        state.backfill.status = 'done';
+        fireBackfillDone(options, state);
+        return;
+    }
+    state.backfill.status = 'running';
+    state.backfill.done = 0;
+    // Delegate progress while the pass runs; onDone is fired right here exactly
+    // once so the pass callback does not double-report backfill completion.
+    const scanOptions = options && typeof options.onProgress === 'function'
+        ? { onProgress: options.onProgress }
+        : undefined;
+    try {
+        await scanPersisted(ctx, state, scanOptions);
+        state.backfill.status = 'done';
+        fireBackfillDone(options, state);
+    }
+    catch (error) {
+        state.backfill.status = 'done';
+        fireBackfillDone(options, state);
+    }
+}
+function fireBackfillDone(options, state) {
+    if (options && typeof options.onDone === 'function') {
+        options.onDone({
+            status: state.backfill.status,
+            total: state.backfill.total,
+            done: state.backfill.done,
+        });
+    }
+}

package/lib/host/settings.js

@@ -0,0 +1,100 @@
+/**
+ * Price table + cost computation.
+ *
+ * Persistence is the official plugin-config path: `index.js` exports a
+ * schemastery `Config`, so DSH materializes a form under the plugin entry's
+ * id (`usage`) in the Plugins settings tab and stores values in the profile
+ * patch. There is deliberately no private `settings.yaml` / settings-service
+ * registration here — DSH 0.2.x `ctx.settings` (SettingsForms) only offers
+ * `describe/update/replace/mutate/configure`, and hand-rolled namespaces are
+ * not reachable from the client config surface.
+ *
+ * The store below stays the in-memory view the aggregation code reads.
+ */
+export const DEFAULT_CURRENCY = '¥';
+export const DEFAULT_PRICES = {
+    'deepseek-chat': { inputPerM: 0.27, outputPerM: 1.1, cacheReadPerM: 0.07, cacheWritePerM: 0.27 },
+    'deepseek-v3': { inputPerM: 0.27, outputPerM: 1.1, cacheReadPerM: 0.07, cacheWritePerM: 0.27 },
+    'deepseek-v3.1': { inputPerM: 0.27, outputPerM: 1.1, cacheReadPerM: 0.07, cacheWritePerM: 0.27 },
+    'deepseek-v4': { inputPerM: 0.27, outputPerM: 1.1, cacheReadPerM: 0.07, cacheWritePerM: 0.27 },
+    'deepseek-v4-flash': { inputPerM: 0.14, outputPerM: 0.56, cacheReadPerM: 0.04, cacheWritePerM: 0.14 },
+    'deepseek-v4.1-flash': { inputPerM: 0.14, outputPerM: 0.56, cacheReadPerM: 0.04, cacheWritePerM: 0.14 },
+    'deepseek-v4.1-flash-1017': { inputPerM: 0.14, outputPerM: 0.56, cacheReadPerM: 0.04, cacheWritePerM: 0.14 },
+    // DSH's routed default model id (`magpie` provider) aliases the same route;
+    // without this entry every session bills as "unpriced" on a stock install.
+    'group/auto-deepseek-v4-1-flash': { inputPerM: 0.14, outputPerM: 0.56, cacheReadPerM: 0.04, cacheWritePerM: 0.14 },
+    'deepseek-reasoner': { inputPerM: 0.55, outputPerM: 2.19, cacheReadPerM: 0.14, cacheWritePerM: 0.55 },
+    'deepseek-r1': { inputPerM: 0.55, outputPerM: 2.19, cacheReadPerM: 0.14, cacheWritePerM: 0.55 },
+};
+/**
+ * Shallow-merge configured prices over the defaults.
+ *
+ * @param {unknown} incoming - configured per-model prices.
+ * @returns {Record<string, object>} complete price table.
+ */
+export function mergePrices(incoming) {
+    const merged = Object.assign({}, DEFAULT_PRICES);
+    if (incoming && typeof incoming === 'object' && !Array.isArray(incoming)) {
+        for (const [model, price] of Object.entries(incoming)) {
+            if (price && typeof price === 'object') {
+                merged[model] = {
+                    inputPerM: Number(price.inputPerM) || 0,
+                    outputPerM: Number(price.outputPerM) || 0,
+                    cacheReadPerM: Number(price.cacheReadPerM) || 0,
+                    cacheWritePerM: Number(price.cacheWritePerM) || 0,
+                };
+            }
+        }
+    }
+    return merged;
+}
+export function createPriceStore(defaultPrices, defaultCurrency) {
+    const prices = Object.assign({}, defaultPrices);
+    let currency = defaultCurrency || DEFAULT_CURRENCY;
+    const store = {
+        prices,
+        get currency() { return currency; },
+        /** Merge incoming per-model prices (each field coerced to a number). */
+        setPrices(incoming) {
+            if (!incoming || typeof incoming !== 'object')
+                return;
+            for (const [model, p] of Object.entries(incoming)) {
+                if (p && typeof p === 'object') {
+                    prices[model] = {
+                        inputPerM: Number(p.inputPerM) || 0,
+                        outputPerM: Number(p.outputPerM) || 0,
+                        cacheReadPerM: Number(p.cacheReadPerM) || 0,
+                        cacheWritePerM: Number(p.cacheWritePerM) || 0,
+                    };
+                }
+            }
+        },
+        setCurrency(v) {
+            if (typeof v === 'string' && v.length > 0)
+                currency = v;
+        },
+        /** Look up a price by `provider/model` composite first, then bare model. */
+        priceOf(r) {
+            const composite = r.provider ? r.provider + '/' + r.model : '';
+            return prices[composite] || prices[r.model];
+        },
+        /** Whether an explicit price entry exists (composite first, then bare model). */
+        hasPrice(r) {
+            const composite = r.provider ? r.provider + '/' + r.model : '';
+            return composite in prices || r.model in prices;
+        },
+        costOf(r) {
+            const p = store.priceOf(r);
+            if (!p)
+                return 0;
+            return (r.inputTokens * p.inputPerM +
+                r.outputTokens * p.outputPerM +
+                r.cacheReadTokens * (p.cacheReadPerM || 0) +
+                r.cacheWriteTokens * (p.cacheWritePerM || 0)) / 1e6;
+        },
+        snapshot() {
+            return { prices: Object.assign({}, prices), currency };
+        },
+    };
+    return store;
+}

package/lib/host/state.js

@@ -0,0 +1,32 @@
+/**
+ * Mutable runtime state capsule for the usage host half.
+ *
+ * - records: folded usage records, one per billed assistant settlement
+ *   (`assistant/message` or `assistant/attempt`) that reported usage.
+ * - watermarks: sessionId -> last folded event seq.
+ * - revisions: sessionId -> last persisted revision folded (opaque equality
+ *   token from `sessionPersistence.list()`); lets the slow scan skip sessions
+ *   whose log did not change.
+ * - backfill: progress counters surfaced through query results.
+ * - prices: the price store from settings.js.
+ * - lastSample: sessionId -> { turn, step, record } — the replacement slot the
+ *   official tokenUsage projection keeps, so a later sample for the same
+ *   (turn, step) replaces in place and `llm/retry-started` clears it.
+ * - route: sessionId -> { provider, model } from the latest request route,
+ *   used to attribute settlements that carry no `message.source`
+ *   (`assistant/attempt` never does).
+ * - index: incremental aggregation index (aggregate.js), kept in sync by
+ *   fold.js and consumed by query.js.
+ */
+export function createState(priceStore) {
+    return {
+        records: [],
+        watermarks: new Map(),
+        revisions: new Map(),
+        backfill: { status: 'idle', total: 0, done: 0 },
+        prices: priceStore,
+        lastSample: new Map(),
+        route: new Map(),
+        index: null, // wired by apply() after createUsageIndex(state)
+    };
+}

package/lib/host/time.js

@@ -0,0 +1,82 @@
+/**
+ * Time helpers for usage bucketing — pure, dependency-free.
+ * Granularity keys: 'day' | 'hour' | 'minute'.
+ *
+ * User-facing buckets (dayKey / alignFloor / bucketKeyFor non-day cases) use
+ * LOCAL calendar time. dayIndex is a local-midnight-based ordinal used to
+ * align step-day blocks. DST-consistent handling is owned by this module.
+ */
+export const DAY_MS = 86400000;
+export function dayKey(t) {
+    const d = new Date(t);
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+/** Ordinal day number (local-midnight based), for step alignment. */
+export function dayIndex(t) {
+    return Math.floor(alignFloor(t, 'day') / DAY_MS);
+}
+/** Local-midnight epoch of the day whose dayIndex ordinal is `block`. */
+function localMidnightForOrdinal(block) {
+    let epoch = alignFloor(block * DAY_MS, 'day');
+    let idx = Math.floor(epoch / DAY_MS);
+    while (idx < block) {
+        epoch = alignFloor(epoch + DAY_MS, 'day');
+        idx = Math.floor(epoch / DAY_MS);
+    }
+    while (idx > block) {
+        epoch = alignFloor(epoch - DAY_MS, 'day');
+        idx = Math.floor(epoch / DAY_MS);
+    }
+    return epoch;
+}
+/** Bucket key for one instant under a granularity (day buckets may span stepDays). */
+export function bucketKeyFor(t, g, stepDays) {
+    const pad = (n) => String(n).padStart(2, '0');
+    if (g === 'day') {
+        // Single-day buckets are the local calendar day itself (DST-safe by construction).
+        if (stepDays === 1)
+            return dayKey(t);
+        const block = Math.floor(dayIndex(t) / stepDays) * stepDays;
+        return dayKey(localMidnightForOrdinal(block));
+    }
+    const d = new Date(t);
+    const date = `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+    const hm = pad(d.getHours()) + ':' + (g === 'hour' ? '00' : pad(d.getMinutes()));
+    return date + ' ' + hm;
+}
+export function stepMs(g) {
+    return g === 'day' ? DAY_MS : g === 'hour' ? 3600000 : 60000;
+}
+/** Floor an instant to its granularity boundary. */
+export function alignFloor(t, g) {
+    const d = new Date(t);
+    if (g === 'day') {
+        d.setHours(0, 0, 0, 0);
+        return d.getTime();
+    }
+    if (g === 'hour') {
+        d.setMinutes(0, 0, 0);
+        return d.getTime();
+    }
+    d.setSeconds(0, 0);
+    return d.getTime();
+}
+/** Floor an instant to its stepDays block start (local midnight of the block's anchor day). */
+export function alignBlock(t, stepDays) {
+    if (stepDays === 1)
+        return alignFloor(t, 'day');
+    const block = Math.floor(dayIndex(t) / stepDays) * stepDays;
+    return localMidnightForOrdinal(block);
+}
+/**
+ * Bucket key under a day granularity with a range-anchored step grid:
+ * blocks start at the range's first day, so a custom range reads naturally
+ * (e.g. 90 days -> 18 x 5-day buckets starting on the range's first day).
+ */
+export function stepDayKey(r, dayStart, stepDays) {
+    const k = Math.floor((alignFloor(r.time, 'day') - dayStart) / (stepDays * DAY_MS));
+    return dayKey(dayStart + k * stepDays * DAY_MS);
+}
+/** Cap on zero-filled output buckets; beyond it we emit present-only buckets. */
+export const MAX_BUCKETS = 2000;